---
sha256: 5f42496f3c4775e959e0fb39e0dc1e9ecd90897fdb80619ddc30c4f39aadf837
source: "https://mp.weixin.qq.com/s/SZv3pDXPrL9vwV3Ua_84Kg"
title: "鹅厂团队 14 章节完整 Skill 写作实战：踩坑经验 + 工程化评估（Anthropic 官方做法整合）"
author: jackjchou（腾讯）
publisher: 腾讯程序员
date: 2026-06-05
type: article
ingested: 2026-06-05
review_value: 8
review_confidence: 8
review_recommendation: worth-reading
---

# 鹅厂团队 14 章节完整 Skill 写作实战：踩坑经验 + 工程化评估

> 作者：jackjchou（腾讯） · 发布：2026-06-05

> 这篇文章把我们写 Skill 踩过的坑、总结出的经验，再加上 Anthropic 官方的一些好做法，整理到了一起。希望能帮你少走弯路，把团队积累的知识真正"喂"给 AI，让它干活更靠谱。

> 本文示例以 Go 语言为主，兼顾 Python、Java 等语言，所有原则和技巧适用于任何编程语言。

## 阅读建议

| 你的情况 | 推荐阅读路径 |
|----------|--------------|
| 从没写过 Skill，想快速上手 | 一 → 二（重点看 2.5 Quick Start）→ 三 → 八 |
| 写过但效果不好，想提升质量 | 三 → 五 → 十二（反模式）→ 十三（检查清单） |
| 负责团队 Skill 规范和管理 | 四 → 七 → 十一 → 十二 |
| 想了解 MCP 和外部服务集成 | 六 |
| Skill 跑不通，想排查问题 | 九 → 十 |

## 一、Skill 是什么

### 1.1 Skill 本质

**Skill = 给 AI 编程助手（Claude Code、CodeBuddy 等）"加装"的能力包**。本质上，它是一种**结构化的 Prompt Engineering**——通过标准的文件格式，把分散在人脑中的领域知识、操作流程和最佳实践，转化为 AI 可理解、可执行的指令集。

物理上看，它就是一个文件夹，里面放一个 `SKILL.md` 文件，再加上一些可选的脚本和参考资料。**核心就三样东西**：
- **指令（Instructions）**：告诉 AI 该怎么干活，按什么步骤来
- **上下文（Context）**：给 AI 补课，告诉它项目背景、团队规范
- **工具（Tools）**：辅助脚本、配置模板，AI 可以直接拿来用

> "裸着的 AI 就像一个刚入职的新人，啥都得问；装了 Skill 之后，就像拿到了老员工整理的操作手册，照着就能干。"

### 1.2 5 大痛点

| 痛点 | Skill 怎么解决 |
|------|----------------|
| **知识太散**（经验藏在 TAPD/Wiki/代码注释/脑子里） | 全部整理进 Skill，将知识结构化封装 |
| **重复搬砖** | 写成 Skill 让 AI 自动跑 |
| **做出来不统一**（张三一个样李四一个样） | 用 Skill 固定流程，谁来做都一个标准 |
| **新人上手慢** | Skill 本身就是最好的培训材料 |
| **人走知识也走** | 把经验沉淀进 Skill，知识完整留存 |

### 1.3 渐进式加载机制（Anthropic 设计）

| 层级 | 加载时机 | 内容要求 | Token 成本 |
|------|----------|----------|------------|
| **Level 1** | 常驻（每次对话都在） | name + description，控制在 100 字以内 | **50-150 Token / 个 Skill** |
| **Level 2** | 匹配触发时一次性加载 | SKILL.md 正文，建议不超过 500 行 | **2,000-5,000 Token** |
| **Level 3** | 执行中按需读取 | 脚本、参考文档、模板等 | 按实际引用大小计算 |

**Token 估算规则**：
- 英文：约 1 Token / 4 字符
- 中文：约 1 Token / 1.5-2 字符
- 不同模型 tokenizer 差异 ±20%

**核心原则**："**Level 1 越精准越好**（决定触发时机），**Level 2 越精简越好**（减少 Token 消耗），**Level 3 放心放**（按需加载不占常驻空间）。"

## 二、Skill 长什么样

### 2.1 基本结构

```
my-skill/
├── SKILL.md              # 核心指令文件（必需）
├── scripts/              # 可执行脚本（可选）
├── references/           # 参考文档（可选）
└── assets/               # 静态资源（可选）
```

## 三、Description 是 Skill 灵魂

**Description 决定了 Skill 在什么时候被触发**——写好 description = Skill 能被正确调用。

**实战经验**：
- 把"做什么 + 触发场景 + 不做什么"三件事说清
- 加入**具体关键词**（Go / HTTP / 迁移等）
- 包含**反例**（避免误触发）
- 长度控制在 100 字以内（Level 1 token 上限）

