Skill structure
<objective>- What the skill does and why it matters (1-3 paragraphs)<quick_start>- Immediate, actionable guidance (minimal working example)<success_criteria>or<when_successful>- How to know it worked
<context>- Background/situational information<workflow>or<process>- Step-by-step procedures<advanced_features>- Deep-dive topics (progressive disclosure)<validation>- How to verify outputs<examples>- Multi-shot learning<anti_patterns>- Common mistakes to avoid<security_checklist>- Non-negotiable security patterns<testing>- Testing workflows<common_patterns>- Code examples and recipes<reference_guides>or<detailed_references>- Links to reference files
See use-xml-tags.md for detailed guidance on each tag.
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
<examples>
<example number="1">
<input>User input</input>
<output>Expected output</output>
</example>
</examples>
Always close tags:
<workflow> not <steps>
- <success_criteria> not <done>
- <anti_patterns> not <dont_do>
Be consistent within your skill. If you use <workflow>, don't also use <process> for the same purpose (unless they serve different roles).
Examples:
- ✅ process-pdfs
- ✅ manage-facebook-ads
- ✅ setup-stripe-payments
- ❌ PDF_Processor (uppercase)
- ❌ helper (vague)
- ❌ claude-helper (reserved word)
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:
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.
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
Avoid:
Examples: create-agent-skills, create-hooks, create-landing-pages
Examples: manage-facebook-ads, manage-zoom, manage-stripe, manage-supabase
Examples: setup-stripe-payments, setup-meta-tracking
Examples: generate-ai-images
helper, utils, tools
- Generic: documents, data, files
- Reserved words: anthropic-helper, claude-tools
- Inconsistent: Directory facebook-ads but name facebook-ads-manager
---
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.
---
<objective>
Extract text and tables from PDF files, fill forms, and merge documents using Python libraries.
</objective>
<quick_start>
Extract text with pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
Claude loads forms.md or reference.md only when needed.
</pattern>
<pattern name="domain_organization">
For skills with multiple domains, organize by domain to avoid loading irrelevant context:
When user asks about revenue, Claude reads only finance.md. Other files stay on filesystem consuming zero tokens.
</pattern>
<pattern name="conditional_details">
Show basic content in SKILL.md, link to advanced in reference files:
```xml
<objective>
Process DOCX files with creation and editing capabilities.
</objective>
<quick_start>
<creating_documents>
Use docx-js for new documents. See [docx-js.md](docx-js.md).
</creating_documents>
<editing_documents>
For simple edits, modify XML directly.
**For tracked changes**: See [redlining.md](redlining.md)
**For OOXML details**: See [ooxml.md](ooxml.md)
</editing_documents>
</quick_start>
Claude reads redlining.md or ooxml.md only when the user needs those features.
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).
- Use forward slashes:
reference/guide.md(notreference\guide.md) - Name files descriptively:
form_validation_rules.md(notdoc2.md) - Organize by domain:
reference/finance.md,reference/sales.md
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
✅ Use pure XML structure:
<objective>
PDF processing with text extraction, form filling, and merging.
</objective>
<quick_start>
Extract text...
</quick_start>
<advanced_features>
Form filling...
</advanced_features>
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
scripts/helper.py (not scripts\helper.py)
<objective>, <quick_start>, and <success_criteria> (or <when_successful>).
- ✅ 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