Part 1 Chapter 5 Last verified 2026-05-29 Fresh

Skills & Progressive Disclosure

A Skill is procedural knowledge you author once that loads only when relevant. Progressive disclosure is the payoff, the description is the load-bearing interface, and a Skill is ergonomics — not a security boundary.

Volatility: feature-surface

Tools compared: claude-codecross-tool

On this page

A Skill is just-in-time procedural knowledge
The description is the interface
Which mechanism — and what a Skill is not
Distribution and governance
Patterns
Quick reference
Practice

The previous chapter ended on the rule: the always-loaded file is for broadly-applicable facts, and everything else loads on demand. Skills are the cleanest realization of “everything else.” This chapter is entirely first-party — every claim is from Anthropic’s own docs and engineering blog. That makes it authoritative on what Skills are and do, but it is not independent evidence of efficacy; the chapter is tagged accordingly.

A Skill is just-in-time procedural knowledge

A Skill is “a directory containing a SKILL.md file that contains organized folders of instructions, scripts, and resources that give agents additional capabilities.” [Official] Equipping agents for the real world with Agent Skills · Anthropic (2025)T1-official original The framing is teach-once: it packages “your expertise into composable resources for Claude.” Equipping agents for the real world with Agent Skills · Anthropic (2025)T1-official original

The point of that packaging is the loading discipline. “Progressive disclosure is the core design principle that makes Agent Skills flexible and scalable,” Equipping agents for the real world with Agent Skills · Anthropic (2025)T1-official original and it runs at three levels: the name+description metadata is loaded “at startup and include[d] in the system prompt”; Agent Skills (overview) · AnthropicT1-official original the SKILL.md body is read “from the filesystem via bash. Only then does this content enter the context window”; Agent Skills (overview) · AnthropicT1-official original and bundled scripts “provide deterministic operations without consuming context.” Agent Skills (overview) · AnthropicT1-official original

This is the same principle as the instruction-layer budget, inverted: instead of fitting everything broadly-true into the window, you keep procedures out of the window until a task needs them.

The description is the interface

Because only the description loads at startup, it is the single highest-leverage authoring decision. The docs are explicit about the mechanism: “The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems,” [Official] Skill authoring best practices · AnthropicT1-official original and it is “critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills.” Skill authoring best practices · AnthropicT1-official original

A minimal SKILL.md — and the description that carries it Worked example

A real Skill is small — a directory with one SKILL.md:

---
name: cut-release
description: Use when cutting a release — runs the version bump, changelog, and git tag steps for this repo.
---

# Cut a release

1. Bump the version in `package.json` (semver; patch unless told otherwise).
2. Regenerate `CHANGELOG.md` from commits since the last tag.
3. Commit as `release: vX.Y.Z`, then `git tag vX.Y.Z`.
4. Stop and report the tag; do **not** push without confirmation.

Only the description is always loaded, so it carries the whole retrieval decision:

Weak: description: Release helper. — names a topic, not a trigger; the agent cannot tell when it applies, so it fires at random or never.
Strong: description: Use when cutting a release — runs the version bump, changelog, and git tag steps for this repo. — names the situation and the steps, so it is selected when relevant and stays quiet otherwise.

The body can be as long as the task needs; the description is the one line you actually engineer.

Which mechanism — and what a Skill is not

The recurring confusion is Skill vs. CLAUDE.md vs. tool vs. subagent. The hinge is crisp: reach for a Skill “when a section of CLAUDE.md has grown into a procedure rather than a fact.” [Official] Extend Claude with skills · AnthropicT1-official original Facts stay always-on; procedures become load-on-demand skills.

One correction matters for architects: a Skill shapes what the model sees and reaches for, but it is not a security boundary. The allowed-tools frontmatter “does not restrict which tools are available: every tool remains callable” Extend Claude with skills · AnthropicT1-official original — it is pre-approval, not a sandbox. And the SDK skills option is “a context filter, not a sandbox. Unlisted Skills are hidden from the model and rejected by the Skill tool, but their files remain on disk and are reachable through Read and Bash.” Agent Skills in the SDK · AnthropicT1-official original That frontmatter scoping is “not… applied when using Skills through the SDK” Agent Skills in the SDK · AnthropicT1-official original at all.

