Skill Creation

Skill Creation

Create effective, discoverable, and reliable skills using a test-driven approach.

Core principle: Creating skills IS Test-Driven Development applied to process documentation. If you did not watch an agent fail without the skill, you do not know if the skill teaches the right thing.

When to Use

• Creating a new skill for a recurring technique or workflow
• Editing an existing skill to improve quality or add missing patterns
• Reviewing a skill's description for CSO (triggering conditions, not workflow summary)
• Packaging skill content with progressive disclosure (SKILL.md + references/)
• Verifying a skill changes Claude's behavior before publishing

When NOT to Use

• Project-specific conventions (put in CLAUDE.md instead)
• One-off solutions that won't recur across projects
• Mechanical constraints enforceable by linting or validation (automate it)
• Standard practices well-documented in official docs

When to Create a Skill

Create when:

• Technique was not intuitively obvious
• You would reference this again across projects
• Pattern applies broadly (not project-specific)
• Others would benefit

Skill Anatomy

skill-name/
  SKILL.md              # Main reference (required)
  scripts/              # Executable code
  references/           # Documentation loaded on demand
  assets/               # Files used in output (templates, fonts)

SKILL.md Structure

---
name: kebab-case-name
description: Use when [specific triggering conditions and symptoms]
allowed-tools:            # Optional: minimum tools needed
  - Read
  - Glob
---

# Skill Name

## Overview
What is this? Core principle in 1-2 sentences.

## When to Use
Bullet list with SYMPTOMS and use cases.

## When NOT to Use
Scenarios with named alternatives.

## Core Pattern / Process / Quick Reference
[Main content]

## Common Mistakes
What goes wrong + fixes.

## Verification
Checklist for output validation.

Frontmatter Requirements

• name: Letters, numbers, and hyphens only. Verb-first active voice: creating-skills not skill-creation.
• description: Max 1024 characters total. Third-person, starts with "Use when..." Include specific symptoms, situations, contexts. Never summarize the skill's workflow.

Claude Search Optimization (CSO)

The description field is the ONLY thing that controls when a skill activates.

Critical Rule: Description = Triggering Conditions ONLY

# BAD: Summarizes workflow — Claude may follow this instead of reading skill
description: Use when executing plans — dispatches subagent per task with code review

# GOOD: Just triggering conditions, no workflow summary
description: Use when executing implementation plans with independent tasks in the current session

Why this matters: Testing revealed that when a description summarizes workflow, Claude may follow the description as a shortcut instead of reading the full skill. A description saying "code review between tasks" caused Claude to do ONE review, even though the skill showed TWO reviews. Changing to just triggering conditions fixed it.

Keyword Coverage

Use words Claude would search for:

• Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
• Symptoms: "flaky", "hanging", "zombie", "pollution"
• Tools: Actual commands, library names, file types

Progressive Disclosure

Skills use a three-level loading system:

1. Metadata (name + description) — Always in context (~100 words)
2. SKILL.md body — When skill triggers (target <500 lines)
3. Bundled resources — As needed (unlimited)

Content Splitting Rules

All references must be one hop from SKILL.md. No reference chains (A → B → C).

Workflow Skill Patterns

Phase Structure

Every phase needs:

• A number (Phase 1, Phase 2, ...)
• Entry criteria (what must be true before starting)
• Numbered actions (what to do)
• Exit criteria (how to know it is done)

Unnumbered prose instructions produce unreliable execution order.

The TDD Process for Skills

The Iron Law

NO SKILL WITHOUT A FAILING TEST FIRST

Write skill before testing? Delete it. Start over.

RED-GREEN-REFACTOR for Skills

RED (Baseline): Run pressure scenarios with a subagent WITHOUT the skill. Document:

• What choices did the agent make?
• What rationalizations did it use (verbatim)?
• Which pressures triggered violations?

GREEN (Write Skill): Write the skill addressing those specific rationalizations. Run the same scenarios WITH the skill. Agent should now comply.

REFACTOR (Close Loopholes): Agent found a new rationalization? Add explicit counter. Re-test until bulletproof.

Bulletproofing Against Rationalization

Close Every Loophole Explicitly

Do not just state the rule — forbid specific workarounds:

Write code before test? Delete it. Start over.

**No exceptions:**
- Do not keep it as "reference"
- Do not "adapt" it while writing tests
- Delete means delete

Build a Rationalization Table

Capture rationalizations from baseline testing:

Anti-Pattern Quick Reference

Quantitative Eval Framework

Before publishing any skill, verify it actually changes Claude's behavior:

1. Run a baseline — execute the target scenario WITHOUT the skill loaded. Document the output verbatim.
2. Run with the skill — execute the same scenario WITH the skill loaded.
3. Score on 3–5 behavioral markers — concrete, binary checks:
   • Does the specific framework or process appear in the output?
   • Is domain-specific vocabulary used correctly?
   • Is the output structured per the skill's specified format?
   • Are the required phases or steps present?
   • Are prohibited patterns absent?
4. Target: >80% marker pass rate before publishing. Below 80% means the skill content is too generic or the description isn't loading it reliably.
5. If with-skill output equals baseline output, the skill is not working — either the description needs sharper trigger conditions or the content needs to be more prescriptive.

Description Optimization Loop

Treat the description as a retrieval query that must match how users actually phrase requests.

1. Write 10 realistic trigger prompts — things real users would type, not abstract descriptions of the skill.
2. Test each: does Claude load the skill for that prompt? Track pass/fail.
3. Iterate on trigger terms until ≥8/10 prompts activate the skill.

Common failure: description summarizes the workflow instead of listing trigger conditions.

# BAD: workflow summary
description: "Covers the full lifecycle of skill development from drafting to publishing."

# GOOD: trigger conditions with keyword list
description: "Use when creating a new SKILL.md, editing an existing skill for quality or discoverability,
  or testing whether a skill changes Claude's behavior. Triggers: 'create a skill', 'edit skill',
  'skill description', 'SKILL.md', 'skill not triggering'."

Skill Creation Checklist

RED Phase

• Create pressure scenarios (3+ combined for discipline skills)
• Run scenarios WITHOUT skill — document baseline behavior verbatim
• Identify patterns in rationalizations/failures

GREEN Phase

• Name uses only letters, numbers, hyphens
• YAML frontmatter with name and description (max 1024 chars)
• Description starts with "Use when..." — triggering conditions only
• Description in third person, no workflow summary
• Keywords throughout for search
• When to Use AND When NOT to Use sections
• Content addresses specific baseline failures from RED phase
• SKILL.md under 500 lines; heavy content in references/
• No broken file references; all links one hop from SKILL.md
• Run scenarios WITH skill — verify agents now comply

REFACTOR Phase

• Identify new rationalizations from testing
• Add explicit counters for each
• Build rationalization table
• Create red flags list
• Re-test until bulletproof

Deployment

• Validate frontmatter, naming, structure
• Run skill-scanner on the skill directory before installing — check for hooks, scripts, symlinks, payload patterns
• Commit skill and push
• Test one more time in clean context
• Do NOT batch-create multiple skills without testing each