写过 11 个 Skill 后，我总结出一套从 0 到 1 的“Skill 开发 5 步法“——附 3 个模板 + 5 大反模式

鑫云数智

238人浏览 · 2026-05-29 17:58:54

鑫云数智 · 2026-05-29 17:58:54 发布

写这一章之前，我自己已经在 Claude Code 上开发和使用了 11 个 Skill——鉴渊、DocManager、frontend-architect、quant-auditor、master-architect、comic-video、docx/xlsx/pptx/pdf 四件套、claude-api……

它们的形态完全不同——有"知识对话型"（鉴渊覆盖 3000+ 著作）、有"工具集成型"（DocManager 集成本地文档库）、有"工作流编排型"（comic-video 跑从剧本到成片的全自动流水线）、有"专业审计型"（quant-auditor 用 Red Team 视角找量化系统的 Bug）。

但是当我把这 11 个 Skill 摆在一起看的时候，我发现——**它们背后是同一套设计原理**。

这一章就是把这套原理抽出来，**变成可复用、可教学的"通用 Skill 开发方法论"**。读完之后，你应该能独立完成自己的第一个 Skill——从问题识别、能力边界设计、SKILL.md 编写、迭代测试到落地使用。

> **「读万卷书不如行万里路，行万里路不如自己造一个。」** —— 鉴渊

下面把这件事讲透。

### 一、再探 Skill 的本质——它是知识编排，不是代码插件

当大多数开发者听到"扩展系统"时，脑中浮现的是 VSCode Extension、Chrome Plugin、Vim Plugin——你写一段代码，编辑器/浏览器加载它，代码在运行时执行。

**Claude Code 的 Skill 完全不同。** 一个 Skill **不包含任何可执行代码**——它是一个 Markdown 文件（SKILL.md），里面写的是自然语言指令和领域知识。当用户的请求触发了某个 Skill，Claude Code 把 SKILL.md 注入到 Claude 的上下文，让 Claude "临时获得"这个领域的专家知识。

打个比方——

- 传统插件像给机器人安装了一条新机械臂——它获得了一个新的物理能力。
- Skill 像给一个通才顾问递了一本专业手册——他本来就能做这件事，但现在他知道了最佳实践和注意事项。

**区别在于：机械臂是能力的扩展，手册是知识的注入。**

下面这张表把 VSCode Extension 与 Claude Skill 的九个维度差异列出来——

| 维度 | VSCode Extension | Claude Skill |
| --- | --- | --- |
| 实现语言 | TypeScript / JavaScript | 自然语言（Markdown） |
| 执行方式 | Node.js 进程内运行 | 注入 LLM 上下文 |
| API 依赖 | vscode.* API，版本耦合 | 无 API 依赖，零耦合 |
| 分发方式 | Marketplace 发布 | Git 仓库或本地目录 |
| 开发门槛 | TypeScript + VSCode API | 领域知识 + 提示工程 |
| 调试方式 | 断点、日志 | 观察 Claude 行为是否符合预期 |
| 升级维护 | 需跟随 VSCode API 变更 | 几乎永远不需要更新 |
| 能力边界 | 受限于 API 暴露的功能 | 理论上可编排 Claude 能做的任何事 |
| 可组合性 | 通常独立运行 | 多 Skill 可同时激活，知识叠加 |

**最后一行特别值得关注。** VSCode Extension 只能调用 vscode.* API 暴露的功能——API 不支持的操作，你就无法实现。但 Skill 的能力边界 = Claude 本身的能力边界。Claude 能写代码、能分析数据、能生成文档——**Skill 只是告诉它"在特定场景下应该怎么做"**。

这意味着——**Skill 的上限不取决于平台 API 的丰富程度，而取决于编写者的知识编排能力**。一个优秀的 Skill 编写者需要的不是编程技能，而是**领域专业知识 + 将知识结构化表达的能力**。

### 二、SKILL.md 文件结构——description / TRIGGER / DO NOT TRIGGER

每个 Skill 是一个目录，至少包含一个 SKILL.md 文件。这个文件由两部分组成——frontmatter（YAML 元数据）和 body（Markdown 指令内容）。

