# Claude Code Skill 规范开发指南

本指南融合官方 skill-creator 指南与实践经验,为 Skill 开发提供完整的方法论和最佳实践。

## 一、Skill 基础概念

### 1.1 什么是 Skill

Skill 是模块化的自包含包,通过提供专业化知识、工作流程和工具来扩展 Claude 的能力。将 Skill 视为特定领域或任务的"入职指南"——它们将 Claude 从通用代理转变为配备了模型无法完全拥有的程序性知识的专业代理。

### 1.2 Skill 提供的能力

1. **专业化工作流** - 特定领域的多步骤过程
2. **工具集成** - 处理特定文件格式或 API 的指令
3. **领域专业知识** - 公司特定知识、模式、业务逻辑
4. **捆绑资源** - 用于复杂和重复任务的脚本、参考资料和资源

### 1.3 渐进式披露原则

Skill 使用三级加载系统高效管理上下文:

1. **元数据(name + description)** - 始终在Claude code主窗口的上下文中(~100 词)
2. **SKILL.md 主体** - 当 Skill 触发时(<3k 词)
3. **捆绑资源** - 根据 Claude 需要加载(脚本可以在不读入上下文窗口的情况下执行)

## 二、Skill 目录结构

### 2.1 标准结构

```
skill-name/
├── SKILL.md (必需)
│   ├── YAML frontmatter 元数据(必需)
│   │   ├── name: (必需)
│   │   └── description: (必需)
│   └── Markdown 指令(必需)
└── 捆绑资源(可选)
    ├── scripts/          - 可执行代码(Python/Bash 等)
    ├── references/       - 详细执行指南、领域知识、复杂流程说明(供按需查阅)
    ├── assets/           - 项目类型配置、业务规则等数据性文件
    ├── templates/        - 文档模板、输出格式模板
    ├── examples/         - 示例文档、参考案例(不在执行时加载)
    └── temp/             - Agent 间传递数据的临时文件
```

### 2.2 各目录职责

#### SKILL.md (必需)

- **元数据**: YAML frontmatter 中的 `name` 和 `description` 决定 Skill 触发时机,使用第三人称描述
- **内容**: 只包含执行流程概要、关键步骤、必要的调用格式
- **风格**: 使用祈使/不定式形式(如 "To accomplish X, do Y"),客观指导性语言

#### scripts/ (可选)

- **用途**: 确定性可靠的可执行代码,不依赖 Claude Code 能力
- **优势**: Token 高效,可不加载到上下文直接执行
- **适用**: 重复编写的相同代码

#### references/ (可选)

- **用途**: 详细执行指南、领域知识、复杂流程说明,按需加载
- **最佳实践**: 大文件(>10k 词)在 SKILL.md 中提供 grep 搜索模式
- **避免重复**: 详细信息放这里,核心精要放 SKILL.md

#### assets/ (可选)

- **用途**: 配置、业务规则等数据文件,用于输出而非加载到上下文
- **示例**: 模板、图标、样板代码、字体

#### templates/ (可选)

- **用途**: 文档模板、输出格式模板

#### examples/ (可选)

- **用途**: 示例文档、参考案例,供用户参考,不在执行时加载

#### temp/ (可选)

- **用途**: Agents 间数据交换的临时文件

## 三、Skill 创建流程

### 步骤 1: 理解 Skill 使用场景

通过用户示例或验证的生成示例,理解 Skill 的具体使用方式。

**关键问题**:

- Skill 应支持什么功能?
- 典型使用示例有哪些?
- 什么样的用户请求应触发此 Skill?

**目标**: 对 Skill 应支持的功能有清晰认识。

### 步骤 2: 规划可重用资源

分析示例,识别可重用的资源:

**分析方法**:
1. 考虑如何从头执行示例
2. 识别重复执行时需要的脚本、详细的参考资料和资源

**示例**:
- **pdf-editor**: 旋转 PDF 需重写代码 → `scripts/rotate_pdf.py`
- **webapp-builder**: 前端样板重复使用 → `assets/hello-world/` 模板
- **big-query**: 表模式需重复查询的详细指南 → `references/schema.md`

**输出**: 可重用资源列表 (scripts/references/assets)。

### 步骤 3: 初始化 Skill

运行 `init_skill.py` 脚本创建新 Skill 目录和模板:

```bash
scripts/init_skill.py <skill-name> --path <output-directory>
```

自动生成 SKILL.md 模板和示例资源目录,然后根据需要自定义或删除。

### 步骤 4: 编辑 Skill

**原则**: 专注于对 Claude 有益且非显而易见的信息。

#### 4.1 实现可重用资源

