name: claude-code-skill-development description: This skill should be used when the user asks to "create a skill", "write a skill", "build a skill", or wants to add new capabilities to Claude Code. Use when developing SKILL.md files, organizing skill content, or improving existing skills. allowed-tools: Read, Grep

Skill Development

Create effective Claude Code skills that are concise, discoverable, and well-structured.

Quick Reference

You MUST read these references for detailed guidance:

Best Practices - Official Anthropic guidance
Skill Examples - Patterns from real skills
Skill Categories & Patterns - Three categories and five reusable patterns
Testing Guide - Triggering, functional, and performance testing
Troubleshooting - Common problems and fixes
The Complete Guide to Building Skills for Claude - Comprehensive Anthropic guide (source PDF)

Before You Start

Define 2-3 concrete use cases before writing anything:

Use Case: [Name]
Trigger: User says "[phrase]" or "[phrase]"
Steps:
1. [First action]
2. [Second action]
Result: [What gets produced]

Then identify which category your skill falls into — this determines which techniques to use. See Skill Categories & Patterns.

Core Principles

Concise is key - Only add context Claude doesn't already have
Progressive disclosure - SKILL.md is the overview; details go in references/
Write in third person - "This skill processes..." not "I can help you..."

Skill Structure

skill-name/
├── SKILL.md              # Main instructions (< 500 lines)
├── scripts/              # Optional: executable code (Python, Bash, etc.)
├── assets/               # Optional: templates, fonts, icons
└── references/           # Detailed docs (loaded on demand)
    ├── guide.md
    └── examples/

YAML Frontmatter

---
name: my-skill-name
description: This skill should be used when the user asks to "do X", "create Y", or mentions Z. Be specific about triggers.
context: fork          # Optional: run in isolated context (prevents side effects)
user-invocable: true   # Optional: show in slash command menu (default: true)
---

Name rules:

Lowercase letters, numbers, hyphens only
Max 64 characters
No reserved words (anthropic, claude)

Description rules:

Max 1024 characters
Third person ("This skill..." not "I can...")
Include WHAT it does AND WHEN to use it

Optional fields:

context: fork - Run skill in isolated sub-agent context, preventing unintended side effects on main agent state
user-invocable: false - Hide from slash command menu (skills are visible by default)
allowed-tools - Restrict which tools the skill can use (e.g., "Bash(python:*) Bash(npm:*) WebFetch"). Skills with references/ directories should include allowed-tools: Read, Grep to avoid permission prompts when accessing bundled files (claude-code#15757)
license - e.g., MIT, Apache-2.0
compatibility - Environment requirements (1-500 chars)
metadata - Custom key-value pairs (author, version, mcp-server)

Writing Effective Descriptions

Structure: [What it does] + [When to use it] + [Key capabilities]

# Good - specific triggers
description: This skill should be used when the user asks to "create a hook", "add a hook", or mentions Claude Code hooks.

# Bad - vague
description: Helps with automation tasks.

Progressive Disclosure Pattern

Keep SKILL.md under 500 lines. Link to details:

# My Skill

## Quick start
[Essential info here]

## Advanced features
See [detailed-guide.md](./references/detailed-guide.md)

## API reference
See [api-reference.md](./references/api-reference.md)

Claude loads reference files only when needed.

Testing Your Skill

Validate across three dimensions before sharing:

Triggering - Does it load when it should? Not load when it shouldn't?
Functional - Does it produce correct outputs and handle errors?
Performance - Is it actually better than no skill? (fewer messages, fewer errors, less tokens)

See Testing Guide for test examples and success criteria.

Troubleshooting

Common issues and fixes:

Symptom	Fix
Doesn't trigger	Add specific trigger phrases to description
Triggers too often	Add negative triggers, narrow scope
Instructions ignored	Make instructions concise, use explicit headers
Slow responses	Move content to `references/`, reduce SKILL.md size

See Troubleshooting for detailed solutions.

Important

After creating or modifying skills, inform the user:

No restart needed. Skill changes take effect immediately - skills are hot-reloaded.

Checklist

Before finalizing a skill:

Name	skill-development
Description	This skill should be used when the user asks to "create a skill", "write a skill", "build a skill", or wants to add new capabilities to Claude Code. Use when developing SKILL.md files, organizing skill content, or improving existing skills.