---

name: create-skill-file description: Guides Claude in creating well-structured SKILL.md files following best practices. Provides clear guidelines for naming, structure, and content organization to make skills easy to discover and execute.

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

Freedom	Use Case	Writing Approach
High	Requires creativity, multiple solutions	Provide guiding principles, not specific steps
Medium	Recommended patterns but allow variations	Provide parameterized examples and default flows
Low	Error-prone, requires strict execution	Provide detailed step-by-step instructions or scripts

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:

Field	Requirements	Description
name	Lowercase letters, numbers, hyphens, ≤64 characters	Must match directory name
description	Plain text, ≤1024 characters	Used for retrieval and activation

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

---