Claude Agent Skill Writing Guide

How to create high-quality SKILL.md files

Table of Contents

• Quick Start
• Core Principles
• File Structure Standards
• Naming and Description Standards
• Content Writing Guide
• Quality Checklist

Quick Start

3 Steps to Create a Skill

Step 1: Create Directory

mkdir -p .claude/skill/your-skill-name
cd .claude/skill/your-skill-name

Step 2: Create SKILL.md

---
name: your-skill-name
description: Brief description with trigger keywords and scenarios
---

# Your Skill Title

## When to Use This Skill

- User asks to [specific scenario]
- User mentions "[keyword]"

## How It Works

1. Step 1: [Action]
2. Step 2: [Action]

## Examples

**Input**: User request
**Output**: Expected result

Step 3: Test - Use keywords from description in conversation to trigger - Observe whether Claude executes correctly - Adjust based on effectiveness

Core Principles

1. Keep It Concise

Only add new knowledge that Claude doesn't know: - ✅ Project-specific workflows - ✅ Special naming conventions or format requirements - ✅ How to use custom tools and scripts - ❌ General programming knowledge - ❌ Obvious steps

Example Comparison:

# ❌ Too Detailed
1. Create Python file
2. Import necessary libraries
3. Define functions
4. Write main program logic

# ✅ Concise and Effective
Use `scripts/api_client.py` to call internal API.
Request headers must include `X-Internal-Token` (from environment variable `INTERNAL_API_KEY`).

2. Set Appropriate Freedom

Decision Criteria: - Is there a clear "correct answer"? → Low freedom - Does it need to adapt to different scenarios? → High freedom - What's the cost of errors? → High cost = low freedom

3. Progressive Disclosure

Organize complex content in layers:

SKILL.md (Main document, 200-500 lines)
├── reference.md (Detailed documentation)
├── examples.md (Complete examples)
└── scripts/ (Executable scripts)

Rules: - SKILL.md > 500 lines → Split into sub-files - Sub-files > 100 lines → Add table of contents - Reference depth ≤ 1 level

File Structure Standards

YAML Frontmatter

---
name: skill-name-here
description: Clear description of what this skill does and when to activate it
---

Field Specifications:

Naming Prohibitions: - ❌ XML tags, reserved words (anthropic, claude) - ❌ Vague terms (helper, utility, manager) - ❌ Spaces or underscores (use hyphens -)

Description Tips:

# ❌ Too Generic
description: Helps with code tasks

# ✅ Specific with Keywords
description: Processes CSV files and generates Excel reports with charts. Use when user asks to convert data formats or create visual reports.

# ✅ States Trigger Scenarios
description: Analyzes Python code for security vulnerabilities using bandit. Activates when user mentions "security audit" or "vulnerability scan".

Directory Organization

Basic Structure (Simple Skill):

skill-name/
└── SKILL.md

Standard Structure (Recommended):

skill-name/
├── SKILL.md
├── templates/
│   └── template.md
└── scripts/
    └── script.py

Naming and Description Standards

Skill Naming

Recommended Format: Verb-ing + noun form

✅ Good Names:
- processing-csv-files
- generating-api-docs
- managing-database-migrations

❌ Bad Names:
- csv (too brief)
- data_processor (uses underscores)
- helper (too vague)

Description Writing

Must use third person:

# ❌ Wrong
description: I help you process PDFs

# ✅ Correct
description: Processes PDF documents and extracts structured data

4C Principles: - Clear: Avoid jargon and vague terms - Concise: 1-2 sentences explaining core functionality - Contextual: Describe applicable scenarios - Complete: Functionality + trigger conditions

Content Writing Guide

"When to Use" Section

Clearly state trigger scenarios:

## When to Use This Skill

- User asks to analyze Python code for type errors
- User mentions "mypy" or "type checking"
- User is working in a Python project with type hints
- User needs to add type annotations

Patterns: - Direct request: "User asks to X" - Keywords: "User mentions 'keyword'" - Context: "User is working with X" - Task type: "User needs to X"

Workflow Design

Simple Linear Flow:

## How It Works

1. Scan the project for all `.py` files
2. Run `mypy --strict` on each file
3. Parse error output and categorize by severity
4. Generate summary report with fix suggestions

Conditional Branching Flow:

## Workflow

1. **Check project type**
   - If Django → Use `django-stubs` config
   - If Flask → Use `flask-stubs` config
   - Otherwise → Use default mypy config

