Agent skills: packaging repeatable expertise so agents stop improvising

Tools, skills and instructions

Three things get confused because they all end up in an agent's context. It is worth keeping them apart:

• A tool is a capability: a typed operation the agent can invoke, like erp.post_invoice. It is code.
• A skill is a procedure: how your company handles a recurring situation, which tools it uses in what order, what the exceptions are, what "done" looks like. It is content, loaded when relevant.
• The instructions are the agent's standing identity and constraints, always present.

Teams that only have tools and instructions end up with enormous prompts that try to describe every procedure at once, and agents that improvise when a case does not match. Skills are how you stop that.

What a skill contains

A skill is a short document with a name, a description of when it applies, and the procedure itself. The description matters as much as the body: it is what lets the agent decide the skill is relevant. Vague descriptions produce skills that never load or load at the wrong time.

name: supplier-credit-note
when: an incoming document is a credit note from a supplier,
      or an invoice that references an earlier invoice number
procedure:
  1. Match to the original invoice by supplier and invoice number.
  2. If the original was already posted, create an offset draft.
  3. If it was not posted, cancel the draft and note the reason.
  4. Credit notes above the approval threshold always go to review.
exceptions:
  - Multiple originals: never guess, escalate with both candidates.
  - Currency differs from the original: escalate.

Notice what is not in it: no model instructions, no personality, no restating of permissions. Skills describe the work, not the agent.

Why not put all of this in the prompt?

Three reasons, in increasing order of importance.

Context cost. Twenty procedures in one prompt means paying for twenty procedures on every request, including the nineteen that are irrelevant.

Interference. Procedures that are all present at once bleed into each other. The credit-note rule leaks into ordinary invoice handling, and you debug it by nudging wording, which breaks something else.

Ownership. A prompt is an engineering artefact. A skill can be reviewed, corrected and approved by the person who actually owns the process. When the finance lead says "we changed the threshold", that is a one-line edit to a document with a version history, not a ticket for the AI team.

Version them like code, review them like policy

Skills live in version control, go through review, and carry a changelog. The reviewer is not only an engineer: the process owner signs off on the procedure, because it is their procedure. Every change gets an entry in the evaluation set, so "we tightened the credit-note rule" is a measurable change rather than a hopeful one.

This matters more than it sounds. Most of the drift in a live agent system is not model drift, it is procedure drift: the business changed a rule in March and nobody told the system. Versioned skills with named owners are how that gets caught in review instead of in an audit.

Testing a skill

A skill is testable in a way a personality prompt is not, because it makes claims about specific cases. For each skill, keep a handful of real cases and assert the outcome:

• Cases the skill should handle end to end, with the expected result.
• Cases that should trigger each listed exception, with the expected escalation.
• Near-miss cases that should not load this skill at all, to catch over-broad descriptions.

That last category is the one people skip and the one that finds real bugs. A skill whose description is too generous will capture cases meant for another procedure, and the failure looks like the model being wrong rather than the routing being wrong.

When a skill should become a tool

If a procedure has no judgment in it, stop writing it as a skill and write it as code. A skill that says "call these three tools in this order, always" is a tool that has not been created yet. Deterministic sequences belong in a tool: they are cheaper, faster and cannot be done slightly differently on a bad day.

The reverse test is just as useful. If a tool keeps needing prose in the prompt to explain when to use it and what to do with the result, that prose is a skill trying to exist.

How many skills?

One per recurring situation that a new employee would need explained to them. In practice a mature back-office agent team runs on somewhere between five and twenty, most of them under a page. If a skill is growing past two pages, it is usually two skills, or it contains a procedure that should be a tool.

The payoff

Skills turn "the AI handled it differently this time" into a question with an answer: which skill applied, what version was it, who approved that version, and what did the evaluation set say when it changed. That traceability is what lets a company hand a real process to an agent team and still be able to explain, months later, why a particular case went the way it did. It is also the layer that changes most often in ongoing maintenance, which is why it is worth designing as a first-class artefact rather than as prompt text.

Frequently asked questions

Is a skill the same thing as a prompt template?

No. A template shapes how a single request is phrased. A skill is a durable description of a procedure: when it applies, which tools it uses, what the exceptions are, and what the finished state looks like. It is loaded only when relevant, versioned, and owned by the person who owns the process.

Who should write the skills?

The process owner writes the procedure, an engineer shapes it into the structure the agent can act on, and both review changes. Skills written entirely by engineers tend to miss the exceptions that make the process real; skills written entirely by process owners tend to omit the tool boundaries.

How do skills interact with permissions?

They do not grant anything. Permissions live on tools, so a skill can describe a procedure an agent is not allowed to complete, and the tool call will fail. That is intentional: the skill says what should happen, the permission model decides what can.