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

字段规范:

命名禁忌:

• ❌ 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.ad

...