What you will be able to do
- Explain how Agent Skills differ from one-off prompts as a reuse mechanism
- Describe the three loading levels of progressive disclosure and their token costs
- Write a valid SKILL.md frontmatter with a description that triggers reliably
- Structure a growing Skill so Claude loads only what each task needs
1.From repeated prompts to Skills
Pasting the same instructions into every conversation is the most basic form of prompt reuse, and it scales poorly: the guidance must be repeated, and it fills context whether or not the task needs it. Agent Skills package that guidance as modular capabilities. Each Skill bundles instructions, metadata and optional resources such as scripts and templates, and Claude uses it automatically when it is relevant. The documentation puts the contrast directly: prompts are conversation-level instructions for one-off tasks, while Skills load on demand. The stated benefits are specialising Claude for domain tasks, reducing repetition (create once, use automatically), and combining Skills for complex multistep work.
Skills use Claude's VM environment. Each Skill is a directory of instructions, executable code and reference material, which the documentation compares to an onboarding guide for a new team member. 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 are available in your environment.
Checkpoint 1 of 6· Check yourself
According to the Skills documentation, what most distinguishes a Skill from a prompt as a reuse mechanism?
Prompts are conversation-level instructions for one-off tasks. A Skill is written once and loaded on demand whenever it is relevant.
“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.”Source: platform.claude.com
Sources1
2.Progressive disclosure: three loading levels
Skills keep context costs low through progressive disclosure: information is loaded in stages as it is needed, not all at the start. Each kind of content enters context at a different time. A Skill's name and description are always present. Its instructions load only when the Skill is triggered. Bundled files load only when Claude reads them, and scripts never load at all: Claude runs them through bash and sees only their output.
| 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 |
As a result, you can install many Skills and bundle large reference sets without filling context up front. Unused files cost nothing. The trade-off is that the metadata of every installed Skill is always loaded, so Claude has to be able to choose correctly from name and description alone.
Checkpoint 2 of 6· Put it in order
Put the steps in which Claude loads and uses a custom pdf-processing Skill for "Extract the text from this PDF and summarize it" in order
- 1.Claude completes the task using the instructions from SKILL.md
- 2.The user asks Claude to extract and summarize text from a PDF
- 3.The system prompt already contains the Skill's name and description from startup
- 4.Claude runs cat on pdf-processing/SKILL.md, loading its instructions into context
- 5.Claude decides form filling isn't needed, so it doesn't read FORMS.md
Metadata is loaded at startup, the request matches the description, SKILL.md is read, and referenced files are opened only if the task needs them.
“Claude determines: Form filling is not needed, so FORMS.md is not read”Source: platform.claude.com
Sources1
3.Writing SKILL.md so it triggers
Every Skill needs a SKILL.md file that begins with YAML frontmatter. Only two fields are required, name and description. name can be at most 64 characters, may use only lowercase letters, numbers and hyphens, and may not contain XML tags or the reserved words anthropic and claude. description must not be empty, can be at most 1024 characters, and may not contain XML tags.
---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---
# Your Skill Name
## Instructions
[Clear, step-by-step guidance for Claude to follow]
## Examples
[Concrete examples of using this Skill]The description is how Claude finds the Skill. Claude compares each request against it, possibly among 100 or more installed Skills, so it has to say both what the Skill does and when to use it, with specific trigger terms. Descriptions like "Helps with documents" or "Processes data" are what to avoid. For names, the best-practices guide suggests a consistent gerund style such as processing-pdfs. Keep the body short as well: once loaded, every token competes with conversation history, so include only what Claude doesn't already know.
Checkpoint 3 of 6· Check yourself
Which description best follows the authoring guidance?
A good description states what the Skill does and when to use it, with concrete trigger terms. The XML-tagged option breaks a field rule, and the others are too vague to trigger reliably.
“The description must include both what the Skill does and when Claude should use it.”Source: platform.claude.com
4.Structuring a Skill as it grows
Treat SKILL.md as a table of contents that points to more detailed files. Keep the body under 500 lines and split content out into separate files as it approaches that limit. Link every reference file directly from SKILL.md, one level deep. With nested references, Claude may preview a file with something like head -100 and miss part of it. A reference file longer than 100 lines should start with its own table of contents. If a Skill covers several domains, give each domain its own file, for example reference/finance.md and reference/sales.md, so that a sales question loads only the sales material.
Also decide how much freedom each instruction allows. Use high freedom (text guidance) when several approaches are valid. Use medium freedom (pseudocode or parameterised scripts) when there is a preferred pattern. Use low freedom (an exact script) when an operation is fragile and must run in a fixed sequence. Because a Skill's effectiveness depends on the model running it, test it on every model you plan to use.
Checkpoint 4 of 6· Match them up
Match each degree of freedom to the situation it suits
Tap a term, then the definition that fits it.
How specific an instruction should be depends on how fragile the task is. Exact scripts suit something like a database migration, and general guidance suits a code review.
“Match the level of specificity to the task's fragility and variability.”Source: platform.claude.com
Checkpoint 5 of 6· Exam question
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.
Sources2
5.Where Skills are shared, and with whom
How far a Skill is reused depends on where it is installed. On the Claude API, you reference a Skill by skill_id in the container parameter, alongside the code execution tool. Custom Skills uploaded through the /v1/skills endpoints are shared across the workspace, and they run in a sandbox with no network access. In Claude Code, Skills are plain directories: ~/.claude/skills/ for personal Skills or .claude/skills/ for project Skills, with nothing to upload. In claude.ai, custom Skills are uploaded as zip files and belong to the individual user, so they are not shared across the organization.
A Skill can run code and invoke tools, so installing one is like installing software. Use Skills only from trusted sources, audit every bundled file, and be especially wary of Skills that fetch content from external URLs.
Checkpoint 6 of 6· Check yourself
A team wants every member to reuse one custom Skill. Which statement is accurate?
Skills uploaded through the API are shared across the workspace. claude.ai custom Skills belong to one user, and Claude Code reads Skills from the filesystem without any upload.
“Custom Skills are shared workspace-wide: all workspace members can access them.”Source: platform.claude.com
Sources1
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.An installed Skill costs no context at all until it is triggered.Why is that wrong?
The body and bundled files cost nothing until they are used, but every Skill's name and description is loaded into the system prompt at startup (about 100 tokens each).
Covered in Progressive disclosure: three loading levels
2.Chaining reference files (SKILL.md → advanced.md → details.md) is a fine way to organise deep material.Why is that wrong?
Claude may only partly read files reached through nested references, so link every reference file directly from SKILL.md.
Covered in Structuring a Skill as it grows
3.A custom Skill uploaded in claude.ai is available to everyone in the organization.Why is that wrong?
Custom Skills in claude.ai belong to the individual user. Admins cannot share them organization-wide or manage them centrally.
Covered in Where Skills are shared, and with whom
Practise it for real
Create a project-level custom Skill in Claude Code and confirm that its description triggers it
1.Create a directory .claude/skills/processing-pdfs/ in your project
Why: Claude Code finds project Skills on the filesystem, with no upload needed
You should see: An empty Skill directory inside .claude/skills/
2.Add SKILL.md with frontmatter: name: processing-pdfs and a description saying what it does and when to use it (mention PDFs, forms, document extraction)
Why: name and description are the only required fields, and the description is what requests are matched against
You should see: A name using only lowercase letters, numbers and hyphens, and a description under 1024 characters
3.Write a short instructions body and move any detailed material into FORMS.md, linked directly from SKILL.md
Why: A lean body with one-level-deep references keeps the Level 2 cost low and loads detail only when needed
You should see: SKILL.md well under 500 lines, pointing to FORMS.md
4.Start a session and ask Claude to extract text from a PDF
Why: A request matching the description should make Claude read SKILL.md
You should see: Claude reads SKILL.md and does not open FORMS.md, because no form filling was requested
Stuck? Get a nudge
If the Skill never triggers, rewrite the description with the exact words users say, such as 'PDF', 'forms' or 'extract'.
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Agent Skills are modular capabilities that extend Claude's functionality.”
↩︎ From repeated prompts to Skills“Reduce repetition: Create once, use automatically”
↩︎ From repeated prompts to Skills“Progressive disclosure ensures only relevant content occupies the context window at any given time.”
↩︎ Progressive disclosure: three loading levels“When instructions mention executable scripts, Claude runs them through bash and receives only the output (the script code itself never enters context).”
↩︎ Progressive disclosure: three loading levels“Must contain only lowercase letters, numbers, and hyphens”
↩︎ Writing SKILL.md so it triggers“Custom Skills in Claude Code are filesystem-based and don't require API uploads: place them in ~/.claude/skills/ (personal) or .claude/skills/ (project).”
↩︎ Where Skills are shared, and with whom“Use Skills only from trusted sources: those you created yourself or obtained from Anthropic.”
↩︎ Where Skills are shared, and with whom“Claude loads this metadata at startup and includes it in the system prompt.”
↩︎ Exam trap 1“Custom Skills are individual to each user. They are not shared organization-wide and cannot be centrally managed by admins.”
↩︎ Exam trap 3“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.”
↩︎ Checkpoint“Claude determines: Form filling is not needed, so FORMS.md is not read”
↩︎ Checkpoint“The description must include both what the Skill does and when Claude should use it.”
↩︎ Checkpoint“Custom Skills are shared workspace-wide: all workspace members can access them.”
↩︎ Checkpoint - 2.
“Claude uses it to choose the right Skill from potentially 100+ available Skills.”
↩︎ Writing SKILL.md so it triggers“Only add context Claude doesn't already have.”
↩︎ Writing SKILL.md so it triggers“Keep SKILL.md body under 500 lines for optimal performance”
↩︎ Structuring a Skill as it grows“For Skills with multiple domains, organize content by domain to avoid loading irrelevant context.”
↩︎ Structuring a Skill as it grows“Keep references one level deep from SKILL.md.”
↩︎ Exam trap 2“Match the level of specificity to the task's fragility and variability.”
↩︎ Checkpoint