Skill Writing & TDD Documentation FAQs

Question 1

What is the core principle of Writing Skills?

Accepted Answer

The core principle is applying Test-Driven Development (TDD) to documentation. You must watch an agent fail a task without the skill before writing the documentation to ensure it actually solves the problem.

Question 2

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

Accepted Answer

Summarizing the workflow in the description can lead Claude to take shortcuts based only on the summary, causing it to skip the detailed instructions within the full skill body.

Question 3

When should I create a new skill versus updating a project file?

Accepted Answer

Create a skill for reusable techniques or patterns that apply across multiple projects. Use project-specific files like CLAUDE.md for conventions unique to a single codebase.

Question 4

How do I make my skills token-efficient?

Accepted Answer

Keep core skill files under 200-500 words, move heavy references to separate files, and use concise descriptions that focus on triggering conditions rather than workflow summaries.

Question 5

What is Claude Search Optimization (CSO)?

Accepted Answer

CSO is a set of practices including rich descriptions and keyword coverage that helps Claude accurately identify and load the most relevant skills for a specific task.

Skill Writing & TDD Documentation

Key Features

Use Cases

Skill Writing & TDD Documentation

Key Features

Use Cases