```markdown
---
name: frontend-architect
description: |
全栈前端架构师技能包——融合设计思维、UI 风格系统、
工程最佳实践、性能优化于一体。
适用于 React/Vue/Svelte/原生 HTML 项目。
---

# Frontend Architect Skill

## TRIGGER
当用户要求构建 Web 页面、组件、应用时自动激活。

## DO NOT TRIGGER
- 纯后端 API 开发
- 数据库操作
- 非 Web 的 CLI 工具

## 核心原则
1. 移动优先响应式设计
2. 组件化思维
3. 性能预算意识
...
```

**description 字段是触发匹配的关键。** 它不只是给人看的说明——它直接参与 Skill 的语义匹配。当用户输入请求时，Claude Code 会将请求文本与所有已安装 Skill 的 description 进行语义匹配，匹配度最高的 Skill 会被注入上下文。

好的 description 应该——

- **包含关键词**——用户可能用的专业术语
- **描述能力范围**——让匹配算法理解适用边界
- **保持简洁**——过长的 description 反而降低匹配精度

**TRIGGER / DO NOT TRIGGER 是 Skill 可靠性的核心保障。**

为什么需要反面条件？因为自然语言的模糊性。"帮我写个文档"——应触发 docx Skill 还是 frontend-architect？如果用户写的是 API 文档但包含代码示例，这模棱两可。DO NOT TRIGGER 帮助消除这种歧义——告诉系统"虽然请求中包含代码相关词，但如果核心需求是文档写作而非前端开发，不要触发 frontend-architect"。

**好的触发条件像法律条文一样精确**——每个条件都是可判断的、无歧义的。模糊的触发条件（如"当用户需要帮助时"）会导致 Skill 被过度触发，浪费上下文窗口；遗漏的触发条件会导致该激活时没被激活。

### 三、5 步法——从 0 到 1 开发一个 Skill

#### Step 1 · 定义能力边界

开发 Skill 前最重要的问题不是"这个 Skill **能**做什么"，而是"这个 Skill **不**做什么"。

方法是画一张"能力矩阵"，把每项任务标记为「必须支持 / 最好支持 / 明确不支持」——

| 任务 | 代码审查 Skill | 理由 |
| --- | --- | --- |
| 审查代码质量 | 必须支持 | 核心能力 |
| 审查安全漏洞 | 必须支持 | 高价值场景 |
| 审查性能问题 | 最好支持 | 有一定复杂度但有用 |
| 重构代码 | 明确不支持 | 超出审查范围，应由其他 Skill 处理 |
| 编写测试 | 明确不支持 | 不同的工作流，不应混在一起 |

**"明确不支持"的列表往往比"必须支持"更重要**——它防止 Skill 变成"什么都做但什么都做不好"的万能 Skill。

#### Step 2 · 编排领域知识

这是 Skill 开发中最需要专业功底的一步。**关键技巧——不要写"教科书"，要写"检查清单"**。

Claude 已经有广泛的基础知识。Skill 提供的是"在这个特定场景下，最重要的 N 件事"。

```markdown
## 代码审查检查清单

### 安全审查 (优先级: P0)
- [ ] SQL 查询是否参数化？直接拼接 SQL = 立即标红
- [ ] 用户输入是否经过验证？特别是路径、URL、正则
- [ ] 密钥/Token 是否硬编码？检查所有字符串常量

### 质量审查 (优先级: P1)
- [ ] 函数长度是否超过 50 行？超过则建议拆分
- [ ] 嵌套深度是否超过 3 层？考虑早返回/策略模式
- [ ] 错误处理是否吞掉异常？catch 块至少要有日志
```

#### Step 3 · 设计工作流

工作流定义了 Claude 使用这个 Skill 时的操作步骤。**一个好的工作流应该是线性的、每步有明确产物的**。避免分支过多——分支越多，Claude 的执行一致性越差。

```
代码审查 Skill 的工作流：
[ 理解变更 ] → [ 安全审查 ] → [ 质量审查 ] → [ 总结报告 ]
```

#### Step 4 · 编写 SKILL.md

有了前三步的准备，编写就是组装工作。但有几个技巧——

- **指令用祈使句**——"检查所有 SQL 查询"而非"应该检查 SQL"
- **用具体示例代替抽象描述**——"像 `SELECT * FROM users WHERE id=${userId}` 这样的拼接"比"SQL 注入风险"更有指导性
- **分优先级**——P0/P1/P2 帮助 Claude 在时间有限时集中精力
- **给正反两种示例**——告诉 Claude"好的代码长这样，差的代码长这样"
- **限制总长度**——SKILL.md 不应超过 30KB（详见第五条）

