Where intelligence lives

A capable model may know FastAPI. It does not automatically know how your team ships a production FastAPI service.

Ask for a service once and a prompt is enough. Ask every week and the prompt grows: directory layout, configuration rules, health endpoints, logging, migrations, tests, deployment conventions, prohibited dependencies, and the definition of done. The prompt becomes a procedure copied between conversations.

That repetition is the signal. A skill moves durable procedure out of an individual's prompt history and into an inspectable package. The model still reasons. The package supplies the local method.

Before and after

The reason to create a skill is not that instructions are long. It is that a method deserves an owner, a boundary, and repeated use.

The conversion test

A repeated prompt is a candidate, not an automatic skill. Convert it when the work has a recognizable trigger, a stable method, a meaningful quality bar, and enough variation to require reasoning. If the same inputs always produce the same outputs, ordinary code may be the better home.

A prompt is an instruction in a moment. A skill is a maintained way of working across moments.

The line is architectural, not syntactic. A markdown file does not become a skill because it has frontmatter. A useful skill has discovery metadata, scoped instructions, a workflow, and a quality contract. It may also carry examples, scripts, references, and templates.

When does it become an agent?

A skill remains subordinate to the agent that selected it. It describes how to perform a class of work. An independent agent owns a goal, chooses among capabilities, maintains execution state, and can decide what to do next. The more autonomy, state, delegation, and open-ended planning a package owns, the closer it is to an agentic subsystem.

The useful distinction is who owns the objective. The agent owns the objective; the skill contributes a method.

Put the routing map in the skill file. Put the territory in supporting files.

pdf-review/
├── SKILL.md
├── examples/
│   ├── good-review.md
│   └── bad-review.md
├── scripts/
│   └── extract_tables.py
├── references/
│   └── review-rules.md
└── assets/
    └── report-template.md

What the frontmatter actually is

Strip away the illustrative names and a real SKILL.md starts with two YAML fields — nothing more exotic:

---
name: pdf-review
description: Reviews an existing PDF for citation integrity against its cited sources; does not create or edit PDFs. Use when a user asks to fact-check, audit, or verify claims in a PDF report against its citations.
---

name and description are the whole discovery contract. The description is written for the selector, not the reader — it states what the skill does and, just as importantly, what it does not do. Everything else in this chapter's "five questions" — sequence, resources, definition of done — lives in the body text below the frontmatter, not in more YAML fields.

What should not go in SKILL.md

Do not turn the entry file into a warehouse. Large domain references crowd out the task. Executable logic becomes harder to test when expressed as prose. Secrets do not belong anywhere in the package. Volatile business state should live in a system designed to own state.

A good entry file answers five questions quickly: when should I use this, what do I need, what sequence should I follow, which resources should I load, and how do I know I am done?

Skills are not one-pass text expansion. They can prescribe an interactive, resumable workflow.

Pause is part of the procedure

If the application omits income, jurisdiction, or consent, a good mortgage-review skill does not hallucinate prerequisites. It identifies the missing decision-critical inputs, asks for them together, and resumes from a named stage. The conversation is part of execution, not a failure to execute.

Resumption requires explicit state. At minimum, retain the task, selected skill version, completed stage, validated inputs, outstanding questions, tool side effects, and evidence collected. Do not hide consequential state inside an ever-growing transcript and call it a workflow engine.

The skill explains how. The tool performs an operation. Confusing them produces either vague tools or brittle skills.

“Create a Jira incident”

The tool might expose create_issue(fields). It should validate the transport-level shape and return a clear result. The skill defines the severity rubric, naming convention, required evidence, escalation policy, duplicate check, and completion criteria. The agent decides that this situation warrants the incident workflow and gathers what it needs.

If severity policy lives only inside the tool, every other incident interface must duplicate it or call an operation merely to understand it. If issue creation lives as prose in the skill, the agent is forced to imitate deterministic application behavior. Keep policy, procedure, and execution visible as separate ownership decisions.

A tool can succeed while the task fails. “Issue created” says nothing about whether it was the right issue.

MCP standardizes access to capabilities. It does not decide the domain procedure for using them.

