Skill Authoring & TDD Documentation FAQs

Question 1

How do I optimize a skill for Claude's discovery process?

Accepted Answer

Focus the description purely on 'triggering conditions' rather than summarizing the workflow. Use 'Use when...' statements and include specific error messages or symptoms that Claude would recognize.

Question 2

When should I create a new skill versus putting it in CLAUDE.md?

Accepted Answer

Create a skill for reusable techniques, patterns, or tools that apply across multiple projects. Use CLAUDE.md for project-specific conventions and one-off solutions.

Question 3

What is the core principle of Writing Skills for Claude Code?

Accepted Answer

The core principle is applying Test-Driven Development (TDD) to documentation: you must watch an agent fail without the skill (RED) to verify that the skill is actually teaching the right behavior (GREEN).

Question 4

What is the difference between a technique and a pattern skill?

Accepted Answer

A technique is a concrete method with specific steps to follow (like root-cause-tracing), whereas a pattern is a conceptual way of thinking about or structuring problems (like flatten-with-flags).

Question 5

Why is token efficiency important in skill creation?

Accepted Answer

Frequently referenced skills load into every conversation. Minimizing word counts and using cross-references ensures you don't exhaust the agent's context window prematurely.

Skill Authoring & TDD Documentation

Skill Authoring & TDD Documentation

Key Features

Use Cases

Key Features

Use Cases