skill-development

# Skill Development for Claude Code

## Overview

Skills are modular packages that extend Claude's capabilities by providing specialized knowledge, workflows, and resources. Think of them as "onboarding guides" that transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge.

**Key capabilities:**
- Create new skills with proper structure and frontmatter
- Edit existing skills to improve discovery and content
- Organize skills using progressive disclosure
- Validate skills against best practices
- Package skills for distribution

## When to Use This Skill

Use this skill when:
- **Creating** a new skill from scratch
- **Editing** an existing skill's description, instructions, or structure
- **Refactoring** skills for token optimization or progressive disclosure
- **Validating** skill structure and frontmatter
- **Organizing** skill content across SKILL.md, references/, examples/, scripts/

## Skill Anatomy

Every skill consists of a required SKILL.md and optional bundled resources:

```
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description)
│   └── Markdown body (core instructions)
└── Bundled Resources (optional)
    ├── references/    - Detailed docs loaded as needed
    ├── examples/      - Working code examples
    └── scripts/       - Utility scripts
```

### Progressive Disclosure

Skills use three-level loading to manage context:

| Level | When Loaded | Size Limit | Content |
|-------|-------------|------------|---------|
| **Metadata** | Always (startup) | ~100 words | `name` and `description` from frontmatter |
| **Instructions** | When triggered | <5k words (~1,500-2,000 words ideal) | SKILL.md body |
| **Resources** | As needed | Unlimited | references/, examples/, scripts/ |

**Design principle:** Keep SKILL.md lean. Move detailed content to references/.

## Quick Start: Create or Edit?

Determine from context whether user wants to create or edit. If unclear, ask:

```json
{
  "que