**触发评估小技巧**："触发评估"——自己想 20 个问题（一半该触发、一半不该触发），测试 AI 是不是每次都能正确判断。如果命中率不够高，就回来调 description。

## 四、Skill 主体写作原则

### 4.1 开头说清三件事

每个 Skill 上来就该把**做什么 + 为什么 + 怎么判断是否需要做**说明白。

**反例 ❌**：
```
# API 对接
把旧的 API 调用改成新的。
```

**正面案例 ✅**：
```
## 目标
将项目中的 HTTP 请求从 old-http-client 迁移到 unified-httpclient
## 适用判断
执行前检查项目是否使用了旧版客户端：grep "old-http-client" go.mod
如果未使用该模块，可跳过此 Skill。
```

### 4.2 祈使句下指令 + 解释"为什么"

**原则 1**：别用商量的口吻，直接说"做什么"。

**原则 2**：与其一堆"MUST"，不如讲清楚为什么。

> "AI 要是理解了背后的道理，遇到你没想到的情况也能做出合理判断。光靠'MUST'只是死记硬背，换个场景就傻了。"

### 4.3 Before/After 对比（最关键部分）

让 AI 清楚知道"改什么"和"改成什么"。**三种方式**：
- **方式 1：注释标注**（适合简单变更）
- **方式 2：完整文件对比**（适合复杂变更）
- **方式 3：Diff 格式**（推荐，最直观）

### 4.4 Few-Shot 3-5 个示例

**经验之谈**：在 Skill 里放 **3-5 个高质量的输入/输出示例**，AI 的表现会稳定很多。

**关键原则**：
- 覆盖典型场景（正常/边界/错误各一个）
- 输入输出成对出现
- 示例之间有差异
- 先放最典型的（AI 倾向模仿前面的）

### 4.5 复杂检查点（Checkpoint）

在关键步骤之间插入验证命令——"**不是一口气跑完才验证，中间有自检**"。

## 五、模块化拆分（主 Skill + 子 Skill）

**子 Skill 拆分原则**：按业务环节拆，每个子 Skill 都能单独使用。

**好处**：
- 只需要部分改造的场景
- 快速修复特定问题
- 新项目的增量接入

**关键约束**："**拆出来的子 Skill 不应该离了主流程就没法跑**"。

## 六、MCP 集成

**MCP（Model Context Protocol）**——专为 AI 设计的标准化工具协议。

**核心价值**：让 Skill 可以**安全调用外部服务和数据源**（数据库、API、内部系统）。

## 七、安全设计

### 7.1 4 大安全风险

| 风险 | 防护措施 |
|------|----------|
| 读取用户提供文件名（嵌入 AI 指令） | 路径格式校验，只允许合法字符 |
| API 返回内容拼入 Skill 指令（注入） | 标记为"数据"而非"指令" |
| 环境变量值拼接命令（shell 注入） | 引号包裹 + 格式校验 |
| 文件路径操作（路径穿越） | 拒绝 `..` 路径段 |

**核心原则**："**区分'指令'和'数据'。Skill 中的步骤是指令，从外部读取的内容是数据。数据永远不应该被当成指令来执行。**"

## 八、Skill Creator（Anthropic 官方"帮你写 Skill 的 Skill"）

**Skill Creator 思路**："**先写出来 → 测一测 → 看效果 → 逐步优化 → 工程化评估兜底**"。

### 8.1 安装方式
- **插件市场**：CodeBuddy/WorkBuddy 搜索 `skill-creator` 一键安装
- **OpenSkills**：`npx openskills install anthropics/skills`
- **手动安装**：`git clone https://github.com/anthropics/skills.git` 后复制到 `~/.codebuddy/skills/`

### 8.2 5 步工作流程

1. **定义意图**：用大白话描述 Skill 做什么，Skill Creator 追问细节
2. **生成草稿**：自动生成 SKILL.md（含 YAML 元数据 + Markdown 指令）
3. **对比测试**：2-3 个测试用例 + 并发运行"有 Skill"vs"无 Skill"两组对比
4. **反馈迭代**：哪里不满意直接说，自动调整并重测（一般 2-3 轮即可）
5. **工程化评估**（新增）：自动生成触发评估用例 + 批量运行 + 输出综合报告

### 8.3 工程化评估 3 阶段

| Phase | 名称 | 内容 |
|-------|------|------|
| 1 | **触发评估**（Trigger Evaluation） | 自动生成正例/反例/边界用例 → 计算 Precision/Recall → 标注漏触发和误触发 |
| 2 | **效果评估**（Quality Evaluation） | 预定义测试用例 + "有 Skill vs 无 Skill"对比 + 按评分标准（格式/准确性/完整性）打分 |
| 3 | **综合报告与优化建议** | 汇总两阶段数据 → 自动标注薄弱环节 → 给出针对性建议 → 可选自动应用并重评 |

