如何写好 Skill：一份来自腾讯团队的终极实战经验手册

前言

大家在用 Claude Code、CodeBuddy 这类 AI 编程工具时，是不是总遇到这些痛点：AI 不懂团队内部规范、代码输出风格飘忽、重复机械工作每次都要重新说明、核心业务经验随着老员工离职直接流失？

腾讯技术工程团队在长期落地 AI 编程助手的过程中，沉淀了大量 Skill 踩坑、优化、工程化落地经验，同时结合 Anthropic 官方设计规范与官方原生工具 Skill Creator，整理出这份完整实战手册。不管你是零基础新手、写过 Skill 但效果拉胯的开发者，还是负责团队 Skill 标准化的负责人，都能直接复用这套方法论，把团队沉淀的领域知识标准化 “喂” 给 AI，大幅提升编码、迁移、审查等工作效率。

本文适配 Go/Python/Java 全主流编程语言，覆盖从 5 分钟快速上手、高阶优化、外部服务集成、安全规范、排错调试、Anthropic 官方 Skill Creator 完整实操到工程化评估全流程。

一、先搞懂：Skill 到底是什么，为什么必须写

1.1 Skill 核心定义

Skill 是给 AI 编程助手加装的结构化能力包，本质是标准化提示工程载体，由三层核心内容构成：指令集、业务上下文、可执行工具脚本。 从物理形态看，它就是一套标准化文件夹，核心文件为 SKILL.md，配套脚本、参考文档作为补充资源。

打个通俗比方：裸 AI 等于刚入职啥都不懂的实习生；加载 Skill 后，等于直接给到一套完整老员工操作手册，无需反复讲解就能独立完成标准化任务。

1.2 团队落地五大核心痛点 & Skill 解决方案

1.3 Skill 三层渐进加载机制（关键 Token 成本逻辑）

Anthropic 原生设计三层加载模型，也是所有 Skill 优化的底层基础，绝大多数效果差、上下文过载问题都源于对三层机制不了解：

核心优化原则：Level1 精准精简、Level2 去冗余、Level3 大胆存放参考资料。

1.4 Skill 三大触发模式

1.5 适用全场景清单

代码框架迁移、自动化代码审查、API 文档生成、项目模板初始化、自动生成测试用例、日志 / 数据库批量处理等标准化重复任务，全部适合用 Skill 落地。

二、5 分钟快速上手：从零搭建第一个可用 Skill

2.1 Skill 标准目录结构

最简结构（新手推荐）

go-test-gen/
└── SKILL.md # 唯一必需核心文件

复杂工程化完整结构

http-client-migrate/
├── SKILL.md # YAML头+主体指令
├── scripts/ # 检查、转换脚本
│ └── pre-check.sh
├── references/ # 业务规范、API对照表
│ └── api-mapping.md
└── assets/ # 模板配置
└── template.json

2.2 SKILL.md 标准格式拆解

文件分为顶部 YAML 元数据 + Markdown 执行正文，缺一不可。

YAML 头（决定触发逻辑，重中之重）

—
name: go-test-gen
description: >
为Go函数生成表驱动风格单元测试，用户要求编写单测、补充测试用例时自动触发，覆盖正常、边界、异常三类场景。
metadata:
version: "1.0"
author: 后端工程组
license: MIT
—

Markdown 正文通用模板

# Go单元测试生成Skill
## 目标
清晰一句话说明核心功能
## 前置判断条件
给出可执行校验命令，无需执行直接跳过的场景
## 分步执行流程
分Step拆解，关键步骤增加校验检查点
## 输入输出示例（Few-Shot）
Before/After代码对比
## 完成验证清单
可一键执行校验脚本
## 常见问题FAQ
覆盖高频边界场景

2.3 实战演示：Go 单测最小可用 Skill

完整可直接复制的 SKILL.md 示例：

—
name: go-test-gen
description: >
为Go函数自动生成表驱动单元测试，用户提出编写单测、补充测试、完善用例时触发，仅适配标准testing库。
metadata:
version: "1.0"
—
# Go单元测试自动生成
## 目标
基于目标函数生成规范table-driven单测，使用t.Run子测试，覆盖正常值、边界值、错误入参。
## 执行规则
1. 不引入第三方测试框架
2. 测试函数命名统一为Test+函数名
3. 全部用例放入结构体切片循环执行
## 示例
### 输入原函数
```go
func Add(a,b int)int{
return a+b
}
```
### 生成结果
```go
func TestAdd(t *testing.T){
tests:=[]struct{
name string
a,b int
want int
}{
{"正数相加",1,2,3},
{"零值",0,0,0},
{"负数",-1,-2,-3},
}
for _,tt := range tests {
t.Run(tt.name,func(t *testing.T){
if got:=Add(tt.a,tt.b);got!=tt.want{
t.Errorf("Add(%d,%d) 结果=%d,预期=%d",tt.a,tt.b,got,tt.want)
}
})
}
}
```
## 验证命令
```bash
go test ./… -v
```

