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

Skill Checklist (Pocock)

skillsagentschecklistqualityclaude-codeframework

Skill Checklist (Pocock)

Matt Pocock's four-dimension rubric for auditing and improving agent skills — his answer to "skill hell" (no shared way to tell a good skill from a bad one). From Building Great Agent Skills (Matt Pocock, AI Engineer).

The four dimensions

1. Trigger — how the skill is invoked

Decide user-invoked vs model-invoked, and treat it as a cost tradeoff:

Model-invoked User-invoked
Mechanism Description sits in agent context; agent decides to open SKILL.md No context pointer; pilot invokes explicitly
Cost Context load — every description costs tokens on every request + one more thing for the agent to weigh Cognitive load — the pilot must know the skill set deeply
Failure mode Unpredictability: the agent "may just choose not to follow" the pointer → you end up eval-ing trigger reliability Skill never fires because the human forgot it exists

Pocock's own repo leans user-invoked (control, small context load); the rival superpowers repo leans model-invoked (flexibility). Neither is free.

2. Structure — steps + reference

Every skill decomposes into steps (the procedure) and reference (supporting material). Keep SKILL.md minimal. The branch rule: reference material needed on every path stays inline; material needed by only one branch moves behind a context pointer to a separate file bundled with the skill ("external reference").

3. Steering — getting the agent to actually do it

  • Leading Words — the headline technique; see its own page.
  • Leg-work splitting — when the agent under-invests in a step because it can see the ultimate goal (canonical case: plan mode's clarifying questions rushed to reach "make the plan"), split that step into its own skill that hides the future steps. One skill per phase; the agent only sees the phase it's in.

4. Pruning — keeping it small

Massive skills are a symptom. Watch for:

  • Duplication — every part of the skill gets a single source of truth, including across reference files.
  • Sediment — shared-doc decay: everyone adds, nobody feels brave enough to delete others' material. Fix via the structure pass (rebranch, kill stale material).
  • No-ops — instructions that don't change behavior in context (especially common when an agent wrote the skill). Detect with a deletion test: remove the paragraph; if behavior survives (e.g. "write a long detailed commit message" — the agent would anyway), it was a no-op.

Relation to the vault's existing skills thread

Skills (Claude Code) covers three construction paths (forward / reverse-engineer / self-improving). This checklist is the quality layer on top — usable as a lint rubric. The deletion test is the manual counterpart of Binary Eval Assertions-driven pruning; the trigger dimension formalizes what the vault's own CLAUDE.md does by routing operations behind explicit trigger phrases.

Pocock's codebase-side companion

Pocock's follow-up talk at the same conference — Software Fundamentals Matter More Than Ever (Matt Pocock, AI Engineer) — applies the same rubric shape to codebases rather than skills. Deep modules with simple interfaces are the codebase form of "small SKILL.md with reference behind context pointers." Ubiquitous Language is the codebase form of a well-defined skill's shared vocabulary. Design Concept (Brooks) is the shared-understanding-before-artifact discipline this rubric prescribes at the skill scale, applied at the plan/spec scale. Read the two together.

Cross-links