---

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.

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

Copyskill-name/
├── SKILL.md              # Main instructions (< 500 lines)
└── references/           # Detailed docs (loaded on demand)
    ├── guide.md
    └── examples/

YAML Frontmatter

Copy---
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:

Copy# 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:

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