Every practitioner who leans on Claude Code eventually asks the same question: how do you encode a reusable methodology without paying a context tax on every session? The answer Anthropic ships is SKILL.md — and its economics are the reason it now travels across products.
What makes SKILL.md cheap to maintain even with large bundled companions?
SKILL.md stays cheap because of progressive disclosure: at initialization the agent loads only each skill's name and description into the system prompt, and defers the full instruction body plus any bundled scripts or reference files until a request actually matches that description. A SKILL.md carrying 2,000 words of reference material "costs almost nothing until you need it" .
Since December 18, 2025 the format is an open standard at agentskills.io, so one SKILL.md directory runs unchanged in Claude.ai, Claude Code, the Claude Agent SDK, and the Claude Developer Platform .
The current baseline is Claude Code v2.1.199 (July 2, 2026), which fixed stacked slash-skill invocations — the commands reference confirms up to six can be chained; v2.1.198 (July 1) made subagents background-by-default, and v2.1.197 (June 30) promoted Sonnet 5 to the default model .
Authoring a SKILL.md: frontmatter, body, and directory layout
A SKILL.md needs only two moving parts: YAML frontmatter and a markdown body. The frontmatter carries a name — which becomes the slash-command label, so name: deploy yields /deploy — and a description, which is the trigger phrase the model matches against a live request . Write the description as a concise intent statement ("Summarize uncommitted changes for review"), not a title; that string is what the agent scans at startup to decide whether to load the full instruction body .
Placement determines precedence. The same skill can live at four scopes, and higher tiers silently override lower ones — enterprise wins with no warning emitted :
| Tier | Location | Precedence |
|---|---|---|
| Enterprise | managed policy path | Highest — overrides all below |
| Personal | ~/.claude/skills/ | Above project |
| Project | .claude/skills/ | Above plugin |
| Plugin | bundled with a plugin | Lowest |
Custom commands were merged into skills, so .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md are equivalent — both register /deploy .
To ground instructions in live state, prefix any body line with a shell expansion. Anthropic's canonical summarize-changes getting-started example inlines !`git diff HEAD` before Claude reads the skill, so review reflects the actual working tree rather than a stale snapshot :
---
name: summarize-changes
description: Summarize uncommitted changes in the working tree for review
---
Review the following diff and summarize it for a reviewer:
!`git diff HEAD`
Companion files — style guides, error catalogs, architecture diagrams — sit alongside SKILL.md in the skill directory and load lazily. Reference them by relative path from the body; they do not count toward the name-plus-description cost paid at initialization, which is what keeps a heavily-documented skill cheap until it fires .
Translating daily practitioner competencies into SKILL.md entries
The recurring habits that make Claude Code reliable each day map cleanly onto discrete SKILL.md files. Anthropic documents five operational areas — codebase reconnaissance, planning, reusable knowledge, review, and delegation — and each becomes a named, version-controlled skill rather than a pasted prompt . The translation is mechanical once you know the pattern: the description carries the trigger phrasing, the body carries the method, and companion files carry the durable reference.
Codebase reconnaissance. Encode the onboarding questions Anthropic's common workflows start with — request an architecture overview, identify key data models, trace how authentication is handled, and answer "why is this function called?" . Ground the body in real paths with @ file and directory references so responses cite the actual tree, and set the description to match phrasing like "understand the codebase structure" or "explore the authentication flow" so it fires on those prompts.
PRD interviewing loop. In "5 Claude Code skills I use every single day," Matt Pocock splits planning into three separate SKILL.md files: a "grill me" skill that interviews the user and walks each branch of Fred Brooks' design tree, a "write a PRD" skill that verifies assertions against the repo and emits the result as a GitHub issue, and a "PRD to issues" skill that decomposes it into atomic tasks (video: Matt Pocock). He frames this as a correction to plan mode:
"Plan mode produces a plan document before shared understanding is reached," — Matt Pocock, in 5 Claude Code skills I use every single day.
Reusable knowledge layer. Split by volatility. Put durable facts — coding standards, library choices, review checklists — in CLAUDE.md, which is always loaded; put procedural methodology with dynamic context in SKILL.md, which loads only when triggered . Never duplicate the same instruction in both. That developers already encode recurring behavior in config is empirical: an arXiv study analyzed 253 CLAUDE.md manifests across 242 public repositories .
Diff review. A summarize-changes skill with a !`git diff HEAD` injection line grounds review in the live working tree. Complement it with the bundled /code-review skill, which reviews the current diff for correctness bugs and accepts --fix, rather than re-implementing that logic inside your own SKILL.md .
Delegation. Encode per-project subagent prompts with scoped tool access, then run /run-skill-generator once to auto-record the project launch recipe to .claude/skills/run-<name>/ . The run-verify-test loop becomes a single repeatable named invocation instead of a manual sequence.
Failure modes practitioners hit: precedence, description tuning, and chain depth
Most skill failures are silent, not loud. The four that recur — precedence collisions, description mismatch, CLAUDE.md/SKILL.md duplication, and chain overflow — share a symptom: the agent does something other than what you encoded, with no error logged. Skills resolve across four scopes (enterprise, personal at ~/.claude/skills/, project at .claude/skills/, and plugin) with enterprise > personal > project precedence . If an enterprise skill shares a name with yours, it wins and nothing warns you. Before naming a new skill, audit with ls ~/.claude/skills/ and confirm the enterprise namespace is clear.
Description mismatch is the next trap. If the model rarely auto-invokes a skill, the description field is not matching live requests — auto-invocation triggers only when the prompt matches that text . Confirm the body is correct first by running /skill-name explicitly, then iterate on wording. A description that is too specific and one that is too generic produce the identical failure, so tune the middle ground rather than adding detail.
Duplication between CLAUDE.md and SKILL.md causes inconsistent weighting across long sessions as context fills. Keep the boundary clean: CLAUDE.md owns durable facts — coding standards, architecture decisions — while SKILL.md owns procedural methodology whose body loads only when used . Audit for overlaps whenever a skill stops behaving predictably.
Finally, chain depth. Claude Code v2.1.199 (July 2, 2026) fixed stacked slash-skill invocations and the commands reference confirms up to six leading skills can chain in one prefix . Behavior past six is undefined and logs no error, so keep production chains at five or fewer and compose longer pipelines as nested calls inside the skill body. As Matt Pocock frames the underlying discipline, his skills are "a corrective to plan mode," which "produces a plan document before shared understanding is reached" — precision in the skill definition, not chain length, is what makes delegation reliable (video: Matt Pocock).
Going further with SKILL.md: MCP, event-driven automation, and portability
Once a skill body is precise, three extensions widen its reach without bloating it. The Model Context Protocol (MCP) lets a skill address external systems — Notion, Figma, Slack, Gmail, Outlook, issue trackers, and documentation servers such as Context7 — either by naming the target MCP server in frontmatter or calling it inline in the instruction body . That turns a "write a PRD" or "code-review" skill from a local text operation into one that reads live tickets and writes results back where the team works .
Lifecycle hooks handle the side effects a skill body should not carry. Deterministic shell commands or HTTP endpoints fire on SessionStart, UserPromptSubmit, PreToolUse, and PostToolUse events — reserve them for actions that must happen every time, such as linting after each edit or blocking writes to sensitive paths, not as a substitute for skill-level instruction .
Portability is the payoff of the December 18, 2025 open standard at agentskills.io: a .claude/skills/ directory drops into Claude.ai unchanged, configured under Profile → Settings → Capabilities on a paid Pro or Team plan (video: Kevin Stratvert). For naming and description phrasing, Agensi marketplace demand is a useful reference: code-reviewer, git-commit-writer at 65 installs, and pr-description-writer at 36 installs rank highest . The concrete takeaway: keep the SKILL.md body focused on judgment, push repeatable side effects into hooks, reach outward through MCP, and write the description as if a stranger will install it — because now they can.
Frequently asked questions
What is the difference between SKILL.md and CLAUDE.md?
CLAUDE.md loads in full at session start and stays in context throughout, which makes it the right place for durable facts — coding standards, preferred libraries, architecture decisions, and review checklists . SKILL.md instead uses progressive disclosure: only the name and description enter the system prompt at init, and the full body loads only when a request matches the description . Rule of thumb: CLAUDE.md is always-on context; SKILL.md is on-demand methodology that "costs almost nothing until you need it."
How does Claude Code decide when to auto-invoke a SKILL.md skill?
The model matches your live request against each skill's description field. If the description closely matches the intent of your prompt, Claude Code loads the full body and runs the skill; otherwise nothing loads . The practical workflow is to test the skill explicitly first with /skill-name to confirm the body works, then iterate on the description wording until automatic invocation triggers consistently. Vague descriptions are the most common reason a correct skill never fires.
Can I reuse the same SKILL.md in Claude.ai and Claude Code?
Yes. On December 18, 2025 the format was published as an open, portable standard at agentskills.io, so a single skill directory runs across Claude.ai, Claude Code, the Claude Agent SDK, and the Claude Developer Platform without modification . Two caveats: Skills on Claude.ai require a paid Pro or Team plan , and any bundled scripts may need path validation per environment.
What bundled skills does Claude Code ship with, and how do I disable them?
Bundled skills are available every session unless turned off, and include /code-review, /debug, /batch, /loop, /security-review, /run, /verify, /dataviz, and /claude-api . To remove all of them, set disableBundledSkills: true in settings.json. Note the scope: at enterprise scope this affects every user in the organization, so confirm intent before pushing that change.
How many SKILL.md entries can chain in a single slash invocation after v2.1.199?
Up to six leading skills can chain in a single slash prefix, per the commands reference . Claude Code v2.1.199, dated July 2, 2026, fixed a bug that prevented stacked slash-skill invocations from resolving correctly . Behavior past six is undefined in current docs, so keep production chains at five or fewer.