Distribution and governance

Skills are a filesystem-and-distribution story, not an API. Metadata is “discovered at startup from user and project directories; full content loaded when triggered.” Agent Skills in the SDK · AnthropicT1-official original Sharing scales by scope — “Skills can be distributed at different scopes depending on your audience” Extend Claude with skills · AnthropicT1-official original — from a committed repo, to a plugin (the anthropics/skills repo registers as one via “/plugin marketplace add anthropics/skills”, anthropics/skills: Public repository for Agent Skills · AnthropicT2-release-notes original each skill “self-contained in its own folder” anthropics/skills: Public repository for Agent Skills · AnthropicT2-release-notes original ), to a marketplace catalog “to discover and install these extensions without building them yourself,” Discover and install prebuilt plugins through marketplaces · AnthropicT1-official original to org-wide managed settings. On a name collision, “enterprise overrides personal, and personal overrides project.” Extend Claude with skills · AnthropicT1-official original

Patterns

Description-as-interface. Sketch: write the third-person description for retrieval, not prose. When to use: every skill. Skill authoring best practices · AnthropicT1-official original Mechanics: state specifically when the skill applies; the body holds the how. Remember: only the description is always loaded — a skill that doesn’t trigger is dead weight.

Procedure → Skill, fact → CLAUDE.md. Sketch: move grown procedures out of the always-loaded file. When to use: a CLAUDE.md section has become a multi-step how-to. Extend Claude with skills · AnthropicT1-official original Mechanics: extract it to a SKILL.md; leave only the broadly-true fact behind. Remember: facts paid every turn; procedures paid on relevance.

Filter is not a sandbox. Sketch: never rely on skill scoping for security. When to use: any time you think “hide it to block it.” Agent Skills in the SDK · AnthropicT1-official original Mechanics: control capability in the permission/sandbox layer; use skills only for ergonomics. Remember: files stay on disk; tools stay callable; the SDK ignores allowed-tools.

Distribute by scope. Sketch: match the sharing path to the audience. When to use: a library outgrows one project. Extend Claude with skills · AnthropicT1-official original Mechanics: commit → plugin → marketplace → managed settings; remember enterprise>personal>project on collisions. anthropics/skills: Public repository for Agent Skills · AnthropicT2-release-notes original Remember: governance is about what loads and from where, by filesystem and policy.

Quick reference

Skill = just-in-time procedural knowledge — a SKILL.md artifact, loaded on relevance.
Three levels: metadata at startup → body on relevance → scripts on demand (no context cost).
The description is the interface — author it as a retrieval problem.
Procedure → Skill; fact → CLAUDE.md.
Ergonomics, not a sandbox — scoping shapes what the model sees, not what’s possible.
Distribute by scope: commit → plugin → marketplace → managed settings (enterprise>personal>project).
First-party-only — authoritative on mechanism, not yet independently corroborated.

Practice

Exercise solutions

Solution ↑ Exercise

If you keep pasting the same multi-step instructions, it should be a Skill — that’s the docs’ own trigger (“a procedure rather than a fact”). A good description names the situation, not the mechanics: “Use when cutting a release — runs the version-bump, changelog, and tag steps for this repo” beats “Release helper.” Specificity drives both halves of retrieval: enough detail that it’s selected when relevant, and bounded enough that it doesn’t fire on unrelated tasks. If you can’t write a description that distinguishes it from neighboring skills, that’s a signal the skill’s scope is unclear.

Solution ↑ Exercise

The assumption is wrong on two counts. First, allowed-tools is a pre-approval list (tools the agent may use without prompting while the skill is active), and per the docs it “does not restrict which tools are available: every tool remains callable” — it never subtracts capability. Second, through the SDK the frontmatter is ignored entirely, and the skills option is “a context filter, not a sandbox” — unlisted content is hidden but “files remain on disk and are reachable through Read and Bash.” Real restriction lives in the permission/sandbox layer (deny rules, OS sandbox) covered in the guardrails chapter — not in a skill’s frontmatter.