You installed twenty agent skills, and your agent got worse. The skills aren't broken individually. Nobody checked whether they trigger at the right time, fit together, or say anything the model didn't already know.
Developers have a gift for inventing new kinds of hell. First it was tutorial hell, then framework hell, where a new JavaScript framework shipped every other week. Now it's skill hell: hundreds of free skills one download away, and no way to tell a good one from a bad one before it's already in your agent's context.
Companies hit the same wall from the other side. They try to turn their runbooks and review standards into skills, and the agent follows maybe half of what's written.
What's missing is a shared rubric. We use four checks on every skill we write or adopt: trigger, structure, steering, and pruning. This post walks through each one, with examples, and ends with the checklist in a form you can paste into a review.
What is an agent skill?
An agent skill is a folder of instructions an agent loads when it needs them. The entry point is a SKILL.md file with YAML frontmatter, usually a name and a description, followed by a markdown body. Anything else in the folder (templates, reference docs, scripts) is a file the body can point to.
---
name: write-prd
description: Turn a conversation into a product requirements document. Use when someone asks for a PRD, a spec, or a requirements doc.
---
1. Gather the relevant context from the conversation and the codebase.
2. Confirm the testing approach with the user before writing anything.
3. Write the PRD using the template below.
...Claude Code, Codex, and other agents that follow the Agent Skills format all read this layout. The format is simple, which is exactly why it's easy to write a bad skill: nothing stops you.
1. Trigger: user-invoked or model-invoked skills
A user can always invoke a skill by name. The model can also invoke it, if the skill has a description.
That description sits in the agent's context on every request. It works as a context pointer: the agent reads it, decides the skill fits the task, and only then loads the full SKILL.md.
So the first decision is whether the model should be allowed to pick the skill up on its own. Neither answer is free.
Model-invoked skills cost context. Every description is sent with every request, and every one is another option the agent has to weigh. The Agent Skills spec allows descriptions up to 1,024 characters, which is roughly 250 tokens. Install 100 skills with long descriptions and you're spending something like 25,000 tokens per request before the agent has read your prompt.
User-invoked skills cost attention. Every skill you add is one more thing you have to remember exists, and understand well enough to call at the right moment.
Model invocation is also unpredictable. Any time one piece of context points at another, the model can decline to follow the pointer, even when the skill is a perfect fit. I've watched an agent write a blog post from scratch while a blog writing skill sat right there in its listing. The only way to catch this is to check whether your skills actually fire when they should.
Some teams accept that unpredictability in exchange for an agent that knows what to reach for. Others want full control and turn model invocation off for anything that matters. In Claude Code, that's one line of frontmatter:
---
name: release-notes
description: Draft release notes from merged PRs since the last tag.
disable-model-invocation: true
---Both choices are legitimate. The mistake is not choosing, and ending up with 60 model-invoked skills because that's the default.
2. Structure: steps, reference, and keeping SKILL.md small
Most skills are made of two kinds of content:
- Steps: the procedure the skill walks through.
- Reference: the material those steps need, like templates, definitions, and conventions.
A skill can be all steps or all reference. Still, sorting every paragraph into one of the two makes skills much easier to design.
Take the PRD skill above. It has three steps: gather context, confirm the testing approach with the user (a human-in-the-loop checkpoint), and write the document. Its reference material is a PRD template and a short explainer on test seams.
Branches decide what belongs in SKILL.md
Smaller skills are easier to audit and maintain, and every word you cut is a token you stop paying for on every run. The best tool for cutting is to think in branches: the different paths a single run of the skill can take.
If a piece of reference material is needed on every branch, it belongs in SKILL.md. The PRD skill has one path, and it always needs both the template and the explainer, so both stay inline.
Now take a domain-modeling skill that can update a glossary, write an architecture decision record (ADR), or do neither. Each template is only needed on its own branch, so each gets its own file:
domain-modeling/
├── SKILL.md # steps + "if you're updating the glossary, read glossary-template.md"
├── glossary-template.md
└── adr-template.mdSKILL.md carries one line per branch, along the lines of "if you need to write an ADR, read adr-template.md." The template ships with the skill but only enters context when that branch runs. Call it an external reference.
The rule of thumb: hide branch-specific reference material behind context pointers.
3. Steering: leading words that make agents follow instructions
You wrote clear instructions, and the agent ignored them. In our experience the most common cause is that the instruction is a sentence when it should be a word.
A leading word, from the German Leitwort, is a term that carries a lot of meaning in very few tokens. Martin Buber used the word for terms that recur through a biblical narrative and steer how you read it. In a skill, it works similarly: put the word in, and the agent repeats it in its reasoning and its output, and the repetition reinforces the behavior.
Here's a failure every agent user has seen. Give an agent a large feature and it builds layer by layer: the whole database layer, then every schema, then every endpoint, then the entire front end. Nothing runs end to end until the very last step.
You could write "don't code layer by layer, start with a small piece that works end to end." Or you could write vertical slice. Developers already use that term, so it activates everything the model already knows about the practice. Use it consistently through the skill, then read the reasoning traces.
If the agent starts saying "let's do this as a thin vertical slice first," the word is doing its job, and your implementation plans should get better with it.
If it doesn't show up, either use the word more consistently or find a stronger one. English is a very wide API, and agents are good at brainstorming candidates if you ask them for ten alternatives.
Splitting skills to get more leg work
Sometimes the agent understands the instruction fine and just doesn't put in the effort. On steps like "ask clarifying questions" or "explore the codebase," it does the minimum, because it can see the real goal waiting at the end of the skill.
Plan mode is the classic case. It has two steps: ask clarifying questions, then write a plan. In practice the agent asks two questions and sprints to the plan.
The fix is to split the phases into separate skills. The questioning skill only describes questioning. When it's done, you run the planning skill.
Because the agent can't see the next step, it gives the current one its full attention. You don't need to do this everywhere, but when you need one phase done thoroughly, nothing we have tried works as well.
4. Pruning: how to make a skill smaller
Once a skill works, prune it. A bloated skill almost always has one of three problems.
Duplication. Every fact should have one source of truth. A template or definition repeated across steps and reference files will eventually drift, and then the agent has two versions to choose from.
Sediment. When several people edit a shared markdown file, nobody feels brave enough to delete someone else's paragraph. Over time the file fills up with stale, irrelevant, or misplaced material.
Fix sediment with the structure check from section 2. For each addition, ask whether every branch needs it. If not, move it behind a context pointer. If no branch needs it, delete it.
No-ops. These are instructions that look useful and change nothing. They're especially common in skills an agent wrote for you. Run a deletion test: if you removed this paragraph, would the agent behave any differently?
"Write a long, detailed commit message" in an implementation skill is a typical no-op, because the agent was going to do that anyway. Delete it.
Checking skills across a team
The four checks above work for any skill and any agent. The harder part, once a team adopts them, is that the skill on your machine and the one on your colleague's machine stop being the same file. Someone prunes a skill, someone else is still running last month's copy, and the trigger you tested is no longer the trigger anyone's using.
That's the problem we built to11 for. Every change to a skill becomes a new version, and releasing it moves a label, like prod, that the whole team syncs from. One release, and everyone runs the same skill:
to11 skill store write-prd --dir ./write-prd --reason "Moved ADR template behind a context pointer"
to11 skill release write-prd # the only step anyone else sees
to11 skill sync # on every other machine: install what the label publishesstore writes a new version and installs it only on your machine, so you can test the pruned skill before anyone else gets it. release moves the label.
The trigger decision from section 1 also becomes something each developer controls in their own configuration instead of by deleting files:
projects:
- project: acme/platform
label: prod
skills:
noisy-skill: { disabled: true } # never delivered to this machine
careful-skill: { version: 4 } # held at v4 while you test v5For the steering and trigger checks, you need to see what the agent actually did, not what you hoped it did. to11 traces coding agent sessions, so you can check whether a skill was loaded on the tasks it was meant for, and whether your leading word shows up in the agent's reasoning.
The full skill review checklist
Paste this into your next skill review:
- Trigger: Is the skill user-invoked or model-invoked, and was that a deliberate choice? Are you paying in context, in attention, or in unpredictability? Have you checked that it fires when it should?
- Structure: Is every paragraph either a step or reference? Is branch-specific material behind a context pointer instead of inline in
SKILL.md? - Steering: Have you condensed key instructions into leading words, and do those words show up in the agent's reasoning? Should any phase be split into its own skill to get more effort out of it?
- Pruning: Have you removed duplication, sediment, and no-ops? Does every paragraph pass the deletion test?
Run it over your own skills first, then over every community skill before you install it. It's the fastest way to find out whether a skill does what its description claims. If you want the versioning and rollout side handled too, the to11 skills docs cover setting up a project and your first to11 skill sync.