create-skill-file

Claude Agent Skill Writing Standards

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

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 conversation using keywords from the description
• Observe whether Claude executes it correctly
• Adjust based on the results

---

Core Principles

1. Keep It Concise

Only add what Claude doesn't knowas new knowledge:

• ✅ Project-specific workflows
• ✅ Special naming conventions or formatting 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 Level of Freedom

Level of Freedom	Applicable Scenarios	How to Write
High	Requires creativity, multiple solutions	Provide guiding principles, without specifying concrete steps
Medium	Has recommended patterns but allows variation	Provide parameterized examples and default flows
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 freedom
• Does it need to adapt to different scenarios? → High freedom
• How costly are mistakes? → If the cost is high, use low 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 Standards

YAML Frontmatter

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

Field Standards:

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

Naming Taboos:

• ❌ XML tags, reserved words(anthropic, claude)
• ❌ Vague words(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 Standards

Skill Naming

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

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

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

Description Writing

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 words
• Concise (Concise): Explain the core function in 1-2 sentences
• Contextual (Context): Explain applicable scenarios
• Complete (Complete): Function + 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(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 directory name
• Contains only information Claude doesn't know
• No redundant or duplicate content

Functional 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 input and expected output
• Error handling has guidance

Structural Standards

• Sections are clearly organized
• Over 200 lines has table of contents 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 entire text to ensure it is fluent and easy to read
• Test triggers with real scenarios
• Length is moderate (200-500 lines, or already split)

---

Common Questions

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 users would say
• Explain specific scenarios ("when user asks to X")
• Mention relevant tool names

Q: What should be done if multiple Skills have overlapping functionality?

• Use a more specific description to distinguish
• Explain the relationship in "When to Use"
• Consider merging into a single 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

---