Skills

A skill is instructions an agent keeps on the shelf until it needs them, not text it carries into every turn. Anthropic’s own documentation draws that line directly against a system prompt: “Unlike prompts (conversation-level instructions for one-off tasks), Skills load on demand, so you don’t have to repeat the same guidance across conversations”[1]. The mechanism is progressive disclosure, which Anthropic documents in three stages: a skill’s name and description load at startup and stay in context; the body of its SKILL.md, the actual instructions, loads only when the skill is triggered; anything else it bundles (further reference files, scripts) costs nothing until it is read or run[1].

A skill differs from RAG in what gets fetched (RAG retrieves facts, a skill supplies a procedure) and from fine-tuning in where the knowledge lives: fine-tuning bakes a behavior into the weights, while a skill loads per request and can be edited or removed in seconds.

Choosing which skill to load, if any, is the level-5 decision here, the same shape as choosing a tool in single agent. Your code runs the lookup, appends the body, and can cap how many skills load before forcing an answer.

This page provides primary references and illustrative examples. The examples are scripted, not measured model runs; source references do not establish the correctness of every implementation or outcome.

"Is the DW-480 drain pump covered under warranty,
and for how long?"

def run(
    question: str,
    model: Model,
    embedder: Embedder | None,
    tracer: Tracer,
    *,
    registry: dict[str, Skill] = SKILLS,
    max_steps: int = MAX_STEPS,
    max_tokens: int = MAX_TOKENS,
) -> Answer:
    del embedder  # skills are loaded from the registry below, not retrieved from the corpus
    listing = _skill_list(registry)
    tracer.record(kind="code", decided_by="code", title="List skill descriptions (always in context)", detail=listing)
    system = (
        "Answer the question. These skills are available; each description says what it is for. "
        "Call load_skill with a skill's name if one of them applies before answering:\n" + listing
    )
    messages = [Message(role="system", content=system), Message(role="user", content=question)]

    loaded: list[str] = []
    tokens_used = 0
    for _ in range(max_steps):
        completion = model.complete(messages, tools=[LOAD_SKILL_TOOL], max_tokens=250)
        tokens_used += completion.tokens_in + completion.tokens_out

        if not completion.tool_calls:
            record_completion(tracer, decided_by="model", title="Model answers", completion=completion)
            return Answer(text=completion.text, citations=loaded)

        name = str(completion.tool_calls[0].arguments.get("name", ""))
        record_completion(tracer, decided_by="model", title="Model chooses a skill to load", completion=completion, detail=name)
        skill = registry.get(name)
        if skill is None:
            body = f"unknown skill: {name}"
        else:
            body = skill.body
            loaded.append(skill.name)
        tracer.record(kind="code", decided_by="code", title="Load the skill body into context", detail=body[:200])
        messages.append(Message(role="assistant", content=f"[loaded skill {name}]"))
        messages.append(Message(role="user", content=f"Skill '{name}' body:\n{body}"))

        if tokens_used >= max_tokens:
            reason = f"token budget reached: {tokens_used} >= {max_tokens}"
            final = force_final(messages, model, tracer, reason=reason, max_tokens=300)
            return Answer(text=final.text, citations=loaded)

    final = force_final(messages, model, tracer, reason=f"step cap reached: {max_steps} steps", max_tokens=300)
    return Answer(text=final.text, citations=loaded)

python -m examples.skills --model stub:scripted

Failure modes

Cost and latency

Illustrative, not measured: no result file exists for this technique yet, so every number below is a worked example. See docs/EVALS.md for how a real run is recorded and scored.

How to Evaluate It

skills does not do the site’s own question-answering task (there is no document, no question about it, and no citation to grade), so it is not part of the shared 60-question set, the same way embeddings_search and memory are not (see docs/EVALS.md). What would actually be measured is specific to this task: given a labeled set of questions and the skill each one should trigger, selection accuracy (did it load the right one, none when none applies, and not an extra one it never used) and the token cost actually spent against what always-loading every skill would have cost. scripts/eval_run.py knows skills and refuses to score it, printing that reason; no runner for the measures above exists yet.

Run it

Try it

1. Use it

   Find a project that ships an AGENTS.md, CLAUDE.md or a skills directory. Read one skill's body, not its description: does what it says match what the description promised?

2. Build it

   Run python -m examples.skills --model stub:scripted from the repo root: three descriptions sit in context, the model loads warranty-checklist, and answers from its three steps. Change the name it loads in SCRIPTED (examples/skills/__main__.py) to one that does not exist: the loader reports unknown skill as text, the model answers anyway, and skills loaded reads none.

3. Either lane

   Write two skill descriptions for a task you do regularly, worded so a person skimming them, not just a model, could tell which applies when. If you cannot tell them apart quickly, a model will not either.

4. Either lane

   Write a SKILL.md-shaped body, a numbered procedure rather than prose, for a measurement you would otherwise explain aloud: the ripple on a switching regulator, on the oscilloscope with its 20 MHz bandwidth limit on, never on a multimeter whose AC volts function stops below the frequencies that make the ripple. Could an engineer who never watched you do it follow it? That is the test of a skill.