What is the Iron Law of skill creation?

No skill should be created or edited without a failing test first. If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.

What is TDD for documentation?

It is the practice of testing an AI agent's failure on a task before writing the instructions to fix it, ensuring the documentation is truly effective and necessary.

How does this help with Claude's context window?

The skill provides strict guidelines for token efficiency, moving heavy references to external files and keeping core instructions under specific word counts.

Why use subagents for testing skills?

Subagents allow you to simulate specific pressure scenarios to see if an agent complies with your documentation or finds loopholes through rationalization.

TDD for Documentation Skills

Name: TDD for Documentation Skills
Author: franroa

byfranroa

Learning & Documentation

Applies Test-Driven Development principles to creating, verifying, and refining documentation and skills for AI agents.

About

This skill adapts the Red-Green-Refactor cycle of TDD to the process of writing AI instructions and skills. By forcing authors to watch an agent fail a pressure scenario before writing the documentation, it ensures that every instruction is necessary, effective, and resilient against agent rationalizations. It provides a structured framework for creating high-performance, token-efficient skills that Claude can reliably discover and execute across different projects.

Key Features

Claude Search Optimization (CSO) guidelines
Red-Green-Refactor workflow for documentation
0 GitHub stars
Token-efficient documentation patterns
Standardized SKILL.md structure
Subagent pressure-testing framework

Use Cases

Optimizing documentation for AI discoverability and context efficiency
Refining existing instructions to prevent agent hallucinations
Creating new specialized skills for Claude Code

About

Key Features

Claude Search Optimization (CSO) guidelines
Red-Green-Refactor workflow for documentation
0 GitHub stars
Token-efficient documentation patterns
Standardized SKILL.md structure
Subagent pressure-testing framework

Use Cases

Optimizing documentation for AI discoverability and context efficiency
Refining existing instructions to prevent agent hallucinations
Creating new specialized skills for Claude Code