← narwal.one/Second Brain
SecondBrain
Ask the Brain
Index/Conceptupdated Sat Jul 25 2026 08:00:00 GMT+0800 (Philippine Standard Time)

Skills (Claude Code)

claude-codeskillscapabilitiesagentsharnessself-improvementcontext-rightsizing

note 2026-07-24 addition — Anthropic's official skill-authoring guidance for the Claude 5 era Thariq Shihipar's Anthropic-blog sequel The New Rules of Context Engineering for Claude 5 (Thariq Shihipar) gives skill authors first-party guidance: skills should be lightweight retrieval guides; divide long skills across multiple files (progressive disclosure); avoid overconstrained instructions except in critical areas; encode team-specific opinions/knowledge/best-practices rather than generic procedure. Anthropic ships claude doctor / /doctor — the first-party tool for rightsizing existing skills for the newer model class — which is the operational answer to Pocock's deletion test in Skill Checklist (Pocock). See Context Rightsizing for the discipline.

note 2026-07-07 addition — "smaller prompt, fewer examples" for Fable-class models Thariq Shihipar (Claude Code MTS) in Field Guide to Fable (Thariq Shihipar, Anthropic) revealed Claude Code removed 80% of its system prompt for the Fable-class tier. Examples that used to help older models now constrain Fable — it's more imaginative than the examples given. Direction of travel: small system prompt + many tools + fewer examples, reversing the intermediate-generation practice of large system prompts with many examples. Direct implication for skills: prefer context and pointers over prescriptive procedure; the SKILL.md should describe what and when, not spell out how in step-by-step examples if the target is Fable-class. Also see Ubiquitous Language (Pocock's parallel prescription: shared vocabulary, not verbose instructions) and Design Concept (Brooks) (front-load the alignment, not the artifact).

Skills (Claude Code)

Reusable instruction files that encode how you specifically do a task, callable by natural language (or as a /slash-command). In the Four C's Framework they are the Capabilities layer — the thing that turns a generic model into one that writes a LinkedIn post in your voice, runs your monthly report, or hands off a session.

Skills can live locally (scoped to one project) or globally (available in any directory). Nate Herk (AI Automation) moves frequently-used skills to global; project-specific ones stay local.