2. **Run type checking**
   - If errors found → Proceed to step 3
   - If no errors → Report success and exit

Checklist Pattern (Validation tasks):

## Pre-deployment Checklist

Execute in order. Stop if any step fails.

- [ ] Run tests: `npm test` (must pass)
- [ ] Build: `npm run build` (no errors)
- [ ] Check deps: `npm audit` (no critical vulnerabilities)

Examples and Templates

Input-Output Examples:

## Examples

### Example 1: Basic Check

**User Request**: "Check my code for type errors"

**Action**:
1. Scan for `.py` files
2. Run `mypy` on all files

**Output**:

   Found 3 type errors in 2 files:
   src/main.py:15: error: Missing return type
   src/utils.py:42: error: Incompatible types

Script Integration

When to Use Scripts: - Simple commands → Describe directly in SKILL.md - Complex processes → Provide standalone scripts

Script Writing Standards:

#!/usr/bin/env python3
"""
Brief description of what this script does.

Usage:
    python script.py <arg> [--option value]
"""

import argparse

DEFAULT_VALUE = 80  # Use constants, not magic numbers

def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("directory", help="Directory to process")
    parser.add_argument("--threshold", type=int, default=DEFAULT_VALUE)

    args = parser.parse_args()

    # Validate inputs
    if not Path(args.directory).is_dir():
        print(f"Error: {args.directory} not found")
        return 1

    # Execute
    result = process(args.directory, args.threshold)

    # Report
    print(f"Processed {result['count']} files")
    return 0

if __name__ == "__main__":
    exit(main())

Key Standards: - ✅ Shebang line and docstring - ✅ Type annotations and constants - ✅ Parameter validation and error handling - ✅ Clear return values (0=success, 1=failure)

Best Practices

Do: - ✅ Provide executable commands and scripts - ✅ Include input-output examples - ✅ State validation criteria and success conditions - ✅ Include Do/Don't lists

Don't: - ❌ Include general knowledge Claude already knows - ❌ Use abstract descriptions instead of concrete steps - ❌ Omit error handling guidance - ❌ Use pseudocode instead of real code in examples

Quality Checklist

Core Quality

• [ ] name follows naming conventions (lowercase, hyphens, ≤64 characters)
• [ ] description includes trigger keywords and scenarios (≤1024 characters)
• [ ] Name matches directory name
• [ ] Only includes information Claude doesn't know
• [ ] No redundant or duplicate content

Functional Completeness

• [ ] Has "When to Use" section with 3-5 trigger scenarios
• [ ] Has clear execution flow or steps
• [ ] At least 2-3 complete examples
• [ ] Includes input and expected output
• [ ] Error handling guidance provided

Structure Standards

• [ ] Clear section organization
• [ ] Table of contents for >200 lines
• [ ] Reference nesting ≤ 1 level
• [ ] All paths use forward slashes /
• [ ] Consistent terminology

Scripts and Templates

• [ ] Scripts include usage instructions and parameter documentation
• [ ] Scripts have error handling
• [ ] Avoid magic numbers, use configuration
• [ ] Template format is clear and usable

Final Check

• [ ] Read through for fluency and readability
• [ ] Test triggering with actual scenarios
• [ ] Appropriate length (200-500 lines, or split)

FAQ

Q: How long should a Skill be? - Minimum: 50-100 lines - Ideal: 200-500 lines - Maximum: 500 lines (split if exceeded)

Q: How to make Skills easier to activate? - Use keywords in description that users would say - State specific scenarios ("when user asks to X") - Mention related tool names

Q: What if multiple Skills overlap? - Use more specific description to differentiate - Explain relationships in "When to Use" - Consider merging into one Skill

Q: Do Skills need maintenance? - Review quarterly, update outdated information - Iterate based on usage feedback - Update promptly when tools or APIs change

Quick Reference

Frontmatter Template

---
name: skill-name
description: Brief description with trigger keywords
---

Basic Structure Template

# Skill Title

## When to Use This Skill
- Scenario 1
- Scenario 2

## How It Works
1. Step 1
2. Step 2

## Examples
### Example 1
...

## References
- [Link](url)

Related Resources

• Claude Agent Skills Official Documentation
• Best Practices Checklist
• Template Files - Ready-to-use templates
• Basic skill template
• Workflow skill template
• Example Library - Complete Skill examples
• Good examples
• Common mistakes