writing-skills

Apply TDD to process documentation by testing with subagents before writing skills, iterating until bulletproof against rationalization.

• Reusable techniques, patterns, or tools for agent behavior
• Reference guides for proven methods and practices
• Test-driven documentation that evolves through failure and compliance
• A way to ensure skills are effective by validating against real agent behavior

• Write test cases (pressure scenarios) with subagents before drafting the skill
• Observe agent failures (RED) to define baseline behavior
• Create skill document (SKILL.md) to fix violations (GREEN)
• Refactor to close loopholes and maintain compliance
• Must observe failure without skill before writing it
• Follow RED-GREEN-REFACTOR cycle for iterative improvement
• Skills live in agent-specific directories (e.g., ~/.claude/skills)
• Use rich, trigger-based descriptions in frontmatter

1. 1.Run a pressure scenario with a subagent to observe failure (RED)
2. 2.Document the exact rationalization the agent uses to fail
3. 3.Write a minimal skill (SKILL.md) to address the failure
4. 4.Verify that the agent now complies (GREEN)
5. 5.Refactor the skill to close new loopholes and re-verify compliance
6. 6.Ensure description starts with 'Use when...' and includes symptoms and triggers