The Missing Manual For Agent Skills

Many agent projects do not fail because the model is too weak.

They fail because the agent does not know when to use which knowledge, how to work, and which parts of its instruction actually shape behavior.

That sounds small. It is one of the most important architecture questions in agentic systems.

In his video "The Missing Manual: How to Write Great AI Skills", Matt Pocock describes this failure mode as a kind of Skill Hell: skills grow, repeat themselves, load too much context, steer too little behavior, and eventually make agents less predictable instead of more reliable.

The ag3nt.id reading is simple: skills are not documentation for humans. They are an operating interface for agents.

A Skill Is Not A Knowledge Store

The obvious mistake is to treat skills like small wikis.

Teams put everything into them that might become useful later: rules, examples, edge cases, references, reminders, exceptions, desired behavior, safety notes. It feels thorough. For an agent, it is often weight.

A good skill is not the place where everything lives.

A good skill is the place that moves the agent into the right action.

That is a different standard. Not: "Is the information complete?" But: "Does this information change behavior at the right moment?"

That question decides whether a skill is a tool or just context fog.

Trigger: Who Decides That A Skill Applies?

The first architecture point is the trigger.

A skill can be invoked explicitly by the user. Or the model can decide whether the skill fits the current context.

Both choices have costs.

A user-invoked skill is more predictable. But it puts the decision on the user: which skill is the right one now?

A model-invoked skill feels more elegant. It moves the decision to the agent. That reduces cognitive load for the user, but increases context load and risk: the agent can miss the right skill or load the wrong one.

Trigger design therefore becomes a product question.

Not every skill should automatically sit inside the model's search space. Some skills are better as clear commands. Others need to be model-invoked because users cannot know in advance that they are needed.

The discipline is to make that decision deliberately.

Structure: Keep SKILL.md Small

The second point is structure.

Pocock's recommendation is simple and strong: separate Steps from Reference.

The main skill should guide the flow. It should say which steps the agent runs, what it must watch for, and when it needs to load deeper material.

Reference material belongs behind it.

This is more than tidy file organization. It is context engineering.

If every branch, exception, and special case lives directly in the main file, the agent has to carry everything at once. That makes it more expensive, slower, and often worse. The skill becomes an overloaded checklist, not guidance.

A better pattern:

• SKILL.md contains the core flow.
• Specific variants live in separate references.
• The agent loads those references only when the concrete case requires them.
• The main skill stays small enough to actually steer behavior.

That makes a skill modular. Not because modularity looks nice, but because agents work with a limited attention budget.

Steering: Behavior Needs Leading Words

The third point is steering.

Many skill files describe desired behavior without really guiding the agent. They say, in effect: "Do this well, carefully, and sensibly." That sounds reasonable, but it is too soft.

Agents respond strongly to recognizable leading words.

These terms compress meaning. They give the model a stable handle for behavior: gather context first, then decide; verify the source first, then write; constrain scope first, then implement.

This is not magic prompting. It is operating semantics.

When a team uses the same terms consistently, it creates a small shared language between human, agent, and system. The agent does not have to infer from scratch what "thorough", "safe", or "done" means. The terms become behavior triggers.

Even more important: complex flows do not always need to be visible all at once.

If an agent jumps to the next step too early, it can make sense to hide future steps behind separate skills or references. The agent receives the next context only after the current phase is complete.

That is process design for thinking machines.

Pruning: Deletion Is Architecture Work

The fourth point is pruning.

Skills age.

They collect sediment: old rules, duplicate warnings, edge cases nobody needs anymore, sections that sound responsible but do not change behavior.

This is where deletion becomes serious agent work.

Pocock's deletion test is a useful standard: if a section can be removed and agent behavior does not get worse, that section was probably a no-op.

That is uncomfortable, because no-ops often look like responsibility.

But for agents, useless text is not neutral. It consumes context. It competes with important rules. It makes decisions more diffuse.

A maintained skill is therefore not the longest skill. It is the skill where every paragraph has a job.

The ag3nt.id Take

Agent skills are the new middle layer between model and operations.

They sit between:

• raw model capability
• company context
• tool access
• governance
• execution logic
• human expectation

Teams that write skills well are not just writing better prompts. They are building a reusable operations layer for agents.

This matters especially once agents do more than answer: touch repositories, triage tickets, analyze data, create documents, operate systems, prepare decisions.

At that point, "give the model more context" is not enough.

The context needs a shape.

Trigger, Structure, Steering, and Pruning are a useful frame:

• Trigger decides when a skill enters the run.
• Structure decides how much context is visible immediately.
• Steering decides which behavior is repeated reliably.
• Pruning decides whether the skill gets better or heavier over time.

Conclusion

The next agent phase will not be won by better models alone.

It will be won by better working surfaces for models.

Good skills do not make agents omniscient. They make them steerable, testable, and maintainable. That is their value.

A skill is finished when it no longer explains an impressive amount, but reliably triggers the right behavior.

Source: The Missing Manual: How to Write Great AI Skills by Matt Pocock / AI Engineer.