2.4 Skill vs Rule 分清，别写混

很多新手混淆两者，一张表区分边界：

选择判断口诀：全流程通用约束写 Rule，单次专项任务写 Skill。

三、写出高质量 Skill 七大核心实战技巧

3.1 Description 是成败关键，精准才能不误触发

❌ 反面模糊写法：description:处理代码迁移 ✅ 标准优质写法：

description: >
将Go项目中旧版old-http-client全局替换为统一请求库unified-httpclient，包含import替换、结构体参数适配、错误处理改造，仅识别使用旧依赖的仓库。

优化小技巧：自行构造 20 条提问（10 条应触发、10 条不相关）自测命中率，误触发 / 漏触发持续迭代描述文案。

3.2 指令用祈使句，讲清底层原理，拒绝生硬 MUST

3.3 必加 Before/After 代码对比，直观降低 AI 理解成本

三种对比格式按需选用：注释片段、完整文件、标准 Diff 格式，复杂代码迁移优先 Diff。

— a/client.go
+++ b/client.go
-import oldhttp "old-http-client"
+import uhttp "unified-httpclient"
-return oldhttp.Do(req)
+return uhttp.Do(req)

3.4 3-5 组 Few-Shot 示例，解决 AI 自由发挥乱输出问题

每组示例严格包含：输入代码 + 标准输出结果，覆盖正常、边界、异常三类场景，最典型案例放在最前面。 以代码审查 Skill 为例，分别提供安全漏洞、空指针、命名规范三类完整输出样例，AI 输出一致性直接提升 80%。

3.5 复杂流程用表格 / ASCII 流程图替代大段文字

AI 解析结构化表格、流程图远优于长文本，分支逻辑一目了然。

示例：Import 替换分支决策图

读取import语句
↓ 是否直接导入？→ 自动替换路径
↓ 是否别名导入？→ 替换路径保留别名
↓ 是否点导入？→ 替换并校验符号冲突
↓ 其他 → 标记人工处理

3.6 复杂校验逻辑抽离 scripts，SKILL.md 只调用不堆砌

环境检查、批量检索、数据转换等长逻辑全部放入独立 shell/python 脚本，SKILL.md 仅保留调用命令，精简正文 Token 占用，同时脚本可单独复用。

3.7 高危操作增加备份 & 确认机制，筑牢安全底线

删除文件、数据库 DDL、批量覆盖代码等操作，强制前置备份、交互式确认，禁止无防护直接执行。

四、大型项目必备：Skill 模块化拆分方案

4.1 什么时候必须拆分

4.2 拆分架构：主 Skill 编排 + 独立子 Skill

project-migrate/ # 主Skill，流程总调度
├── SKILL.md
└── steps/
├── env-check.md
├── api-transform.md
# 独立可单独使用子Skill
migrate-env-check/
└── SKILL.md
migrate-api-transform/
└── SKILL.md

4.3 主 Skill 编排规范

按顺序执行，每一步执行完成必须运行检查点，校验失败直接终止流程，禁止跳过错误执行后续步骤。

五、外部服务集成：MCP 与 HTTP 脚本怎么选

Skill 经常需要调用数据库、第三方 API，两种方案取舍逻辑清晰：

核心对比表

选择决策流程

需要调用外部服务 → 是否存在成熟 MCP 服务？是→优先 MCP → 需多 Skill / 多平台复用？是→封装 MCP → 仅单次简单调用→直接 HTTP 脚本

混合落地最佳实践

数据查询用 MCP，复杂批量写入用 HTTP 脚本，Skill 统一串联整体流程。

六、安全红线：Skill 开发必须遵守的规范

Skill 配套脚本可真实执行操作，一旦疏漏极易造成密钥泄露、数据丢失，六条强制安全规则：

八、懒人福音：用 Skill Creator 帮你写 Skill（Anthropic 官方原生工具，含完整工程化评估）