实现步骤 2 识别的 `scripts/`、`references/` 和 `assets/` 文件,可能需要用户提供素材。删除不需要的示例文件。

#### 4.2 编写 SKILL.md

**风格**: 祈使/不定式形式,客观指导性语言。

**内容**:

1. Skill 的目的(几句话)
2. 触发时机
3. 使用方法(引用所有可重用资源)

### 步骤 5: 迭代优化

实际使用 → 发现问题 → 更新资源 → 测试验证

## 四、多 Agents 协作最佳实践

### 4.1 Agents 创建准则

#### 4.1.1 Agent 定义位置

Agents 在全局 `.claude/agents/` 目录下创建,每个 agent 一个独立的 markdown 文件:

```
.claude/
└── agents/
    ├── req_interviewer.md
    ├── pm_reviewer.md
    └── domain_expert_reviewer.md
```

**Agent 文件结构**:

```markdown
---
name: agent_name
description: Agent 的简要描述和触发时机
---

# Agent 名称

## 职责

[agent 的核心职责描述]

## 固化规则

[agent 内部固化的执行规则、工具使用规范、评估标准]

## 工作流程

1. [步骤1]
2. [步骤2]
...

## 输入参数

- 参数1: [说明,通常是标识符或文件路径]
- 参数2: [说明]

## 输出格式

- **推荐**: 直接返回完整结果文字
- **备选**: 结果极大时写入 `temp/` 文件并返回路径

## 可用工具

[列出 agent 可使用的工具]
```

**SKILL.md 中引用 Agents**:

在 SKILL.md 中通过 Task tool 调用已定义的 agents,使用 `subagent_type` 参数指定 agent 名称。

#### 4.1.2 Agent 设计原则

**自治性**:

- Agent 内部固化所有执行规则、工具使用规范、评估标准
- 配置文件由 Agent 自己读取,不依赖主窗口传递
- 业务逻辑在 Agent 定义中完整描述

**职责单一**:

- 每个 Agent 只负责一个明确的任务阶段
- 避免创建"万能 Agent",职责重叠会导致混乱

**数据自给**:
- Agent 的行为准则应在自己的定义md文件中写定，必要时从 `references/` 或 `assets/` 读取所需配置
- 主窗口只传递标识符(如项目类型)和文件路径

#### 4.1.3 Agent 命名规范

- 使用 `snake_case` 命名: `req_interviewer`, `domain_expert_reviewer`
- 名称应体现职责: `{角色}_{动作}` 或 `{领域}_{专家}`
- 避免泛化名称: 用 `pm_reviewer` 而非 `reviewer1`

### 4.2 主窗口职责

**定位**: 主窗口是流程协调者,不是数据中转站。

**职责**:
- 只传递协调必要信息(如项目类型标识符、文件路径)
- 不传递 agents 的行为规则、配置内容或完整数据
- 根据工作流程依次调用 agents
- 汇总 agents 返回的概要信息呈现给用户

### 4.3 数据传递优化

**主窗口 → agents**:
- 主窗口只给 Agent 传递必须的、需要从主窗口上下文获取到的信息精要或标识符
- agents 的行为规范或详细指南(不依赖主窗口上下文的)应该在 Agent 内部固化写入,不应依赖主窗口通过 prompt 传递

**agents → 主窗口**:
- **推荐**: 直接通过 prompt 返回完整文字结果(高效)
- **备选**: 结果极大时才写入 `temp/` 文件(需在主窗口 prompt 中提示读取)

**agents → agents**:

- 通过 `temp/` 文件传递数据
- 主窗口只传文件路径,作为协调的中转站

**核心原则**: 主窗口传标识符,Agent 读详细配置;Agent 间传文件路径;Agent 向主窗口直接返回文字。

## 五、SKILL.md 设计最佳实践

### 5.1 渐进式披露与信息组织

**SKILL.md 只包含**:
- 执行流程概要
- 关键步骤
- 必要的调用格式

**详细内容分类**:
- 复杂执行细节 → `references/`
- 示例案例 → `examples/`
- 配置数据 → `assets/`
- 输出模板 → `templates/`

**信息分配原则**(避免重复):
1. 核心工作流指导 → SKILL.md
2. 详细参考材料 → references/
3. 配置和数据 → assets/
4. 输出模板 → templates/

**效果**: 保持 SKILL.md 精简清晰,详细信息按需加载。

## 六、参考资源

- [代理技能 - Claude Code Docs](https://code.claude.com/docs/en/skills?utm_source=chatgpt.com)
- [Claude Agent Skills: A First Principles Deep Dive](https://leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/)