Writing Skills for Claude Code FAQs

Question 1

What is the recommended structure for a SKILL.md file?

Accepted Answer

A SKILL.md file should include YAML frontmatter (name and description), an overview, triggering symptoms for use, core patterns with code examples, and common mistakes.

Question 2

What is the core principle of the Writing Skills plugin?

Accepted Answer

The core principle is Test-Driven Development (TDD) applied to documentation. You must watch an agent fail without the skill (RED) before writing the documentation to ensure it actually solves a real problem (GREEN).

Question 3

How can I keep my skills token-efficient?

Accepted Answer

The plugin recommends moving large reference details to tool help files, using cross-references instead of repeating instructions, and aiming for word counts under 200 for frequently-loaded skills.

Question 4

Where are Claude Code skills stored?

Accepted Answer

Personal skills for Claude Code are stored in the ~/.claude/skills directory, while project-specific conventions should remain in CLAUDE.md.

Question 5

How does this improve Claude's performance?

Accepted Answer

It uses Claude Search Optimization (CSO) to write descriptions that focus on 'triggering conditions.' This helps Claude correctly identify when to load a skill without creating 'shortcuts' where it skips the full documentation.

Writing Skills for Claude Code

Key Features

Use Cases

Writing Skills for Claude Code

Key Features

Use Cases