<!-- title: Claude Code Skill开发：从零到发布 -->

# Claude Code Skill 开发实战：从零创建一个自定义 Skill

> **学习目标**：掌握 Claude Code Skill 的完整开发流程，包括 SKILL.md 规范、YAML frontmatter 配置、渐进式加载机制、测试迭代方法，最终独立开发并发布一个可用的自定义 Skill。
>
> **适用人群**：已有 Claude Code 基础使用经验的开发者，希望将重复工作流封装为可复用的"技能模块"。

---

## 一、什么是 Skill？为什么需要它？

在 Claude Code 中，每次对话你都需要重复描述你的偏好、工作流程、输出格式。Skill 的出现解决了这个痛点——它是一个**结构化的指令包**，教会 Claude 如何以一致的方式完成特定类型的任务。

一个 Skill 本质上是一个文件夹，核心是 `SKILL.md` 文件：

```
my-skill/
├── SKILL.md           ← 必需，包含元数据 + 指令
└── (可选资源)
    ├── scripts/       ← 可执行脚本
    ├── references/    ← 参考文档
    └── assets/        ← 模板、图标等资源
```

Skill 遵循 **Agent Skills 开放标准**（[agentskills.io](https://agentskills.io)），同一份 SKILL.md 可以在 Claude Code、GitHub Copilot、Cursor 等支持该标准的工具中通用。

---

## 二、Skill 的三层加载机制

理解 Skill 的加载方式对编写高质量 Skill 至关重要。Claude 采用**渐进式披露**（Progressive Disclosure）策略：


![图表1](images/claude-code-tutorial-r2-1648-mermaid-0.png)

> *图表 1*


| 层级 | 内容 | 何时加载 | 大小建议 |
|------|------|---------|---------|
| **L1 元数据** | name + description | 始终在上下文中 | ~100词 |
| **L2 正文** | SKILL.md 的 Markdown 指令 | Skill 被触发时 | < 500行 |
| **L3 资源** | scripts/、references/、assets/ | 按需加载 | 无限制 |

这意味着：**description 是触发机制的核心**。Claude 根据 description 判断是否需要调用你的 Skill。

---

## 三、环境准备

### 前置条件

- Claude Code CLI 已安装（`claude --version` 可用）
- Node.js 18+ 环境
- 基本的命令行操作能力
- 一个可用的 Git 仓库（用于测试 Skill）

### 安装官方 Skill 开发工具

Anthropic 提供了 `skill-creator` 这个元技能（meta-skill），专门用于创建和测试其他 Skill：

```bash
# 注册官方 Skill 市场
claude /plugin marketplace add anthropics/skills

# 安装 example-skills 插件（包含 skill-creator）
claude /plugin install example-skills@anthropic-agent-skills
```

安装完成后，你可以在 Claude Code 中直接使用 `/skill-creator` 命令。

---

## 四、SKILL.md 文件规范详解

### 4.1 最小化模板

从 Anthropic 官方模板出发：

```markdown
---
name: template-skill
description: Replace with description of the skill and when Claude should use it.
---

# Insert instructions below
```

YAML frontmatter 只有**两个必需字段**：

| 字段 | 必需 | 说明 |
|------|------|------|
| `name` | 是 | Skill 的唯一标识符，小写 + 连字符，如 `my-code-reviewer` |
| `description` | 是 | 描述 Skill 的功能**和触发时机**，这是 Claude 判断是否使用此 Skill 的主要依据 |

### 4.2 description 编写技巧

description 是整个 Skill 中最关键的字段。Anthropic 官方建议写得**稍微"激进"一些**，因为 Claude 默认倾向于"少触发"（undertrigger）。

**反面示例**（太保守）：
```yaml
description: 如何构建一个简单的仪表盘。
```

**正面示例**（推荐风格）：
```yaml
description: |
  如何构建高质量的交互式仪表盘和数据可视化界面。
  当用户提到仪表盘、dashboard、数据可视化、监控面板、
  指标展示、metrics board，或者想要展示任何类型的结构化数据时，
  都应使用此 Skill，即使用户没有明确提到"仪表盘"这个词。
```

### 4.3 可选字段

除了 `name` 和 `description`，SKILL.md 还支持以下可选 frontmatter 字段：

```yaml
---
name: my-skill
description: 技能描述...
license: Apache-2.0           # 许可证
compatibility:                 # 兼容性说明
  tools: [Bash, Read, Write]   # 所需工具
  dependencies: [node>=18]     # 运行依赖
---
```

---

## 五、实战：创建一个 Git 提交规范 Skill

让我们从头创建一个实用的 Skill——`smart-commit`，它教会 Claude 按照 Conventional Commits 规范生成高质量的 Git 提交信息。

### 5.1 创建目录结构

```bash
# 在项目根目录创建 Skill
mkdir -p .claude/skills/smart-commit
```

或者创建全局可用的 Skill（所有项目共享）：

```bash
mkdir -p ~/.claude/skills/smart-commit
```

### 5.2 编写 SKILL.md

创建文件 `.claude/skills/smart-commit/SKILL.md`：

```markdown
---
name: smart-commit
description: |
  智能生成符合 Conventional Commits 规范的 Git 提交信息。
  当用户需要提交代码、写 commit message、暂存文件、
  创建 git commit，或者提到"提交"、"commit"、"保存进度"时，
  都应使用此 Skill。即使用户只说了"提交一下"这样模糊的指令也应触发。
---

# Smart Commit

生成高质量、规范化的 Git 提交信息，遵循 Conventional Commits 标准。

## 工作流程

### 第一步：分析变更

1. 运行 `git status` 查看所有变更文件
2. 运行 `git diff --staged` 查看已暂存的变更
3. 运行 `git diff` 查看未暂存的变更
4. 运行 `git log --oneline -10` 了解最近的提交风格

### 第二步：分类变更

根据变更内容确定 commit 类型：

| 类型 | 说明 | 示例 |
|------|------|------|
| feat | 新功能 | 新增用户注册接口 |
| fix | Bug 修复 | 修复登录超时问题 |
| docs | 文档变更 | 更新 API 文档 |
| style | 格式调整（不影响逻辑） | 修正缩进、空格 |
| refactor | 重构（非新功能、非修复） | 提取公共方法 |
| perf | 性能优化 | 优化列表查询速度 |
| test | 测试相关 | 新增用户模块单元测试 |
| chore | 构建或辅助工具 | 升级依赖版本 |

### 第三步：生成提交信息

格式要求：

**示例 1：**
Input: 新增了用户登录的 JWT 认证功能，包含 token 签发和验证
Output: `feat(auth): implement JWT-based user authentication`

**示例 2：**
Input: 修复了当用户名为空时系统崩溃的问题
Output: `fix(user): handle empty username to prevent crash`

**示例 3：**
Input: 把 utils.js 里的重复代码提取成了独立函数
Output: `refactor(utils): extract shared helper functions`

### 第四步：确认与提交

1. 展示生成的 commit message 给用户确认
2. 用户确认后，执行 `git add`（只添加相关文件，不使用 `git add -A`）
3. 执行 `git commit`，使用 HEREDOC 格式传递 message

## 约束

- 绝不自动 push 到远程仓库
- 绝不提交 .env、credentials、secrets 等敏感文件
- 不使用 `--no-verify` 跳过 hooks
- 优先让用户确认后再执行 git 操作
- 如果有 pre-commit hook 失败，修复问题后创建新 commit，不使用 amend
```

### 5.3 添加参考文档（可选）

如果 Skill 需要更详细的参考信息，可以创建 `references/` 目录：

```bash
mkdir -p .claude/skills/smart-commit/references
```

创建 `.claude/skills/smart-commit/references/scopes-guide.md`：

```markdown
# Scope 命名指南

## 常用 scope 对照表

| 目录 | 推荐 scope |
|------|-----------|
| src/auth/ | auth |
| src/api/ | api |
| src/components/ | ui |
| src/utils/ | utils |
| tests/ | test |
| docs/ | docs |
| config/ | config |

## 多 scope 处理

当变更涉及多个模块时：
- 主要变更决定 scope
- 如果两个模块同等重要，用 `/` 分隔：`feat(auth/api): ...`
- 超过两个模块时省略 scope：`feat: ...`
```

在 SKILL.md 中引用此文件：

```markdown
## 参考
- 当不确定 scope 命名时，参考 `references/scopes-guide.md`
```

---

## 六、Skill 的测试与迭代

### 6.1 手动测试

最简单的测试方式——在 Claude Code 中直接对话：

```
你: 帮我提交一下当前的代码

（Claude 应该触发 smart-commit Skill，分析变更并生成规范的 commit message）
```

测试多种触发方式：
- "提交代码"
- "commit 一下"
- "保存当前进度"
- "帮我写个 commit message"
- "git commit"

### 6.2 使用 skill-creator 进行系统测试

使用 `/skill-creator` 触发自动化测试流程。它的工作流程如下：


![图表2](images/claude-code-tutorial-r2-1648-mermaid-1.png)

> *图表 2*


### 6.3 evals.json 格式

测试用例保存在 `evals/evals.json`：

```json
{
  "skill_name": "smart-commit",
  "evals": [
    {
      "id": 1,
      "prompt": "帮我提交一下，我刚改了登录模块的 bug",
      "expected_output": "生成 fix(auth): ... 格式的 commit message",
      "files": [],
      "assertions": [
        {
          "text": "commit message 以 fix( 开头",
          "check": "output_matches",
          "pattern": "^fix\\("
        },
        {
          "text": "不包含敏感文件",
          "check": "output_not_contains",
          "pattern": "\\.env|credentials"
        }
      ]
    },
    {
      "id": 2,
      "prompt": "I added a new REST API endpoint for user registration",
      "expected_output": "生成 feat(api): ... 格式的 commit message",
      "files": []
    }
  ]
}
```

### 6.4 测试工作空间结构

使用 skill-creator 测试时，它会在 Skill 旁边创建工作空间：

```
smart-commit/              ← Skill 目录
smart-commit-workspace/    ← 测试工作空间
├── evals/
│   └── evals.json
├── iteration-1/
│   ├── descriptive-name/
│   │   ├── eval_metadata.json
│   │   ├── with_skill/
│   │   │   ├── outputs/
│   │   │   └── timing.json
│   │   └── without_skill/
│   │       ├── outputs/
│   │       └── timing.json
│   └── grading.json
└── iteration-2/
    └── ...
```

每次迭代都会保留完整的测试记录，方便对比改进效果。

---

## 七、多域 Skill 的组织模式

当 Skill 需要支持多个变体（如不同的部署平台、不同的框架），采用域组织模式：

```
cloud-deploy/
├── SKILL.md              ← 主入口，包含工作流和选择逻辑
└── references/
    ├── aws.md            ← AWS 部署细节
    ├── gcp.md            ← GCP 部署细节
    └── azure.md          ← Azure 部署细节
```

SKILL.md 中的引用方式：

```markdown
## 部署指南

根据用户指定的云平台，读取对应的参考文件：

- AWS → 读取 `references/aws.md`
- GCP → 读取 `references/gcp.md`
- Azure → 读取 `references/azure.md`

如果用户未指定平台，询问他们的偏好。
```

这种模式下，Claude 只会加载当前需要的参考文件，避免浪费上下文窗口。

---

## 八、Skill 的安装与分发

### 8.1 本地 Skill

Skill 放在以下位置会自动被发现：

| 位置 | 作用域 |
|------|--------|
| `<项目>/.claude/skills/` | 仅当前项目 |
| `~/.claude/skills/` | 全局所有项目 |

### 8.2 通过 Plugin Marketplace 分享

创建自己的 Skill 市场（适用于团队或社区）：

```bash
# 创建 marketplace
claude /plugin marketplace add your-org/your-skills-repo

# 团队成员安装
claude /plugin install your-skill-set@your-marketplace
```

Marketplace 本质上是一个 Git 仓库，结构如下：

```
your-skills-repo/
├── plugin.json           ← 插件配置
├── skills/
│   ├── smart-commit/
│   │   └── SKILL.md
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── ...
└── README.md
```

`plugin.json` 示例：

```json
{
  "name": "team-workflow-skills",
  "description": "团队工作流 Skill 集合",
  "skills": [
    {
      "name": "smart-commit",
      "path": "skills/smart-commit"
    },
    {
      "name": "code-reviewer",
      "path": "skills/code-reviewer"
    }
  ]
}
```

### 8.3 .skill 文件打包

使用 `skill-creator` 内置的打包工具：

```bash
python -m scripts.package_skill ./smart-commit/
# 输出: smart-commit.skill
```

`.skill` 文件是一个自包含的压缩包，可以直接分享给其他人安装。

---

## 九、编写高质量 Skill 的核心原则

### 9.1 解释"为什么"而非堆砌"必须"

Claude 是一个足够智能的模型。比起用大写的 ALWAYS/NEVER 强制约束，解释原因效果更好：

**差的写法**：
```markdown
ALWAYS 确保生成的 commit message 不超过 72 个字符。
NEVER 使用过去时态。
```

**好的写法**：
```markdown
commit message 的首行应控制在 72 字符以内，因为 Git 默认截断超过此长度的信息。
使用祈使句（如 "add feature" 而非 "added feature"），与 Git 自身的 merge message 风格保持一致。
```

### 9.2 保持精简

- SKILL.md 正文理想长度 < 500 行
- 超过时，将细节移入 `references/` 并在正文中指向
- 超过 300 行的参考文件应包含目录

### 9.3 包含具体示例

示例比规则更有效。每个关键输出格式都应提供 input/output 对照：

```markdown
**示例：**
Input: 修复了当并发请求数超过 100 时连接池耗尽的问题
Output: fix(pool): prevent connection exhaustion under high concurrency
```

### 9.4 常见问题与避坑

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| Skill 不被触发 | description 不够具体或太保守 | 增加更多触发关键词，写得"激进"一些 |
| Skill 触发但效果差 | 指令太模糊 | 添加具体示例和输出模板 |
| 输出不一致 | 缺少约束 | 明确输出格式，但不要过度使用 MUST/NEVER |
| 上下文窗口溢出 | SKILL.md 太长 | 移入 references/，按需加载 |
| Skill 只对特定输入有效 | 过拟合测试用例 | 泛化指令，解释原因而非给出死板规则 |

---

## 十、实战案例：完整的 API 文档生成 Skill

以下是一个更复杂、可直接使用的 Skill，用于从代码自动生成 OpenAPI 规范文档：

```markdown
---
name: api-doc-generator
description: |
  从源代码自动生成 OpenAPI 3.0 规范文档。
  当用户需要生成 API 文档、创建 OpenAPI/Swagger 规范、
  从代码提取接口定义、编写 API 描述文件，
  或者提到"接口文档"、"API 文档"、"swagger"、"openapi"时使用。
  即使用户只说"帮我整理一下接口"也应触发此 Skill。
---

# API 文档生成器

从项目源代码中提取 API 端点信息，生成标准 OpenAPI 3.0 YAML/JSON 规范文件。

## 工作流程

### 第一步：项目分析

1. 确定项目使用的框架（Express/Fastify/Django/FastAPI/Spring Boot 等）
2. 识别路由定义文件的位置
3. 检查是否已存在 OpenAPI/Swagger 配置

运行以下命令定位路由文件：
- Express: 搜索 `app.get|app.post|router.get|router.post`
- FastAPI: 搜索 `@app.get|@app.post|@router.get`
- Spring: 搜索 `@GetMapping|@PostMapping|@RequestMapping`

### 第二步：端点提取

对每个路由端点，提取：

- HTTP 方法和路径
- 请求参数（query/path/body）
- 请求体 Schema
- 响应格式和状态码
- 认证要求
- 描述信息（从注释中提取）

### 第三步：生成 OpenAPI 文档

输出完整的 `openapi.yaml` 文件，结构如下：

**示例输出：**
```yaml
openapi: '3.0.3'
info:
  title: User Service API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: Paginated user list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
```

### 第四步：验证

1. 将生成的 YAML 保存为 `openapi.yaml`
2. 如果项目中有 swagger-ui 依赖，验证能否正确渲染
3. 检查所有 `$ref` 引用是否有效

## 参考
- 对于框架特定的提取规则，参考 `references/frameworks.md`
- OpenAPI 3.0 规范：https://spec.openapis.org/oas/v3.0.3

## 约束
- 生成有效的 YAML，可通过 OpenAPI 验证器校验
- 不猜测缺失的信息，标记为 `# TODO: 需要补充描述`
- 保持端点顺序与源码中的定义顺序一致
```

---

## 十一、Skill 的完整生命周期


![图表3](images/claude-code-tutorial-r2-1648-mermaid-2.png)

> *图表 3*


### 开发阶段关键检查项

- [ ] `name` 使用小写+连字符，简洁明确
- [ ] `description` 包含功能描述和触发场景，略"激进"
- [ ] 正文控制在 500 行以内
- [ ] 包含具体的 input/output 示例
- [ ] 大型参考文档放在 `references/` 下
- [ ] 重复性任务放在 `scripts/` 下作为可执行脚本

### 测试阶段关键检查项

- [ ] 至少 3 个测试用例，覆盖正常/边界/异常场景
- [ ] 同时运行 with-skill 和 without-skill 基线对比
- [ ] 编写可量化的断言（assertions）
- [ ] 记录 timing.json 用于性能分析

### 发布阶段关键检查项

- [ ] description 已通过触发率优化
- [ ] 在至少 2 个不同项目中验证通用性
- [ ] 打包为 .skill 文件，团队成员可直接安装
- [ ] 如需共享，创建 Plugin Marketplace

---

## 延伸阅读

- [Anthropic 官方 Skills 仓库](https://github.com/anthropics/skills) — 官方 Skill 示例集合，包含 17+ 开源 Skill
- [Agent Skills 规范](https://agentskills.io/specification) — SKILL.md 开放标准的完整定义
- [Skill Creator 文档](https://claude.com/plugins/skill-creator) — Anthropic 官方 Skill 开发工具
- [freeCodeCamp: How to Build Your Own Claude Code Skill](https://www.freecodecamp.org/news/how-to-build-your-own-claude-code-skill) — 面向初学者的 Skill 开发教程

---

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| **适合训练营类型** | AI 工程师实训营、Claude Code 进阶工作坊、DevOps 自动化训练营 |
| **预计教学时长** | 2-3 小时（含动手实践） |
| **难度等级** | ⭐⭐⭐ 中等（需 Claude Code 基础经验） |
| **推荐教学节奏** | 讲解规范 30min → 编写 Skill 45min → 测试迭代 45min → 发布分享 30min |
| **前置知识** | Claude Code 基础操作、Git 基础、Markdown 语法 |

---

## 参考来源
1. [Anthropic Skills 官方仓库](https://github.com/anthropics/skills) — SKILL.md 模板、skill-creator 元技能、17+ 示例 Skill 的源代码
2. [Extend Claude with skills - Claude Code 官方文档](https://code.claude.com/docs/en/skills) — Skill 创建、安装和使用的官方指南
3. [How to Build Your Own Claude Code Skill - freeCodeCamp](https://www.freecodecamp.org/news/how-to-build-your-own-claude-code-skill) — 面向开发者的完整 Skill 开发教程
4. [Claude Code Custom Slash Commands - ThePromptShelf](https://thepromptshelf.dev/blog/claude-code-custom-slash-commands/) — Skill 系统与自定义斜杠命令的实践指南
5. [How to Build Claude Code Skills That Actually Work - dev.to](https://dev.to/whoffagents/how-to-build-claude-code-skills-custom-slash-commands-that-actually-work-1nje) — 工程实践视角的 Skill 开发经验分享

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)