自己手写 SKILL.md 当然没问题，但如果你觉得上手繁琐、不清楚规范、产出效果不稳定，可以直接使用 Skill Creator—— 这是 Anthropic 官方原生提供、专门用来生成、测试、优化 Skill 的元技能，业内俗称 “写 Skill 的 Skill”。 它通过对话引导补齐所有细节，自动生成标准目录与指令，内置一整套标准化工程化评估体系，彻底告别 “写完全靠主观感觉判断好坏”，所有 Skill 质量均可量化。

8.1 三种安装方式，任选其一

安装校验：执行 /skills 命令，或提问 What Skills are available?，列表出现 skill-creator 即代表加载成功。

8.2 Skill Creator 标准核心工作流

整体逻辑：需求生成草稿 → 多组用例对比测试 → 反馈迭代优化 → 工程化评估兜底验收

┌──────────────────────────────────────────────────────────┐
│ Skill Creator 完整工作流程 │
├──────────────────────────────────────────────────────────┤
│ Step 1: 定义意图 │
│ ├── 大白话描述Skill核心能力 │
│ ├── Creator自动追问技术栈、输出规范、边界场景、约束规则 │
│ └── 确认最终预期输出格式 │
│ ↓ │
│ Step 2: 自动生成标准化草稿 │
│ ├── 输出完整SKILL.md（规范YAML元数据+分层Markdown指令） │
│ ├── 按需生成 scripts/、references/ 配套文件夹与模板 │
│ ↓ │
│ Step 3: 对照测试验证 │
│ ├── 自动产出2-3组完整测试用例 │
│ ├── 并行执行「加载Skill」「无Skill」两组对比实验 │
│ └── 自动输出通过率、Token消耗对比报告 │
│ ↓ │
│ Step 4: 反馈迭代调优 │
│ ├── 直接反馈缺陷：漏场景、格式错误、触发不准等 │
│ ├── Creator自动修正并重跑测试 │
│ └── 常规2-3轮迭代即可达到可用标准 │
│ ↓ │
│ Step 5: 工程化标准化评估（官方新增核心能力） │
│ ├── 批量生成触发用例：正例+反例+模糊边界用例 │
│ ├── 批量执行测算触发准确率、召回率 │
│ ├── 基于功能用例做输出质量打分评估 │
│ └── 输出综合评估报告，标注短板与定向优化方案 │
└──────────────────────────────────────────────────────────┘

8.3 定向调优：一键优化 description 提升触发精度

Skill 基础功能跑通后，最常见痛点是误触发、漏触发，无需手动改写描述文案，直接交给 Creator 自动化调优：

示例指令：帮我优化 java-code-review 的 description，提高它的触发准确率

执行逻辑：自动生成 20 条混合测试问句（一半应触发、一半无关场景），反复迭代改写 description 关键词，直至触发指标达到最优区间。

8.4 核心：官方工程化评估体系（数据量化 Skill 质量）

传统开发方式仅手动试几条提问，好坏全凭主观；Skill Creator 的工程化评估将测试流程标准化、自动化，把 Skill 质量转化为可量化指标，也是腾讯团队 Skill 合并 PR 的强制准入门槛。

8.4.1 评估完整双阶段流程

┌──────────────────────────────────────────────────────────┐
│ Skill Creator 工程化评估分层流程 │
├──────────────────────────────────────────────────────────┤
│ Phase 1：触发评估 Trigger Evaluation │
│ ├── 自动批量生成10-20条正例、10-20条反例、边界模糊问句 │
│ ├── 批量模拟用户提问，统计Skill触发状态 │
│ ├── 计算核心指标：触发准确率Precision、召回率Recall │
│ └── 生成报告，逐条标注漏触发、误触发的问题用例 │
│ ↓ │
│ Phase 2：效果质量评估 Quality Evaluation │
│ ├── 读取预定义带评分标准的功能测试用例 │
│ ├── 分别执行有无Skill两套输出结果对比 │
│ ├── 按格式、准确性、完整性多维度自动打分 │
│ └── 输出通过率、Token开销、逐条得分明细 │
│ ↓ │
│ Phase 3：综合报告输出与自动优化建议 │
│ ├── 汇总触发、质量两大维度全部指标数据 │
│ ├── 自动识别短板：边界场景缺失、描述关键词缺失等 │
│ ├── 给出可直接落地的修改方案 │
│ └── 可选：一键自动修改并重跑全量评估 │
└──────────────────────────────────────────────────────────┘

8.4.2 第一阶段：触发评估 —— 校验 description 是否合格

解决核心问题：该触发的时候能不能精准触发、无关场景会不会乱触发。 以 go-test-gen 单测生成 Skill 为例，三类测试用例划分：

调用指令示例

帮我对 go-test-gen Skill 执行一次完整触发评估

