# Building and packaging your own skill
A Skill is a folder with a SKILL.md file at its root, and that one file is the difference between Claude vaguely knowing about your work and Claude reliably doing your work the way your team expects. You already know Claude can follow instructions in a prompt. A Skill makes those instructions portable, reusable, and automatically loaded only when relevant.
This lesson shows you the anatomy of a custom Skill, walks through a real one (your company's report template), and gives you a clean SKILL.md you can copy.
A Skill is a packaged set of instructions, and optionally supporting files, that Claude loads on demand when a task matches its description. Think of it as a folder Claude can "open" when it decides the work calls for it.
The minimum viable Skill is a single file:
report-template/
└── SKILL.mdThat is a complete, valid Skill. Everything else is optional.
The key mechanic to understand: Claude does not read the full contents of every Skill all the time. It reads the metadata (name and description) of available Skills, and only pulls the full SKILL.md body and helper files into context when a request matches. This is called progressive disclosure
The official reference lives at docs.claude.com/en/docs/agents-and-tools/agent-skills. Bookmark it; the format evolves.
SKILL.md is a Markdown file with a YAML frontmatter block at the top (the section fenced by --- lines) followed by free-form Markdown instructions.
The frontmatter carries the two fields that matter most:
That second part is the rule most people get wrong. The description is not marketing copy for humans. It is the routing logic Claude uses to decide whether to load the Skill at all. If your description says "Formats reports," Claude has no trigger. If it says "Use when the user asks to write, format, or finalize a quarterly or monthly business report in the Acme house style," now Claude knows exactly when to reachreachThe number of unique people exposed to your message in a given period. Unlike impressions, reach counts each person once, no matter how often they see it.View full definition → for it.
Write the description like a dispatcher: name the triggers, the document types, the verbs.
Below the frontmatter, the Markdown body holds the actual instructions: the rules, the structure, the do's and don'ts, examples. This is where you put the substance Claude reads once the Skill is triggered.
Keep it focused. If the body balloons, move detail into helper files and reference them.
A Skill can ship with supporting files in its folder:
template.md or template.docx your reports must match.examples/ folder with two or three model outputs.validate.py that checks a draft against formatting rules.approved-language.md of compliance-safe phrasings.Claude can read these files when the Skill is active and, in execution environments like Claude Code or the Agent SDK, can run scripts you include. You reference them from the body so Claude knows they exist and what each is for.
report-template/
├── SKILL.md
├── template.md
├── examples/
│ └── q3-sample.md
└── scripts/
└── validate.pySay your company produces a monthly business review. Every one has the same sections, the same tone, a required executive summary capped at five bullets, and a rule that all dollar figures show year-over-year deltas. New hires get it wrong for months.
You could paste these rules into every prompt. A Skill is better because the rules live in one versioned place, load automatically when someone writes a report, and update for everyone when you edit the file.
Here is a clean, complete SKILL.md for it:
---
name: acme-monthly-report
description: >
Use when the user asks to write, draft, format, or finalize Acme's
monthly business review (MBR) or any monthly/quarterly business report
in Acme house style. Applies the standard section structure, tone, and
financial formatting rules.
---
# Acme Monthly Business Review
Apply these rules when producing an Acme MBR.
## Required structure (in order)
1. **Executive Summary** — max 5 bullets, each one sentence.
2. **Key Metrics** — table of metric, current value, YoY delta.
3. **Wins** — 3 to 5 items, outcome-focused.
4. **Risks & Mitigations** — each risk paired with an owner.
5. **Next Month's Priorities** — max 3, each with a measurable target.
## Formatting rules
- Every dollar or percentage figure must show a year-over-year delta
in parentheses, e.g. `$1.2M (+14% YoY)`.
- Use the company template in `template.md` as the skeleton.
- Tone: direct, no hedging. Cut filler adjectives.
- Never invent numbers. If a metric is missing, write `[TK: source needed]`.
## Before finishing
Run `scripts/validate.py` against the draft and fix any flagged issues.Notice what the description does. It lists the verbs ("write, draft, format, finalize"), the document name and its acronym ("monthly business review (MBR)"), and the variants ("monthly/quarterly business report"). That gives Claude multiple ways to match a real user request.
Notice what the body does. It is specific and checkable. "Cut filler adjectives" is a rule Claude can act on. "Make it good" is not.
Both approaches put instructions in front of Claude. The differences are operational.
Reuse. A prompt dies when the conversation ends. A Skill lives in a folder and applies every time, across every chat, for everyone who has it installed.
Automatic triggering. With a prompt, a user has to remember to include the rules. With a Skill, Claude loads them when the task matches the description. The new hire who does not know the rules exist still gets them applied.
Context efficiency. Pasting a 2,000-word style guide into every prompt burns tokenstokensA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → on every turn, even when the conversation drifts to unrelated topics. A Skill loads only when triggered, so your context windowcontext windowThe context window is the maximum amount of text (measured in tokens) a language model can process at once, including both the input prompt and the generated output.View full definition → stays lean.
Versioning and ownership. A Skill is a folder, so it lives in Git. You review changes in a pull request, roll back a bad edit, and keep one source of truth. Prompts scattered across people's notes drift apart.
Bundled assets and code. A prompt is text only. A Skill can carry a real template.docx, sample outputs, and runnable validation scripts.
The honest tradeoff: a Skill is more setup. For a one-off task you will never repeat, just prompt it. ReachReachThe number of unique people exposed to your message in a given period. Unlike impressions, reach counts each person once, no matter how often they see it.View full definition → for a Skill when a task is recurring, has a right answer, and the rules are stable enough to be worth maintaining.
The same SKILL.md format works across Anthropic surfaces, which is the point of packaging it once.
This portability is why the description and structure matter so much. You author the routing logic once, and it works wherever the Skill is loaded.
A note on the neighbors in this ecosystem. A Skill is instructions and assets. The Model Context Protocol (MCP), documented at modelcontextprotocol.io, is how Claude connects to live tools and data sources (your database, your ticketing system) through Connectors. They compose: a Skill can tell Claude *how* to format a report, while an MCP Connector gives Claude the live metrics to put in it. Do not use a Skill to fake a data connection, and do not use a Connector to carry style rules.
Knowledge check
1. What is the minimum requirement for a folder to qualify as a valid Skill?
2. Why does 'progressive disclosure' allow Skills to scale better than a giant system prompt?
3. According to the lesson, what is the correct way to think about the 'description' field in the frontmatter?
4. Select ALL statements that correctly describe how a Skill improves over instructions typed into a one-off prompt.
Select all the correct answers.
5. Select ALL correct statements about the structure of a SKILL.md file.
Select all the correct answers.
Once your folder is right, packaging is mostly discipline.
Keep `SKILL.md` short, push detail down. The body should be scannable. If a section grows past a screen, move it into a referenced helper file. Claude reads the body to orient, then opens helpers as needed.
Test the trigger, not just the output. Write three realistic requests a user might type, and check that Claude actually loads the Skill for each. If it does not fire on "put together this month's MBR," your description is missing a trigger phrase. Fix the description before you touch the body.
Make scripts runnable and dependency-light. A validate.py that needs ten packages will fail in half your environments. Standard library where possible.
Version it in Git. Treat the Skill folder like code. The official Anthropic repos at github.com/anthropics include example Skills and the SDKs worth studying for structure and conventions.
Write for the model's failure modes. If Claude tends to over-hedge, your body should say "no hedging." If it tends to invent figures, add an explicit "never invent numbers" rule with a [TK] placeholder convention, as in the example above. You are encoding the corrections you would otherwise type every time.
The fastest way to get a Skill right:
1. Draft SKILL.md with a sharp description and a minimal body.
2. Throw three real requests at it and watch whether it triggers.
3. Read the output against your real standard. Note every miss.
4. Turn each miss into one specific rule in the body, or one new helper file.
5. Repeat until the output passes without your intervention.
You are done when a colleague who has never seen the rules gets a correct report just by asking.
SKILL.md at its root; a single file with name and description frontmatter is already a valid Skill.description is routing logic, not a label: name the verbs, document types, and triggers so Claude loads the Skill exactly when it should.SKILL.md short and push detail into helper files (templates, examples, validation scripts) that the body references by name.These actions are compiled in the role's Playbook.