Several diagrams can all be correct because they answer different deployment questions. The important choices are where tool discovery happens, who holds credentials, which layer enforces policy, and whether the skill names a concrete provider or a capability.

Prefer capabilities over brands

“Create the approved incident record” is more durable than “call Jira tool X” when the organization may change systems. A gateway or router can resolve that capability to Jira today and another service later. But abstraction is not free: provider-specific behavior, errors, and permissions still need an owner.

The domain gateway pattern

For consequential enterprise work, a domain gateway can combine internal rules, external MCP servers, APIs, and deterministic validation behind one governed boundary. The skill teaches the review procedure; the gateway supplies controlled domain operations. This keeps the skill readable without scattering business enforcement across prompt text.

“Skill” names a packaging layer, not one implementation shape.

Eight shapes

A real package can combine types. Name its dominant job anyway. That classification clarifies what to evaluate: advice quality, state transitions, tool accuracy, transformation fidelity, or routing.

Composition is valuable when it exposes real sub-problems. It is dangerous when it only moves confusion down a level.

build-feature
├── understand-repo
├── design-change
├── implement
├── test
└── review

Can skills call skills? In many harnesses, the agent selects and loads another skill rather than one file literally invoking another. Architecturally, the distinction matters: the agent remains the execution owner, even when an orchestration skill recommends specialized capabilities.

Three composition rules

1. One owner: one agent or orchestration layer owns the top-level outcome and reports completion.
2. Bounded depth: prefer a shallow graph. Two visible layers are usually easier to debug than an elegant recursive tree.
3. Explicit contracts: each child receives named inputs and returns a defined artifact or status—not an unstructured transcript.

Composition should reduce context and sharpen ownership. If the parent must load every child in full before doing anything, the package graph is organizational theater.

A hundred available skills should not mean a hundred instruction files in every conversation.

Discovery metadata should be small but discriminative. In practice this is usually just two fields — a name and a description written for the selector, not the reader — with trigger language, exclusions, and dependencies folded into that description rather than broken into their own fields. Some systems layer on permission or cost signals for scoring. The selection stage needs enough information to distinguish candidates without importing their procedures.

After selection, load the complete skill instructions. Then follow their routing guidance to open only relevant references, examples, or scripts. This is progressive disclosure: the system spends context when the next decision justifies it.

Selection errors are retrieval errors

Overlapping descriptions create ambiguity before execution begins. “Helps with documents” is weak metadata. “Reviews an existing PDF for citation integrity; does not create or edit PDFs” gives the selector useful boundaries.

Measure both false negatives and false positives. A skill never selected cannot help; a broad skill selected everywhere becomes ambient instruction pollution.

Not everything reusable needs to become a skill.

The decision table

These are not mutually exclusive boxes. A skill may retrieve policy through RAG, call a tool over MCP, run deterministic code, and update a system of record. The table tells you who should own each responsibility.

Most bad skill systems begin as reasonable local optimizations.

Eight anti-patterns

The repair pattern

For each anti-pattern, restore ownership. Move exact computation into code, mutable facts into a system of record, external access into tools, large knowledge into retrievable references, secrets into credential infrastructure, and cross-domain decisions back to the agent or a governed router.

A green tool response is only one checkpoint in a much longer causal chain.

Failure is broader than exceptions

Cover stale instructions, conflicting instructions, hallucinated prerequisites, missing permissions, partial execution, retry storms, duplicate side effects, ambiguous completion, and evidence that no longer supports the decision. Some failures throw errors. The dangerous ones return plausible success.

Design for recovery

• Give side-effecting operations idempotency keys or a reliable duplicate check.
• Record checkpoints only after their required evidence is durable.
• Separate retryable transport failure from a rejected business decision.
• Verify the postcondition in the system of record, not only the tool response.
• Make partial completion and uncertainty visible to both agent and user.

In production, a skill is a versioned execution unit—not invisible prompt text.

skill: mortgage-review
version: 2.3.1
owner: lending-risk
dependencies: [document-extract, rules-gateway]
permissions: [documents:read, decisions:write]
compatible_tools: [extract.v2, rules.v4]
evaluation_suite: mortgage-review-golden-v6

