How to Create Skills
A custom skill is a single Markdown file — SKILL.md — that teaches Claude a repeatable workflow. Write it once, and Claude applies it consistently every time the skill is triggered.
The SKILL.md file
Every custom skill is a directory containing one required file: SKILL.md. It has two parts — YAML frontmatter that Claude reads at startup, and a Markdown body that Claude reads only when the skill is triggered. Dozens of skills can be installed without bloating the context window.
| Part | When loaded | Purpose |
|---|---|---|
| YAML frontmatter | At startup (~100 tokens) | name and description tell Claude the skill exists |
| Markdown body | On trigger (under 5k tokens) | Full instructions Claude follows |
| Bundled files | As needed | Optional references/, scripts/, and other support files |
Frontmatter field rules
| Field | Limit | Guidance |
|---|---|---|
| name | max 64 chars | Lowercase letters, numbers, hyphens only. No reserved words ("anthropic", "claude"). |
| description | max 1024 chars | Describe what the skill does AND when Claude should activate it. Vague descriptions cause missed triggers. |
Creating a skill: step by step
Pick one specific task
Good skills solve one well-defined problem — "format meeting notes" or "review Python code for security issues". Broad skills trigger unpredictably.
Write the SKILL.md
Start with YAML frontmatter (name + description), then add a Goal, Output structure, Guidelines, and an Example section.
Put it in a folder
Name the folder the same as your skill. For Claude Code: ~/.claude/skills/your-skill-name/SKILL.md. For Claude.ai: zip the folder and upload via claude.ai/customize/skills.
Test it
Start a new conversation and try /meeting-notes-formatter or describe the task naturally. Check that the output matches your Output structure section.
Blank template
Copy this and fill in the placeholders. The frontmatter is required — the body sections are a recommended structure.
--- name: your-skill-name description: > What this skill does and when Claude should use it. Be specific: mention the types of input (meeting notes, code files, support tickets) and the expected output. --- # Your Skill Name ## Goal One-sentence description of the skill's purpose. ## Output structure Define the exact format Claude should produce: 1. Section one 2. Section two 3. Section three (table, list, prose — your choice) ## Guidelines - Rule one: be concrete, not vague - Rule two: cover edge cases (what if a field is missing?) - Rule three: specify tone, length, or style if it matters ## Example **Input:** Brief example of raw input text. **Output:** ### [Section heading from your output structure] [Example of what Claude should produce here]
Working example: meeting-notes-formatter
Drop this into a folder called meeting-notes-formatter/ and it works immediately. Notice how the description tells Claude both what the skill does and which user requests should activate it.
--- name: meeting-notes-formatter description: > Formats raw meeting notes into a structured summary with key decisions, action items, and open questions. Use when the user shares meeting notes, a transcript, or asks to clean up or summarise meeting content. --- # Meeting Notes Formatter ## Goal Turn unstructured meeting notes into a clear, scannable document that anyone can read in under a minute. ## Output structure Always produce these four sections in order: 1. **Meeting summary** — 2-3 sentences covering the main topic and outcome. 2. **Key decisions** — bulleted list of what was agreed. 3. **Action items** — table with columns: | Owner | Task | Due date | 4. **Open questions** — items raised but not resolved. ## Guidelines - Extract owner names from context; default to "TBD" if unclear. - Use plain language; keep jargon only if it appears in the notes. - If no due date is mentioned, leave that column blank. - Do not infer or add information that isn't in the notes. - If notes are very short, all four sections may still appear (some will just be "None noted."). ## Example **Input:** we met today about the Q3 launch. sarah said we should push back the date by 2 weeks. john will update the roadmap by friday. still unsure about the pricing model. **Output:** ### Meeting Summary The team discussed the Q3 product launch and agreed to a two-week schedule extension. ### Key Decisions - Launch date pushed back by two weeks. ### Action Items | Owner | Task | Due date | |-------|----------------|----------| | John | Update roadmap | Friday | ### Open Questions - Pricing model still to be determined.
Where to save your skill
| Platform | Steps |
|---|---|
| Claude Code |
For project-scoped skills, use |
| Claude.ai |
Requires Pro, Max, Team, or Enterprise plan with code execution enabled. |
Skill folder structure
Only SKILL.md is required. Optional subfolders — add them as your skill grows:
| Folder | Purpose |
|---|---|
| agents/ | Sub-agent SKILL.md files for multi-step workflows |
| assets/ | Images, icons, data files referenced in instructions |
| eval-viewer/ | Tooling to run and view skill evaluations |
| references/ | Additional .md files with API docs, schemas, examples |
| scripts/ | Executable Python/shell helpers Claude runs via bash |
| LICENSE.txt | Include if distributing your skill publicly |
Before you continue
- Required:
nameanddescriptionin YAML frontmatter; body sections are flexible. - Vague
descriptionfields are the most common reason a skill does not trigger — include words users naturally type. - Claude Code path:
~/.claude/skills/<name>/SKILL.md; Claude.ai: upload a zip. - Review every file in a skill zip before uploading — skills run in a code execution environment with filesystem access.
- Next: build a complete skill folder from scratch with references and scripts.
What's Next
Creation basics done. Next: building a complete skill folder from scratch — SKILL.md, supporting files, and a test run.