writing-skills

To stop rationalization, write process documentation using a test-driven approach with explicit countermeasures like rationalization tables and red flags. This transforms ad-hoc guidance into verifiable references that enforce intended agent behavior.

The RED-GREEN-REFACTOR cycle is a TDD method for testing skill documentation. You draft a SKILL.md, run the testing loop to validate baseline behavior, and refine the docs until they pass robust deployment readiness checks.

Progressive disclosure patterns structure SKILL.md files to load heavy references only when needed. This technique keeps metadata concise and ensures agents retrieve dense contextual information dynamically during execution.

A test-driven approach to skill writing requires no external dependencies. It relies entirely on a standard SKILL.md template and internal RED-GREEN-REFACTOR workflows to validate and refine documentation.

The best way to validate skill documentation before deployment is running the RED-GREEN-REFACTOR testing loop. This process verifies baseline behavior, captures rationalizations, and ensures robust testing readiness.

Avoid TDD-guided documentation when ad-hoc guidance is sufficient and rationalization risks are low. If progressive disclosure and strict deployment checks are unnecessary, standard documentation methods without red flags may be more efficient.