Skip to content
AI Engineer Guide.

concept · coding · intermediate · concept 22 of 30

Agent skills

0 of 30 complete

Why it matters

Useful procedures are longer than a prompt should carry and more specific than a general instruction. Copying them into every system prompt spends context on capabilities the task will not use. A skill splits the problem: a short description is always visible and the body loads only when relevant. That makes discovery the new failure mode, because the agent chooses from descriptions it did not write.

Mental model

It is a labelled drawer in a workshop: you see the labels and open one when needed. The metaphor breaks because the owner wrote the labels, and the agent decides which drawer matches the job from the label alone, without seeing what is inside.

How it works

One skill, three loading depthsInteractive
9 nodes · 3 branches
includedfilerootdirectoryvalidation gateruled out or rejected

Step 1 of 8

The catalogue is the whole context

Only names and descriptions are resident. That is also the budget: every installed skill charges its description on every turn, whether or not the task uses it.

root · current

Skill catalogue

At session start only the name and one-line description of every installed skill sit in context. The bodies do not: a skill is a folder the agent may open, not a prompt that is always present.

Root of the hierarchy

Step 1/8 · The catalogue is the whole context

Figure. A skill decomposed by when each part is loaded: one description line per skill, always visible in the catalogue; the body on invocation; a reference and a script only when a step needs them. The crossed branch is a skill whose description names no task, input or output, so nothing can select it.

What to notice. The skill, the request and the file names are an authored example; the page publishes no token counts, so no counts or bars are drawn. The hierarchy is containment, not load order: the edge chips carry the load depth (description at level 0, body at level 1, references and scripts at level 2), and each level enters context only when the level above is loaded. Omitted: installation, permissions and who reviewed the bundled script, which the page treats as supply-chain work rather than as part of the load path.

Text version

A skill catalogue drawn as a hierarchy. The root is the catalogue: descriptions only, always loaded. Under it is refund-review, an installed skill whose description is level 0 and always visible, and a rejected branch called code-helper whose description is 'helps with code' and which is never selected. Under refund-review, the SKILL.md body is level 1 and loads on invocation, with a pinned version v3 recorded per run. The body holds three children: a preconditions check asserted first (clean tree, toolchain installed), references/api.md opened at level 2 only by the step that needs it, and scripts/check.py executed at level 2 with pinned dependencies. Steps walk the catalogue, select on the description, load the body, assert preconditions, open the reference on demand, run the script as code, record the version and test a request that should not trigger the skill.

  1. Write the description as the trigger, naming the task, the inputs, the output and when not to use it.
  2. Keep the main instruction file short and move long references into files opened only when required.
  3. Include scripts for deterministic steps such as scaffolding or validation, with pinned dependencies.
  4. State the preconditions the skill assumes, such as a clean worktree or an installed toolchain.
  5. Version the skill and record which version a run used.
  6. Test invocation with paraphrased requests, including requests that should not trigger it.

Trade-offs

ChoiceGood forCostFails when
Skill with scriptsDeterministic and reusableSupply-chain review, runtime dependenciesScripts need credentials or network
Instructions onlyPortable and easy to reviewModel executes each step by handProcedure is long or error-prone
Few broad skillsLess choice, fewer misfiresCoarse behaviourTasks vary widely
Many narrow skillsPrecise behaviourSelection errors, maintenance loadDescriptions overlap
Trade-off mapInteractive

Good for

Deterministic and reusable

Cost

Supply-chain review, runtime dependencies

Fails when

Scripts need credentials or network

  1. Scripts need credentials or network
  2. Procedure is long or error-prone
  3. Tasks vary widely
  4. Descriptions overlap

Figure. Each choice with what it buys, what it costs, and the case where it loses.

What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.

Text version

Four trade-offs: Skill with scripts is good for Deterministic and reusable, costs Supply-chain review, runtime dependencies, and fails when Scripts need credentials or network. Instructions only is good for Portable and easy to review, costs Model executes each step by hand, and fails when Procedure is long or error-prone. Few broad skills is good for Less choice, fewer misfires, costs Coarse behaviour, and fails when Tasks vary widely. Many narrow skills is good for Precise behaviour, costs Selection errors, maintenance load, and fails when Descriptions overlap

Failure modes

  • Description collision. Two skills claim the same task and the agent picks the wrong one. Debug: log the selected skill and score each description against a set of paraphrases.
  • Skill rot. A script references a tool version the repository no longer uses. Debug: run each skill's scripts in CI against the current image.
  • Silent precondition failure. The skill assumes a clean tree and edits on top of uncommitted work. Debug: assert preconditions at invocation and fail loudly.

In production

Track invocation rate, failure rate and version per skill. Review skills like dependencies and pin the versions of anything their scripts install.

Common misconceptions

People think: Skills are just prompt snippets.

Actually: They carry files and executable scripts, so they need the same review as code.

People think: More skills means more capability.

Actually: Beyond a point, overlapping descriptions cause wrong selection and maintenance drag.

Interview angle

Explain progressive disclosure and treat the description as a retrieval key. A strong answer reviews bundled scripts as dependencies and names a selection failure with a measurement. A folder of prompts, with no discussion of invocation accuracy or versioning, is the weak answer.

Sources