video youtu.be Watch ↗

Building Great Agent Skills: The Missing Manual

TL;DR

A remotely-delivered AI Engineer talk (the speaker identifies himself as the author of the mattpocock/skills repo) argues the thing "missing" from the skills ecosystem is a shared rubric for telling a good skill from a bad one, and offers a four-part authoring checklist — Trigger → Structure → Steering → Pruning — to fill that gap and escape "skill hell." The load-bearing, and most novel, unit is steering by leading words: pack an idea into a short evocative phrase (his example: "vertical slice") repeated through the skill, and you can verify it worked by watching the agent echo the phrase back in its reasoning traces. The other pillars are each a concrete decision: choose user-invoked vs model-invoked deliberately, because model-invocation costs tokens-per-request plus unpredictability (the model may just not call it) while user-invocation costs the operator's memory (cognitive load) — "both have their same costs," so it is genuinely a trade, and he personally prefers user-invocation to avoid ever having to eval whether a skill fires; keep SKILL.md as small as possible by decomposing a skill into steps + reference and hiding branch-specific reference behind context pointers (progressive disclosure); increase "leg work" on an under-served step by splitting the skill so the agent sees one step at a time, hiding the future goal it would otherwise rush toward; and prune relentlessly against four failure modes — non-DRY duplication, "sediment" (shared-doc crud nobody dares delete), and "no-ops" (text that looks instructive but doesn't change behavior), caught with a deletion test (delete the passage; if behavior is unchanged it was a no-op). The whole thing is itself packaged as a runnable /writing-great-skills skill in his repo.

Concepts introduced

Skill Authoring Checklist — the four-pillar rubric (trigger / structure / steering / pruning) offered as the "missing" shared framework for judging and improving a skill.
Skill Invocation Trigger — the deliberate choice between user-invoked and model-invoked, and its trade: context load + unpredictability vs the operator's cognitive load.
Minimal Skill Surface — keep SKILL.md minimal by decomposing into steps + reference and hiding branch-specific reference behind context pointers (progressive disclosure).
Leading Words — steer by compressing an idea into a short evocative phrase the agent repeats back; verify via the reasoning traces.
Step Isolation — increase "leg work" on a neglected step by splitting the skill so the agent sees one step at a time, hiding the future goal.
Skill Pruning — the smallness discipline as failure-mode hunting: DRY, sediment, no-ops, and the deletion test.

Held, not dropped

"Skill hell" (and the tutorial-hell → framework-hell → skill-hell lineage). A vivid framing for the discovery/quality problem a rubric solves; held as rhetorical scaffolding, not minted as a page unless a second source treats "skill hell" as a named phenomenon.
"English is a wide API" / agents help you find leading words. A nice aside that natural language exposes many callable "functions" and the agent itself can brainstorm leading-word candidates; folded into Leading Words rather than given its own page.
Human-in-the-loop test-seam checkpoint inside /to-prd. A concrete instance of a confirmation gate mid-skill; held — spin out only if a source treats in-skill checkpoints as a general pattern (relates to existing supervision concepts).
Organization-level skill-building ("turn operating procedures into things an agent can do"). Named once as motivation; held as a candidate if a source develops org-scale skill authoring concretely.

Key claims

