What you will be able to do
- Explain how Skills differ from repeating the same instructions in each conversation
- Structure a Skill as modular files that load in stages through progressive disclosure
- Place a Skill in Claude Code and predict which one runs when names collide
- Enable Skills on the Claude API with the container parameter and the code execution tool
1.From repeated instructions to reusable Skills
A prompt is the obvious unit of reuse: write good instructions once and paste them in whenever you need them. The trouble is that pasted instructions last for one conversation and occupy the context window every time. Agent Skills handle reuse differently. A Skill is a reusable, filesystem-based resource that packages workflows, context and best practices, and Claude loads it on demand when a request calls for it.
The documentation lists three benefits: specialising Claude for domain tasks, reducing repetition (create once, use automatically), and composing capabilities by combining Skills for complex, multistep tasks. That last one is where modularity comes in. Rather than one large prompt that tries to cover every task, you build separate Skills, and Claude uses whichever ones are relevant. Anthropic provides pre-built Skills for PowerPoint, Excel, Word and PDF, and you can write your own custom Skills. Both kinds work the same way once they're available.
Sources1
2.Modular by design: progressive disclosure
A Skill is a directory. Its SKILL.md holds YAML frontmatter and the main instructions. Next to it can sit more instruction files (FORMS.md, REFERENCE.md), executable scripts, and resources such as schemas or templates. Each of these loads at a different time, so installing many Skills doesn't mean paying for all of their content up front.
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---The description matters most here. Claude compares each request against it to decide whether to trigger the Skill, so it has to say both what the Skill does and when to use it. A description like "Helps with PDF forms." covers what but not when. The sources below don't include a full rulebook for the name field. The only naming restrictions they give are Claude Code's reserved folder names, synced and anthropic-skills.
While authoring a custom Skill, a developer sets the frontmatter to name: claude-pdf-helper and description: "Helps with PDF forms." When Claude Code attempts to load the Skill, it is rejected. What is the most likely reason, based on the required field rules for SKILL.md?
Correct answer: A — The name contains the reserved word "claude," which is not permitted in a Skill's name field alongside "anthropic."
- A. Correct. SKILL.md name fields must contain only lowercase letters, numbers, and hyphens, and are explicitly barred from containing the reserved words "anthropic" or "claude." "claude-pdf-helper" violates that rule.
- B. Incorrect. Descriptions must simply be non-empty and no longer than 1,024 characters; there is no minimum character count requirement.
- C. Incorrect. There is no requirement for a version suffix in the name field; names just need to satisfy the character and reserved-word rules.
- D. Incorrect. Hyphens are an accepted character in the name field alongside lowercase letters and numbers; the rejection here is due to the reserved word, not the hyphen.
| Level | When loaded | Token cost | Content |
|---|---|---|---|
| Level 1: Metadata | Always (at startup) | ~100 tokens per Skill | name and description from YAML frontmatter |
| Level 2: Instructions | When Skill is triggered | Under 5k tokens | SKILL.md body with instructions and guidance |
| Level 3+: Resources | As needed | None until accessed | Bundled files; scripts run through bash and only their output enters context |
Only SKILL.md. Claude reads it with bash once the request matches the description. The task doesn't need form filling, so FORMS.md is never read. The script isn't run, and even when a script is run, only its output enters context, never its code.
Sources1
3.Where Skills live in Claude Code
In Claude Code, a Skill is a folder containing SKILL.md. Where you put the folder determines who can use it. A personal skill in ~/.claude/skills/<skill-name>/SKILL.md works in all your projects on that machine. A project skill in .claude/skills/<skill-name>/SKILL.md works in sessions in that repository, and committing it shares it with your team. There are also enterprise, nested, plugin and claude.ai-synced locations. Markdown files in .claude/commands/ are the older format and still work. The documentation recommends Skills for new work because they can carry supporting files.
---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---
## Current changes
!`git diff HEAD`
## Instructions
Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.| Same name in | Which one runs |
|---|---|
| Two of enterprise, personal, and project | Enterprise over personal, and personal over project |
| A skill and a file in .claude/commands/ | The skill |
| A project-root skill and a nested skill | Both load |
| A plugin skill and a skill at any other location | Both load, because plugin skills are namespaced as /plugin-name:skill-name |
Sources2
4.Using Skills through the Claude API
On the API, Skills run in the code execution tool's container. You list the Skills in the container parameter and include the code execution tool in tools. Pre-built Skills are referenced by skill_id (pptx, xlsx, docx, pdf). Custom Skills are uploaded through the /v1/skills endpoints and shared across the workspace. The container has no network access and cannot install packages at runtime.
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
container={
"skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
},
messages=[
{
"role": "user",
"content": "Create a presentation about renewable energy with 5 slides",
}
],
tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
)The request never says "use the PowerPoint Skill". Claude matches the task to the Skill's metadata and loads the full instructions only at that point, which is the same progressive disclosure described above.
Sources1
5.Keep reusable content lean
Loading on demand doesn't make a Skill free once it loads. Its instructions then share the context window with the system prompt, the conversation history, other Skills' metadata and the request itself. The authoring guidance is to assume Claude is already very smart and add only context it doesn't have. For each paragraph, ask whether it justifies its token cost. In the documentation's example, a roughly 50-token snippet showing how to use pdfplumber does the same job as a 150-token version that first explains what a PDF is.
Sources3
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Installing many Skills fills the context window, because each Skill's full instructions are loaded at startup.Why is that wrong?
At startup only each Skill's name and description (around 100 tokens) are loaded. The SKILL.md body loads when the Skill is triggered, and bundled files load only when they're read.
Covered in Modular by design: progressive disclosure
2.A script bundled with a Skill costs as many tokens as its source code, because Claude has to read the code to run it.Why is that wrong?
Claude runs bundled scripts through bash and receives only their output. The script's code never enters the context window.
Covered in Modular by design: progressive disclosure
3.On the Messages API, listing a Skill in the container parameter is enough to enable it.Why is that wrong?
Skills on the API run inside the code execution tool's container, so the request must also include the code execution tool.
Covered in Using Skills through the Claude API
Practise it for real
Turn a set of instructions you would otherwise repeat into a personal Claude Code Skill, and check that it triggers both from its description and by name.
1.Run
mkdir -p ~/.claude/skills/summarize-changesWhy: A personal skill directory under ~/.claude/skills/ is available in all your projects on this machine.
You should see: An empty summarize-changes folder exists in ~/.claude/skills/.
2.Create SKILL.md in that folder with the description, the
!git diff HEAD`` context line and the Instructions section shown in this lesson.Why: The description is what Claude matches requests against. The body is the reusable instruction set that loads only when the Skill triggers.
You should see: The file starts with YAML frontmatter containing a description that says what the Skill does and when to use it.
3.In a git repository with uncommitted edits, start Claude Code and ask: What did I change?
Why: This checks that the description triggers the Skill without you naming it.
You should see: Claude summarises the diff in two or three bullets and lists risks, following the Skill's instructions.
4.Type
/summarize-changesWhy: Skills can also be invoked explicitly by name.
You should see: The same summary-and-risks output, produced on demand.
Stuck? Get a nudge
If the Skill doesn't trigger from the question, rewrite the description so it names the situations where it applies, not just what it does.
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“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.”
↩︎ From repeated instructions to reusable Skills“Compose capabilities: Combine Skills for complex, multistep tasks”
↩︎ From repeated instructions to reusable Skills“it must say both what the Skill does and when to use it”
↩︎ Modular by design: progressive disclosure“Claude loads information in stages as needed, rather than consuming context upfront.”
↩︎ Modular by design: progressive disclosure“Using Skills through the API requires the code execution tool, whose container Skills run in.”
↩︎ Using Skills through the Claude API“Custom Skills are shared workspace-wide: all workspace members can access them.”
↩︎ Using Skills through the Claude API“Claude loads information in stages as needed, rather than consuming context upfront.”
↩︎ Exam trap 1“When instructions mention executable scripts, Claude runs them through bash and receives only the output (the script code itself never enters context).”
↩︎ Exam trap 2“Using Skills through the API requires the code execution tool, whose container Skills run in.”
↩︎ Exam trap 3 - 2.https://code.claude.com/docs/en/skillsOfficial docs
“Prefer a skill for new work, since skills also support supporting files.”
↩︎ Where Skills live in Claude Code“Enterprise over personal, and personal over project.”
↩︎ Where Skills live in Claude Code - 3.
“being concise in SKILL.md still matters: once Claude loads it, every token competes with conversation history and other context.”
↩︎ Keep reusable content lean“The context window is a public good.”
↩︎ Keep reusable content lean