Introduction
Last time we showed you how to create your first Claude Skill: folder, SKILL.md, zip, upload, test. That got you a working Skill. This tutorial gets you a good one — there is a world of difference between a Skill Claude reaches for daily and one it quietly ignores.
The SKILL.md file is your Skill’s brain and its business card in one. At startup, Claude reads only two lines — the name and description in the YAML frontmatter — to decide which of your installed Skills to trigger. Everything else loads only when the Skill fires, and every token then competes with your conversation for context. So writing a SKILL.md is a craft: concise, specific, and structured the way Anthropic’s authoring best practices recommend.
What You’ll Need
- A Skill to rewrite — from your own folder from last tutorial.
- Any plain-text editor: Notepad, TextEdit, VS Code.
- Anthropic’s Skill authoring best practices page (docs.anthropic.com) open for reference.
- About 40 minutes for a full rewrite pass.
Step 1: Get the Frontmatter Right
Every SKILL.md opens with a YAML frontmatter block — two required fields, and both are load-bearing:
--- name: writing-invoices-reminders description: Drafts polite payment-reminder emails for overdue invoices in our company tone. Use when the user mentions overdue invoices, payment reminders, or chasing late payments. ---
Name rules (from Anthropic’s docs): max 64 characters, lowercase letters/numbers/hyphens only, no “anthropic” or “claude”, no XML tags. Prefer the gerund form — verb + -ing — because it names the activity clearly: processing-pdfs, drafting-invoices-reminders. Never use vague names like helper, utils, or tools: you can’t tell one helper from another in a Skill library, and neither can Claude.
Description rules: non-empty, max 1,024 characters, no XML tags — and it must say both what the Skill does and when to use it. Use the trigger terms the user would actually type: “overdue invoices”, “payment reminders”. Vague descriptions (“handles financial communications”) either never trigger or fire on the wrong tasks. This is the most important line you’ll write — the only one Claude reads before deciding to use your Skill.
Step 2: Assume Claude Is Already Smart
The first principle of Anthropic’s authoring guide is: concise is key. The context window is a public good — your Skill shares it with the system prompt, conversation history, and other Skills’ metadata. Challenge every paragraph: “Does Claude really need this explanation? Does it justify its token cost?”
In practice: don’t explain what a PDF is or how invoices work in general. Add only context Claude doesn’t have — your company’s tone, product names, internal rules. A 50-token SKILL.md that assumes the model’s knowledge beats a 150-token version that re-teaches it things it already knows.
Step 3: Match Specificity to Task Fragility
Anthropic calls this setting appropriate degrees of freedom:
- High freedom — plain text. Multiple approaches are valid: code reviews, drafting copy, summarizing research.
- Medium freedom — pseudocode or scripts with parameters. A preferred pattern exists with some acceptable variation: data-analysis workflows.
- Low freedom — exact scripts. Fragile, error-prone operations where a sequence must run identically every time: database migrations.
The analogy from the docs: a narrow bridge over a cliff needs guardrails (low freedom); an open field just needs a direction (high freedom). For most small-business Skills — emails, summaries, checklists — high freedom with clear rules is the sweet spot.
Step 4: Structure the Body Like an Onboarding Doc
Below the frontmatter, write the instruction body like the onboarding guide you’d hand a sharp new hire:
- Context — company, audience, what “good” looks like.
- Workflow — numbered steps in order. For complex tasks, use a checklist Claude can copy and check off.
- Rules — hard constraints: tone, length, things to never do.
- Examples — one input/output pair showing success. Examples teach faster than any paragraph of adjectives.
Use consistent terminology — pick one term and stick with it (“API endpoint”, not “endpoint/URL/route”). Inconsistent vocabulary silently degrades reliability.
Step 5: Use Progressive Disclosure for Everything Else
A great SKILL.md stays under 500 lines and acts like a table of contents: the main file loads when the Skill triggers, and detailed material lives in separate files Claude opens only when needed — REFERENCE.md for background, EXAMPLES.md for sample outputs, scripts/ for code that’s run rather than read. Extra files cost nothing until used.
Two structural rules: keep references one level deep from SKILL.md (deeper nesting gets only partially read), and give any reference file over 100 lines a table of contents at the top so Claude sees its full scope even in a partial preview.
Step 6: Build in Validation Loops
Skills that produce files or formatted output get far more reliable with a feedback loop: run a validator, fix the errors, repeat. The validator can be a script or a reference document — the docs show a STYLE_GUIDE.md that Claude reads and checks its own output against. Also, avoid time-sensitive information — “this quarter’s pricing” expires on a timer; keep historical context in an “old patterns” section instead. Then evaluate: run Claude on representative tasks without the Skill, note the failures, and write just enough instruction to fix them.
Step 7: Test and Iterate
Most misses are fixed at the description level — if the Skill never fires, the description is too narrow or missing trigger phrases; if it fires wrongly, it’s too broad. Test with all the models you plan to use: a Skill tuned for Opus may over-explain for Haiku and under-guide another model. Use Claude itself in the loop — one instance drafts and trims, a fresh instance tests it on realistic tasks.
Pro Tips
- Fix the description first. When a Skill misfires, the description is the cheapest change and solves most problems.
- Examples beat adjectives. One real input/output pair teaches tone and format faster than a paragraph describing them.
- Conditional workflows for decisions. Spell out the branches explicitly (“under 30 days late: friendly template; over 60: escalate”) instead of hoping Claude infers them.
Frequently Asked Questions
How long should a SKILL.md file be?
Keep the body under 500 lines. Approaching the limit? Split detail into REFERENCE.md or EXAMPLES.md, linked one level deep — Claude loads them only when needed.
What is the most common mistake people make?
A vague description. It’s the only text Claude reads at startup, so include specific trigger terms: “use when the user mentions overdue invoices” fires; “helps with financial communications” does not.
Do I need scripts in my Skill?
No. Start with Markdown — scripts are for fragile, consistency-critical operations. Most small-business Skills never need code.
Does the Skill name actually matter?
Yes. Besides the rules (max 64 chars, lowercase/hyphens), prefer the gerund form — processing-pdfs, drafting-invoices — and avoid generic names like helper, which make a Skill library unmanageable.
Conclusion
A Skill that works is discoverable, concise, and honest about how much freedom the task allows. Get the description right, assume Claude is already smart, keep SKILL.md lean, and test with real tasks before polishing the prose. Do that, and your Agent Skills stop being clever demos and start being coworkers. Open your SKILL.md and run the seven steps.
