create-skill-file

Claude Agent Skill Writing Guidelines

How to create high-quality SKILL.md files

Table of Contents

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

---

Quick Start

Create a Skill in 3 Steps

Step 1: Create the 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

• Trigger it in a conversation using the keywords in the description
• Observe whether Claude executes it correctly
• Adjust based on the results

---

Core Principles

1. Keep It Concise

Only add new knowledge that Claude does not know:

• ✅ Project-specific workflows
• ✅ Special naming conventions or format requirements
• ✅ How to use custom tools and scripts
• ❌ General programming knowledge
• ❌ Obvious steps

Example Comparison:

# ❌ 过度详细
1. 创建 Python 文件
2. 导入必要的库
3. 定义函数
4. 编写主程序逻辑

# ✅ 简洁有效
使用 `scripts/api_client.py` 调用内部 API。
请求头必须包含 `X-Internal-Token`(从环境变量 `INTERNAL_API_KEY` 获取)。

2. Set an Appropriate Degree of Freedom

Degree of Freedom	Applicable Scenarios	How to Write
High	Requires creativity, multiple solutions	Provide guiding principles, do not prescribe specific steps
Medium	Has a recommended pattern but allows variation	Provide parameterized examples and a default process
Low	Error-prone, requires strict execution	Provide detailed step-by-step instructions or scripts

Criteria for Judgment:

• Does the task have a clear "correct answer"? → Low degree of freedom
• Does it need to adapt to different scenarios? → High degree of freedom
• How great is the cost of an error? → If the cost is high, use a low degree of freedom

3. Progressive Disclosure

Organize complex content in layers:

SKILL.md (主文档, 200-500行)
├── reference.md (详细文档)
├── examples.md (完整示例)
└── scripts/ (可执行脚本)

Rules:

• SKILL.md exceeds 500 lines → split into subfiles
• Subfile exceeds 100 lines → add a table of contents
• Reference depth ≤ 1 level

---

File Structure Guidelines

YAML Frontmatter

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

Field Guidelines:

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

Naming Taboos:

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

Description Tips:

# ❌ 过于泛化
description: Helps with code tasks

# ✅ 具体且包含关键词
description: Processes CSV files and generates Excel reports with charts. Use when user asks to convert data formats or create visual reports.

# ✅ 说明触发场景
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 Guidelines

Skill Naming

Recommended Format: Gerund form (verb-ing + noun)

✅ 好的命名:
- processing-csv-files
- generating-api-docs
- managing-database-migrations

❌ 不好的命名:
- csv (过于简短)
- data_processor (使用下划线)
- helper (过于模糊)

Writing the Description

Must use third person:

# ❌ 错误
description: I help you process PDFs

# ✅ 正确
description: Processes PDF documents and extracts structured data

4C Principles:

• Clear (Clear): Avoid jargon and vague terms
• Concise (Concise): Explain the core function in 1-2 sentences
• Contextual (Context): Explain the applicable scenarios
• Complete (Complete): Function + trigger conditions

---

Content Writing Guide

"When to Use" Section

Clearly state the 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(verification-type 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 → explain directly in SKILL.md
• Complex flows → 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
• ✅ Explain validation criteria and success conditions
• ✅ Include a Do/Don't checklist

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 the directory name
• Includes only information Claude doesn't know
• No redundant or duplicate content

Feature Completeness

• Has a "When to Use" section listing 3-5 trigger scenarios
• Has a clear execution flow or steps
• At least 2-3 complete examples
• Includes inputs and expected outputs
• Error handling is guided

Structural Standards

• Sections are clearly organized
• Over 200 lines has a table of contents for navigation
• Reference hierarchy ≤ 1 level
• All paths use forward slashes /
• Terminology is used consistently

Scripts and Templates

• Scripts include usage instructions and parameter documentation
• Scripts have error handling
• Avoid magic numbers; use configuration
• Template format is clear and easy to use

Final Check

• Read through the full text to ensure it is smooth and easy to read
• Test triggers with real scenarios
• Length is appropriate (200-500 lines, or already 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 can a Skill be made easier to activate?

• In description use keywords the user would say
• Explain specific scenarios ("when user asks to X")
• Mention relevant tool names

Q: What should be done when multiple Skills overlap in functionality?

• Use more specific description to distinguish
• Explain the relationship in "When to Use"
• Consider merging into one Skill

Q: Do Skills need maintenance?

• Review once a quarter and 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
  • Template for a basic skill
  • Template for a workflow skill
• Example Library - Complete Skill examples
  • Good examples
  • Common mistake examples

---