writing-skills

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

Writing Skills

Overview

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

Personal skills live in agent-specific directories (~/.claude/skills for Claude Code, ~/.codex/skills for Codex)

You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).

Core principle: If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.

REQUIRED BACKGROUND: You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.

Official guidance: For Anthropic's official skill authoring best practices, see anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill.

What is a Skill?

A skill is a reference guide for proven techniques, patterns, or tools. Skills help future Claude instances find and apply effective approaches.

Skills are: Reusable techniques, patterns, tools, reference guides

Skills are NOT: Narratives about how you solved a problem once

TDD Mapping for Skills

TDD Concept	Skill Creation
Test case	Pressure scenario with subagent
Production code	Skill document (SKILL.md)
Test fails (RED)	Agent violates rule without skill (baseline)
Test passes (GREEN)	Agent complies with skill present
Refactor	Close loopholes while maintaining compliance
Write test first	Run baseline scenario BEFORE writing skill
Watch it fail	Document exact rationalizations agent uses
Minimal code	Write skill addressing those specific violations
Watch it pass	Verify agent now complies
Refactor cycle	Find new rationalizations → plug → re-verify

The entire skill creation process follows RED-GREEN-REFACTOR.

When to Create a Skill

Create when:

• Technique wasn't intuitively obvious to you
• You'd reference this again across projects
• Pattern applies broadly (not project-specific)
• Others would benefit

Don't create for:

• One-off solutions
• Standard practices well-documented elsewhere
• Project-specific conventions (put in CLAUDE.md)
• Mechanical constraints (if it's enforceable with regex/validation, automate it—save documentation for judgment calls)

Skill Types

🧠 Knowledge Modules (Fractal Skills)

1. Technique

2. Pattern

3. Reference

4. 1. Rich Description Field

5. 2. Keyword Coverage

6. 3. Descriptive Naming

7. 4. Token Efficiency (Critical)

8. 4. Cross-Referencing Other Skills

9. Self-Contained Skill

10. Skill with Reusable Tool

11. Skill with Heavy Reference

12. Discipline-Enforcing Skills (rules/requirements)

13. Technique Skills (how-to guides)

14. Pattern Skills (mental models)

15. Reference Skills (documentation/APIs)

16. Close Every Loophole Explicitly

17. Address "Spirit vs Letter" Arguments

18. Build Rationalization Table

19. Create Red Flags List

20. Update CSO for Violation Symptoms

21. RED: Write Failing Test (Baseline)

22. GREEN: Write Minimal Skill

23. REFACTOR: Close Loopholes

24. ❌ Narrative Example

25. ❌ Multi-Language Dilution

26. ❌ Code in Flowcharts

27. ❌ Generic Labels