Matt Pocock's Agent Skill Design Checklist: 4 Steps to Reliable Skills

Step 1: Decide How the Skill Is Invoked

Before writing a skill, ask who will invoke it. There are two invocation modes:

Model-invoked : The agent decides whether to call the skill based on its description. Pros: flexible. Cons: each added model-invoked skill adds its description to the agent's context, increasing token consumption and cognitive load. 100 model-invoked skills = 100 descriptions in the agent's head.

User-invoked : Only the user can trigger the skill by explicit input; the agent never sees the skill description. Pros: zero context pollution. Cons: users must remember skill names and usage.

Matt prefers user-invoked skills because model invocation adds unpredictability—the agent may skip a needed call or invoke one inappropriately. User invocation shifts cognitive load to the human but removes that uncertainty.

Recommendation : Make core, high-frequency skills model-invoked so the agent handles them automatically; make low-frequency, risk-sensitive, or precision-critical skills user-invoked. Don't dump everything into the agent.

Step 2: Build the Skill's Internal Structure

A skill consists of two core units:

Steps : the sequential procedure the skill executes.

References : auxiliary information that helps the skill complete its steps.

Example: Matt's "2 PRD" skill generates a Product Requirements Document. Steps: (1) find context, (2) confirm test cases with the user, (3) write the PRD. References: test-case说明 and a PRD template.

Keeping skill.md Small

Smaller skill files are easier to maintain, audit, and consume fewer tokens per invocation. The trick: hide branch-specific references behind context pointers.

If your skill has multiple branches (e.g., a "Domain Modeling" skill might update a glossary, create an Architecture Decision Record, or do nothing), the references needed for each branch should not all be stuffed into skill.md.

Move branch-only references into separate files and reference them via context pointers. The skill.md then retains only core steps and common references; branch content is loaded on demand.

Step 3: Control Agent Behavior with Guide Words

Matt considers this the highest-value technique in the talk.

Guide Words are compact terms that carry rich meaning. When placed in the skill text, the agent reuses them during reasoning, altering its behavior pattern.

Example: Agents tend to write code layer-by-layer (database → API → frontend). To make the agent work in vertical slices, instead of a long description, use the guide word "vertical slice". The agent's reasoning trace then shows: "We will proceed in a vertical slice manner."

Why it works: English itself is a broad API; guide words are the function names that invoke that API.

Testing Guide Word Effectiveness : Observe the agent's reasoning trace. If the guide word appears, it's working. If not, replace it with a stronger, more consistent term.

Hide Future Steps to Increase Commitment to the Current Step

Agents sometimes rush through a step because they're focused on the final goal. Matt's solution: split steps into separate skills.

Example: A "Planning Mode" skill had two steps—ask clarifying questions, then create a plan. The agent always skipped clarifying questions and jumped straight to planning. Matt extracted "ask clarifying questions" into a standalone "Document Review" skill. The agent now sees only one step at a time, increasing its investment in that step.

Step 4: Prune Redundancy

After writing a skill, do a thorough pruning pass. Matt identifies three common failure modes:

Duplication (DRY) : The same information appears in multiple places. Ensure each piece has a single authoritative source.

Sediment : In collaborative editing, everyone adds content but no one deletes. The skill accumulates material irrelevant to the current branch. Fix: inspect structure, move unrelated content to branch files, delete the rest.

No-ops : Sections that look like they do something but removing them doesn't change agent behavior. Test by deleting the section and observing whether the agent's behavior changes. If behavior is unchanged, it's a no-op—delete it.

Closing Summary

Matt Pocock's checklist condenses to four actions:

Trigger : Decide user-invoked vs. model-invoked; don't clutter context indiscriminately.

Structure : Split skills into steps and references; hide branch content behind pointers.

Guide : Replace verbose instructions with guide words; hide steps to boost agent commitment.

Prune : Remove duplication, sediment, and no-ops to keep skills minimal.

If you're writing skills, download Matt Pocock's "Writing Excellent Skills" skill from his skill library and run it against your own work—seeing it in action is the best test.