2.3 Skills¶

Maturity: Established (the packaging mechanism is shipping and stabilising; the "new paradigm" framing is contested) · Who decides: mostly your runtime (the model only picks which skill) · Grounding: research + companion repo · Last reviewed: 2026-06

A folder of procedural knowledge the runtime reveals to the model in stages, so the window holds only what the task needs. Installing one is a supply-chain decision: its instructions are followed and its scripts run.

1. Why you'd reach for it¶

A model often needs procedural knowledge that only some of its calls will use. Listing Studio's price step has to apply the supplier's minimum advertised price (MAP), the floor a contract forbids you to undercut, and the house margin rule. The ingest step never touches either. If you paste the pricing rules into the system prompt, every call pays for them in tokens and in attention, including the dozens of calls that never price anything. Multiply that across a house style, a category taxonomy, and a half-dozen multi-step workflows, and the prompt fills with reference material the current task does not need.

The convenience answer is to download a community skill that already packages those rules. But a Skill is not a passive document. A SKILL.md body is instructions the model will follow, and any bundled script executes with whatever authority you grant it.¹ Install a "helpful" skill without reading it and you have installed third-party code. Its markdown can carry injected instructions, where text inside fetched or loaded content reads to the model as a command rather than as data,³ and its script can read a secret or take a privileged action.⁴ The cost of skipping the audit is a supply-chain compromise, a defect introduced through a dependency you trusted by default.⁵

A benign skill can still fail you. A skill is pulled in by matching its description. Write a description that never triggers and you have stranded the whole capability: it sits in context doing nothing while still spending your token budget on its metadata.

The fix in miniature: package the knowledge as a Skill, a SKILL.md plus optional bundled files and scripts, and let the runtime reveal it in stages. The runtime keeps only a one-line description in context until the model decides the task needs the skill, then loads the body, then runs a bundled script only on demand. The pricing rules cost almost nothing until the price step actually prices something.

Reach for a Skill when:

You have reusable procedural knowledge or a workflow the model needs only sometimes, like the MAP and margin rules at the price step.
You want to package rules and a reference script together so they travel as one unit.
You want the same know-how to ride along across sessions without living permanently in the prompt.

The counter-trigger: do not reach for a Skill when the need is connectivity to a live system's tools or data over the wire. That is MCP, chapter 2.4. A Skill packages knowledge; an MCP server provides connectivity.⁶ And when the knowledge is small enough to live permanently in the prompt, leave it in the prompt; staged loading is overhead you do not need.

2. What it actually is¶

A Skill is a folder of procedural knowledge: a SKILL.md file with YAML name and description fields and a fuller instruction body, plus optional bundled files and executable scripts, that the runtime reveals to the model in stages.¹ Anthropic's framing for it is an onboarding guide for a new hire: the reference a capable worker reaches for to do a specific job well, not a rewrite of how the worker thinks.²

Most people meet a skill inside a coding tool such as Claude Code, Codex, or Cursor, where dropping a SKILL.md into a folder teaches the agent a new trick. That is where skills got famous, and it is where the easy misread starts: that a skill is a coding-tool convenience. It is a first-class primitive of agentic architecture. Every major model API now loads skills natively: Anthropic through the code-execution container, OpenAI on the hosted shell tool, and Gemini through Managed Agents, all shipped in 2026.¹⁷¹⁸¹⁹ The batteries-included agent frameworks build the same thing in.²⁰ Where MCP connects an agent to live tools and data, a skill hands it portable know-how; both are architecture, and the coding CLIs are just the most visible place skills appear.

Run the litmus test on it, the question this book sorts every pattern by: who makes the structural decision, the model or your code? On a Skill, your code does. A Skill is context engineering as packaging, where context engineering is the discipline of choosing what goes into the model's window and what stays out. Your runtime decides what to reveal and when. The only thing the model decides is which skill to pull in. The value there is real, but it is operational rather than architectural. A Skill is not a genuinely-new agentic pattern, and selling folders-of-markdown as a breakthrough overclaims it.

