Skill Authoring & Documentation TDD FAQs

Question 1

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

Accepted Answer

Summarizing the workflow creates a shortcut. Claude may follow the brief description instead of reading the full skill body, which can lead to the agent skipping crucial detailed instructions or flowcharts.

Question 2

What is the target word count for a Claude Code skill?

Accepted Answer

Getting-started workflows should be under 150 words, frequently-referenced skills under 200 words, and specialized skills should ideally stay under 500 words to maintain token efficiency.

Question 3

How do I make my skills discoverable by Claude?

Accepted Answer

Use the Claude Search Optimization (CSO) guidelines, specifically focusing on the 'description' field in the YAML frontmatter. It should start with 'Use when...' and describe triggering conditions rather than summarizing the workflow.

Question 4

What is the Red-Green-Refactor cycle for writing skills?

Accepted Answer

Red: Run a baseline scenario and watch the agent fail without the skill. Green: Write the skill and verify the agent now complies. Refactor: Optimize the skill for token efficiency and close any logic loopholes.

Question 5

When is it appropriate to create a new skill?

Accepted Answer

Create a skill when a technique isn't intuitively obvious, the pattern applies broadly across projects, and you've verified that the agent doesn't naturally follow the pattern without explicit guidance.

Skill Authoring & Documentation TDD

Skill Authoring & Documentation TDD

主な機能

ユースケース

主な機能

ユースケース