Skills have three structural components: YAML frontmatter (metadata), pure XML body structure (content organization), and progressive disclosure (file organization). This reference defines requirements and best practices for each component.
**Remove ALL markdown headings (#, ##, ###) from skill body content.** Replace with semantic XML tags. Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links).
Every skill MUST have these three tags:
- **``** - What the skill does and why it matters (1-3 paragraphs)
- **``** - Immediate, actionable guidance (minimal working example)
- **``** or **``** - How to know it worked
Add based on skill complexity and domain requirements:
- **``** - Background/situational information
- **`` or ``** - Step-by-step procedures
- **``** - Deep-dive topics (progressive disclosure)
- **``** - How to verify outputs
- **``** - Multi-shot learning
- **``** - Common mistakes to avoid
- **``** - Non-negotiable security patterns
- **``** - Testing workflows
- **``** - Code examples and recipes
- **`` or ``** - Links to reference files
See [use-xml-tags.md](use-xml-tags.md) for detailed guidance on each tag.
**Simple skills** (single domain, straightforward):
- Required tags only
- Example: Text extraction, file format conversion
**Medium skills** (multiple patterns, some complexity):
- Required tags + workflow/examples as needed
- Example: Document processing with steps, API integration
**Complex skills** (multiple domains, security, APIs):
- Required tags + conditional tags as appropriate
- Example: Payment processing, authentication systems, multi-step workflows
Properly nest XML tags for hierarchical content:
```xml
User input
```
Always close tags:
```xml
Content here
```
Use descriptive, semantic names:
- `` not ``
- `` not ``
- `` not ``
Be consistent within your skill. If you use ``, don't also use `` for the same purpose (unless they serve different roles).
```yaml
---
name: skill-name-here
description: What it does and when to use it (third person, specific triggers)
---
```
**Validation rules**:
- Maximum 64 characters
- Lowercase letters, numbers, hyphens only
- No XML tags
- No reserved words: "anthropic", "claude"
- Must match directory name exactly
**Examples**:
- ✅ `process-pdfs`
- ✅ `manage-facebook-ads`
- ✅ `setup-stripe-payments`
- ❌ `PDF_Processor` (uppercase)
- ❌ `helper` (vague)
- ❌ `claude-helper` (reserved word)
**Validation rules**:
- Non-empty, maximum 1024 characters
- No XML tags
- Third person (never first or second person)
- Include what it does AND when to use it
**Critical rule**: Always write in third person.
- ✅ "Processes Excel files and generates reports"
- ❌ "I can help you process Excel files"
- ❌ "You can use this to process Excel files"
**Structure**: Include both capabilities and triggers.
**Effective examples**:
```yaml
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
```
```yaml
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
```
```yaml
description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
```
**Avoid**:
```yaml
description: Helps with documents
```
```yaml
description: Processes data
```
Use **verb-noun convention** for skill names:
Building/authoring tools
Examples: `create-agent-skills`, `create-hooks`, `create-landing-pages`
Managing external services or resources
Examples: `manage-facebook-ads`, `manage-zoom`, `manage-stripe`, `manage-supabase`
Configuration/integration tasks
Examples: `setup-stripe-payments`, `setup-meta-tracking`
Generation tasks
Examples: `generate-ai-images`
- Vague: `helper`, `utils`, `tools`
- Generic: `documents`, `data`, `files`
- Reserved words: `anthropic-helper`, `claude-tools`
- Inconsistent: Directory `facebook-ads` but name `facebook-ads-manager`
SKILL.md serves as an overview that points to detailed materials as needed. This keeps context window usage efficient.
- Keep SKILL.md body under 500 lines
- Split content into separate files when approaching this limit
- Keep references one level deep from SKILL.md
- Add table of contents to reference files over 100 lines
Quick start in SKILL.md, details in reference files:
```markdown
---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---
Extract text and tables from PDF files, fill forms, and merge documents using Python libraries.
Extract text with pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
**Form filling**: See [forms.md](forms.md)
**API reference**: See [reference.md](reference.md)
```
Claude loads forms.md or reference.md only when needed.
For skills with multiple domains, organize by domain to avoid loading irrelevant context:
```
bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
├── finance.md (revenue, billing metrics)
├── sales.md (opportunities, pipeline)
├── product.md (API usage, features)
└── marketing.md (campaigns, attribution)
```
When user asks about revenue, Claude reads only finance.md. Other files stay on filesystem consuming zero tokens.
Show basic content in SKILL.md, link to advanced in reference files:
```xml
Process DOCX files with creation and editing capabilities.
Use docx-js for new documents. See [docx-js.md](docx-js.md).
For simple edits, modify XML directly.
**For tracked changes**: See [redlining.md](redlining.md)
**For OOXML details**: See [ooxml.md](ooxml.md)
```
Claude reads redlining.md or ooxml.md only when the user needs those features.
**Keep references one level deep**: All reference files should link directly from SKILL.md. Avoid nested references (SKILL.md → advanced.md → details.md) as Claude may only partially read deeply nested files.
**Add table of contents to long files**: For reference files over 100 lines, include a table of contents at the top.
**Use pure XML in reference files**: Reference files should also use pure XML structure (no markdown headings in body).
Claude navigates your skill directory using bash commands:
- Use forward slashes: `reference/guide.md` (not `reference\guide.md`)
- Name files descriptively: `form_validation_rules.md` (not `doc2.md`)
- Organize by domain: `reference/finance.md`, `reference/sales.md`
Typical skill structure:
```
skill-name/
├── SKILL.md (main entry point, pure XML structure)
├── references/ (optional, for progressive disclosure)
│ ├── guide-1.md (pure XML structure)
│ ├── guide-2.md (pure XML structure)
│ └── examples.md (pure XML structure)
└── scripts/ (optional, for utility scripts)
├── validate.py
└── process.py
```
❌ Do NOT use markdown headings in skill body:
```markdown
# PDF Processing
## Quick start
Extract text...
## Advanced features
Form filling...
```
✅ Use pure XML structure:
```xml
PDF processing with text extraction, form filling, and merging.
Extract text...
Form filling...
```
- ❌ "Helps with documents"
- ✅ "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."
- ❌ "I can help you process Excel files"
- ✅ "Processes Excel files and generates reports"
- ❌ Directory: `facebook-ads`, Name: `facebook-ads-manager`
- ✅ Directory: `manage-facebook-ads`, Name: `manage-facebook-ads`
- ❌ Directory: `stripe-integration`, Name: `stripe`
- ✅ Directory: `setup-stripe-payments`, Name: `setup-stripe-payments`
Keep references one level deep from SKILL.md. Claude may only partially read nested files (SKILL.md → advanced.md → details.md).
Always use forward slashes: `scripts/helper.py` (not `scripts\helper.py`)
Every skill must have: ``, ``, and `` (or ``).
Before finalizing a skill, verify:
- ✅ YAML frontmatter valid (name matches directory, description in third person)
- ✅ No markdown headings in body (pure XML structure)
- ✅ Required tags present: objective, quick_start, success_criteria
- ✅ Conditional tags appropriate for complexity level
- ✅ All XML tags properly closed
- ✅ Progressive disclosure applied (SKILL.md < 500 lines)
- ✅ Reference files use pure XML structure
- ✅ File paths use forward slashes
- ✅ Descriptive file names