What is the recommended structure for a SKILL.md file?

A standard SKILL.md includes YAML frontmatter (name and description), an overview, use cases with symptoms, core patterns, and implementation examples with a focus on token efficiency.

What is a Claude Code Skill?

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

How do I optimize skills for Claude search?

Focus the description on 'When to use' (triggering conditions) rather than 'What it does.' Providing specific symptoms and situations helps Claude decide when to load the skill into its context.

Why use TDD for documentation?

Applying Test-Driven Development to documentation ensures the skill actually solves a problem; by watching an agent fail without the skill, you verify that the documentation provides the necessary guidance to make it pass.

When should I avoid creating a skill?

Do not create skills for one-off solutions, standard practices documented elsewhere, or project-specific conventions that belong in a CLAUDE.md file.

Skill Authoring & Documentation

Name: Skill Authoring & Documentation
Author: tianyuanztm

bytianyuanztm

0•

학습 및 문서화

Standardizes the creation and testing of Claude Code skills using a Test-Driven Development approach for process documentation.

The writing-skills skill provides a rigorous framework for developing high-quality, discoverable documentation for Claude Code. By applying TDD principles—watching an agent fail a task before writing the skill—it ensures that documentation effectively addresses specific behavioral gaps. It includes critical guidelines for Claude Search Optimization (CSO), token efficiency, and directory structuring to ensure skills are loaded only when necessary and perform optimally within AI context limits, preventing common pitfalls where agents skip documentation due to poorly structured descriptions.

주요 기능

01Optimized description patterns for Claude Search Optimization (CSO)

02Visual logic mapping via Graphviz and flowchart integration guidelines

03Token-efficient formatting guidelines to minimize context window usage

04TDD-based documentation workflow (Red-Green-Refactor) for behavioral reliability

050 GitHub stars

06Standardized SKILL.md structure and active-voice naming conventions

사용 사례

01Refining project-specific conventions for better LLM discoverability

02Verifying existing documentation effectiveness through subagent pressure scenarios

03Creating reusable techniques or architectural patterns for AI agents

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add tianyuanztm/myplan writing-skills

For use in Claude.ai and ChatGPT

Download Skill