Why shouldn't I summarize the workflow in the skill description?

If the description summarizes the workflow, Claude may follow that summary instead of reading the full skill content, leading to skipped steps or less accurate results.

What is the recommended word count for a Claude Skill?

Frequently loaded skills should aim for under 200 words total, while general skills should stay under 500 words to ensure token efficiency.

What does it mean to apply TDD to documentation?

It means writing a test scenario where an agent fails a task, creating a skill to address that failure, and then verifying the agent passes the task once the skill is provided.

When should I create a new skill versus updating a CLAUDE.md file?

Create a skill for reusable techniques or patterns that apply across projects. Use CLAUDE.md for project-specific conventions and mechanical constraints.

Skill Authoring & TDD Documentation

Name: Skill Authoring & TDD Documentation
Author: cloudfieldcz

bycloudfieldcz

•

Learning & Documentation

Applies Test-Driven Development principles to the creation and optimization of Claude Code skills and process documentation.

The Writing Skills plugin introduces a rigorous Test-Driven Development (TDD) framework for authoring Claude Code skills. By mapping the Red-Green-Refactor cycle to documentation, it ensures that every skill is validated against actual agent failure scenarios before being finalized. This approach helps developers create highly effective, token-efficient reference guides that optimize Claude's search discovery and task execution. It includes specific patterns for Claude Search Optimization (CSO), ensuring that the AI correctly identifies triggering conditions without skipping critical workflow steps.

Key Features

01Red-Green-Refactor workflow for documentation validation

02Standardized SKILL.md structure and YAML frontmatter templates

032 GitHub stars

04Token-efficient content patterns and word count targets

05Graphviz flowchart conventions for complex decision points

06Claude Search Optimization (CSO) best practices

Use Cases

01Encoding team-specific technical patterns into reusable AI skills

02Optimizing large skill libraries for discovery and context window efficiency

03Validating that documentation effectively changes AI agent behavior

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add cloudfieldcz/cf-powers writing-skills

For use in Claude.ai and ChatGPT

Download Skill