Creating Skills

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

Core Principles

Skills ARE TDD for Documentation

• Write failing test first - Run pressure scenario WITHOUT skill, document rationalizations

• Write minimal skill - Address those specific failures

• 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

• Understand - Gather concrete usage examples

• Plan - Identify reusable resources (scripts, references, assets)

• Initialize - Run scripts/init_skill.py <name> --path <dir>

• Edit - Implement resources, write SKILL.md

• Package - Run scripts/package_skill.py <path>

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

• How to execute from scratch

• 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

• Start with reusable resources identified in planning

• Test scripts by actually running them

• Delete unused example files

• 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

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

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