<!-- title: Claude Code Skills开发实战全攻略 -->

# Claude Code Skills开发实战全攻略：从零创建自定义Skill

## 概述

本教程带你从零开始创建一个完整的 Claude Code 自定义 Skill。你将深入理解 SKILL.md 规范、触发条件设计、脚本集成、eval 测试和发布流程。适合已具备 Claude Code 基本使用经验、希望将重复工作流封装为可复用自动化的中级开发者。学完后你将拥有一个可安装、可触发、可分享的自定义 Skill，并掌握 Skills 生态的核心开发模式。

## 前置条件

| 条件 | 说明 |
|------|------|
| Claude Code | 已安装并完成认证（`claude` 命令可用） |
| 终端基础 | 熟悉 `cd`、`mkdir`、`cat` 等基本命令 |
| Markdown | 了解 YAML frontmatter 和 Markdown 语法 |
| 开发项目 | 有一个可用于测试的代码仓库 |

## 一、Skills 核心概念

### 1.1 什么是 Skill？

Skill 是 Claude Code 的模块化扩展机制——每个 Skill 是一个文件夹，核心是一个 `SKILL.md` 指令文件。当用户输入匹配的提示词或斜杠命令时，Claude 加载并执行该文件中定义的工作流。

**与 CLAUDE.md 的关键区别：**

```
CLAUDE.md ─── 全局加载，始终生效，定义通用规则和项目上下文
Skills/   ─── 按需加载，触发式激活，定义特定任务工作流
```

### 1.2 Skill 的三层架构

```mermaid
graph TB
    subgraph "Skill 三层加载系统"
        L1["第一层：Frontmatter<br/>元数据（名称、描述、触发条件）"]
        L2["第二层：SKILL.md 正文<br/>工作流指令"]
        L3["第三层：辅助资源<br/>scripts/ references/ assets/"]
    end
    L1 -->|"系统匹配时加载"| L2
    L2 -->|"需要时按需加载"| L3
    style L1 fill:#4A90D9,color:#fff
    style L2 fill:#7B68EE,color:#fff
    style L3 fill:#9370DB,color:#fff
```

这种渐进式加载（Progressive Disclosure）设计确保了即使你有数百个 Skill，系统也不会被拖慢——只有匹配的 Skill 才会被完整加载。

### 1.3 四级作用域

```mermaid
graph LR
    subgraph "优先级从高到低"
        E["企业级<br/>管理员统一管理"]
        P["个人级<br/>~/.claude/skills/"]
        R["项目级<br/>.claude/skills/"]
        G["插件级<br/>plugin/skills/"]
    end
    E --> P --> R --> G
    style E fill:#E74C3C,color:#fff
    style P fill:#F39C12,color:#fff
    style R fill:#2ECC71,color:#fff
    style G fill:#3498DB,color:#fff
```

| 作用域 | 路径 | 可见范围 | 适用场景 |
|--------|------|----------|----------|
| 企业级 | 管理员配置 | 全公司 | 安全规范、合规流程 |
| 个人级 | `~/.claude/skills/<name>/` | 你的所有项目 | 个人效率工具 |
| 项目级 | `.claude/skills/<name>/` | 当前项目 | 团队共享工作流 |
| 插件级 | `<plugin>/skills/<name>/` | 插件启用时 | 功能分发 |

## 二、动手创建第一个 Skill

### 2.1 创建目录结构

我们先创建一个实用 Skill：**代码变更日志生成器**——自动分析 Git 提交历史，生成结构化的 CHANGELOG。

```bash
# 进入你的项目目录
cd your-project

# 创建 Skill 目录
mkdir -p .claude/skills/changelog-gen/scripts
mkdir -p .claude/skills/changelog-gen/references
```

最终目录结构：

```
.claude/skills/changelog-gen/
├── SKILL.md              # 核心指令文件（必需）
├── scripts/
│   └── git-log-fmt.sh    # Git 日志格式化脚本（可选）
└── references/
    └── template.md       # 输出模板参考（可选）
```

