Creating Skills

This skill provides guidance for creating effective skills using TDD methodology.

Core Principles

Skills ARE TDD for Documentation

1. Write failing test first - Run pressure scenario WITHOUT skill, document rationalizations
2. Write minimal skill - Address those specific failures
3. Watch pass, refactor - Find new loopholes, plug them, re-test

If you didn't watch an agent fail without it, you don't know what to teach.

Concise is Key

The context window is a public good. Default assumption: Claude is already very smart. Only add context Claude doesn't already have. Challenge each piece: "Does Claude really need this explanation?"

Prefer concise examples over verbose explanations.

Set Appropriate Degrees of Freedom

Match specificity to task fragility:

Freedom Level	When to Use	Examples
High (text)	Multiple valid approaches, context-dependent	Heuristics, guidelines
Medium (pseudocode)	Preferred pattern exists, some variation OK	Configurable scripts
Low (scripts)	Fragile operations, consistency critical	Specific sequences

Quick Reference

Phase	Action
RED	Run pressure scenario WITHOUT skill, document rationalizations
GREEN	Write minimal skill addressing those failures
REFACTOR	Find new loopholes, plug them, re-test

Skill Type	Test Focus
Technique	Recognition + application under pressure
Pattern	When to apply + when NOT to apply
Reference	Can agent find and use information?

When to Create

Create when: Technique wasn't obvious, applies broadly, others benefit Don't create for: One-offs, standard practices, project-specific (use CLAUDE.md)

Anatomy of a Skill

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation loaded as needed
    └── assets/           - Files used in output (templates, icons, fonts)

Frontmatter

---
name: skill-name-with-hyphens
description: Use when [triggering conditions only, never workflow summary]
---

• name: Letters, numbers, hyphens only
• description: Primary triggering mechanism. Start "Use when...", max 1024 chars, third person
  • Include what the Skill does AND specific triggers/contexts for when to use it
  • Include ALL "when to use" here - NOT in the body (body loads only after triggering)
  • ❌ Workflow summaries create shortcuts - agent skips body

Bundled Resources

Directory	Purpose	When to Include
scripts/	Executable code	Same code rewritten repeatedly, deterministic reliability needed
references/	Documentation	Information Claude should reference while working
assets/	Output files	Templates, images, fonts used in final output

Avoid duplication: Information lives in SKILL.md OR references, not both. Keep SKILL.md lean (<500 lines).

What NOT to Include

• README.md, INSTALLATION_GUIDE.md, CHANGELOG.md
• Setup/testing procedures, user-facing documentation
• Auxiliary context about creation process

Skill Creation Process

1. Understand - Gather concrete usage examples
2. Plan - Identify reusable resources (scripts, references, assets)
3. Initialize - Run scripts/init_skill.py <name> --path <dir>
4. Edit - Implement resources, write SKILL.md
5. Package - Run scripts/package_skill.py <path>
6. Iterate - Test and refine based on real usage

Step 1: Understanding with Examples

Ask questions like:

• "What functionality should this skill support?"
• "Can you give examples of how this skill would be used?"
• "What would a user say that should trigger this skill?"

Step 2: Planning Resources

For each example, analyze:

1. How to execute from scratch
2. What scripts, references, assets would help when repeating

Step 3: Initializing

scripts/init_skill.py <skill-name> --path <output-directory>

Creates skill directory with SKILL.md template and example resource directories.

Step 4: Editing

1. Start with reusable resources identified in planning
2. Test scripts by actually running them
3. Delete unused example files
4. Update SKILL.md (always use imperative/infinitive form)

Step 5: Packaging

scripts/package_skill.py <path/to/skill-folder> [output-dir]

Validates and creates .skill file (zip with .skill extension).

Step 6: Iterate

STOP Before Next Skill: After writing ANY skill, complete deployment before creating another. Untested skills = untested code.

Progressive Disclosure

Keep SKILL.md body to essentials (<500 lines). Split content into separate files when approaching limit.

Pattern 1: High-level guide with references

## Quick start
[code example]

## Advanced features
- **Feature A**: See [A.md](references/A.md)

Pattern 2: Domain-specific organization

references/
├── finance.md
├── sales.md
└── product.md

Pattern 3: Conditional details

For simple edits, modify directly.
**For advanced feature**: See [ADVANCED.md](references/ADVANCED.md)

Guidelines:

• Avoid deeply nested references - keep one level deep from SKILL.md
• Structure longer files (>100 lines) with table of contents

Anti-Patterns

Pattern	Problem
❌ Narrative	"In session 2025-10-03, we found..." (too specific)
❌ Multi-language	example-js.js, example-py.py (maintenance burden)
❌ Workflow in description	Creates shortcut, agent skips body
❌ Batching skills	Test each before moving to next

References

TDD & Testing

• TDD Mapping - RED-GREEN-REFACTOR cycle for skills
• Skill Types - Technique, Pattern, Reference testing
• Testing Methodology - Full checklist
• Bulletproofing - Closing rationalization loopholes

Structure & Design

• Skill Structure - Directory layout and template
• CSO - Claude Search Optimization for discovery
• Workflows - Sequential workflows and conditional logic
• Output Patterns - Template and example patterns

Related

• sharing-skills - Contributing skills upstream
• maestro-core - Workflow routing and skill hierarchy