writing-skills

To prevent AI agents from rationalizing SKILL.md documentation, apply test-driven development by capturing baseline failures under pressure scenarios, then writing minimal targeted instructions with anti-rationalization artifacts like red-flag lists to close loopholes.

Test-driven development for agent documentation is a verification loop using a RED-GREEN-REFACTOR cycle to enforce required behaviors in SKILL.md files. Use it when authoring discipline-enforcing or technique skills to ensure instructions resist rationalization.

To create pressure scenarios for testing agent instructions, design specific adversarial prompts that challenge your skill's rules, run them without the skill to capture verbatim baseline rationalizations, then iteratively update SKILL.md and re-run with subagents until compliance.

Yes, test-driven documentation validation supports both discipline-enforcing process skills and technique skills. It systematically verifies required behaviors across model types by capturing baseline failures and applying iterative fixes using mandatory deployment checklists.

The best way to structure SKILL.md files for enforcing required behaviors is using targeted minimal instructions with YAML frontmatter, supplemented by explicit anti-rationalization artifacts like rationalization tables and red-flag lists to prevent agents from exploiting ambiguous language.

Agents bypass documentation rules by misinterpreting ambiguous guidance or exploiting loopholes under pressure. Rationalization tables fix this by capturing verbatim baseline failure reasoning, allowing you to write targeted minimal instructions that explicitly close those specific rationalization loopholes.