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

Summarizing the workflow creates a shortcut that Claude may follow instead of reading the full skill content, often leading it to miss nuanced steps or flowcharts.

When should I create a new skill versus a project-specific CLAUDE.md file?

Skills should be created for broad, reusable patterns that apply across projects. Project-specific conventions belong in CLAUDE.md, while mechanical constraints should be automated with tools.

What is a Claude Code Skill?

A skill is a specialized reference guide for proven techniques, patterns, or tools that help future Claude instances find and apply effective approaches to specific tasks.

How does TDD apply to writing skills?

You write a pressure scenario (test), watch the agent fail to follow the desired logic (red), write the skill documentation (green), and then refine the instructions to close loopholes (refactor).

Writing Skills & Skill Authoring

Name: Writing Skills & Skill Authoring
Author: tianzecn

bytianzecn

•

Learning & Documentation

Standardizes the creation and optimization of Claude Code skills using a Test-Driven Development (TDD) approach.

About

This skill provides a rigorous framework for developing specialized capabilities within Claude Code by applying TDD principles to process documentation. By treating agent instructions as production code and pressure scenarios as test cases, it ensures that every skill is necessary, effective, and token-efficient. It guides users through the Red-Green-Refactor cycle for documentation, offering specific patterns for Claude Search Optimization (CSO) and directory structure to maximize agent discovery and compliance.

Key Features

Pressure-test scenario design for subagents
Red-Green-Refactor workflow for documentation
Claude Search Optimization (CSO) patterns
1 GitHub stars
Standardized directory structure guidelines
Token-efficient documentation templates

Use Cases

Improving agent compliance with existing team workflows
Developing new domain-specific skills for Claude Code
Refactoring bulky documentation for better token efficiency

About

Key Features

Pressure-test scenario design for subagents
Red-Green-Refactor workflow for documentation
Claude Search Optimization (CSO) patterns
1 GitHub stars
Standardized directory structure guidelines
Token-efficient documentation templates

Use Cases

Improving agent compliance with existing team workflows
Developing new domain-specific skills for Claude Code
Refactoring bulky documentation for better token efficiency