SKILL.md File Format Complete Guide

The SKILL.md file is the heart of every Claude Skill. Master its format to create professional, reliable skills.

File Structure

According to the official Anthropic Skills repository, a SKILL.md file uses YAML frontmatter:


markdown
1---
2name: my-skill-name
3description: A clear description of what this skill does and when to use it
4---
5
6# My Skill Name
7
8[Add your instructions here that Claude will follow when this skill is active]
9
10## Examples
11- Example usage 1
12- Example usage 2
13
14## Guidelines
15- Guideline 1
16- Guideline 2
1---
2name: my-skill-name
3description: A clear description of what this skill does and when to use it
4---
5
6# My Skill Name
7
8[Add your instructions here that Claude will follow when this skill is active]
9
10## Examples
11- Example usage 1
12- Example usage 2
13
14## Guidelines
15- Guideline 1
16- Guideline 2

Frontmatter (Required)

The YAML frontmatter at the top requires only two fields:

name: A unique identifier for your skill (lowercase, hyphens for spaces)
description: A complete description of what the skill does and when to use it

Example:


yaml
---
name: pdf-extractor
description: Extract text, tables, and form data from PDF documents for analysis and processing
---
---
name: pdf-extractor
description: Extract text, tables, and form data from PDF documents for analysis and processing
---

Instructions Section

Write clear, actionable steps:


markdown
1## Instructions
2When processing documents:
31. Validate input format
42. Extract content sections
53. Apply transformations
64. Validate output
75. Return structured data
1## Instructions
2When processing documents:
31. Validate input format
42. Extract content sections
53. Apply transformations
64. Validate output
75. Return structured data

Best Practices:

Use numbered lists for sequences
Include decision points ("If X, then Y")
Define expected inputs/outputs
Specify error conditions

Usage Examples

Provide concrete examples:


markdown
1## Usage Examples
2
3### Example 1: Basic Processing
4**Input**: document.pdf
5**Output**: {"text": "...", "pages": 5}
6
7### Example 2: With Options
8**Input**: document.pdf, {"extract_images": true}
9**Output**: {"text": "...", "images": [...]}
1## Usage Examples
2
3### Example 1: Basic Processing
4**Input**: document.pdf
5**Output**: {"text": "...", "pages": 5}
6
7### Example 2: With Options
8**Input**: document.pdf, {"extract_images": true}
9**Output**: {"text": "...", "images": [...]}

Dependencies

List all requirements:


markdown
1## Dependencies
2- Python: >= 3.8
3- PyPDF2: >= 3.0.0
4- pdfplumber: >= 0.9.0
5
6Install with:
7```bash
8pip install PyPDF2 pdfplumber
1## Dependencies
2- Python: >= 3.8
3- PyPDF2: >= 3.0.0
4- pdfplumber: >= 0.9.0
5
6Install with:
7```bash
8pip install PyPDF2 pdfplumber


## Advanced Features

### Conditional Logic

```markdown
If document is encrypted:
1. Request password
2. Decrypt content
3. Proceed with extraction
Otherwise:
- Process directly

Multi-Step Workflows


markdown
1Phase 1: Preparation
2- Validate inputs
3- Set up environment
4
5Phase 2: Processing
6- Execute main logic
7- Collect results
8
9Phase 3: Cleanup
10- Remove temp files
11- Return final output
1Phase 1: Preparation
2- Validate inputs
3- Set up environment
4
5Phase 2: Processing
6- Execute main logic
7- Collect results
8
9Phase 3: Cleanup
10- Remove temp files
11- Return final output

Common Mistakes

❌ Vague instructions: "Process the file" ✅ Clear instructions: "Extract text from pages 1-10"

❌ Missing error handling: No failure cases ✅ Complete error handling: Specify all error scenarios

❌ No examples: Just instructions ✅ Rich examples: Multiple use cases demonstrated

Validation Checklist

[ ] All metadata fields present
[ ] Instructions are numbered and clear
[ ] At least 2 usage examples provided
[ ] Dependencies listed with versions
[ ] Error handling documented
[ ] Security considerations noted

Resources

Reading Time: 4 minutes

Author: ClaudeSkills Team