writing-skills

Test-driven development for skills follows the RED-GREEN-REFACTOR workflow: first define failure scenarios with subagents to identify baseline gaps, then build skill documentation that passes those tests, ensuring compliance before deployment. This approach prevents skills from failing to guide agent behavior effectively.

Structure skills by meeting frontmatter field constraints (name and description), following deterministic naming conventions, and applying scoped behavior requirements for reproducible agent compliance. Validate against pressure scenarios to ensure your skill guides behavior reliably across user and project scopes.

Choose user scope (~/.claude/skills/) for personal skills you'll reuse across projects, and project scope (.claude/skills/) for skills tied to specific codebases or teams. Scope selection prevents organizational chaos and version control conflicts.

Optimize skill discoverability through Claude Search Optimization: craft precise names and descriptions matching your skill's core task, select keywords that reflect the problem it solves, and follow best practices for naming conventions. This maximizes the chance future AI instances find your skill when they need it.

Yes. Apply TDD to validate or edit existing skills across both scopes by running pressure scenarios with subagents to elicit failures, then refactoring documentation to achieve green compliance. This ensures even legacy skills meet current compliance standards.

Compliance failures surface specific gaps in documentation clarity or behavior guidance. The RED-GREEN-REFACTOR cycle catches these issues before deployment: refactor your skill's structure, frontmatter, and naming to pass pressure scenarios, ensuring it reliably guides agent behavior in production.