标准输出报告样例

=== 触发评估报告 ===
Skill: go-test-gen
总测试用例数: 30 （正例15，反例12，边界3）
📊 触发准确率(Precision): 93.3% ✅
正确触发14/15，误触发1/12
📊 触发召回率(Recall): 93.3% ✅
正确触发14/15，漏触发1/15

❌ 漏触发用例：
– "帮我补充math.go的test coverage"
优化建议：在description补充coverage、补充测试相关关键词

⚠️ 误触发用例：
– "帮我测试部署脚本能否运行"
优化建议：description明确排除集成测试、部署脚本测试场景

🟡 边界用例分析：
– "检查这个函数逻辑" → 未触发（符合预期）
– "这个函数需要补充测试吗" → 正常触发（符合预期）

拿到报告后针对性修改 description，重新跑评估，直到指标达标。

8.4.3 第二阶段：效果评估 —— 校验触发后输出质量

触发准确只是基础，输出代码是否规范、完整、符合团队标准，由效果评估量化打分。 每条测试用例固定三要素：用户输入代码上下文、预期输出标准、量化评分勾选标准。

示例测试用例 1：普通数值函数

输入：为以下函数生成标准单元测试

func Max(a, b int) int {
if a > b {
return a
}
return b
}

评分标准

• 使用表驱动结构体切片 + t.Run 子测试
• 覆盖 a>b、a<b、a==b 三类分支
• 不引入第三方测试库
• 测试函数命名规范 TestMax
• 代码可直接编译执行无报错

示例测试用例 2：带错误返回函数

输入：为 Divide 除法函数生成单元测试

func Divide(a, b float64) (float64, error) {
if b == 0 {
return 0, fmt.Errorf("division by zero")
}
return a / b, nil
}

评分标准

• 覆盖正常计算、除零异常两大场景
• 异常场景校验 error 非空
• 正常场景校验 error 为空、数值匹配
• 浮点数值比较设置精度误差容差

调用指令示例

使用下方提供的两组测试用例，对go-test-gen执行效果评估

标准效果评估报告样例

=== 效果评估报告 ===
Skill: go-test-gen
测试用例总数:5
📊 整体通过率：88.0%（加载Skill） VS 52.0%（无Skill）
📊 Token开销均值：1200 Token/用例 VS 2100 Token/用例

逐用例得分对比：
┌──────────────┬──────────────┬──────────────┬───────────┐
│ 用例 │ 有Skill得分 │ 无Skill得分 │ 提升幅度 │
├──────────────┼──────────────┼──────────────┼───────────┤
│ 简单数值函数 │ 5/5 ✅ │ 3/5 │ +40% │
│ 带错误返回 │ 4/5 ✅ │ 2/5 │ +40% │
│ 多返回值函数 │ 5/5 ✅ │ 3/5 │ +40% │
│ 接口方法 │ 4/5 ✅ │ 2/5 │ +40% │
│ 并发场景函数 │ 4/5 ⚠️ │ 3/5 │ +20% │
└──────────────┴──────────────┴──────────────┴───────────┘

⚠️ 薄弱点优化提示：
1. 除法用例浮点对比未设置精度容差 → 在Skill示例补充浮点校验代码
2. 并发场景缺少竞态检测逻辑 → 增加`go test -race`校验步骤

8.4.4 评估用例持久化：纳入 Skill 工程目录长期维护

将评估用例作为 Skill 固定资产，和业务代码一同迭代，目录规范：

my-skill/
├── SKILL.md # 技能主体指令
├── scripts/ # 辅助执行脚本
├── references/ # 规范参考文档
└── evaluation/ # 官方评估配套目录
├── trigger-cases.md # 触发评估：正例、反例、边界问句
└── quality-cases.md # 效果评估：输入代码+评分标准

变更后评估执行规则

官方 & 腾讯团队统一达标指标

团队落地规范：所有 Skill 代码提交 PR，必须附带 Skill Creator 产出的完整评估报告，类似单元测试报告，无报告不予合并。

8.5 Skill Creator 从零落地耗时小结

从零产出一套规范、可上线、有数据佐证的标准化 Skill：总耗时 30~50 分钟。

适配人群

重要局限性提醒（官方说明）

Skill Creator 输出仅为标准化草稿，并非开箱即用成品：

九、Skill 完成后全维度验证流程

9.1 标准化自检清单（以 http 客户端迁移 Skill 举例）

功能校验

• 项目内所有旧版 import 全部替换完成
• 新客户端依赖已写入 go.mod
• 旧依赖已从 go.mod 移除
• go vet ./… 无静态告警

