Guide users through creating Agent Skills for Claude Code. Use when the user wants to create, write, author, or design a new Skill, or needs help with SKILL.md files, frontmatter, or skill structure.
This Skill helps you create well-structured Agent Skills for Claude Code that follow best practices and validation requirements.
Use this Skill when:
First, understand what the Skill should do:
Ask clarifying questions:
Keep it focused: One Skill = one capability
Determine where to create the Skill:
Personal Skills (~/.claude/skills/):
Project Skills (.claude/skills/):
Create the directory and files:
# Personal
mkdir -p ~/.claude/skills/skill-name
# Project
mkdir -p .claude/skills/skill-name
For multi-file Skills:
skill-name/
├── SKILL.md (required)
├── reference.md (optional)
├── examples.md (optional)
├── scripts/
│ └── helper.py (optional)
└── templates/
└── template.txt (optional)
Create YAML frontmatter with required fields:
---
name: skill-name
description: Brief description of what this does and when to use it
---
Field requirements:
name:
pdf-processor, git-commit-helperPDF_Processor, Git Commits!description:
Optional frontmatter fields:
allowed-tools: Read, Grep, Glob
The description is critical for Claude to discover your Skill.
Formula: [What it does] + [When to use it] + [Key triggers]
Examples:
✅ Good:
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.
✅ Good:
description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.
❌ Too vague:
description: Helps with documents
description: For data analysis
Tips:
Use clear Markdown sections:
# Skill Name
Brief overview of what this Skill does.
## Quick start
Provide a simple example to get started immediately.
## Instructions
Step-by-step guidance for Claude:
1. First step with clear action
2. Second step with expected outcome
3. Handle edge cases
## Examples
Show concrete usage examples with code or commands.
## Best practices
- Key conventions to follow
- Common pitfalls to avoid
- When to use vs. not use
## Requirements
List any dependencies or prerequisites:
```bash
pip install package-name
For complex scenarios, see reference.md.
### Step 7: Add supporting files (optional)
Create additional files for progressive disclosure:
**reference.md**: Detailed API docs, advanced options
**examples.md**: Extended examples and use cases
**scripts/**: Helper scripts and utilities
**templates/**: File templates or boilerplate
Reference them from SKILL.md:
```markdown
For advanced usage, see [reference.md](reference.md).
Run the helper script:
\`\`\`bash
python scripts/helper.py input.txt
\`\`\`
Check these requirements:
✅ File structure:
name✅ YAML frontmatter:
--- on line 1--- before contentname follows naming rulesdescription is specific and < 1024 chars✅ Content quality:
✅ Testing:
Restart Claude Code (if running) to load the Skill
Ask relevant questions that match the description:
Can you help me extract text from this PDF?
Verify activation: Claude should use the Skill automatically
Check behavior: Confirm Claude follows the instructions correctly
If Claude doesn't use the Skill:
Make description more specific:
Check file location:
ls ~/.claude/skills/skill-name/SKILL.md
ls .claude/skills/skill-name/SKILL.md
Validate YAML:
cat SKILL.md | head -n 10
Run debug mode:
claude --debug
---
name: code-reader
description: Read and analyze code without making changes. Use for code review, understanding codebases, or documentation.
allowed-tools: Read, Grep, Glob
---
---
name: data-processor
description: Process CSV and JSON data files with Python scripts. Use when analyzing data files or transforming datasets.
---
# Data Processor
## Instructions
1. Use the processing script:
\`\`\`bash
python scripts/process.py input.csv --output results.json
\`\`\`
2. Validate output with:
\`\`\`bash
python scripts/validate.py results.json
\`\`\`
---
name: api-designer
description: Design REST APIs following best practices. Use when creating API endpoints, designing routes, or planning API architecture.
---
# API Designer
Quick start: See [examples.md](examples.md)
Detailed reference: See [reference.md](reference.md)
## Instructions
1. Gather requirements
2. Design endpoints (see examples.md)
3. Document with OpenAPI spec
4. Review against best practices (see reference.md)
Before finalizing a Skill, verify:
Skill doesn't activate:
Multiple Skills conflict:
Skill has errors:
See the documentation for complete examples:
When creating a Skill, I will:
The result will be a complete, working Skill that follows all best practices and validation rules.
