Writing Skills TDD FAQs

Question 1

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

Accepted Answer

Summarizing the workflow in the description can cause Claude to take a 'shortcut' and follow the summary instead of reading the detailed instructions in the full SKILL.md file.

Question 2

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

Accepted Answer

Create a skill for reusable techniques, patterns, or tools that apply across multiple projects. Project-specific conventions should remain in CLAUDE.md.

Question 3

How long should a Claude Code skill be?

Accepted Answer

Skills should be highly concise for token efficiency. Getting-started workflows should be under 150 words, and most other skills should aim for under 500 words.

Question 4

What is the core principle of the Writing Skills skill?

Accepted Answer

It treats documentation as Test-Driven Development. You must watch an agent fail a task without the skill to ensure the instructions you write actually solve a specific behavioral problem.

Question 5

What is Claude Search Optimization (CSO)?

Accepted Answer

CSO is a technique to ensure Claude finds the right skill at the right time. It involves writing descriptions that focus on 'triggering conditions' rather than summarizing the workflow.

Writing Skills TDD

Key Features

Use Cases

Writing Skills TDD

Key Features

Use Cases