writing-skills

Test-driven development for agent skills involves running failing baseline pressure scenarios, observing agent failures, authoring minimal SKILL.md guidance, and iterating red-green-refactor until the agent follows documented rules under stress.

Agents rationalize workarounds when skill documentation lacks explicit anti-rationalization clauses. Applying TDD to skills surfaces these failures under time, sunk-cost, authority, or fatigue pressure, allowing you to add concrete rules that prevent undeclared assumptions and regressions.

The best way to structure SKILL.md frontmatter for agent discovery is including a name and a discovery-focused description optimized for search, along with concise trigger phrasing and keywords. This ensures agents can reliably find and invoke the skill when needed.

Pressure test agent skills by designing scenarios involving time constraints, sunk costs, authority pressure, or fatigue. Observe how the agent rationalizes workarounds during these failing baseline tests, then add explicit anti-rationalization clauses to your SKILL.md.

No dependencies are required to write and test agent skills with TDD. The process relies on creating baseline scenarios, capturing rationalizations, authoring minimal SKILL.md guidance, and iterating using provided checklists and sample test formats until compliance is achieved.