编译构建校验

• 本地开发环境 go build ./… 编译无报错
• 全量单元测试 go test ./… 全部通过
• 编译产物不存在旧包残留引用

运行时校验

• 业务核心接口请求正常收发
• 异常、超时、重试逻辑完整可用

9.2 可直接复制的批量校验脚本

# 1. 全局检索旧依赖残留
echo "===== 校验旧版依赖残留 ====="
grep -rn "old-http-client" . –include="*.go" \\
&& echo "❌ 存在未清理的旧引用" || echo "✅ 旧依赖清理完毕"

# 2. Go静态语法检查
echo -e "\\n===== 静态代码校验 ====="
go vet ./… && echo "✅ 静态检查通过" || echo "❌ 静态检查存在问题"

# 3. 单元测试全量执行
echo -e "\\n===== 单元测试校验 ====="
go test ./… && echo "✅ 全部测试通过" || echo "❌ 单元测试失败"

# 4. 项目整体编译校验
echo -e "\\n===== 编译完整性校验 ====="
go build ./… && echo "✅ 项目编译正常" || echo "❌ 编译失败"

9.3 Skill 通用质量评估闭环（官方标准循环）

完整迭代闭环： 编写/修改Skill → 执行Creator评估用例 → 解读量化报告 → 定向优化Skill → 重复评估 循环终止条件：指标全部达标 → 扩充测试用例覆盖更多场景 → 正式纳入团队技能库

核心观测指标（优先关注 2 项核心）

十、避坑：六大高频反模式（团队审查必查）

十一、Skill 全生命周期标准化管理

11.1 版本规范（SemVer）

• 小版本（1.0→1.1）：修复边界问题、补充说明；
• 中版本（1.1→1.2）：新增场景、补充步骤；
• 大版本（1.x→2.0）：整体架构重构、流程重写； 所有变更维护 CHANGELOG 文件，团队变更走 PR Review，PR 必须附带 Skill Creator 评估报告。

11.2 复用与维护

• 通用 Skill 同步至用户全局目录，全项目共享；
• 定期清理废弃 Skill，减少常驻 Level1 Token 占用；
• 每次线上使用后记录 AI 执行错误，迭代补充边界规则；
• 季度统一使用 Skill Creator 批量优化存量 Skill，降低整体上下文开销。

十二、落地验收：完整自查清单

内容规范

• 目标、触发场景清晰无歧义；
• Description 经过 Creator 批量用例测试，触发指标达标；
• 分步指令简洁，附带风险原理说明；
• 包含正常 / 边界 / 异常多组 Few-Shot 代码对比；
• 复杂流程使用表格 / 流程图梳理；
• 高危操作标注风险与强制备份方案；
• 配套完整一键验证命令与检查清单。

工程结构

• 文件目录分层清晰，参考资料、脚本、评估用例分离；
• 超长 Skill 完成模块化拆分，子 Skill 可独立运行；
• YAML 元数据版本、归属团队信息完整；
• evaluation 目录配套触发、效果两套测试用例（Skill Creator 生成）。

安全校验

• 无明文密钥、账号 Token 硬编码；
• 文件 / 数据库高危操作存在备份与交互式确认；
• 外部输入、文件路径做白名单过滤，防注入、路径穿越；
• 配套脚本前置依赖校验、异常捕获逻辑。

结语

Skill 本质是团队工程经验的数字化载体，不是一次性工具，而是长期迭代沉淀的知识资产。 初期不需要追求完美，先用 Skill Creator 快速搭建最小可用版本落地，再结合日常开发反馈持续迭代优化。遵循本文腾讯团队落地的分层加载、模块化拆分、Anthropic 官方 Skill Creator 自动化生成、标准化工程评估、安全规范整套体系，既能大幅降低 AI 上下文 Token 损耗，又能让标准化代码工作输出稳定可控，真正把 AI 编程助手转化为团队真实提效生产力。

互动话题：你们团队现在有一套 Skill 评审规范吗？会不会把 Skill Creator 的评估报告纳入 PR 准入门槛？大家觉得 Skill 工程化评估，最该盯紧哪一项核心指标？我是阿宇，欢迎大家评论互动！

内容参考：Anthropic 官方 Skills 仓库 anthropics/skills: Public repository for Agent Skills、Anthropic 官方"创建 Skill 的 Skill" skills/skills/skill-creator/SKILL.md at main · anthropics/skills、腾讯技术工程公众号 如何写好 Skill：一份终极实战经验手册