A skills ecosystem needs a shared rubric to distinguish good skills from bad; without one, users can't get the promised results ("skill hell"). observation — the talk's framing of the gap it fills. → Skill Authoring Checklist
Decide deliberately whether a skill is user-invoked or model-invoked — it is a genuine trade, not a strict win for either. principle → Skill Invocation Trigger
Every model-invoked skill adds a description to the agent's context on every request (token "context load") plus one more thing for the agent to weigh; 100 skills = 100 descriptions. (best practice) — context: managing a growing skill library where per-request context budget matters. → Skill Invocation Trigger
Model invocation buys unpredictability: even a perfectly-matched skill may just not be invoked, which forces you to eval whether skills fire at the right time — a class of problem the speaker prefers to remove by using user-invoked skills. (best practice) — context: an operator who values control/predictability and can absorb the cognitive load of remembering their skills. → Skill Invocation Trigger
Most skills decompose into two units — steps (the procedure) and reference (supporting material) — and thinking in these units makes skills easier to break down. (best practice) — context: authoring or refactoring a skill from scratch. → Minimal Skill Surface
Keep SKILL.md as small as possible: smaller skills are easier to maintain and audit, and every word shaved is a token shaved from every invocation. (best practice) — context: skills that recur in the token budget; "small" is instrumentally best, not an end in itself. → Minimal Skill Surface, Agentic Simplicity, Concise Prompting
Reference material used in only one branch of a multi-branch skill should be moved out behind a context pointer ("external reference"), not kept inline. (best practice) — context: skills with more than one usage path; single-branch skills keep their reference inline. → Minimal Skill Surface
Leading words — short, meaning-dense phrases repeated through a skill — steer agents because the agent re-emphasizes the word in its thinking and output, and that re-emphasis changes behavior. principle → Leading Words
You can confirm a leading word landed by watching it appear in the agent's reasoning traces; if the agent isn't complying, make leading words more consistent and more powerful, or find better ones. (best practice) — context: iterating on a skill's steering; presupposes access to reasoning/thinking traces. → Leading Words
Agents under-invest "leg work" in intermediate steps because they can see the ultimate goal and rush to it (classic case: plan mode's clarifying-questions phase). observation → Step Isolation
Splitting a multi-step skill so the agent sees one step at a time — hiding the future goal — reliably increases leg work on the current step. (best practice) — context: a step that genuinely needs deeper effort (exploration, clarifying questions); not every skill needs splitting. → Step Isolation
Massive skills are usually a symptom of another failure mode, not a root cause. observation → Skill Pruning
Give every part of a skill a single source of truth; don't repeat reference material across steps or places. (best practice) — context: any non-trivial skill; DRY applied to prose. → Skill Pruning
"Sediment" — irrelevant/stale accumulation in shared skill docs that nobody feels brave enough to delete — is a distinct bloat source; fix it by re-examining structure, relocating to the right branch, or killing stale content. observation → Skill Pruning
"No-ops" — passages that appear instructive but don't change agent behavior (common when an agent writes the skill) — are found with a deletion test: remove the passage; if behavior is unchanged, it was a no-op. principle → Skill Pruning
The speaker states his mattpocock/skills is "one of the most popular engineering skill sets," that a rival popular repo is called "superpowers" (primarily model-invoked), that a disable-model-invocation: true flag makes a skill user-only, and that the framework ships as a runnable /writing-great-skills skill in his repo. observation — external, groundable claims (repo popularity, the "superpowers" repo, the exact config key, the skill's existence); reproduced as the source's claims, flagged for a later grounding pass, not verified here. → Skill Invocation Trigger, Skill Authoring Checklist

Why this is novel (with corroboration underneath)

The dominant stance is novel: the vault's existing skill/loop cluster (Skill-Driven Loop Development, Reusable Workflow Library, Agentic Distribution) is about composing, distributing, and looping over skills — treating a skill as a validated unit. This talk opens a distinct, higher-resolution area the graph did not cover: the craft of authoring a single skill — how it's triggered, structured, steered, and pruned. Hence six new concept pages.

It corroborates the vault's minimalism spine from the skill-authoring angle: "make SKILL.md as small as possible / prune no-ops" is Agentic Simplicity and Concise Prompting ("say less, cut the redundant procedure") applied to skills, and the context-pointer / progressive-disclosure mechanism is Context Routing's "don't load what you weren't pointed to" at the intra-skill scale. Leading Words is the positive-steering counterpart to Negative Prompting (bound the action) — both are compact steering levers for a capable model. No stance here is contradicts; the talk extends rather than tensions the existing graph.

Illustrated walkthrough

This is a talking-head-over-full-screen-slides format, and the slides are minimalist white-text-on-black leading-word cards. (Fittingly, the talk's own slides practice the leading-words advice: one or two load-bearing words per card.)

t=00:08 (f0001) — Cold open, talking head in a book-lined room. He can't attend the World's Fair in person ("family matters"), so this is the talk he'd have given. Frames the problem lineage: tutorial hell → framework hell → now "skill hell" — a glut of freely downloadable skills with "no shared rubric" to tell good from bad, so people don't get the results the skills promise. Confesses skin in the game: his mattpocock/skills is "one of the most popular engineering skill sets," so he wants to help its users out of the hole.
t=02:34 (f0020) — The framework slide: 1. Trigger 2. Structure 3. Steering 4. Pruning. Trigger = how the skill is invoked; Structure = internal layout; Steering = how you get the skill to make the agent do what you want; Pruning = making it as small as possible. Pointer: it's all encoded in a /writing-great-skills skill you can run immediately.
t=04:08 (f0035) — Description → SKILL.md. The invocation mechanism: a skill's description always lands in the agent's context and acts as a context pointer — it points at the SKILL.md "where the meat is," which the agent reads into context only if it chooses to invoke. Progressive disclosure by construction. (See Minimal Skill Surface, Context Routing.)
t=05:10 (f0050) — Tip #1: "Decide if your skill is user-invoked or model-invoked." A model-invocable skill has a description the agent sees (and can auto-invoke). His grill-me skill sets disable-model-invocation: true, so its description shows only to the user — a user-invocable skill. The comparison target he keeps getting asked about is the "superpowers" skills repo, which is primarily model-invoked; his own are user-invoked "to stay in full control." (See Skill Invocation Trigger.)
t=08:04 (f0075) — /to-prd, the worked structure example: a skill built from steps (find context → confirm test seams with the user [a human-in-the-loop checkpoint] → write the PRD) plus reference (a "what is a test seam" note + a literal PRD markdown template). Because /to-prd has only one branch and always needs both references, they stay inline; his domain-modeling skill, with two-or-three branches, moves its templates out behind context pointers as "external references." (See Minimal Skill Surface.)
t=14:10 (f0110) — Vertical Slice → '…a thin vertical slice' → Better implementation plans. The steering centerpiece: instead of the verbose "don't code layer by layer, build a small slice first," use the leading word "vertical slice." It triggers the agent's prior, compresses paragraphs into a phrase, and — crucially — you know it worked because the reasoning trace starts saying "we'll do this as a thin vertical slice." (See Leading Words.)
t≈15:50–16:48 (no distinct slide sampled; read from transcript) The leg work lever: agents under-invest in intermediate steps (canonical case: plan mode's "ask clarifying questions" rushes because it can see the goal is "make a plan"). His fix — split it into a separate grill-with-docs skill so the agent only sees that one step, then hands off to /to-prd — "hides the future goal" and forces more leg work. (See Step Isolation.)
t=16:48 (f0130) — 4. Pruning. The failure-mode sweep: massive skills are a symptom; watch for non-DRY duplication (every part gets a single source of truth), sediment (shared-doc crud nobody deletes → fix by looking at structure, moving to the right branch, or killing stale content), and no-ops (a paragraph telling the agent to "write a long detailed commit message" it would write anyway — caught with a deletion test). (See Skill Pruning.)
t=20:06 (f0150) — mattpocock/skills → /writing-great-skills. The resource: download the skill, run it over your own — and over community skills — to check what you're pulling in is any good. Newsletter at aihero.dev; an "AI coding crash course" teased.