writing-skills

Testing agent skills requires applying a test-driven development cycle to SKILL.md files, documenting agent failures under pressure scenarios before writing rules, and verifying compliance through subagent re-runs. This ensures skills reliably guide agents.

Test-driven documentation applies a RED-GREEN-REFACTOR cycle to SKILL.md authoring, observing agents failing under pressure before writing minimal rules, then verifying they comply. It detects rationalizations and bypasses agents use to ignore instructions.

Preventing agents from bypassing SKILL.md rules involves running multi-pressure scenario testing covering time, sunk cost, and authority pressures. You capture rationalizations agents use, then deploy rationalization tables and explicit negations to close loopholes.

Structuring SKILL.md files for deployment requires YAML frontmatter with a name and description, passing pressure scenario testing with subagents, adding rationalization defenses, and completing a mandatory verification checklist ensuring skills are tested and refactored.

Supporting files are optional but recommended when authoring agent skills, including flowchart rendering guidance to visualize workflows and persuasion-principles research documents to design discipline-enforcing skills that withstand pressure scenarios.

Agents ignore SKILL.md instructions and take shortcuts because untested documentation allows rationalizations under pressure. Writing-skills addresses this by testing agents under multi-pressure scenarios, documenting failures verbatim, and writing minimal rules to close loopholes.