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 编写规范

如何创建高质量的 SKILL.md 文件

快速开始

3步创建 Skill

第1步: 创建目录

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

第2步: 创建 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

第3步: 测试

在对话中使用 description 中的关键词触发
观察 Claude 是否正确执行
根据效果调整

核心原则

1. 保持简洁

只添加 Claude 不知道的新知识:

✅ 项目特定的工作流程
✅ 特殊的命名规范或格式要求
✅ 自定义工具和脚本的使用方法
❌ 通用编程知识
❌ 显而易见的步骤

示例对比:

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

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

2. 设定合适的自由度

自由度	适用场景	编写方式
高	需要创造性、多种解决方案	提供指导原则,不限定具体步骤
中	有推荐模式但允许变化	提供参数化示例和默认流程
低	容易出错、需严格执行	提供详细的分步指令或脚本

判断标准:

任务是否有明确的"正确答案"? → 低自由度
是否需要适应不同场景? → 高自由度
错误的代价有多大? → 代价高则用低自由度

3. 渐进式披露

将复杂内容分层组织:

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

规则:

SKILL.md 超过 500行 → 拆分子文件
子文件超过 100行 → 添加目录
引用深度 ≤ 1层

文件结构规范

YAML Frontmatter

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

字段规范:

字段	要求	说明
`name`	小写字母、数字、短横线,≤64字符	必须与目录名一致
`description`	纯文本,≤1024字符	用于检索和激活

命名禁忌:

❌ XML 标签、保留字(anthropic, claude)
❌ 模糊词汇(helper, utility, manager)
❌ 空格或下划线(用短横线 -)

Description 技巧:

# ❌ 过于泛化
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".

目录组织

基础结构(简单 Skill):

skill-name/
└── SKILL.md

标准结构(推荐):

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

命名和描述规范

Skill 命名

推荐格式: 动名词形式 (verb-ing + noun)

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

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

Description 编写

必须使用第三人称:

# ❌ 错误
description: I help you process PDFs

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

4C 原则:

Clear (清晰): 避免术语和模糊词汇
Concise (简洁): 1-2句话说明核心功能
Contextual (上下文): 说明适用场景
Complete (完整): 功能 + 触发条件

内容编写指南

"When to Use" 章节

明确说明触发场景:

## 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

模式:

直接请求: "User asks to X"
关键词: "User mentions 'keyword'"
上下文: "User is working with X"
任务类型: "User needs to X"

工作流设计

简单线性流程:

## 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

条件分支流程:

## 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 模式(验证型任务):

## 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

### 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

脚本集成

何时使用脚本:

简单命令 → 直接在 SKILL.md 中说明
复杂流程 → 提供独立脚本

脚本编写规范:

#!/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())

关键规范:

✅ Shebang 行和 docstring
✅ 类型注解和常量
✅ 参数验证和错误处理
✅ 清晰的返回值(0=成功, 1=失败)

最佳实践

Do:

✅ 提供可执行的命令和脚本
✅ 包含输入-输出示例
✅ 说明验证标准和成功条件
✅ 包含 Do/Don't 清单

Don't:

❌ 包含 Claude 已知的通用知识
❌ 使用抽象描述而非具体步骤
❌ 遗漏错误处理指导
❌ 示例使用伪代码而非真实代码

质量检查清单

核心质量

name 符合命名规范(小写、短横线、≤64字符)
description 包含触发关键词和场景(≤1024字符)
名称与目录名一致
只包含 Claude 不知道的信息
没有冗余或重复内容

功能完整性

有"When to Use"章节,列出 3-5 个触发场景
有清晰的执行流程或步骤
至少 2-3 个完整示例
包含输入和预期输出
错误处理有指导

结构规范

章节组织清晰
超过 200行有目录导航
引用层级 ≤ 1层
所有路径使用正斜杠 /
术语使用一致

脚本和模板

脚本包含使用说明和参数文档
脚本有错误处理
避免魔法数字,使用配置
模板格式清晰易用

最终检查

通读全文,确保流畅易读
使用实际场景测试触发
长度适中(200-500行,或已拆分)

常见问题

Q: Skill 多长才合适?

最小: 50-100行
理想: 200-500行
最大: 500行(超过则拆分)

Q: 如何让 Skill 更容易激活?

在 description 中使用用户会说的关键词
说明具体场景("when user asks to X")
提及相关工具名称

Q: 多个 Skill 功能重叠怎么办?

使用更具体的 description 区分
在"When to Use"中说明关系
考虑合并为一个 Skill

Q: Skill 需要维护吗?

每季度审查一次,更新过时信息
根据使用反馈迭代
工具或 API 变更时及时更新

快速参考

Frontmatter 模板

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

基础结构模板

# 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)

create-skill-file

Install Skill

SKILL.md