### 2.2 编写 SKILL.md

这是 Skill 的核心。创建 `.claude/skills/changelog-gen/SKILL.md`：

```yaml
---
name: changelog-gen
description: >
  分析 Git 提交历史并生成结构化 CHANGELOG。
  当用户说"生成更新日志"、"changelog"、"版本变更记录"时触发。
  支持按版本号、日期范围、作者过滤提交。
trigger:
  - "生成更新日志"
  - "changelog"
  - "变更记录"
  - "版本更新"
  - "release notes"
allowed-tools:
  - Read
  - Write
  - Bash(git log *)
  - Bash(git tag *)
  - Bash(git diff *)
  - Glob
  - Grep
version: 1.0.0
author: your-name
tags: [git, changelog, release, documentation]
---
```

> **关键点：** `description` 是 Skill 最重要的一行。Claude 通过它判断是否自动激活你的 Skill。遵循公式：**做什么 + 技术栈/领域 + 何时触发**。

YAML frontmatter 之后，编写 Markdown 正文指令：

```markdown
# 代码变更日志生成器

## 工作流程

### 第一步：收集提交信息

1. 运行 `git log --oneline --no-merges` 获取提交概览
2. 运行 `git tag --sort=-v:refname` 获取最近的版本标签
3. 确定变更范围：
   - 如果用户指定了版本号，使用 `git log v{prev}..v{curr}`
   - 如果用户指定了日期，使用 `git log --since="{date}"`
   - 默认使用自上一个 tag 以来的所有提交

### 第二步：分类整理

将提交按以下类别自动分组：
- 🚀 **新功能** (feat): 包含 "feat"、"add"、"新增"、"支持" 的提交
- 🐛 **Bug 修复** (fix): 包含 "fix"、"bug"、"修复"、"解决" 的提交
- ♻️ **重构** (refactor): 包含 "refactor"、"重构"、"优化" 的提交
- 📝 **文档** (docs): 包含 "docs"、"文档"、"README" 的提交
- 🔧 **配置** (chore): 包含 "chore"、"config"、"配置" 的提交
- ✅ **测试** (test): 包含 "test"、"测试" 的提交

### 第三步：生成 CHANGELOG

输出格式严格遵循以下模板：

```markdown
# Changelog

## [版本号] - YYYY-MM-DD

