writing-skills

Test-driven development for skills follows a RED-GREEN-REFACTOR cycle: write failing test cases with subagents first, then craft skill descriptions that pass those tests, then refine for clarity. This validates behavior before deployment and prevents ineffective documentation.

Include a name and description in YAML frontmatter. Write descriptions in concise third-person language, start with "Use when..." to specify triggers, and structure content according to Claude authoring guidelines. This ensures skills are discoverable and clearly understood by AI agents.

Explicitly close loopholes and address common excuses in your skill documentation. Use pressure scenarios with subagents to test edge cases and validate that the skill resists misinterpretation under various conditions.

Use TDD when creating complex internal process skills where clarity and robustness matter—especially when other AI agents will follow the skill under pressure. It prevents ambiguous documentation and ensures skills behave as intended across varied scenarios.

Ineffective documentation lacks clear triggers, contains loopholes AI agents exploit, and hasn't been tested against real agent behavior. Effective documentation follows the RED-GREEN-REFACTOR cycle, includes specific use-case conditions, and passes validation with subagents.

Yes. Write rich descriptions with relevant keywords, structure content for clarity, use "Use when..." conditions to signal intent, and ensure YAML frontmatter is complete. This improves skill discoverability when other agents search for solutions.