writing-skills

Writing Skills - A Guide to Creating Claude Skills

Skill Overview

Writing Skills applies test-driven development (TDD) to skill documentation. Through the RED-GREEN-REFACTOR cycle, it ensures skill quality and helps developers create high-quality skills that can be discovered and effectively used by Claude agents.

Applicable Scenarios

1. Creating New Skills

When you have mastered a reusable technical pattern, tool usage method, or problem-solving approach and want to turn it into a skill for future Claude instances, Writing Skills provides a complete creation process—from naming conventions and directory structure to content organization and test validation.

2. Editing Existing Skills

When you need to improve existing skill content, fix flaws, or add missing use cases, this skill emphasizes that every edit must first be validated through testing to ensure the modification actually solves the problem without introducing new issues.

3. Verifying Skill Deployment

Before deploying a skill to production, use stress testing to verify whether the skill can be correctly understood and executed by Claude. Writing Skills provides multiple testing methods and corresponding validation strategies for different skill types: discipline, technical, pattern, and reference skills.

Core Features

1. TDD-Driven Skill Development Process

This maps traditional test-driven development to documentation writing: first run stress tests to observe violations by the agent without the skill (RED), then write a minimal skill to solve the specific problem (GREEN), and iteratively patch flaws through further testing (REFACTOR). This ensures every skill has clear validation criteria and avoids documentation that “looks clear” but is unusable in practice.

2. Claude Search Optimization (CSO) Guidance

Provides detailed SEO optimization strategies to help Claude agents discover and correctly use skills. These include describing only trigger conditions rather than summarizing the workflow in the description field, covering error messages and symptoms with keywords, using verb-first naming conventions, and applying writing techniques that control token consumption. These optimizations directly affect how skills are loaded and applied in real conversations.

3. Skill Type Classification and Testing Methods

Skills are divided into four categories, each with a corresponding testing strategy:

Discipline skills are tested with academic questions and pressure scenarios to evaluate rule compliance.

Technical skills are tested with application scenarios and variations to assess technical mastery.

Pattern skills are tested with recognition scenarios to evaluate the application of mental models.

Reference skills are tested with retrieval scenarios to assess information-finding accuracy.

Each type has clearly defined success criteria.

Frequently Asked Questions

What is a skill? How is it different from ordinary documentation?

A skill is a validated, reusable technical method, pattern, or tool reference guide designed to help future Claude instances find and apply effective approaches. Skills focus on broadly applicable content that can be reused across projects rather than one-off solutions. Ordinary documentation may be a narrative record of problem-solving, but a skill must be tested and validated to ensure that agents can correctly understand and execute it.

Why must testing come before skill creation?

This is the application of TDD’s core principle to documentation. If you do not first observe the agent’s behavior without the skill, you cannot determine whether the skill truly solves the problem. Testing reveals the rationalizations agents use to violate rules and the pressures that lead to incorrect decisions, giving skill writing a clear objective. Writing the skill first and testing afterward often produces documentation that “looks clear” but cannot actually be interpreted correctly by the agent.

How can I get Claude to discover and use my skill?

The key is to optimize the description field. The description should describe only the trigger conditions and use cases, not summarize the skill’s workflow. If the description includes a workflow summary such as “code review,” Claude may perform a review once and stop, even if the skill body clearly requires multiple reviews. You should also include error messages, symptom descriptions, synonyms, and actual tool names in the skill, as these are keywords Claude may match during search.

What types of skills are there, and how do I choose one?

Skills fall into four categories:

Technical: Specific methods with actionable steps, such as conditional waiting.

Pattern: Mental models, such as flattened design.

Reference: API documentation and syntax guides.

Discipline: Mandatory rules, such as TDD.

Choose the type based on the nature of the content you want to record: use a technical skill for executable steps, a pattern skill for ways of thinking, a reference skill for lookup material, and a discipline skill for rules that must be followed.

What should SKILL.md contain?

It must include YAML frontmatter containing only the name and description fields; an overview covering the core principles; when to use it, including applicable scenarios and trigger conditions; core patterns, with before-and-after code comparisons or explanations; a quick reference, such as a table or list of common operations; implementation details, including code examples or file links; common errors; and real-world impact (optional).

Content should be concise: getting-started skills should be limited to 150 words, commonly used skills to 200 words, and other skills to 500 words.