## 九、Skill 验证与评估

### 9.1 5 大评估指标

| 指标 | 说明 | 参考目标 |
|------|------|----------|
| **触发准确率** | 该触发时正确触发的比率 | **90%** |
| **触发误报率** | 不该触发时误触发的比率 | **5%** |
| **输出一致性** | 同一输入多次执行的相似度 | **85%** |
| **Token 效率** | 完成相同任务所消耗的 Token 量 | **比无 Skill 减少 30%+** |
| **完成准确率** | 输出结果符合预期的比率 | **80%** |

> "不需要每个指标都精确测量。重点关注**触发准确率**和**完成准确率**，这两个直接决定 Skill 是否可用。"

### 9.2 评估循环

```
编写/修改 Skill → 运行测试用例 → 评估结果 → 优化 Skill → 重复
                                          ↓
                                满意 → 扩大测试规模 → 正式发布
```

## 十、调试与排错

### 10.1 AI 该触发却没触发

**排查链**：
```
Skill 没触发
  ↓
1. Skill 加载了吗？ — 没有 → 检查文件路径
  ↓ 加载了
2. Description 匹配吗？ — 不匹配 → 调整 description 措辞
  ↓ 匹配
3. 是否被其他 Skill 抢了？ — 是 → 检查 description 冲突
  ↓ 否
4. 用户提问措辞太模糊？ — 是 → 在 description 中补充关键词
```

**高频原因**：
- 路径放错（应放 `~/.codebuddy/skills/` 或项目的 `.codebuddy/skills/`）
- YAML 格式错误（开头 `---` 缺失或缩进不对）
- Description 太笼统 / 太窄

### 10.2 多个 Skill 冲突

**解决策略**：
- **差异化 description**（让每个 Skill 有明确区分关键词）
- **合并为一个**（如果两个 Skill 经常一起被触发）
- **添加排斥说明**（"本 Skill 不处理 XXX 场景"）
- **手动指定**（对话中明确指定使用哪个）

## 十一、团队管理与协作

- **Skill 是团队的"知识资产"**：可以分发给所有成员
- **版本管理**：跟代码一起进版本控制
- **评审流程**：Skill 也要 code review
- **共享市场**：公司内部 Skill 市场

## 十二、反模式（常见错误）

**反模式 = "写了但不好使"的模式**。典型：
- Description 太宽泛（什么场景都触发）
- 指令模糊（"尽量做好一点"）
- 没有 Few-Shot 示例
- Token 成本过高（Level 2 写到 5000 行）
- 没有错误处理

## 十三、检查清单

### 13.1 安全检查清单
- [ ] 文件中没有硬编码密钥/Token
- [ ] 危险操作（删除/覆盖/DDL）有确认或备份
- [ ] 脚本中用户输入做了校验
- [ ] 路径操作没使用未经验证的变量拼接
- [ ] 网络请求用 HTTPS + 合理超时

### 13.2 质量检查清单
- [ ] 触发准确率 ≥ 90%
- [ ] 完成准确率 ≥ 80%
- [ ] Token 效率比无 Skill 减少 30%+
- [ ] Few-Shot 示例 ≥ 3 个
- [ ] 验证命令可直接复制粘贴

## 十四、附录

### 14.1 核心术语速查

| 术语 | 含义 |
|------|------|
| **Level 1/2/3** | Skill 三层渐进式加载 |
| **Few-Shot** | 多个输入/输出示例让 AI 模仿 |
| **Before/After** | 改动前后代码对比 |
| **Checkpoint** | 关键步骤间插入的验证命令 |
| **Description** | YAML 头信息描述字段（决定触发时机） |
| **MCP** | Model Context Protocol，AI 工具协议 |
| **主 Skill / 子 Skill** | 模块化拆分后的编排层和执行层 |

### 14.2 参考资源

- **Anthropic 官方 Skills 仓库**：github.com/anthropics/skills
- **Skill Creator 元技能**：skill-creator/SKILL.md
- **OpenSkills 生态**：github.com/openskills
- **MCP Server 列表**：github.com/modelcontextprotocol/servers
- **OpenAI Tokenizer**：platform.openai.com/tokenizer

## 核心金句

> "**写 Skill 这件事，说到底就是把你脑子里'知道怎么做'的经验，变成 AI 也能'照着做'的格式**。"

> "**第一版肯定不完美，但没关系，用着用着就知道哪里需要改了。好的 Skill 都是在实际使用中一点点打磨出来的**。"

---

**作者**：jackjchou（腾讯）