---

name: writing-skills description: Use when creating new skills, editing existing skills, or verifying skills work before deployment

Writing Skills

Invariant Principles

1. No Skill Without Failing Test: Run scenario WITHOUT skill first. Document baseline failures verbatim. Same as code TDD.
2. Description Triggers, Not Summarizes: Description = when to load, never workflow summary. Workflow in description causes agents to skip body.
3. One Excellent Example Beats Many: Single complete, runnable example in relevant language. You port well.
4. Keywords Enable Discovery: Error messages, symptoms, synonyms throughout. Future Claude must FIND this.
5. Close Every Loophole Explicitly: Agents rationalize under pressure. Each excuse needs explicit counter.

Inputs

Outputs

Skill Types

SKILL.md Schema

Copyskills/<name>/
  SKILL.md              # Required. Main content inline
  supporting-file.*     # Only for heavy reference (100+ lines) or reusable tools

Frontmatter (YAML only):

Copy---
name: skill-name-with-hyphens   # letters, numbers, hyphens only
description: Use when [triggering conditions and symptoms only, NEVER workflow]
---

Required sections:

Copy# 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
[Small inline flowchart IF decision non-obvious]

## Core Pattern (for techniques/patterns)
Before/after code comparison

## Quick Reference
Table or bullets for scanning common operations

## Implementation
Inline code for simple patterns
Link to file for heavy reference

## Common Mistakes
What goes wrong + fixes

Naming Conventions

Principles:

• Name by what you DO or core insight, not generic category
• root-cause-tracing > debugging-techniques
• using-skills not skill-usage

Claude Search Optimization (CSO)

Copy# BAD: Workflow summary - agents skip body
description: Use when executing plans - dispatches subagent per task with code review

# GOOD: Triggers only - forces reading body
description: Use when executing implementation plans with independent tasks

Keyword coverage:

• Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
• Symptoms: "flaky", "hanging", "zombie", "pollution"
• Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
• Tools: Actual commands, library names, file types

Iron Law

CopyNO SKILL WITHOUT FAILING TEST FIRST

Write skill before testing? Delete it. Start over. Edit skill without testing? Same violation.

No exceptions:

• Not for "simple additions"
• Not for "just adding a section"
• Not for "documentation updates"
• Don't keep untested changes as "reference"
• Don't "adapt" while running tests
• Delete means delete

RED-GREEN-REFACTOR

RED - Write Failing Test (Baseline):

Run pressure scenario with subagent WITHOUT the skill. Document:

• What choices did they make?
• What rationalizations did they use (verbatim quotes)?
• Which pressures triggered violations?

This is "watch the test fail" - you must see what agents naturally do.

GREEN - Write Minimal Skill:

Write skill addressing those specific rationalizations. Don't add extra content for hypothetical cases. Run same scenarios WITH skill. Agent should now comply.

REFACTOR - Close Loopholes:

Agent found new rationalization? Add explicit counter. Re-test until bulletproof.

Bulletproofing Discipline Skills

Build rationalization table from testing:

Red flags list (agents self-check):

• Code before test
• "I already manually tested it"
• "Tests after achieve the same purpose"
• "It's about spirit not ritual"
• "This is different because..."

All of these mean: Delete code. Start over with TDD.

Token Efficiency

Targets:

• Getting-started skills: <150 words
• Frequently-loaded skills: <200 words
• Other skills: <500 words

Techniques:

• Reference --help instead of documenting all flags
• Cross-reference other skills: **REQUIRED BACKGROUND:** test-driven-development
• One excellent example, not multi-language
• No @ links (force-loads files, burns context)

File Organization

Code Examples

One excellent example beats many mediocre ones.

Choose most relevant language:

• Testing techniques → TypeScript/JavaScript
• System debugging → Shell/Python
• Data processing → Python

Good example: Complete, runnable, well-commented explaining WHY, from real scenario, ready to adapt.

Don't: Implement in 5+ languages, create fill-in-the-blank templates, write contrived examples.

Flowchart Usage

Use ONLY for:

• Non-obvious decision points
• Process loops where you might stop too early
• "When to use A vs B" decisions

Never use for: Reference material (→ tables), Code examples (→ markdown), Linear instructions (→ numbered lists).

Anti-Patterns

Discovery Workflow

How future Claude finds your skill:

1. Encounters problem ("tests are flaky")
2. Finds SKILL (description matches)
3. Scans overview (is this relevant?)
4. Reads patterns (quick reference table)
5. Loads example (only when implementing)

Optimize for this flow - searchable terms early and often.

Skill Creation Checklist

Use TodoWrite to create todos for EACH item.

RED Phase:

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

GREEN Phase:

• Name uses only letters, numbers, hyphens
• YAML frontmatter with name and description (<1024 chars)
• Description starts "Use when..." - triggers only, NO workflow
• Description in third person
• Keywords throughout (errors, symptoms, tools)
• Clear overview with core principle
• Address specific baseline failures from RED
• One excellent example (not multi-language)
• Run scenarios WITH skill - verify compliance

REFACTOR Phase:

• Identify NEW rationalizations from testing
• Add explicit counters (for discipline skills)
• Build rationalization table from all test iterations
• Create red flags list
• Re-test until bulletproof

Quality Checks:

• Quick reference table for scanning
• Common mistakes section
• Small flowchart only if decision non-obvious
• No narrative storytelling
• Supporting files only for tools or heavy reference

Deploy:

• Commit skill to git
• Push to fork if configured
• Consider PR if broadly useful

Self-Check

Before completing:

• RED phase documented: baseline agent behavior captured verbatim
• GREEN phase verified: skill changes behavior in re-run
• Description starts "Use when..." and contains only triggers
• YAML frontmatter has name and description
• Schema elements present: Overview, When to Use, Quick Reference, Common Mistakes
• Token budget met: <500 words core instructions
• No workflow summary in description
• Rationalization table built (for discipline skills)

If ANY unchecked: STOP and fix before declaring complete.

<FINAL_EMPHASIS> Creating skills IS TDD for process documentation. Same Iron Law: No skill without failing test first. Same cycle: RED (baseline) → GREEN (write skill) → REFACTOR (close loopholes). If you follow TDD for code, follow it for skills. Untested skills are untested code - they will break in production.

REQUIRED BACKGROUND: Understand test-driven-development skill before using this skill. </FINAL_EMPHASIS>