Anatomy of a Skill

What an installable skill is made of – the required file and optional bundled resources

my-skill/ (as a folder, or packaged as a .skill file)
SKILL.md Required
YAML frontmatter
name and description – determine whether and when the skill gets suggested at all. Only these ~100 words are always in context.
Markdown instructions
The actual procedure: steps, rules, examples. Loaded as soon as the skill is actually triggered – ideally under 500 lines.
Bundled resources Optional
scripts/
Executable code for fixed, repetitive tasks – runs without the content itself needing to be read.
convert.pybuild.js
references/
Reference documents loaded only when needed – for details that don't need to sit in context all the time.
schemas.mdapi.md
assets/
Files that flow directly into the output: templates, fonts, icons, sample images.
template.docxfonts/

Progressive Disclosure

Three loading stages – only as much context as is actually needed

1
Metadata
Name + description are always loaded, so Claude knows the skill exists.
~100 words · always in context
→
2
SKILL.md content
The full instructions are loaded once the skill is actually triggered.
ideally < 500 lines
→
3
Resources
Scripts, references, and assets are loaded or run only when actually needed.
unlimited · as needed
ℹ︎

The only required file is SKILL.md – so a skill can consist of just this one file. To install it, the folder is packaged as a .skill file (a ZIP archive) or shared as a standalone SKILL.md; the user confirms the installation via the "Save skill" button.

™

Note on brand and product names: The product, company and brand names mentioned in this document — including Claude — are trademarks or registered trademarks of their respective rights holders. They are used here solely for illustrative and explanatory purposes; no affiliation, endorsement, or partnership with the respective companies is implied.