Maturity: Established overall, with parts moving at different speeds. The packaging mechanism is shipping and stabilising, and the parts that matter for building on it, the three-level loading model and the split between packaging knowledge and providing connectivity, are settling into accepted practice.¹² The SKILL.md format itself is trending toward Standard: it was open-sourced as the Agent Skills standard and is being adopted across tools beyond its origin.¹¹¹² Progressive disclosure as a context principle, the idea of loading context in stages, is older and stronger, and counts as Standard. What is still Emerging is the surrounding ecosystem: governance and versioning of the format, distribution and packaging conventions, and dependable audit and signing tooling for third-party skills, which is why the security burden in the Security & trust section falls on you rather than on the ecosystem. The framing that "Skills are a new paradigm" or the endgame is Contested: the word "skills" today lumps together markdown instructions, packaged code, and workflow orchestration that have little in common, and the durable win is routing plus context management more than smarter prompts.⁷⁸

A Skill is not an agent, and not a tool. It packages the workflow that may call tools (the call-execute-return contract from Tool Use), and it can teach the model how to drive an MCP server. Skills compose with tools and MCP; this is not a versus.

3. How to do it¶

Which path is right¶

You almost never write a skill's loading yourself. The decision that matters is who runs it for you, and there are three honest answers:

On a coding agent (Claude Code, Codex, Gemini CLI): drop the folder. Put the SKILL.md in the agent's skills directory and you are done; the harness discovers it, discloses it, and runs its scripts.
On an agent framework: let the framework own it. In LangChain, deepagents ships a SkillsMiddleware that does the three-level disclosure for you and stays model-agnostic, so you pass a folder path and the same skill runs under any tool-calling model.²⁰ Do not hand-roll it on bare create_agent.
On a raw model API: use the native skills parameter. Anthropic attaches skills to the code-execution container (container.skills), OpenAI mounts them on the hosted shell tool (environment.skills), and Gemini exposes them through Managed Agents. In each case the platform loads the metadata, discloses the body on demand, and runs bundled scripts in its own sandbox. (Disclosure here is not fully hands-off: on the Anthropic API you attach up to eight skills per request yourself, and any runtime lets you name a skill to force it.)

The one move to avoid is the one that looks easiest: flattening a skill into a single function tool with its whole body pasted into the system prompt. That makes the body always-resident, so progressive disclosure is gone, and it reinvents loading the runtime already ships for free.

Underneath, all three paths read the same open SKILL.md folder; the format is portable across every runtime above, and only the discloser differs, the vendor's infrastructure or your framework. Here is that shared mechanism unpacked, so you can reason about its cost even though you rarely write it.

Progressive disclosure loads context in stages so the window only ever holds what the current task needs. A Skill realises it at three levels. Rounded nodes are the model deciding, rectangles are your code or runtime deciding, the hexagon is the capability the skill packages:

flowchart LR
    L1["Level 1: name + description<br>always in the system prompt"] --> M("Model decides:<br>does the task need this skill?")
    M -- "yes" --> L2["Level 2: runtime loads<br>the SKILL.md body"]
    L2 --> R("Model follows the body,<br>asks to run a script")
    R --> L3["Level 3: runtime runs<br>the bundled script"]
    L3 --> CAP{{"script output<br>(not its source)<br>enters context"}}

Level 1 is the metadata: the name and description, always in the system prompt, tiny by design. Level 2 is the SKILL.md body, the full how-to, loaded only when the skill is triggered. Level 3 is a referenced file or script, read or executed only on demand, where the script's output enters context and its source never does.

Unpacked, that mechanism is two pieces. First, the Level-1 payload, the metadata that rides in the system prompt for every registered skill whether or not it is ever used:

@dataclass
class SkillMeta:
    """Level-1 payload — always in the system prompt.

    Tiny by design: the model reads name + description for every skill in the
    registry. The full body (Level 2) loads only when the skill is triggered.
    Everything that can be deferred, is deferred.
    """
    name: str          # YAML front-matter `name` field
    description: str   # YAML front-matter `description` field
    skill_dir: Path    # path to the skill bundle on disk

This is the place to be precise about how the model loads only some skills, because it is the part most people get wrong. The skill body is not in the prompt. What rides in the prompt is one line per installed skill: its name and its description, roughly a hundred tokens each, assembled into a single catalog the model can see on every call.⁹ Selection is the model reading those lines and choosing the one whose description matches the task. There is no router in front of it, no classifier, no embedding lookup, just the model reading text. A reverse-engineering of Claude Code's skills came to the same conclusion: the matching is the model reading descriptions, not a separate routing layer.¹⁰ When a description matches, the runtime loads that skill's Level-2 body from disk; the Level-3 scripts run only when the model asks for them.

The catalog itself is the entire selection surface, and the loader builds it from nothing but the names and descriptions:

def build_skill_catalog(metas: list[SkillMeta]) -> str:
    """Render the always-resident Level-1 catalog for the system prompt.

    Every installed skill contributes exactly one line — its name and its
    description — and nothing more. The body (Level 2) and script output
    (Level 3) stay off the context until a skill is triggered.

    This is what "selection is a catalog, not a router" means in practice:
    the model reads each line and matches the task to a description. There is
    no classifier, no embedding lookup, no routing logic — just text. The
    token budget grows linearly with the number of installed skills, which is
    the cost to keep in mind when the catalog gets large.
    """
    lines = [f"{m.name}: {m.description}" for m in metas]
    return "\n".join(lines)

The body is [f"{m.name}: {m.description}" for m in metas]: names and descriptions, nothing else.

The catalog is always resident, so every installed skill's metadata is paid for on every call whether the skill is used or not, and the catalog has a budget.
As the catalog grows the cost rises and the selection accuracy drops together, the same way an oversized tool list degrades tool choice (Tool Use): more descriptions to read, more chances to read the wrong one or none.
Some runtimes truncate or drop descriptions past a budget, which can make a skill undiscoverable even though it is installed. The runtime does not error; the docs surface it (a /doctor diagnostic, for instance), so you find out only if you go looking.⁹
The mitigations are to keep descriptions precise and keyword-first so they match on the words a task actually uses, to enable or disable skills so only the relevant set is resident, and to namespace skills so two similar ones stay distinguishable.

Second, the three load functions, one per level. The Level-3 function carries the failure-return contract: when a script errors, times out, or produces nothing, it returns a structured, recoverable message rather than a raw stack trace, and never reports a silent success.

def load_skill_meta(skill_dir: Path) -> SkillMeta:
    """Level 1 — parse only the YAML front matter from SKILL.md.

    Returns a SkillMeta without reading the body. Called at startup so that
    every registered skill contributes a tiny name+description token budget
    to the system prompt, regardless of whether it is ever triggered.
    """
    skill_md = skill_dir / "SKILL.md"
    raw = skill_md.read_text(encoding="utf-8")
    fm = _parse_front_matter(raw)
    return SkillMeta(
        name=fm["name"].strip(),
        description=fm["description"].strip(),
        skill_dir=skill_dir,
    )


def load_skill_body(meta: SkillMeta) -> str:
    """Level 2 — load the full SKILL.md body.

    Called only when the skill is triggered (the model chose this skill or
    the runtime matched a keyword). The body contains the detailed how-to
    instructions that fill the model's context for this task.
    """
    skill_md = meta.skill_dir / "SKILL.md"
    raw = skill_md.read_text(encoding="utf-8")
    # Strip the YAML front matter; return the markdown body.
    return _strip_front_matter(raw).strip()


