writing-skills

Test agent instructions for compliance by applying a test-driven RED-GREEN-REFACTOR process to skill documentation. Establish a baseline failure without the Skill, then iterate until the agent consistently follows instructions under pressure.

Agents rationalize away instructions under time, authority, sunk cost, or exhaustion pressure by generating workarounds. This Skill hardens documentation by capturing these verbatim excuses and adding explicit negations and red flags to maintain compliance.

The best way to harden skill documentation is through iterative pressure-scenario testing. Capture new rationalizations verbatim during testing and update the instructions with explicit counters and red flags to ensure stable agent compliance.

Test-driven development applies to writing AI agent prompts by treating documentation as code. You observe baseline failures without the Skill (RED), update instructions to achieve compliance (GREEN), then refactor to close loopholes (REFACTOR).

Use a test-first approach for editing skill documentation when creating or revising agent instructions that must hold firm under multiple pressures in the same session. It verifies the guidance prevents rationalization before deployment.

Optimize skill descriptions for Claude Search by ensuring the YAML description focuses on "when to use" triggers rather than a workflow summary. This trigger-based approach improves search discovery and ensures the skill is surfaced appropriately.