Guide for creating effective Claude Code skills. Use when creating new skills, refactoring existing skills, or validating skill structure. Covers YAML frontmatter, progressive disclosure, naming conventions, and best practices.
Provides guidelines for creating effective Claude Code skills with YAML frontmatter and structure.
/plugin marketplace add hgeldenhuys/claude-code-sdk/plugin install hgeldenhuys-session-naming@hgeldenhuys/claude-code-sdkThis skill inherits all available tools. When active, it can use any tool Claude has access to.
EXAMPLES.mdTEMPLATES.mdCreate effective Claude Code skills that are concise, well-structured, and follow official best practices.
| Element | Requirement |
|---|---|
| Filename | SKILL.md in skill directory |
| Name | Lowercase, hyphens, numbers only (max 64 chars) |
| Description | Third person, max 1024 chars |
| Main file | Under 500 lines |
| References | One level deep from SKILL.md |
Every skill requires frontmatter:
---
name: skill-name
description: Third person description of what skill does and when to use it. Include trigger phrases.
allowed-tools: ["Read", "Write", "Edit", "Glob", "Grep", "Bash"] # Optional
model: sonnet # Optional: opus, sonnet, haiku
---
| Field | Required | Notes |
|---|---|---|
name | Yes | Lowercase letters, numbers, hyphens. Max 64 chars |
description | Yes | Third person. Max 1024 chars. Include when to use |
allowed-tools | No | Restricts which tools the skill can use |
model | No | Force specific model (opus, sonnet, haiku) |
context | No | Set to fork to run in sub-agent context |
agent | No | Agent type when context: fork (requires context) |
hooks | No | Lifecycle-scoped hooks (PreToolUse, PostToolUse, Stop) |
user-invocable | No | false hides from slash menu but allows Skill tool |
disable-model-invocation | No | true blocks Skill tool invocation |
Use gerund form (verb ending in -ing):
| Good | Avoid |
|---|---|
writing-skills | skill-writer |
debugging-api | api-debugger |
creating-hooks | hook-creator |
Rules:
Keep SKILL.md focused. Split detailed content to reference files.
## Reference Files
| File | Contents |
|------|----------|
| [TEMPLATES.md](./TEMPLATES.md) | Starter templates |
| [EXAMPLES.md](./EXAMPLES.md) | Real-world examples |
| [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) | Common issues |
For detailed templates, see [TEMPLATES.md](./TEMPLATES.md).
## Advanced Configuration
If you need custom model settings, see [ADVANCED.md](./ADVANCED.md).
skills/
└── skill-name/
├── SKILL.md # Main skill file (required)
├── TEMPLATES.md # Starter templates (optional)
├── EXAMPLES.md # Detailed examples (optional)
└── TROUBLESHOOTING.md # Common issues (optional)
Skills are discovered from these locations:
| Location | Scope | Priority |
|---|---|---|
.claude/skills/ | Current project | Highest |
~/.claude/skills/ | All your projects | Lower |
Plugin skills/ | Where plugin enabled | Lowest |
Nested Skills Discovery (2.1.6+): When working with files in subdirectories, Claude Code automatically discovers skills from nested .claude/skills directories. This enables monorepos and multi-package projects to have package-specific skills.
my-monorepo/
├── .claude/skills/ # Root skills (always available)
│ └── deploy/
├── packages/
│ ├── frontend/
│ │ └── .claude/skills/ # Auto-discovered when working in frontend/
│ │ └── component-generator/
│ └── backend/
│ └── .claude/skills/ # Auto-discovered when working in backend/
│ └── api-scaffolder/
Descriptions appear in skill discovery. Make them count.
[What it does]. [When to use it]. [Key triggers/phrases].
Good:
Guide for creating effective Claude Code skills. Use when creating new
skills, refactoring existing skills, or validating skill structure.
Covers YAML frontmatter, progressive disclosure, and naming conventions.
Avoid:
A skill for writing skills.
Include step-by-step workflows with copyable checklists.
## Workflow: [Name]
### Prerequisites
- [ ] Requirement 1
- [ ] Requirement 2
### Steps
1. **Step Name**
- [ ] Action item
- [ ] Action item
2. **Step Name**
- [ ] Action item
### Validation
- [ ] Check 1
- [ ] Check 2
Show concrete input/output pairs.
## Examples
### Example: [Scenario Name]
**Input:**
User request or context
**Output:**
Expected result or response
**Why:** Brief explanation of approach.
Before finalizing a skill:
| Mistake | Fix |
|---|---|
| Over 500 lines | Split to reference files |
| Vague description | Add specific triggers and use cases |
| No workflows | Add step-by-step procedures |
| Missing examples | Add input/output pairs |
| Deep file nesting | Keep references one level deep |
Run skills in an isolated sub-agent context using context: fork:
---
name: complex-analysis
description: Deep analysis that benefits from isolated context
context: fork
agent: Explore # Optional: specify agent type
---
When to use:
Control how skills appear and can be invoked:
| Setting | Slash Menu | Skill Tool | Use Case |
|---|---|---|---|
| (default) | Visible | Allowed | Normal skill |
user-invocable: false | Hidden | Allowed | Model-only skills |
disable-model-invocation: true | Visible | Blocked | User-only skills |
| Both false/true | Hidden | Blocked | Completely hidden |
---
name: internal-helper
description: Helper skill only invoked by other skills
user-invocable: false # Hide from slash menu
---
Add lifecycle hooks that run during skill execution:
---
name: validated-deploy
description: Deploy with validation hooks
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./validate.sh"
once: true
---
See creating-hooks for complete hook documentation.
Skills can be auto-loaded for custom subagents using the skills field in agent definitions:
# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code using specialized skills
skills:
- code-review
- security-practices
---
Note: Built-in agents (Explore, Plan, general-purpose) do not have skill access.
| File | Contents |
|---|---|
| TEMPLATES.md | Starter templates for new skills |
| EXAMPLES.md | Real-world skill examples |
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.