### 🚀 新功能
- **scope**: 简短描述 (#PR号)

### 🐛 Bug 修复
- **scope**: 简短描述 (#PR号)

### 其他变更
- 描述
```

### 边界条件处理
- 如果没有任何提交，输出"自上次发布以来无变更"
- 如果无法识别版本标签，提示用户手动指定范围
- 合并提交（Merge commit）默认排除
- 提交信息过长的截断为 80 字符

### 输出位置
将生成的 CHANGELOG 写入项目根目录的 `CHANGELOG.md` 文件。
如果文件已存在，将新内容插入到文件顶部（保留历史记录）。
```

### 2.3 创建辅助脚本（可选但推荐）

创建 `.claude/skills/changelog-gen/scripts/git-log-fmt.sh`：

```bash
#!/usr/bin/env bash
# 格式化 Git 日志为 JSON，方便 Claude 解析

set -euo pipefail

SINCE="${1:-}"
FORMAT='{ "hash": "%h", "subject": "%s", "author": "%an", "date": "%ad" }'

if [ -n "$SINCE" ]; then
    git log --since="$SINCE" --no-merges --format="$FORMAT" --date=short
else
    git log -50 --no-merges --format="$FORMAT" --date=short
fi
```

赋予执行权限：

```bash
chmod +x .claude/skills/changelog-gen/scripts/git-log-fmt.sh
```

### 2.4 创建输出模板参考（可选）

创建 `.claude/skills/changelog-gen/references/template.md`：

```markdown
# 变更日志模板参考

## 标准格式
- 版本号遵循语义化版本 (SemVer)
- 日期格式：YYYY-MM-DD
- 每个变更条目以动词开头
- PR 号码放在括号内

## 示例输出
## [2.3.0] - 2026-06-09

### 🚀 新功能
- **api**: 新增批量导出接口 (#142)
- **ui**: 支持暗色模式切换 (#138)

### 🐛 Bug 修复
- **auth**: 修复 Token 过期后未自动刷新的问题 (#145)
```

## 三、测试你的 Skill

### 3.1 手动触发测试

在项目目录中启动 Claude Code，输入斜杠命令：

```
/changelog-gen
```

**预期行为：** Claude 应该立即加载 Skill 指令，执行 git 命令收集信息，并生成结构化的 CHANGELOG。

### 3.2 自然语言触发测试

不用斜杠命令，直接用自然语言：

```
帮我生成这个项目的更新日志
```

```
分析最近的 Git 提交，写一份 changelog
```

**预期行为：** Claude 通过 `description` 和 `trigger` 字段匹配，自动激活 Skill。

### 3.3 使用 Eval 系统自动测试

创建 `.claude/skills/changelog-gen/evals.json`：

```json
{
  "skill_name": "changelog-gen",
  "evals": [
    {
      "id": 1,
      "prompt": "生成这个项目的更新日志",
      "expected_output": "生成了包含版本号、日期和分类变更条目的 CHANGELOG.md 文件",
      "assertions": [
        {"name": "file-created", "text": "CHANGELOG.md 文件被创建或更新"},
        {"name": "has-categories", "text": "输出包含至少一个分类标题（新功能/Bug修复等）"},
        {"name": "has-date", "text": "包含日期信息，格式为 YYYY-MM-DD"}
      ]
    },
    {
      "id": 2,
      "prompt": "从 v2.0.0 到现在的变更记录",
      "expected_output": "仅包含 v2.0.0 之后提交的变更日志",
      "assertions": [
        {"name": "version-range", "text": "正确使用版本范围过滤提交"},
        {"name": "no-old-commits", "text": "不包含 v2.0.0 之前的提交"}
      ]
    },
    {
      "id": 3,
      "prompt": "最近一周的 changelog",
      "expected_output": "按日期范围过滤并生成变更日志",
      "assertions": [
        {"name": "date-filter", "text": "使用 --since 参数过滤日期"},
        {"name": "recent-only", "text": "只包含最近7天的提交"}
      ]
    }
  ]
}
```

通过 `/skill-creator` 的 eval 功能运行测试：

```
/skill-creator eval changelog-gen
```

## 四、深入理解 Frontmatter 字段

### 4.1 完整字段参考

```yaml
---
# ===== 必需字段 =====
name: my-skill                    # 唯一标识符，kebab-case 格式
description: >                    # 功能描述 + 触发场景（最关键的字段）
  一句话说明做什么。另一句说明何时触发。

# ===== 触发控制 =====
trigger:                          # 显式触发关键词（补充 description）
  - "关键词1"
  - "关键词2"
disable-model-invocation: false   # true = 只允许 /命令 手动触发
user-invocable: true              # false = 从 / 菜单中隐藏

# ===== 执行环境 =====
context: default                  # default 或 fork（隔离子代理）
model: sonnet                     # 覆盖模型：sonnet/opus/haiku
effort: high                      # 努力级别：low/medium/high/max
agent: Explore                    # context:fork 时的子代理类型

# ===== 权限控制 =====
allowed-tools:                    # 工具白名单
  - Read
  - Write
  - Bash(npm *)
  - Bash(git *)

# ===== 元数据 =====
version: 1.0.0
author: your-name
tags: [tag1, tag2]
disabled: false                   # 暂停而不删除
---
```

### 4.2 字段选择决策树

```mermaid
flowchart TD
    A[开始创建 Skill] --> B{需要自动触发？}
    B -->|是| C[写好 description + trigger]
    B -->|否| D[设置 disable-model-invocation: true]
    C --> E{涉及敏感操作？}
    D --> E
    E -->|是| F[设置 context: fork<br/>限制 allowed-tools]
    E -->|否| G[使用默认 context]
    F --> H{需要特定模型能力？}
    G --> H
    H -->|是| I[设置 model + effort]
    H -->|否| J[使用默认设置]
    I --> K[完成 Frontmatter]
    J --> K
    style A fill:#4A90D9,color:#fff
    style K fill:#2ECC71,color:#fff
```

## 五、六种实战 Skill 设计模式

### 5.1 原子模式（Atomic Pattern）

单一职责，只做一件事。最简单的 Skill 类型。

```yaml
# 示例：代码行数统计
---
name: line-count
description: 统计项目代码行数，按语言分类。输入"统计代码行数"时触发。
trigger: ["代码行数", "line count", "代码统计"]
---
```

**适用场景：** 快捷工具类操作。

### 5.2 管道模式（Pipeline Pattern）

多步骤顺序执行，前一步输出是后一步输入。

```yaml
# 示例：API 文档生成
---
name: api-doc-gen
description: >
  从代码自动生成 API 文档。扫描路由定义 → 提取参数和返回值 → 
  生成 Markdown/OpenAPI 文档。当用户说"生成API文档"时触发。
trigger: ["API文档", "接口文档", "api docs", "openapi"]
---
```

**适用场景：** 多阶段数据转换。

### 5.3 路由模式（Router Pattern）

根据输入条件分发到不同的处理逻辑。

```yaml
# 示例：多框架组件生成器
---
name: component-gen
description: >
  根据项目技术栈生成前端组件。自动检测 React/Vue/Svelte/Angular，
  使用对应的最佳实践和模板。当用户说"创建组件"时触发。
trigger: ["创建组件", "generate component", "新建组件"]
---
```

**适用场景：** 需要适配多种技术栈的通用工具。

### 5.4 扇出模式（Fan-out Pattern）

并行处理多个目标，汇总结果。

```yaml
# 示例：批量文件翻译
---
name: batch-translate
description: >
  批量翻译项目中的 Markdown 文件。支持并行处理多个文件，
  保持原始格式和代码块不变。当用户说"批量翻译"时触发。
trigger: ["批量翻译", "translate files", "翻译文档"]
allowed-tools:
  - Read
  - Write
  - Glob
context: fork
---
```

**适用场景：** 需要并行处理的批量任务。

### 5.5 守卫模式（Guard Pattern）

在关键操作前进行安全检查。

```yaml
# 示例：安全部署守卫
---
name: deploy-guard
description: >
  部署前安全检查。运行测试 → 检查敏感信息泄露 → 验证依赖安全性 → 
  确认版本号更新。任何检查失败则阻止部署。当用户说"部署"时触发。
trigger: ["部署", "deploy", "发布上线"]
disable-model-invocation: true
---
```

**适用场景：** 安全敏感的阻断式流程。

### 5.6 适配器模式（Adapter Pattern）

将一种格式/协议转换为另一种。

```yaml
# 示例：数据库 Schema 转换器
---
name: schema-adapter
description: >
  在不同 ORM 的 Schema 格式间转换。支持 Prisma ↔ TypeORM ↔ 
  Sequelize ↔ Drizzle 互转。当用户说"转换 Schema"时触发。
trigger: ["转换schema", "schema迁移", "ORM转换"]
---
```

**适用场景：** 格式转换、平台迁移。

## 六、进阶技巧

### 6.1 description 优化公式

description 是 Skill 的"SEO"。优化原则：

```python
# 好的 description 公式
"[做什么] + [技术栈/领域] + [何时触发]"

# ❌ 差的写法
description: "代码生成工具"

# ✅ 好的写法
description: >
  从 OpenAPI/Swagger 规范自动生成 Express.js 路由处理器和 TypeScript 类型定义。
  当用户提供 API 规范文件并要求生成后端代码时触发。
```

**经验法则：** 保持 50-150 个字符；包含 2-3 个具体触发场景；避免模糊描述。

### 6.2 工具权限精细化控制

```yaml
# 精确控制 Bash 命令范围
allowed-tools:
  - Read                              # 所有文件读取
  - Bash(git log *)                   # 只允许 git log
  - Bash(npm test *)                  # 只允许 npm test
  - Bash(npx eslint *)                # 只允许 eslint
  - Grep                              # 所有搜索
  - Glob                              # 所有文件匹配
```

**安全提示：** 对于可能产生副作用的 Skill（修改文件、执行命令），始终设置最窄的 `allowed-tools` 范围。

### 6.3 使用 context:fork 隔离执行

当 Skill 可能消耗大量上下文窗口时：

```yaml
context: fork        # 在独立子代理中执行
model: sonnet        # 使用更快/便宜的模型
effort: medium       # 适中的努力级别
```

适用情况：
- 需要处理大量文件的批量操作
- 生成过程可能产生大量中间输出
- 不希望污染主对话上下文

### 6.4 辅助资源分层加载

```
skill-name/
├── SKILL.md              # 始终加载（< 500 行）
├── scripts/              # Claude 按需调用
│   ├── validate.sh       # 输入验证
│   └── format.py         # 输出格式化
└── references/           # 仅在需要时读取
    ├── api-spec.md       # 参考文档
    └── examples.md       # 示例集合
```

在 SKILL.md 正文中引用资源的方式：

```markdown
## 参考资料
- 如需了解 API 规范细节，读取 `references/api-spec.md`
- 格式化输出时，先执行 `scripts/format.py`
```

## 七、发布与分享

### 7.1 项目级分享（Git）

最简单的分享方式——将 `.claude/skills/` 提交到 Git 仓库：

```bash
git add .claude/skills/changelog-gen/
git commit -m "feat: add changelog generator skill"
```

团队成员 clone 项目后自动获得该 Skill。

### 7.2 个人级安装

将 Skill 复制到个人目录，所有项目可用：

```bash
cp -r .claude/skills/changelog-gen/ ~/.claude/skills/
```

### 7.3 通过 skill-creator 优化和打包

使用内置的 skill-creator 进行优化：

```
/skill-creator optimize changelog-gen
```

该命令会：
1. 分析触发准确率
2. 优化 description 措辞
3. 建议工具权限调整
4. 运行 eval 测试套件

### 7.4 社区发布

将 Skill 发布到 GitHub 仓库供社区使用：

```bash
# 创建独立的 Skill 仓库
mkdir claude-skill-changelog-gen
cd claude-skill-changelog-gen

# 复制 Skill 文件
cp -r ../your-project/.claude/skills/changelog-gen/* .

# 添加 README 和 package 信息
# 推送到 GitHub
git init && git add . && git commit -m "init"
git remote add origin https://github.com/yourname/claude-skill-changelog-gen.git
git push -u origin main
```

用户安装：

```bash
# 克隆到个人 Skills 目录
git clone https://github.com/yourname/claude-skill-changelog-gen.git \
    ~/.claude/skills/changelog-gen
```

## 八、完整工作流程图

```mermaid
flowchart TB
    subgraph "Skills 开发全流程"
        A["1. 需求分析<br/>确定 Skill 要解决什么问题"]
        B["2. 目录创建<br/>mkdir -p .claude/skills/name"]
        C["3. 编写 Frontmatter<br/>name + description + trigger"]
        D["4. 编写指令正文<br/>步骤化工作流"]
        E["5. 添加辅助资源<br/>scripts/ references/"]
        F["6. 手动测试<br/>/skill-name"]
        G["7. Eval 自动测试<br/>多场景验证"]
        H["8. 优化迭代<br/>description + 触发精度"]
        I["9. 发布分享<br/>Git / 社区"]
    end

    A --> B --> C --> D --> E --> F
    F -->|"有问题"| D
    F -->|"通过"| G
    G -->|"失败"| H
    H --> D
    G -->|"全部通过"| I

    style A fill:#3498DB,color:#fff
    style I fill:#2ECC71,color:#fff
    style H fill:#E67E22,color:#fff
```

## 九、常见问题与排错

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| Skill 不被自动触发 | description 不够精确 | 优化描述，添加 trigger 关键词 |
| 触发了错误的 Skill | 多个 Skill description 重叠 | 细化描述，使用更具体的领域词汇 |
| Skill 执行报权限错误 | allowed-tools 未包含需要的工具 | 添加工具到白名单 |
| 输出结果不符合预期 | 指令不够具体 | 添加更多示例和格式说明 |
| context 窗口溢出 | SKILL.md 过长或参考文件太多 | 缩减正文，使用 references/ 分层加载 |
| `/` 菜单看不到 Skill | user-invocable 设为 false | 改为 true 或移除该字段 |
| fork 模式下工具不可用 | 子代理未继承工具权限 | 在 allowed-tools 中明确列出 |

## 十、实战案例：完整的代码审查 Skill

以下是一个可直接使用的完整 Skill，综合运用了本文所有知识点：

`.claude/skills/pr-review/SKILL.md`：

```yaml
---
name: pr-review
description: >
  对当前分支的代码变更进行全面审查，覆盖安全漏洞、性能问题、
  代码规范和最佳实践。当用户说"审查代码"、"review PR"、
  "检查代码质量"时自动触发。
trigger:
  - "审查代码"
  - "review"
  - "代码检查"
  - "PR审查"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(git diff *)
  - Bash(git log *)
context: fork
effort: high
version: 1.0.0
tags: [code-review, security, quality]
---

# PR 代码审查

## 工作流程

### 第一步：获取变更范围
1. 运行 `git diff --name-only main...HEAD` 获取变更文件列表
2. 过滤掉无关文件（lock 文件、自动生成文件）
3. 对每个文件运行 `git diff main...HEAD -- <file>` 获取具体变更

### 第二步：逐文件审查
对每个变更文件按以下维度分析：

**安全性（Critical）：**
- SQL 注入、XSS、CSRF 风险
- 硬编码密钥、Token、密码
- 不安全的反序列化
- 未验证的用户输入

**性能（High）：**
- N+1 查询问题
- 不必要的全表扫描
- 内存泄漏风险
- 缺少缓存的热路径

**代码质量（Medium）：**
- 命名不规范
- 重复代码
- 过深的嵌套
- 缺少错误处理

**最佳实践（Low）：**
- 框架惯用法偏离
- 缺少类型注解
- 文档缺失

### 第三步：生成审查报告

输出格式：

```markdown
# 🔍 代码审查报告

## 概要
- 变更文件：X 个
- 发现问题：Critical X / High X / Medium X / Low X
- 总体评价：✅ 可合并 / ⚠️ 需修改 / ❌ 需重做

## Critical 问题
### [SEC-001] SQL 注入风险
- **文件**：`src/api/users.ts:45`
- **代码**：`query("SELECT * FROM users WHERE id = " + id)`
- **建议**：使用参数化查询

## 亮点 🌟
- [值得肯定的代码实践]

## 改进建议
- [非阻断性建议]
```
```

安装测试：

```bash
mkdir -p .claude/skills/pr-review
# 将上面的内容保存为 .claude/skills/pr-review/SKILL.md
```

在 Claude Code 中触发：

```
/review
```

或自然语言：

```
帮我审查一下当前分支的代码变更
```

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| **适合训练营类型** | AI 工程师实战营、开发者效率提升营、DevOps 自动化营 |
| **预计教学时长** | 4-6 小时（含实操练习） |
| **难度等级** | ⭐⭐⭐ 中级（需要 Claude Code 使用基础） |
| **实操占比** | 70% 动手 + 30% 理论 |
| **考核方式** | 学员独立创建一个可用的自定义 Skill 并通过 eval 测试 |
| **前置课程** | Claude Code 入门篇（安装配置与基本使用） |
| **后续课程** | MCP 服务器开发（Skill + MCP 组合进阶） |

## 参考来源

1. [Claude Code Skills 官方文档 - Anthropic](https://docs.anthropic.com/en/docs/claude-code/skills) — Skills 系统完整规范和 API 参考
2. [Claude Code GitHub Skills 示例仓库 - anthropics/agent-skills](https://github.com/anthropics/agent-skills) — 官方示例 Skills 源码，含 skill-creator 等核心 Skill
3. [Claude Code 最佳实践指南 - Anthropic Engineering Blog](https://www.anthropic.com/engineering/claude-code-best-practices) — Skill 设计模式、触发优化和 eval 测试方法论
4. [SkillsMP 社区市场 - skillsmp.dev](https://skillsmp.dev) — 社区 Skill 分发平台，1000+ 可安装 Skills
skills for team workflows"
```

团队其他成员 `git pull` 后立即可用。

### 9.2 跨项目复用

将 Skill 放在用户全局目录：

```bash
# 全局 Skills 目录
mkdir -p ~/.claude/skills/my-skill/
cp -r .claude/skills/changelog-generator ~/.claude/skills/
```

所有项目都能使用该 Skill。

### 9.3 发布到社区

**方式一：GitHub 仓库**

```bash
# 创建专用仓库
mkdir claude-code-skills
cd claude-code-skills
git init

# 每个 Skill 一个目录
cp -r ~/project/.claude/skills/changelog-generator ./
cp -r ~/project/.claude/skills/api-doc-generator ./

# 添加 README
echo "# My Claude Code Skills\n\nInstall with ..." > README.md

git add . && git commit -m "Initial skills collection"
git remote add origin https://github.com/username/claude-code-skills
git push -u origin main
```

**方式二：SkillsMP 市场**

2026 年 Claude Code 社区出现了 SkillsMP（Skills Marketplace），支持一键安装：

```bash
# 安装他人发布的 Skill
claude skill install @username/changelog-generator

# 发布自己的 Skill
claude skill publish ./changelog-generator
```

### 9.4 Skill 安装清单

在项目根目录维护一个 `skills.json` 记录依赖的 Skills：

```json
{
  "skills": [
    {
      "name": "changelog-generator",
      "source": "git+https://github.com/username/claude-skills#changelog-generator",
      "version": "1.0.0"
    },
    {
      "name": "api-doc-generator",
      "source": "local",
      "path": ".claude/skills/api-doc-generator"
    }
  ]
}
```

---

## 十、调试与优化技巧

### 10.1 调试 Skill 触发

如果 Skill 没有被触发，按以下步骤排查：

```mermaid
flowchart TD
    A[Skill 未触发] --> B{检查 SKILL.md 位置}
    B -->|位置错误| C[移到 .claude/skills/name/SKILL.md]
    B -->|位置正确| D{检查 frontmatter}
    D -->|格式错误| E[修复 YAML 语法]
    D -->|格式正确| F{检查 trigger}
    F -->|不匹配| G[添加更多触发词]
    F -->|匹配| H{检查 Claude 版本}
    H -->|版本过低| I[升级到 1.0+]
    H -->|版本正常| J[检查是否有多个 Skill 冲突]
```

### 10.2 优化 Skill 性能

| 优化方向 | 具体方法 | 效果 |
|----------|----------|------|
| 减少上下文 | SKILL.md 控制在 500 行以内 | 降低 Token 消耗 |
| 精准触发 | trigger 条件控制在 3-5 个 | 减少误触发 |
| 脚本输出 | 脚本返回结构化 JSON | Claude 解析更准确 |
| 分层指令 | 简单任务在前，复杂逻辑在后 | 按需深入 |
| 懒加载 | 大段模板放在 resources/ 下 | 只在需要时读取 |

### 10.3 版本管理最佳实践

```bash
# 在 SKILL.md 中记录版本
---
name: changelog-generator
version: "1.2.0"
changelog:
  - "1.2.0: 支持自定义输出格式"
  - "1.1.0: 添加 Conventional Commits 分类"
  - "1.0.0: 初始版本"
---

# 使用 Git tag 管理 Skill 版本
git tag -a "skill/changelog-generator/v1.2.0" -m "Changelog generator v1.2.0"
```

---

## 十一、Skills 与 MCP 的协作模式

Skills 和 MCP（Model Context Protocol）不是互斥的，而是互补的：

```mermaid
graph TB
    subgraph "Claude Code 扩展体系"
        A[用户输入] --> B{路由判断}
        B -->|简单工作流| C[Skills 处理]
        B -->|外部工具调用| D[MCP Server 处理]
        B -->|复杂场景| E[Skills + MCP 协作]

        C --> F[纯指令执行]
        D --> G[调用外部 API/工具]
        E --> H[Skill 定义流程]
        H --> I[MCP 提供工具]
        I --> J[整合输出]
    end

    style C fill:#4CAF50,color:#fff
    style D fill:#2196F3,color:#fff
    style E fill:#FF9800,color:#fff
```

| 维度 | Skills | MCP |
|------|--------|-----|
| 本质 | 结构化的提示词 | 外部工具服务器 |
| 开发成本 | 写 Markdown | 写代码（Python/TS） |
| 能力边界 | Claude 自身能力 | 无限扩展（API/数据库/文件） |
| 调试难度 | 低 | 中到高 |
| 共享难度 | 极低（复制文件） | 中（需要部署服务器） |

**最佳实践：** 先用 Skills 解决问题，当 Skills 的纯指令能力不够时，再引入 MCP。

---

## 十二、常见问题 FAQ

**Q1：一个项目可以有多个 Skill 吗？**

可以。`.claude/skills/` 下每个子文件夹是一个独立的 Skill。Claude 根据触发条件自动选择匹配的 Skill。

**Q2：Skill 之间可以互相调用吗？**

目前不支持 Skill 间的直接调用。但可以在 SKILL.md 的 Instructions 中引导 Claude 执行另一个 Skill 的触发命令，实现间接串联。

**Q3：Skills 的 frontmatter 支持哪些字段？**

核心字段为 `name`、`description`、`trigger`。社区扩展了 `version`、`author`、`tags` 等字段，部分市场工具会识别。

**Q4：Skill 执行时会影响 Claude 的上下文窗口吗？**

会。SKILL.md 的内容会占用上下文窗口。建议控制单个 Skill 在 2000 Token 以内，复杂内容放在 resources/ 下按需读取。

**Q5：如何让 Skill 只在特定项目中生效？**

放在项目的 `.claude/skills/` 下即可，只在当前项目生效。放在 `~/.claude/skills/` 下则全局生效。

---

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| 适合训练营类型 | AI 工具实战训练营、开发者效率提升营 |
| 教学时长 | 2-3 小时（含动手练习） |
| 难度定位 | 中级（需 Claude Code 基础使用经验） |
| 实操比例 | 70% 动手 + 30% 讲解 |
| 分组建议 | 2-3 人一组，每组完成 1 个自定义 Skill |
| 考核方式 | 现场演示 Skill 的触发与执行效果 |

---

## 参考来源

1. [Extend Claude with skills - Claude Code 官方文档](https://code.claude.com/docs/en/skills) — Anthropic 官方 Skills 开发指南，涵盖创建、管理和分享
2. [How to Build Claude Code Skills: 5 Examples (2026)](https://fp8.co/articles/Claude-Code-Skills-Complete-Developer-Guide) — FP8 提供的 5 个完整 Skill 示例，含 SKILL.md 规范和安全控制
3. [Agent Skills Tutorial - GitHub](https://github.com/StrayDragon/my-claude-skills/blob/main/CLAUDE_CODE_SKILL_TUTORIAL.md) — 开源社区维护的 Skills 教程，含目录结构和最佳实践
4. [Claude Skills Tutorial: Build Your First SKILL.md in 10 Minutes](https://techsy.io/en/blog/claude-skills-tutorial) — Techsy 的快速入门教程，适合 10 分钟内上手
5. [skill-creator Complete Guide - SmartScope](https://smartscope.blog/en/ai-development/skills/skill-creator-complete-guide/) — skill-creator 工具的完整使用指南，含 eval 流水线说明

> [!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)