writing-skills

Test-driven documentation applies the RED-GREEN-REFACTOR cycle to skill docs, capturing real failures and mitigating gaps. You structure SKILL.md with frontmatter, document the testing workflow, and run pressure-based scenarios to verify narrative guidance before deployment.

Preventing rationalization gaps requires discipline enforcement patterns like red flags and rationalization tables. You define baseline pressure scenarios to reveal where agents deviate from narrative guidance, then apply deployment checklists to ensure compliance before release.

Structuring SKILL.md requires adding name and description frontmatter followed by concise sections. You document the RED-GREEN-REFACTOR workflow within the file, ensuring the narrative guidelines and testing artifacts are structured for both agent discovery and reliable execution.

Verifying skill documentation without code tests uses pressure-based testing scenarios. You define baseline scenarios that reveal rationalizations and gaps in the narrative guidance, then enforce compliance through deployment checklists and rationalization tables instead of traditional code assertions.

The RED-GREEN-REFACTOR cycle is needed when transforming narrative skill documentation into verifiable guidance. You use it during skill creation and verification workflows to ensure real failures are captured, mitigated, and refined before agents operate under pressure.

Agent skills fail under pressure when narrative documentation lacks verifiable testing artifacts. You mitigate this by applying pressure-based testing to reveal rationalization gaps, then enforcing discipline patterns like red flags and deployment checklists to ensure compliance.