Agent skills

Read these first

• The extensibility landscape

What you will know

• Write a skill that an agent loads and follows

  Keep the instructions scoped and deterministic enough that a reviewer can verify the expected behavior without relying on hidden author intent.

• Compare a skill with a tool on the same task and record which work belongs in each

  A tool performs an invocable operation; a skill supplies policy, workflow, or local conventions, and confusing them creates brittle prompts or unnecessary APIs.

• Bundle a script alongside instructions and have the agent use it

  The script must be executable in the target environment, with its inputs, outputs, permissions, and failure behavior made explicit.

• Show a skill firing on the right task

  Test both a positive trigger and plausible near-misses, because vague descriptions cause accidental activation and missed activation.

• Trace a skill’s instructions, references, and scripts through one agent run and identify the resulting behavior

  On-demand loading can hide stale files, conflicting guidance, or context-budget effects that are invisible from the final answer alone.

Chapters

1. 1

   A skill carries the procedure; the tool performs the act

   A skill is a folder of instructions, optionally with scripts and references, loaded when a task calls for it; it supplies policy and local convention the model applies itself, while a tool supplies an invocable operation. The dividing line: the skill states which environments need approval, the tool performs the release. Putting those rules in the tool's description instead looks stronger, but it sits in context every session and still only asks the model to comply. The two also change at different speeds — a rule inside a tool description moves only when someone ships a code release, while a skill is a file the people who own the rules can edit and review on their own cadence.

   Read chapter
2. 2

   A description that says what a skill contains never matches a request

   'Contains the team's database migration standards' never fires on 'add a nullable column to users', because it describes the cupboard rather than the occasion. The opposite error draws the boundary around a subject — 'anything relating to production incidents' — and hijacks requests to summarise a Slack thread. Test both directions: real requests that should fire, and the neighbouring tasks that must not. The source of those cases is the request log, not your imagination.

   Read chapter
3. 3

   Hidden author intent is the defect a reviewer cannot see

   Once a skill reliably fires, the body has to say what changes when it does. Write it so someone who did not author it can state, before running anything, what the agent will do differently from an unaided run. That means naming the action, the sequence and the exception rather than gesturing at a preference. A skill that reads well but leaves its expected behaviour in the author's head produces runs nobody can call correct or incorrect, which is where unreviewable skills come from.

   Read chapter
4. 4

   A bundled script is background until the body names the command

   Traces where the agent reads the instructions and then writes its own inline Python mean the body never gave it a command, arguments, the expected success output and the meaning of a non-zero exit. Fix that and a second defect remains: a mandatory check that dies on ModuleNotFoundError and lets the run continue anyway. Environment executability and failure handling are separate problems with separate evidence in a trace.

   Read chapter
5. 5

   A bundled reference is a fork that nothing recompiles

   Copy the auth docs into `reference/auth.md` and you have created a branch of them that no build breaks when the original changes. Because the file loads only on demand, the staleness surfaces as a confident answer using a flow deprecated six months ago. Trace one run end to end — which instructions, which references, which scripts entered context — and the drift becomes visible before a user finds it.

   Read chapter
6. 6

   Two skills loading at once can quietly contradict each other

   The trace shows which bodies entered context; it does not tell you what the agent did when more than one did. A migrations skill that forbids backfilling in the same statement and a data-repair skill that requires it produce a run defensible against either document alone, and a skill that contradicts a standing system-prompt instruction resolves however the model reads it — silently, with no error to attribute the outcome to. Give each skill a scope line saying what it does not govern, and decide in advance which source wins, because the moment one skill becomes several this is the normal case rather than the odd one.

   Read chapter
7. 7

   Six skills compete for the requests one skill used to win

   A 900-line `engineering-standards` skill loads migrations, on-call etiquette and the review checklist together whenever any of them is wanted, and no failure can be attributed to a specific rule. Splitting it is right and not free: six descriptions now contest overlapping requests, and boundaries between API design, testing and code review are not clean. Land a labelled set of real requests before the split, not after.

   Read chapter