I watched a talk by Matt Pocock about writing great skills for AI agents. He could not make it to the AI Engineer World's Fair in person, so he recorded the talk and shared it online. It is called The Missing Manual: How to Write Great Skills.
Source: The Missing Manual: How to Write Great Skills on YouTube
He starts with a problem he calls skill hell. There are many skills available now. You can download them, write your own, or copy from community repos. But it is hard to tell a good skill from a bad one. People try to stitch too many skills together and do not get the results the skills promise.
His fix is a simple checklist. It has four parts: the trigger, the structure, the steering, and the pruning.
1. The trigger
A skill can be invoked in two ways.
- User invoked: the user tells the agent to use it.
- Model invoked: the agent decides on its own to use it, based on the skill's description.
Model invoked skills sound better because the agent can use them automatically. But every model invoked skill adds load to the agent's context. If you have a hundred of them, the agent has to think about a hundred descriptions on every request. User invoked skills put the load on the user instead. You have to remember which skills exist and when to call them.
Matt prefers user invoked skills. He says they remove a kind of unpredictability. A model invoked skill might be perfect for the task and still not get picked. User invoked skills cost more brainpower, but they make the result more reliable.
2. The structure
A skill is made of two main parts:
- Steps: the procedure the agent should follow.
- Reference: supporting material that helps it follow those steps.
Some skills are mostly steps. Some are mostly reference. Most need both.
He gives an example of a skill that writes a product requirements document. It has three steps: find context, confirm test seams with the user, then write the PRD. The reference part includes a short explanation of test seams and a PRD template.
The main skill.md file should be as small as possible. If a piece of reference is only needed in one branch of the skill, move it behind a context pointer to a separate file. He calls this an external reference. This keeps the main skill short and saves tokens.
3. The steering
Steering is how you get the agent to actually do what the skill says.
Matt's main technique is leading words. These are short phrases that pack a lot of meaning. You repeat them in the skill, and the agent starts repeating them back in its reasoning. For example, if you want the agent to build a small working slice first instead of coding layer by layer, you use the leading words vertical slice. The agent will start saying things like "I will do this as a thin vertical slice" and behave accordingly.
Another steering problem is when the agent does not put enough effort into the current step because it is already thinking about the next step. Matt fixes this by splitting skills so the agent only sees one step at a time. For example, he has one skill called grill with docs that only asks clarifying questions. After that finishes, he runs a separate skill to write the PRD.
4. The pruning
Once a skill works, you prune it.
Matt lists three ways skills get bloated:
- Duplication: the same idea appears in more than one place. Every part of the skill should have a single source of truth.
- Sediment: people keep adding material but nobody deletes the old stuff. If something is irrelevant or stale, remove it.
- No-ops: text that looks important but does not actually change the agent's behavior. Matt suggests a deletion test: if you remove a paragraph and the agent still behaves the same, that paragraph is a no-op and should go.
My takeaway
The checklist is a useful lens. Before this talk, I would read a skill and think "this is fine" without knowing why. Now I can ask:
- Is the trigger right for the job?
- Are the steps and reference separated cleanly?
- Does it use leading words to steer the agent?
- Is anything duplicated, stale, or a no-op?
Matt also released a new skill called writing great skills in his skills repo. I have not tried it yet, but I plan to use it on the skills I already have. If you write or use skills often, it is worth checking out.