Two ways to build a skill

  1. Forward — name a recurring task, invoke a skill-creator, give the end goal + the tools/considerations involved, then iterate. "Sometimes 50 tries until you like it." Then keep evolving it: every use, give feedback ("this was good, this wasn't — change it so next time it doesn't happen").
  2. Reverse-engineer (Nate's more common method) — do the task end-to-end first, get a good output, then ask Claude: "Look back at our conversation. What did we do to get there? What tools did you need? What did you ask me?" and build a skill that reproduces that output.

Skills aren't only big SOPs

A skill can be as small as a prompt you keep retyping. Nate's example: a global /session-handoff skill that outputs a full breakdown — what was done, files created, open decisions, what's next — so he can clear context or move from Claude Code to Codex and pick up cleanly. Just a prompt, but worth a slash command because he ran it many times a day. (This vault's own CLAUDE.md operations — ingest/query/lint/journal/crm — are the same idea: codified repeatable workflows.)

Another small-skill archetype from the Fable walkthrough: "grill me" (adapted from Matt Pocock's grill-with-docs) — the skill interviews you, 15–30 questions deep, writing answers to brainstorm docs. Elicitation as a skill: it pulls knowledge out of the owner's head into the AIOS instead of waiting for them to write context docs. Nate used it to plan the very video it appears in.

The feedback ritual, made explicit in the same source: "every single time I use a skill, I give it feedback and say update the skill" — preferences, models, and endpoints drift, so a four-month-old skill still gets iterated on every use. "There's no such thing as a finished product." (The manual counterpart of the overnight self-improvement loop below.)

Governance

A skill's reach is governed by Bike Method (earn autonomy in phases) and Capabilities vs Instructions (Agent Keys) (a skill can only do what keys are on the ring). Ryan Lopopolo's harness engineering is the industrial-scale version of the same skill-as-capability discipline.

Self-improvement (third construction path)

Beyond forward (build from a spec) and reverse (build from a good output), Simon Scrapes's video adds a third: let the skill iterate on itself overnight against a fixed eval set. Two distinct layers, two distinct loops:

Layer Optimizes Loop Status
1 — Trigger YAML description → activation rate Skill-creator's built-in description-improvement loop (improve_description.py + run_loop.py) Already ships in Anthropic's skill-creator (Skills 2.0)
2 — Behavior SKILL.md body → output passes structural assertions Custom auto-research loop over Binary Eval Assertions DIY — Simon's worked example: 25 binary assertions, 5 tests, overnight loop

The binary-eval discipline is the make-or-break: subjective evals under optimization pressure surface Reward Hacking (see MAC paper); binary evals (regex / parser / boolean check) give a clean keep/revert signal. The video's headline win: a 5th-version marketing-copy skill hit 23/24 first run, found a tone-of-voice rule missing from SKILL.md, added it, hit perfect score on rerun.

Limitations Simon flags: the binary loop does not handle tone, creativity, or whether the skill is actually using its reference files properly. Those need a complementary subjective tier (human or LLM as Judge).

This applies to this vault's own skills too: ingest/query/lint/journal/crm are codified workflows with implicit binary invariants (index.md updated, log.md entry well-formed, raw file moved to processed). See Auto Research Loop (Karpathy) for the concrete vault application.

Judging skill quality (the fourth layer)

The three construction paths above (forward / reverse / self-improving) say how to build a skill; Matt Pocock's Skill Checklist (Pocock) (Building Great Agent Skills (Matt Pocock, AI Engineer)) adds how to judge one — Trigger / Structure / Steering / Pruning:

  • Trigger: user-invoked vs model-invoked is a cost tradeoff — model-invoked descriptions add context load (tokens + decision noise on every request) and unpredictability (the agent may not follow the pointer); user-invoked skills shift the cost to the pilot's cognitive load.
  • Structure: steps + reference; keep SKILL.md minimal by moving branch-specific reference behind context pointers.
  • Steering: Leading Words — dense prior-triggering terms you can verify in reasoning traces; split steps into separate skills when the agent skimps on "leg work" because it can see the end goal.
  • Pruning: hunt duplication, sediment, and no-ops (the deletion test — the manual counterpart of the Binary Eval Assertions loop above).

Directly applicable as a lint rubric to this vault's own CLAUDE.md operations and the user's AIOS skill buildout.

2026-07-21 — Skill engineering as a discipline (AI Engineer WF 2026)

5 AI Engineering Trends That Non Engineers Should Know About (AI Daily Brief) surfaces the community consensus at WF 2026 that skill work is now its own discipline, not a subset of prompt or software engineering — see the dedicated Skill Engineering page. Five named speaker anchors at the event (Paul Backus / Impeccable, Andrew Q / Vercel, Roland Gavrilescu / Introspection, Philip Schmidt / Google DeepMind, Garry Tan / YC) converge on the framing. Tan's closing keynote: skill engineering is "fundamentally integral to being an actual AI-native organization".

Key operational implication for this vault's skills (/ingest, /query, /lint, /journal, /crm): Tyler Brown's rule from the event — "each time there's a new model release, revisit and re-implement your skills; you have a kid growing from middle school to high school — you have to change the curriculum for them to get the benefits of the new model". Skills authored for one model regime silently under- or over-instrument the next one; a skill-review-per-model-release cycle is the operational answer. Concrete example: Shihipar's Claude Code 80% system-prompt reduction for Fable-class models (recorded above) is exactly this pattern at Anthropic's own scale.

The largest visible enterprise skill catalogue as of mid-2026 is Uber's 2,500+ agent skills built during the Agentic Pods programme — proof-of-scale that skill engineering as discipline is operational at 30,000+ employee enterprise size.

Cross-links