Skills teach Claude a repeatable capability — a workflow, a format, a set of best practices — that it loads only when relevant. Build one and watch Claude use it on its own.
Why: a skill packages expertise Claude pulls in automatically when a task calls for it, instead of you re-explaining each time. When: build one for a recurring, specialized workflow (a report format, a migration procedure, an internal API). Where: skills live in .claude/skills/<name>/ as a folder with a SKILL.md.
.claude/skills/
└── pdf-reports/
├── SKILL.md # the instructions Claude reads
├── template.md # supporting files the skill can use
└── generate.py # scripts the skill can runWhy: the description is what makes Claude reach for the skill, so it must say plainly what the skill does and when to use it. When: Claude reads only the description until a task matches, then loads the full file — this "progressive disclosure" keeps context lean. Where: the name and description go in frontmatter; the body holds the actual instructions.
<!-- .claude/skills/pdf-reports/SKILL.md -->
---
name: pdf-reports
description: Generate branded PDF reports from sales data. Use whenever the
user asks for a sales report, a monthly summary, or a PDF export.
---
# Generating a sales report
1. Read the data from the path the user gives.
2. Fill template.md with the figures.
3. Run `python generate.py` to produce the PDF.
4. Always include a totals row and the company footer.Why: a vague description means Claude never loads the skill, and a bloated body wastes context — tight skills win. When: write the description in terms of the user's trigger ("when the user asks for X"), and keep each skill to one job. Where: put rarely-needed detail in separate files the skill links to, not in SKILL.md.
Good skills:
• description names the TRIGGER ("use when the user asks for a PDF report")
• one skill = one capability — don't make a kitchen-sink skill
• keep SKILL.md short; push detail into linked files
• bundle scripts the skill can run, so it does work, not just describes it