Writing Skills & TDD Documentation FAQs

Question 1

What is the difference between a skill and a project convention?

Accepted Answer

Skills are reusable techniques or patterns applicable across projects, while project-specific conventions should be placed in a CLAUDE.md file.

Question 2

When should I create a new skill for Claude?

Accepted Answer

Create a skill when a technique isn't intuitively obvious, applies broadly across different projects, and provides a clear pattern for others to follow.

Question 3

Why is token efficiency important when writing skills?

Accepted Answer

Because frequently-referenced skills load into every conversation; keeping them concise (under 200 words for common skills) saves context window and reduces costs.

Question 4

How do I optimize skills for Claude to find them?

Accepted Answer

Use Claude Search Optimization (CSO) by creating rich 'Use when' descriptions that focus on triggering conditions and symptoms rather than summarizing the workflow itself.

Question 5

What is the core principle of the Writing Skills framework?

Accepted Answer

The core principle is Test-Driven Development (TDD) applied to documentation: you must watch an agent fail without a skill to verify that the skill actually teaches the correct behavior.

Writing Skills & TDD Documentation

About

Key Features

Use Cases

Writing Skills & TDD Documentation

About

Key Features

Use Cases