Writing Skills

REQUIRED BACKGROUND: Read ed3d-extending-claude:writing-claude-directives for foundational guidance on token efficiency, discovery optimization, and compliance techniques. This skill focuses on TDD methodology specific to skill creation.

Core Principle

Writing skills IS Test-Driven Development applied to process documentation.

Write test cases (pressure scenarios), watch them fail (baseline behavior), write the skill, watch tests pass, refactor (close loopholes).

Iron Law: No skill without a failing test first. Same as TDD for code.

TDD Mapping

TDD Concept Skill Creation

Test case Pressure scenario with subagent

Production code SKILL.md document

RED Agent violates rule without skill

GREEN Agent complies with skill present

Refactor Close loopholes, re-test

When to Create a Skill

Create when:

• Technique wasn't intuitively obvious

• You'd reference this across projects

• Pattern applies broadly

• Others would benefit

Don't create for:

• One-off solutions

• Standard practices documented elsewhere

• Project-specific conventions (use CLAUDE.md)

Skill Types

Technique: Concrete method with steps (condition-based-waiting, root-cause-tracing)

Pattern: Mental model for problems (flatten-with-flags, test-invariants)

Reference: API docs, syntax guides, tool documentation

Directory Structure

skills/ skill-name/ SKILL.md # Main reference (required) supporting-file.* # Only if needed

Separate files for: Heavy reference (100+ lines), reusable tools/scripts

Keep inline: Principles, code patterns (<50 lines), everything else

SKILL.md Template

name: Skill-Name-With-Hyphens description: Use when [triggers/symptoms] - [what it does, third person]

Skill Name

Overview

Core principle in 1-2 sentences.

When to Use

Symptoms and use cases. When NOT to use.

Core Pattern

Before/after comparison or key technique.

Quick Reference

Table or bullets for scanning.

Common Mistakes

What goes wrong + fixes.

RED-GREEN-REFACTOR Cycle

RED: Baseline Test

Run pressure scenario WITHOUT skill:

• Create combined pressures (time + sunk cost + exhaustion)

• Document exact violations and rationalizations verbatim

• Identify failure patterns

GREEN: Write Minimal Skill

• Address specific baseline failures identified in RED

• Run scenarios WITH skill

• Verify compliance

REFACTOR: Close Loopholes

• Find NEW rationalizations from testing

• Add explicit counters

• Re-test until bulletproof

REQUIRED: Use ed3d-extending-claude:testing-skills-with-subagents for complete methodology.

Testing by Skill Type

Type Test Approach Success Criteria

Discipline Pressure scenarios, combined stressors Follows rule under maximum pressure

Technique Application scenarios, edge cases Successfully applies to new scenario

Pattern Recognition + counter-examples Knows when/how and when NOT to apply

Reference Retrieval + application tests Finds and correctly uses information

Common Rationalizations to Block

Excuse Reality

"Obviously clear" Clear to you ≠ clear to agents. Test.

"Just a reference" References have gaps. Test retrieval.

"Testing is overkill" Untested skills have issues. Always.

"Too simple" Simple things break. Test anyway.

"No time" Fixing broken skills wastes more time.

All mean: Test before deploying.

Anti-Patterns

• Narrative example: "In session 2025-10-03, we found..." (too specific, not reusable)

• Multi-language dilution: example-js.js, example-py.py (mediocre quality, maintenance burden)

• Code in flowcharts: Can't copy-paste, hard to read

• Generic labels: helper1, step3 (labels need semantic meaning)

Skill Creation Checklist

IMPORTANT: Use TaskCreate to track each item (or TodoWrite in older Claude Code versions).

RED Phase:

• Create pressure scenarios (3+ combined pressures for discipline skills)

• Run WITHOUT skill - document baseline failures verbatim

• Identify rationalization patterns

GREEN Phase:

• Name uses letters, numbers, hyphens only

• Description starts with "Use when...", third person

• Address specific baseline failures

• One excellent example (not multi-language)

• Run WITH skill - verify compliance

REFACTOR Phase:

• Identify new rationalizations

• Add explicit counters

• Re-test until bulletproof

Deployment:

• Commit and push

• Consider contributing via PR