Skill Creation

Create well-structured skills using progressive disclosure and project conventions.

Reference: best-practices.md for comprehensive guidance, reference.md for project patterns and frontmatter specs.

Workflow

Step 1: Understand Use Cases

Gather concrete examples of how the skill will be used:

• What tasks will it handle?
• What would users say to trigger it?
• What variations exist?

Skip this step only when usage patterns are already clearly understood.

Step 2: Plan Contents

Analyze each use case to identify reusable resources:

Step 3: Choose Frontmatter

Required fields:

name: skill-name          # Lowercase, hyphens, max 64 chars
description: |            # Max 1024 chars
  [What it does]. Use when [context].

Optional fields:

Naming pattern: <namespace>[-<subnamespace>]-<action>

• code-debug, spec-create, git-worktree-use

Description format: Third person, what + when.

• "Generate GitHub issue drafts from spec directories. Use when converting specs to GitHub issues."

Step 4: Create Structure

mkdir -p .claude/skills/{skill-name}

Standard structure:

.claude/skills/{skill-name}/
├── SKILL.md              # Main instructions (<500 lines)
├── templates/            # Document templates (.md)
├── scripts/              # Executable code (.sh, .py)
└── references/           # Extended documentation

Step 5: Implement & Test

Write SKILL.md:

• Keep under 200 lines (500 max)
• Progressive disclosure: SKILL.md → references/
• Include concrete examples, no emojis
• Reference authoritative docs (don't duplicate)

Test with real tasks:

1. Does the description trigger correctly?
2. Can Claude find bundled resources?
3. Does the workflow complete successfully?

Degrees of Freedom

Match specificity to task fragility:

High freedom - Multiple approaches valid, context-dependent:

## Code review
1. Analyze structure and organization
2. Check for bugs and edge cases
3. Suggest improvements

Low freedom - Operations fragile, consistency critical:

## Database migration
Run exactly: `python scripts/migrate.py --verify --backup`
Do not modify flags.

Skill Types

Success Criteria

• Name follows <namespace>[-<subnamespace>]-<action>
• Description is third person with what + when
• SKILL.md under 200 lines (500 max)
• Workflow steps numbered and actionable
• Templates extracted to separate files
• References point to authoritative sources
• No emojis (text markers only)

Reference

• best-practices.md - Core principles, patterns, checklist
• reference.md - Project patterns, frontmatter specs, anti-patterns