Writing Skills for Claude Code FAQs

Question 1

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

Accepted Answer

Create a skill for reusable techniques or patterns that apply across multiple projects. Use CLAUDE.md for project-specific conventions and local constraints.

Question 2

What is the TDD approach to writing skills?

Accepted Answer

It involves creating a pressure scenario (Test), watching the AI fail (Red), writing the skill documentation (Green), and then refining the instructions to close loopholes (Refactor).

Question 3

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

Accepted Answer

If the description summarizes the process, Claude may follow the summary and skip reading the detailed instructions in the main skill body, leading to missed steps.

Question 4

How can I keep my skills token-efficient?

Accepted Answer

Aim for word counts under 200 words for frequently loaded skills, move tool-specific flags to --help commands, and use cross-references instead of repeating instructions.

Question 5

How do I ensure Claude actually finds the skill I wrote?

Accepted Answer

Use Claude Search Optimization (CSO) by focusing the YAML description on specific 'Use when' triggering conditions and symptoms rather than summarizing the workflow.

Writing Skills for Claude Code

Key Features

Use Cases

Writing Skills for Claude Code

Key Features

Use Cases