#### Step 5 · 测试与迭代

Skill 的测试不像代码测试那样有 assert——你需要通过实际使用来观察 Claude 的行为是否符合预期。

准备 5-10 个测试场景，覆盖正常情况和边界情况。常见的迭代发现——

- 触发条件太宽导致误触发
- 某个检查项描述不清导致 Claude 理解偏差
- 工作流步骤之间缺少衔接导致跳步

这个循环通常需要 **3-5 轮**才能达到满意稳定性。

### 四、5 大设计原则 + 5 大反模式

**5 大设计原则**——

| # | 原则 | 解释 |
| --- | --- | --- |
| 1 | 单一职责 | 一个 Skill 做一件事。"代码审查"和"代码重构"应是两个 Skill |
| 2 | 可观察性 | 工作流应产出可见的中间产物。每个阶段有明确输出 |
| 3 | 优雅降级 | 定义信息不完整时的行为。基于可见信息给出最好建议，而不是拒绝工作 |
| 4 | 幂等性 | 同样输入产生一致输出。如果每次给不同意见，说明清单不够精确 |
| 5 | 最小上下文 | 只注入必要知识。30KB 的 SKILL.md 几乎总是太长 |

**5 大反模式**——

| # | 反模式 | 典型表现 |
| --- | --- | --- |
| 1 | 瑞士军刀 | 一个 Skill 试图覆盖所有功能 → 拆成多个专注的 Skill |
| 2 | 教科书 | SKILL.md 写成入门教程 → 提供"如何检测"而非"什么是 X" |
| 3 | 空中楼阁 | 工作流华丽但缺少具体判断标准 → 量化（"超过 50 行"）而非定性 |
| 4 | 锁定 | 指令过于刚性 → 给 Claude 灵活应对空间 |
| 5 | 自说自话 | 写得详尽但没测试过 → 5-10 个场景实测 |

### 五、SKILL.md 不超过 30KB 的设计约束

为什么强调 SKILL.md 不应超过 30KB？因为 Skill 内容会被注入到上下文窗口中——一个过大的 Skill 会——

- **压缩可用上下文**——留给用户代码和对话历史的空间变少
- **降低注意力密度**——人类阅读 1000 页手册时会遗漏细节，Claude 也一样
- **增加延迟和成本**——更长上下文意味着更长推理时间和更多 token

实用估算：30KB Markdown ≈ 15,000 中文字 ≈ 7,500 英文词 ≈ 10,000-15,000 token。Claude 的上下文窗口（200K-1M）中，单个 Skill 占比理想 **< 5-7%**。

**大小控制的实用技巧**——

1. 用检查清单代替解释性文字——"检查 SQL 参数化"比"SQL 注入是一种常见的...（200 字）"高效 10 倍
2. 引用外部文档而非内联——"详细标准参见 OWASP Top 10"比把列表全部抄入更好
3. 分层 Skill——把大 Skill 拆成"快速审查"和"深度审查"两个
4. 定期瘦身——每隔一段时间重新审视，删除实践中证明不重要的条目

### 六、三种通用模板：领域专家型 / 工作流编排型 / 工具集成型

**模板一·领域专家型**（适合：编码规范、安全审计、合规检查）

```
---
name: <skill-name>
description: <一句话定位 + 关键词列表>
---

## TRIGGER
<列出 3-5 条精确触发条件>

## DO NOT TRIGGER
<列出 3-5 条排除条件>

## 核心原则
<5-10 条领域内最重要的法则>

## 检查清单 / 决策框架
<分级（P0/P1/P2）的具体可操作项>

## 输出格式
<明确的输出 schema>
```

**模板二·工作流编排型**（适合：CI/CD、发布流程、多步骤任务）

```
## 工作流
### Stage 1: <名称>
Input: <从哪里来>
Activity: <做什么，工具调用清单>
Output: <产出什么>
### Stage 2: ...

## 异常处理
<每阶段失败时的兜底策略>
```

**模板三·工具集成型**（适合：与外部系统集成，如 DocManager、内部 API、CMDB）