📄 Inside SKILL.md
The complete file structure: YAML frontmatter, the name and description fields, the Markdown body, and the folder organization that makes a skill professional.
Every SKILL.md has two parts: a YAML frontmatter block delimited by --- at the top, followed by the body in Markdown with the instructions.
It’s the skeleton of every skill. Get the structure wrong, and the agent won’t even recognize the file.
delimiters --- · YAML · Markdown body · required fields
The skill identifier — always in lowercase kebab case (e.g., frontend-design), unique within the agent.
It’s how the skill is referenced and installed. An ambiguous name or one with uppercase letters or spaces breaks activation.
kebab-case · lowercase · uniqueness · same as the folder name
The sentence the agent reads to decide whether to activate the skill. It should say what it does and exactly when to use it.
It’s the field that has the biggest impact on triggering. A vague description means a skill that never activates.
trigger · WHAT + WHEN · usage examples · pushy
The actual instructions. Written in imperative form, explaining WHY and showing output patterns and examples.
It’s where the actual behavior is defined. Long, unfocused text dilutes the skill.
imperative · explain why · examples · no shouted MUSTs
Folders alongside SKILL.md: scripts/ for deterministic code, references/ for on-demand docs and assets/ for templates.
Organizing resources keeps the SKILL.md lean and lets you load only what’s needed.
scripts/ · references/ · assets/ · bundled resources
Compare a 5-line SKILL.md with the actual frontmatter from Anthropic’s frontend-design skill.
Viewing a production example shows the level of detail a winning description contains.
minimal example · real frontmatter · frontend-design · 488k installs
🎚️ Progressive disclosure & a description that triggers
The 3 loading levels of a skill, how to write a description that triggers at the right time, and how to organize content by domain.
The skill loads in layers: metadata is always present, the body loads when triggered, and resources are available on demand.
Understanding the layers is what lets you write large skills without bloating the context.
level 1 metadata · level 2 body · level 3 resources · context
Only name + description (~100 words) stay loaded in the agent's context all the time.
It’s the only level that’s always present—that’s why the description has to carry the entire burden of triggering.
~100 words · always loaded · context cost
The Markdown body (recommended to be under 500 lines) only enters the context when the skill is activated.
Keeping the body concise improves the agent’s adherence to the instructions.
<500 lines · loaded on trigger · focused
Files in scripts/, references/, and assets/ — unlimited in size, read or run only when needed.
Scripts run without bringing the code into context — that’s how skills become powerful and inexpensive.
unlimited · on demand · deterministic execution
The art of writing the description: what it does, when to use it, and explicit triggers, while being a little pushy.
Claude tends to UNDERTRIGGER skills; a more assertive description fixes this.
pushy · under-triggering · what + when + triggers
Split references by domain (aws.md, gcp.md, azure.md) and add an index to files with more than 300 lines.
The agent reads only the relevant file, saving context and maintaining accuracy.
domain-based splitting · selective reading · table of contents
⭐ The Best Anatomies to Imitate
Dissect the SKILL.md files of top skills—frontend-design, skill-creator, supabase, microsoft-foundry, and azure-ai—and see exactly what to copy from each frontmatter and structure.
Learn to write SKILL.md by dissecting the most installed skills in the ecosystem and extracting their patterns.
Each champion skill solves a different trade-off; together they form a catalog of ready-made patterns.
honest borrowing · form vs. content · trade-offs · pattern catalog
Anthropic’s most installed skill; a description that says what it does, when to use it (with examples), and what sets it apart, without folders.
It’s the most common archetype: a single capability, one body of content, easy to maintain.
action verb · examples as triggers · final differentiator · zero folders
The canonical example of a large skill organized into folders (~33KB), with pointers from the body to the resources.
It’s the template for when there’s reusable code, long docs, and output templates.
scripts/ · references/ · assets/ · pointers in the body
Aggressive description that starts with "Use when doing ANY task" and lists Triggers by category.
It’s the standard when a skill is the gatekeeper for an entire platform and needs to trigger at any entry point.
Triggers: categorized · assertive ANY · metadata · Core Principles
Large skills that use USE FOR / DO NOT USE FOR in the description and a sub-skill table in the body.
It’s how to scale an operational skill without triggering it by mistake or losing control.
USE FOR / DO NOT USE FOR · sub-skills table · pre-execution
A quick decision guide: each anatomy is the answer to a question about your skill.
Knowing how to choose the right template keeps you from having to redo the structure later.
single skill · multi-file · gatekeeper · large operational
🛠️ How to Create: Building a SKILL.md from Scratch
From an empty folder to a ready-to-use file: frontmatter with name and trigger description, imperative body with When to Use and Steps, when to create each folder, and a complete template to copy.
The six-stop creation journey: intent, frontmatter, body, folders, package, iterate.
Having the map keeps you from starting too big; a valid SKILL.md starts with just frontmatter + body.
six steps · start small · optional folders
The skill identifier in lowercase kebab case, with no spaces or uppercase letters, matching the folder name.
A mismatch between name and folder breaks skill loading.
kebab-case · lowercase · name = folder · no suffixes
The description formula: what it does, when to use it, and concrete triggers, in ~100 punchy words.
It’s the only text that’s always loaded and what makes the skill trigger; Claude tends to under-trigger by default.
formula · ~100 words · pushy · real keywords
The Markdown body in imperative form, with a title, When to Use, numbered Steps, and Output Format.
It’s where the actual behavior is defined; explaining why works better than shouting MUSTs in all caps.
imperative · When to Use · Steps · Output Format
The trigger for creating each directory: deterministic → scripts/, long documents → references/, output → assets/.
Folders grow out of need, not aesthetics; every file needs a pointer in the body.
scripts/ deterministic · references/ on demand · assets/ output
A complete SKILL.md file, ready to use: frontmatter, When to Use, Steps, Output Format, and pointers to folders.
Copying, changing the names, and installing is the fastest way to create your first skill.
ready-to-use template · installable · a base to iterate on
🚀 Advanced Tips: Multi-File and Routing
Real progressive disclosure: references/ organized by domain and read selectively, scripts/ that run without context, indexes in long files, SKILL.md under 500 lines, and well-used assets/.
Put the 3 levels into practice: SKILL.md becomes a menu, and each file is loaded only when that route is chosen.
It’s what lets skills cover dozens of services without blowing up the context.
menu · routes · selective loading · context savings
Organize references by variant and let the body handle routing; the agent reads only the relevant file.
Three 300-line files save 66% of the context compared with one 900-line file and are easier to maintain.
domain organization · routing table · selective reading
Deterministic tasks become scripts that run and return only the output; the code never enters the context.
More reliable and cheaper than instructing the agent to reason step by step.
deterministic · context-free execution · extraction of repeated helpers
Add a table of contents at the top of every reference file over 300 lines long.
The agent goes straight to the right section without rereading the whole file; if it’s still large, split it up.
index at the top · anchors · partition by subtopic
Keep the body under 500 lines by moving details to references/ and leaving clear pointers.
The entire body enters the context with every activation; a hierarchy incurs the cost only when needed.
500-line limit · move details · pointers for "when to read"
assets/ stores templates, fonts, and icons filled in the output, distinct from references/ (which is read).
Complete the checklist of what distinguishes a toy skill from one like azure-ai or supabase.
assets filled in · scripts vs. references vs. assets · final checklist
Learning path overview
Two delimiters and everything changes. Dissect the frontmatter line by line.
3 layers, low-cost context, and the description that triggers at the right time.
Dissect top skills and borrow what works from each frontmatter.
From an empty folder to a template ready to copy and install.
Real progressive disclosure, context-free scripts, and pointers.