def run_skill_script(
    meta: SkillMeta,
    script_name: str,
    args: list[str],
    timeout_seconds: float = 10.0,
) -> str:
    """Level 3 — run a bundled script and return its stdout as a string.

    The script's *output* enters the model's context, never the source.
    Any error (non-zero exit, timeout, malformed output) returns a
    structured, recoverable message — never a raw stack trace.

    Security: the script runs in an isolated subprocess with the arguments
    you supply. Never pass untrusted input as arguments without sanitising.
    Scope what the script can reach: it should read only what you give it
    and write nothing.
    """
    script_path = meta.skill_dir / script_name
    if not script_path.exists():
        return _script_error(
            script_name,
            f"script {script_name!r} not found in skill bundle",
        )

    try:
        result = subprocess.run(
            [sys.executable, str(script_path)] + args,
            capture_output=True,
            text=True,
            timeout=timeout_seconds,
        )
    except subprocess.TimeoutExpired:
        return _script_error(script_name, f"timed out after {timeout_seconds}s")
    except Exception as exc:
        return _script_error(script_name, f"failed to launch: {exc}")

    if result.returncode != 0:
        # The script itself returned a structured error (JSON); pass it through.
        stderr_hint = result.stderr.strip()[:200] if result.stderr else ""
        output = result.stdout.strip() or stderr_hint or "(no output)"
        return _script_error(script_name, f"exit {result.returncode}: {output}")

    output = result.stdout.strip()
    if not output:
        return _script_error(script_name, "script exited 0 but produced no output")

    return output

The SKILL.md itself is the unit a contributor ships. The format is YAML front matter (the Level-1 metadata) followed by a markdown body (Level 2), with a bundled-files section that points at the Level-3 scripts:

---
name: map-compliance
description: Validate a proposed price against the supplier MAP floor and gross-margin rules. Use when pricing or compliance checking is required.
---

# MAP Compliance Skill

A pricing analyst uses this skill to verify that a proposed listing price:

1. **Does not undercut the MAP floor.** ...
2. **Meets the margin floor.** Stockwell requires at least 20 % gross margin ...

## How to use this skill

Call the bundled `check_map.py` script with the SKU and proposed price:

    python check_map.py NV-ALDSWORTH-DM 41900

Here is that same skill attached the first-class way in each runtime. The LangGraph tab uses deepagents, the recommended framework path; the OpenAI Responses and Anthropic Messages tabs attach a skill you have uploaded, by its id. In all three the runtime owns the three levels, rather than your code wiring them through a tool loop.

LangGraphOpenAI Responses APIAnthropic Messages API

# Point deepagents at the skill folder. SkillsMiddleware (in the default stack
# when you pass `skills`) does progressive disclosure for you: it reads only
# name + description at startup, loads the SKILL.md body when the model triggers
# the skill, and runs a bundled script on demand — the same three levels, but
# owned by the harness, not hand-rolled, and portable across models.
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",   # or "openai:gpt-5.5" — same skill, any model
    skills=["skills/map_compliance"],
)

result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": (
            "Set a listed price for the Aldsworth Dual-Motor Sit-Stand Desk "
            "(SKU NV-ALDSWORTH-DM). Use the map-compliance skill to validate "
            "the price before confirming it."
        ),
    }]
})
print(result["messages"][-1].content)

# Native skills: mount the skill on the hosted shell tool. The platform adds the
# skill's name + description + path to context (Level 1), loads the SKILL.md body
# when the model triggers it (Level 2), and runs the bundled check_map.py inside
# its own container (Level 3). No function-tool wrapper, no local subprocess.
response = client.responses.create(
    model="gpt-5.5",
    tools=[{
        "type": "shell",
        "environment": {
            "type": "container_auto",
            "skills": [
                {"type": "skill_reference", "skill_id": MAP_COMPLIANCE_SKILL_ID},
            ],
        },
    }],
    input=(
        "Set a listed price for the Aldsworth Dual-Motor Sit-Stand Desk "
        "(SKU NV-ALDSWORTH-DM). Use the map-compliance skill to validate."
    ),
)
print(response.output_text)

