writing-skills

Automate test-driven documentation generation for SKILL.md files.

Updated Nov 3, 2025
One-click install
npx skills add https://github.com/ayourtch/kimichat --skill writing-skills-ayourtch
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: writing-skills
Source: https://github.com/ayourtch/kimichat/tree/main/skills/writing-skills
Command: npx skills add https://github.com/ayourtch/kimichat --skill writing-skills-ayourtch

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill ensures skills are effective, robust, and discoverable by applying Test-Driven Development (TDD) principles to their creation and refinement, making them bulletproof against rationalization.

Core Features & Use Cases

  • TDD for Documentation: Guides through RED (baseline test without skill), GREEN (write skill), and REFACTOR (close loopholes) cycles for skill content.
  • CSO (Claude Search Optimization): Provides guidelines for rich descriptions, keyword coverage, and token efficiency to maximize skill discoverability.
  • Bulletproofing: Includes techniques to resist rationalization, such as explicit negations, rationalization tables, and red flags.
  • Use Case: When creating a new systematic-debugging skill, use this skill to first run a scenario where an agent fails to debug systematically, then write the skill to address those failures.

Quick Start

I'm using the writing-skills skill to create a new data-validation-patterns skill.

Frequently Asked Questions about writing-skills

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I apply test-driven development to write better skill documentation?

Test-driven documentation uses RED-GREEN-REFACTOR cycles: first run a scenario where an agent fails without the skill, then write the skill to pass that test, then refactor to close edge cases. This ensures documentation solves real problems rather than theoretical ones.

What should a skill description include to rank well in search results?

Skill descriptions need YAML frontmatter (name and description), a description starting with 'Use when' to clarify scope, rich keyword coverage for discoverability, and token-efficient phrasing. These elements maximize Claude Search Optimization and help users find your skill.

How do I prevent my skill documentation from being rationalized away or ignored?

Bulletproofing techniques include explicit negations stating what the skill does not do, rationalization tables mapping common workarounds to why they fail, and red flags that highlight when someone might skip the skill. These block users from justifying non-use.

Can I use this approach to create skills for any workflow or domain?

Yes. The RED-GREEN-REFACTOR framework applies to any skill creation: define a baseline failure scenario in your domain, write the skill to address it, then refactor to handle edge cases. The process is domain-agnostic; only the test scenarios change.

What's the difference between writing a skill with and without test-driven practices?

Without TDD, skills often contain aspirational content that sounds good but fails in real use. TDD-driven skills are validated against actual agent failure modes, making them robust, discoverable, and resistant to being bypassed or rationalized.