When should I create a new skill?

Create a skill when a technique isn't intuitively obvious, applies broadly across projects, or represents a pattern you would reference multiple times.

What is the most common mistake in skill descriptions?

Summarizing the skill's workflow instead of focusing on triggering conditions. Descriptions should start with 'Use when...' to help Claude decide when to load the skill.

What is a Claude Code Skill?

A skill is a specialized reference guide for proven techniques, patterns, or tools that enhances Claude's behavior when performing domain-specific tasks.

How does TDD apply to writing documentation?

You write a pressure scenario, watch the agent fail without the skill (Red), write the skill documentation (Green), and then refactor to close behavioral loopholes.

How do I ensure my skills are token-efficient?

Aim for under 200 words for frequently-loaded skills, use cross-references instead of repeating instructions, and move command details to tool help flags.

Skill Writing & TDD Framework

Name: Skill Writing & TDD Framework
Author: Krosebrook

byKrosebrook

•

Learning & Documentation

Standardizes the creation and optimization of AI skills using Test-Driven Development principles to ensure consistent agent compliance.

The Skill Writing & TDD Framework provides a rigorous methodology for authoring Claude Code skills by applying the 'Red-Green-Refactor' cycle to documentation. It helps users define specialized capabilities by first identifying agent failures in specific scenarios, then writing concise, triggering-condition-focused documentation that Claude can easily discover and follow. This framework emphasizes token efficiency and Claude Search Optimization (CSO), ensuring that skills are not just written but are actually utilized by the agent during complex workflows.

Key Features

01TDD-driven documentation lifecycle (Red-Green-Refactor)

02Claude Search Optimization (CSO) formatting rules

03Token-efficient documentation patterns for context savings

04Standardized SKILL.md structure and frontmatter

05Subagent pressure-testing techniques

061 GitHub stars

Use Cases

01Refining agent behavior by closing documentation loopholes

02Standardizing documentation across large monorepos like FlashFusion

03Creating reusable domain-specific guidance for AI agents

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add krosebrook/source-of-truth-monorepo writing-skills

For use in Claude.ai and ChatGPT

Download Skill