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

Core Principles

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

Skill Structure

skill-name/
├── SKILL.md              # Main instructions (< 500 lines)
└── 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)

Writing Effective Descriptions

Include trigger phrases the user might say:

# 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.

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:

• • Description includes triggers ("when user asks to...")
• • SKILL.md under 500 lines
• • Complex content moved to references/
• • Third person throughout
• • No time-sensitive information
• • Consistent terminology