# Native skills ride on the code-execution tool: attach the skill to the
# container and Claude discloses it progressively (name+description, then body,
# then it runs check_map.py inside Anthropic's sandbox). Up to 8 skills per
# request. Beta today, so the feature is gated behind beta headers.
reply = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    container={"skills": [
        {"type": "custom", "skill_id": MAP_COMPLIANCE_SKILL_ID, "version": "latest"},
    ]},
    messages=[{
        "role": "user",
        "content": (
            "Set a listed price for the Aldsworth Dual-Motor Sit-Stand Desk "
            "(SKU NV-ALDSWORTH-DM). Use the map-compliance skill to validate."
        ),
    }],
)
print(reply.content[-1].text if reply.content else "")

One run, at the price step, for the Aldsworth desk:

The MAP-compliance skill's Level-1 metadata sits in the system prompt at near-zero cost: a name and a one-line description, nothing more.
At the price step the model decides the task needs the compliance rules and triggers the skill.
The runtime loads the Level-2 SKILL.md body into context: the MAP and margin workflow, in full.
The model follows that workflow and asks to run the bundled check_map.py (Level 3) on a proposed price, say "I'll list it at $419.00, which I'll validate first."
The runtime executes the script in its sandbox and returns a structured result, the floor and a pass or fail, into context. The script's source never enters context, only its output.
The model reads the result and sets price_cents at or above the floor, at 41900, above the $399.00 MAP.

The runtime decided what to reveal at each level and ran the script; the model only decided that pricing was the task and which skill fit it.

From one skill to a library¶

The singular case is one skill the model can hardly miss. Production hits the plural fast, and the catalog cost above is the price of getting there: as the library grows, the always-on metadata budget grows with it and selection gets harder at the same time. The discipline that keeps a library workable is the same one the bullets named. Keep descriptions distinct and trigger-precise, so the model can tell two skills apart and knows when each applies. Treat the Level-1 metadata as a budget you spend deliberately rather than a free shelf you keep adding to, and disable the skills a given workload never needs. The principle underneath, that every token in the window costs both money and the model's attention, is the context economy, covered in Context Engineering; this chapter owns the Skills mechanism, 1.5 owns the principle.

In the companion repo. The MAP-compliance skill packages the floor and margin rules as a SKILL.md plus a check_map.py script. The price step pulls it in only when it sets price_cents. The script returns the floor and a pass or fail, never its own source.

4. Security & trust¶

Installing a skill is a supply-chain decision, and it is the part of this chapter most likely to cost you. A skill is untrusted code plus untrusted instructions. The SKILL.md body is followed as instructions the moment a task triggers the skill, and any bundled script runs with whatever authority your agent has. The fix is the same one you already apply to an open-source dependency: read it before you trust it. Audit the body for instructions you would not have written, and audit the scripts for what they read, write, and call over the network. Do both, because the body and the scripts are two separate ways in.¹

The body is a prompt-injection surface, the OWASP (Open Worldwide Application Security Project) LLM01 risk, where loaded text reads to the model as a command rather than as data.³ The scripts are an excessive-agency surface, the LLM06 risk: the more a script can reach, the more a single bad run costs.⁴ Scope what the scripts can touch to the least privilege that does the job, and keep the blast radius small, the way run_skill_script runs check_map.py in a subprocess with only the arguments you pass and a write-nothing contract. Gate the irreversible actions behind a person. The general machinery for that, allowlisting and blast-radius control and the human gate, lives in Guardrails & Safety and Human-in-the-Loop; the supply-chain class itself is the one OWASP names for installable capabilities.⁵

