If you want to write great AI agent skills, you need a shared rubric — a checklist that tells you exactly what a skill should and shouldn't contain. Right now, most developers are stuck in what can only be called skill hell: downloading skills freely, piecing frameworks together, and never quite getting the results those skills promise. The fix isn't finding one more skill. It's understanding what makes a skill great in the first place. This guide gives you a four-part checklist — trigger, structure, steering, and pruning — that you can apply to any skill you write or download today.
What Is Skill Hell and Why Does It Matter?
A few years ago, developers suffered through tutorial hell, then framework hell (remember a new JavaScript framework every ten minutes?). Now we have skill hell. Skill hell is the state where you have access to hundreds of freely available agent skills, but no way to evaluate them. You can't tell a good skill from a bad one. You can't see how the pieces fit together. And so you keep adding skills, keep trying new ones, and never extract the value they promise.
This isn't just an individual problem. Organizations face it too. They have no framework for taking their standard operating procedures and turning them into something an agent can reliably execute. Without that, the productivity gains that skills can deliver remain out of reach.
The root cause is simple: there is no shared rubric for what makes a skill great. Until now.
How Do You Write Great AI Agent Skills?
The answer is a four-part checklist. Every skill you write or audit should pass through these four lenses:
- Trigger — How and when is the skill invoked?
- Structure — How is the skill internally composed?
- Steering — How do you get the agent to actually do what you want?
- Pruning — How do you make the skill as small and clean as possible?
Let's walk through each one in detail.
User Invoked vs Model Invoked Skills: Which Is Better?
Every skill can be invoked manually by the user — you communicate to the agent which skill to use and it reads the skill's markdown file into its context window. But skills can also be model invoked, meaning the agent reads a short description sitting in its context and decides on its own to pull in the full skill file.
That description acts as a context pointer: a lightweight signal in the agent's active context that points to a richer file it can retrieve on demand. If a skill has no such description exposed to the model, it is purely user invoked — invisible to the agent until the user explicitly calls it.
So which is better? Neither, cleanly. The tradeoff looks like this:
- Model invoked skills are flexible — the agent or the user can trigger them. But every model-invoked skill adds a description to the agent's context on every single request. With 100 model-invoked skills, that's 100 descriptions eating tokens and cluttering the agent's thinking on every call. It also introduces unpredictability: even a perfectly matched skill may simply not get invoked.
- User invoked skills keep context load minimal and remove a whole class of unpredictability. The tradeoff is higher cognitive load on the user — you need to know your skills well enough to call them at the right time.
The practical recommendation: prefer user-invoked skills where you want predictability and control, and be very selective about which skills earn model-invoked status. Don't let your agent's context become a crowded hallway of descriptions it may or may not act on.
How Should You Structure an AI Skill Internally?
Once you've decided on the trigger, think about the internal layout of the skill. Most skills are built from two units:
- Steps — The sequential procedure the agent walks through.
- Reference — Supporting information the steps rely on (templates, definitions, examples).
Some skills are pure reference. Some are pure steps. But most benefit from clearly separating these two units so the skill is easy to read, audit, and maintain.
Keep the Main Skill File as Small as Possible
Here's a critical constraint: the main skill.md file should be as small as possible. Smaller files are easier to maintain, easier to audit, and cheaper to run — every word you cut is a token you save on every invocation.
The most powerful way to shrink a skill file is to think about branches. A branch is a different path the skill might take depending on the situation. If a piece of reference material is only needed on one branch, it doesn't belong in the main file. Instead, hide it behind a context pointer — a line in the skill that says "if you need this template, go read this separate file." The agent can pull it in when relevant and ignore it otherwise.
For example, a skill that always produces one type of output needs all its reference material inline. But a skill that might create an architectural decision record or update a glossary or do neither? That skill has three branches, and the templates for each branch should live in separate files linked by context pointers — not all crammed into the main skill file.
How Do You Steer an AI Agent to Do What You Want?
This is where most skill writers struggle. You write the skill. You think you've been clear. The agent ignores it anyway. The fix usually comes down to two techniques: leading words and leg work management.
What Are Leading Words and Why Do They Work?
Leading words are terms that pack a large amount of meaning into a small space. When you embed a leading word in a skill, the agent repeats it back to itself in its reasoning traces and its outputs — and that repetition reinforces the behavior you want.
Consider a classic agent problem: coding layer by layer. Left to its own devices, an agent will build the entire database layer, then all the schemas, then all the API endpoints, then the frontend — rather than delivering something small and working first. You could write a paragraph explaining this. Or you could use the leading word "vertical slice."
Vertical slice is a well-understood concept in software development. By using it consistently throughout the skill, you activate the agent's prior knowledge of the term. You'll then see it appear in the agent's reasoning: "Okay, we're going to do this as a thin vertical slice." And the implementation plans improve accordingly.
The diagnostic test is simple: if you put a leading word in your skill and you see it echoed back in the agent's thinking tokens, it's working. If the agent isn't doing what you want, find stronger or more consistent leading words. English is a wide API — there are many candidates, and agents are actually quite good at helping you brainstorm them.
How to Manage Leg Work Per Step
The second steering technique is about how much effort the agent puts into each step. A classic failure mode: you have a planning skill with two phases — ask clarifying questions, then create a plan. The agent, seeing that its ultimate goal is the plan, rushes through the questions and jumps ahead.
The fix is to hide the future goal. Split the skill into separate skills — one for asking clarifying questions, one for creating the plan. When the agent only sees the current step, it has no reason to rush past it. It does the full leg work that step deserves. This isn't always necessary, but for high-stakes phases where you need depth, there is no substitute.
How Do You Prune and Optimize AI Skills?
Once a skill works, the final pass is pruning. Watch for these failure modes:
- Don't repeat yourself. Every concept should have a single source of truth. If the same idea appears in multiple places — across steps, across reference sections — consolidate it.
- Watch for sediment. When multiple people contribute to a shared skill file over time, it accumulates cruft. Old instructions, irrelevant additions, stale examples. Audit for structure first: is this content relevant to all branches? If not, move it or delete it.
- Kill no-ops. A no-op is content that appears to do something but doesn't actually change agent behavior. The deletion test is your friend: remove a section and see if the output changes. If it doesn't, the section was a no-op. Cut it.
The result of disciplined pruning is a skill that is small, focused, and predictable — exactly what you want.
The Full Checklist at a Glance
Run every skill you write or audit through these four checkpoints:
- Trigger: Is this user invoked or model invoked? Are you managing context load vs. cognitive load appropriately?
- Structure: Is the skill divided into steps and reference? Is branching reference material hidden behind context pointers to keep the main file lean?
- Steering: Are you using leading words consistently? Do your reasoning traces echo them back? Are any steps being rushed — and should you split the skill to force deeper leg work?
- Pruning: Have you eliminated repetition, sediment, and no-ops?
These four lenses won't just improve individual skills. They'll change how you read and evaluate every skill you encounter — which is exactly the skill that gets you out of skill hell for good.