A registry makes discovery governable. Version pins make runs reproducible. Owners make stale policy actionable. Dependency and permission metadata allow the harness to reject an impossible or unsafe run before loading the procedure.

Observe the execution, not private reasoning

skill.candidates_found
skill.selected        {name, version, selector_score}
skill.loaded          {references, token_cost}
skill.step.started    {step, attempt}
user.clarification    {fields_requested}
tool.called           {tool, operation, idempotency_key}
tool.failed           {class, retryable}
skill.completed       {duration, outcome_id}
outcome.verified      {system_of_record, status}

Telemetry should explain selection, procedure, external actions, latency, failure, and outcome without logging secrets or private chain-of-thought. Correlation IDs connect the user request, skill run, tool calls, and real-world result.

Production also needs rollout and rollback. A new skill version should face a representative evaluation suite, run in shadow or limited traffic where appropriate, and remain attributable after deployment.

A polished final answer can hide a selection failure, a procedure failure, or a real-world failure — and even a correct one can be too expensive to keep running.

Four lenses, not one

Keep these datasets separate. Selection tests need positive, negative, and confusing neighbor requests. Execution tests need controlled tools, missing inputs, permission errors, stale references, and interrupted runs. Outcome tests need domain judgments or verified postconditions.

Useful measures

Selection precisionSelection recallStep accuracyTool-call accuracyCompletion rateRecovery rateClarification qualityToken overheadLatencyOutcome quality

A clarification rate is not inherently good or bad. Too low may mean invented inputs; too high may mean the skill cannot exploit available context. Read metrics together and inspect the failures they aggregate.

Start where failure is cheap. Add tools, state, and policy only when the problem requires them.

Try level one right now

Level one needs nothing beyond a text file. Save this as .claude/skills/commit-message/SKILL.md in a repository and it is a working skill:

---
name: commit-message
description: Writes a git commit message from a diff, following this repo's conventional-commit style. Use when the user asks for a commit message or asks to commit staged changes.
---

Read the staged diff. Write one commit message:

- Summary line: type(scope): imperative, present tense, under 72 characters.
- Body only if the diff needs explanation a reviewer wouldn't get from the
  diff alone — the why, not a restatement of the what.
- No period on the summary line. No filler like "this commit".

If the diff mixes unrelated changes, say so instead of writing one message
that papers over two.

That is the whole package: a trigger and a boundary in the frontmatter, a method in the body. No examples/, scripts/, or references/ yet — those earn their place once the same procedure needs calibration cases, deterministic checks, or knowledge too large to keep in the entry file.

The build loop

Collect real tasks. Identify the repeated method. Draw the responsibility boundaries. Write the smallest entry file that routes the work. Move bulk knowledge, examples, code, and templates into their own homes. Test selection before polishing execution. Add failure cases before adding more features.

The maturity of a skill is not the number of files it contains. It is how clearly the package owns a method while respecting the systems around it.

Trace one mortgage review from sentence to decision, and annotate every handoff.

User request
    │ application + consent reference
    ▼
Agent ── discovers and selects mortgage-review@2.3.1
    │ validated task context
    ▼
Skill ── procedure, missing-input gates, evidence contract
    │ capability requests
    ├───────────────┐
    ▼               ▼
Rules MCP       Document tool
    │               │
 regulations    extracted fields + provenance
    └───────┬───────┘
            ▼
  Deterministic validators
            │ pass/fail + exact reasons
            ▼
       Agent reasoning
            │ cited evidence + bounded judgment
            ▼
 Decision system of record

Annotate the arrows

Who owns state?

The conversation may display progress, but it should not be the sole system of record. The harness owns run state. External systems own their domain state. The registry owns skill identity and version. Credential infrastructure owns authentication. Logs own operational events. The final decision store owns the business outcome.

Where reasoning should stop

Use the model for interpreting ambiguous evidence, applying a bounded rubric, and explaining a decision. Do not use it for exact arithmetic, authorization, idempotency, identity matching, mandatory compliance gates, or persistence guarantees. The best agent architecture is not the one with the most intelligence in the model. It is the one that places each kind of intelligence where it can be governed.