The uncomfortable part is that skills are unsafe by default. Today's default skill is unversioned, unsigned, unsandboxed, and unreviewed: you get a folder and the runtime's trust, with nothing between them. The risk is not hypothetical. A February 2026 security study of public skills reported that roughly one in seven scanned (about 13.4%) carried a critical issue, from prompt injection to data exfiltration.¹⁶ Treat that as a dated finding from one vendor's scan, not a fixed rate, but treat the direction as real: a marketplace of folders that execute with your permissions is exactly the surface attackers go for. Scanning and validation tooling exists, and running a skill through it before you install is worth the minute it takes. That tooling, and where the format is heading, is the next section.

When a script does fail, the failure has to come back structured and recoverable rather than as a raw stack trace or a silently swallowed success. The run_skill_script failure path does this: a missing script, a timeout, a non-zero exit, and an empty output all return a [skill-script-error] line the model can act on. Skip it and the agent loops on a dead script or proceeds on bad state.

5. Ecosystem & tooling¶

The packaging mechanism is settling, but the ecosystem around it, the standard, the distribution, and the signing, is still forming. Three parts are worth knowing before you build on it.

The format is becoming a real cross-vendor standard. The SKILL.md format was open-sourced in late 2025 as the open Agent Skills standard, with a published spec, and it is being adopted across tools well beyond its origin, including OpenAI Codex, Cursor, Gemini CLI, and Copilot.¹¹¹² What is not settled is the governance and a first-class version field, which is why a skill you install today still has no built-in way to tell you which revision you got.

Distribution is mostly convention. A skill ships as a folder, usually over git, and the internal default is a private repository with code review on the way in. Packaging and versioning are still left to convention rather than enforced by the format. Microsoft's Agent Package Manager (APM) is one contender for fixing that: a manifest plus a lockfile that pins each skill by content hash, so an install is reproducible and you can tell whether the bytes changed.¹³ The honest caveat is that APM is community-maintained, pre-1.0, and not a supported Microsoft product (the repository is hosted in the microsoft GitHub org), and you adopt it as you would any early open-source tool.

Safety validation and provenance are arriving alongside. Scanners now exist that check a skill for prompt-injection, data-exfiltration, excessive-agency, and supply-chain patterns before you install it. NVIDIA SkillSpector is one, open source, and it is the kind of tool the Security & trust finding above argues for running by default.¹⁴ Provenance is forming too: an NVIDIA-Verified skill carries a signed Skill Card attesting what it does.¹⁵ Both are Emerging, not yet standard.

From production. I have used NVIDIA SkillSpector to validate the safety of skills before installing them, and contributed a scanner rule for one of the exfiltration patterns it now checks. I have also used Microsoft APM to distribute skills internally. Neither is a settled standard yet, so I treat the scan and the lockfile as risk reduction, not as a reason to skip reading the skill.

6. Gotchas¶

The supply-chain and script-safety edges have their own section above, the catalog-budget and never-triggering edges are in the How section, and the "new paradigm" overclaim is the Contested half of the maturity line; these are the rest.

Validate a skill script's output before acting on it. A script's stdout enters context, so a poisoned or malformed result is a way to steer the agent even after you have audited the body. Validating that output against a schema before you act on it is a poisoning mitigation, covered in Structured Output.
A skill body can drift from the script it ships with. The body is followed as instructions while the bundled script runs as code, and nothing keeps the two in step. A SKILL.md that documents one flag set and a check_map.py that expects another will pass an audit of either file read alone, so read them together and pin the pair when you distribute.

7. In short¶

Use Skills to package procedural knowledge the model needs only sometimes, like the MAP and margin rules at the price step. They are an Established, practical mechanism, and progressive disclosure is the discipline that justifies them: keep the Level-1 catalog tight and the descriptions trigger-precise, because that catalog is the whole selection surface and there is no router behind it. The hard part is not authoring the folder, it is trusting one you did not write. Audit the body and the scripts before you deploy, scope what those scripts can reach, run a scanner over a third-party skill while the signing ecosystem is still Emerging, and make script failures structured and recoverable. A Skill packages knowledge; an MCP server provides connectivity; the two compose. And do not buy the "new paradigm" pitch.