| name | creating-claude-code-skills |
|---|---|
| description | Guide for creating effective Claude Code Agent Skills. Use when users want to create, improve, or troubleshoot Skills that extend Claude's capabilities with specialized workflows, domain expertise, or tool integrations. |
Creating Claude Code Skills
Skills are modular packages that extend Claude's capabilities with specialized knowledge, workflows, and tools.
Quick Start
my-skill/
├── SKILL.md # Required: metadata + instructions
├── reference.md # Optional: detailed docs
└── scripts/ # Optional: utility scripts
└── helper.py
SKILL.md Structure
---
name: skill-name # lowercase, hyphens, max 64 chars
description: What it does and when to use it. Max 1024 chars.
---
# Skill Name
## Instructions
Clear, step-by-step guidance.
## Examples
Concrete input/output examples.
Core Principles
- Be Concise: Claude is smart. Only add context Claude doesn't already have.
- Progressive Disclosure: SKILL.md is overview. Details go in separate files.
- Match Freedom to Risk: Fragile operations need specific scripts; flexible tasks need general guidance.
Writing Effective Descriptions
The description field is critical for discovery. Include:
- What the skill does
- When to use it (triggers/contexts)
- Key terms users would mention
Good:
description: Extract text from PDF files, fill forms, merge documents. Use when working with PDF files, forms, or document extraction.
Bad:
description: Helps with documents
File Organization Patterns
Simple skill (single file):
commit-helper/
└── SKILL.md
Skill with references:
pdf-processing/
├── SKILL.md # Quick start + navigation
├── FORMS.md # Form-filling details
└── REFERENCE.md # API reference
Skill with scripts:
data-analysis/
├── SKILL.md
├── scripts/
│ └── validate.py
└── references/
└── schema.md
Key Guidelines
- Keep SKILL.md under 500 lines
- Use forward slashes in paths:
scripts/helper.py - Keep references one level deep from SKILL.md
- Use third person in descriptions
- Test with all models you plan to use
Skill Locations
- Personal:
~/.claude/skills/skill-name/ - Project:
.claude/skills/skill-name/
For detailed patterns, see references/patterns.md. For anti-patterns to avoid, see references/anti-patterns.md.