Agent Skills 系列（4）：少打三轮字，把「你每次都要纠正 AI 的话」固化成 Skill

📌 系列说明

如果你已经认同「规范不该靠每轮对话重讲一遍」（见第 1 篇），也清楚 SKILL.md 怎么写、怎么装（见第 2、3 篇），接下来要分享的是：哪些内容值得写成一个 Skill。

---

💸 为什么这件事和「省 token」直接相关

和模型协作时，隐性成本往往不在单次回答长度，而在轮次：你纠正一次、它改一半、你再补约束、它又偏了——每一轮都在重复加载同一套偏好、同一套团队规矩，token也像滚雪球一样浪费掉。

Skill 的作用是把稳定、可复用、且最好在第一轮就生效的信息，提前放进 Agent 的「已知条件」里。好的 Skill 目标很明确：让用户少说一句「不对，我们项目不是这样」。

例：没有 Skill 时，模型第一轮生成 npm install && axios.get(...)；有 Skill 时第一轮就是 pnpm install && import { request } from '@/api/client'——后面两三句纠正话整段省掉。

下面按「是否值得做成 Skill」给落地标准，尽量可对照执行。

---

✅ 先判一道：三条都满足，再写进 Skill

条件	含义	简例
重复	过去两周里，你对不同任务说过同样的话超过三次	例：每个新页面你都补一句「用 useRequest，别用 axios」。
稳定	半年内不太会变（会变的内容放版本号或 CHANGELOG，别靠聊天口述）	例：「JWT 放 httpOnly cookie」半年不会天天改；「本周 sprint 目标」天天变。
可执行	写成 checklist、禁止项、示例片段后，模型能直接照着做	例：「要有测试」太虚；「*.test.ts 与源文件同目录，用 vitest」可执行。

只满足一条的，更适合留在文档、Issue 模板或 CI；三条都满足的，才值得写成一个 Skill。

写 Skill 前，最好先列出 2～3 个具体场景，简单写明「用户怎么提需求」「做对的标准是什么」（一条一行）。正文内容别太啰嗦，大块实例或参考材料放进 references/，正文只需说明「什么情况下去读哪份」。多个 Skill 会共存，description 建议写得具体些，宁窄勿泛，避免不同 Skill 之间抢着被触发。

---

🎓 与 DeepLearning.AI《Agent Skills with Anthropic》的对照

DeepLearning.AI 上的短课（约一小时，偏入门）里，有不少和「什么值得做成 Skill」可直接对齐的说法。这里只收进和选题与落地强相关的几段。

📚 课程把 Skill「归位」的三类事

• 领域专业知识：品牌规范、法务流程、数据分析口径等——团队里「怎么做」的共识，过去多在文档和人脑里。
• 可重复的工作流：周复盘、客户准备、季回顾等有固定步骤的事，一次写清、多次复用。
• 新能力：靠 scripts/、模板、Office 类等资源，让模型稳定产出表格、文档、PDF、幻灯片等原本容易漂的交付物。

若某一包内容同时落进本文上表的「重复 · 稳定 · 可执行」，就尤其值得固化成 Skill。

---

🧩 「标准化领域认知」与渐进式加载

课程里一句总括很贴切：Skill 是标准化的领域认知，也可当作在团队与项目间复用的数字资产——经验不绑在某次对话，而绑在可版本、可引用的目录里；这和本文开篇「少纠正轮次」是同一主张。

机制上，渐进式加载（启动时只挂每个 Skill 的元数据，命中任务再读完整 SKILL.md，references/ 与脚本再按需取用）是 Skill 相对「把全部规范塞进 system prompt 或每条消息重复贴」的优势：少占上下文、也少混乱，规范越多差别越明显。

---

🎨 设计向常见的三个落点（可与下文「8. 设计规范与交付」叠用）

1. 设计自查 Skill：交付前「漏了什么」的检查表；把资深同事脑中的表写成条文，每条尽量带反例 / 正例。description 要写清能力、适用场景、容易触发的用户说法，否则模型不会在目录阶段选中它。YAML 与正文拆法见 概念实战篇。
2. 组件 / 体系 Skill：token、栅格、组件清单、页面骨架等大段材料放进 references/，正文只写选型边界与「何时读哪份」；多人维护时用 Git 与明确 owner，避免规则分叉。若前端通过 MCP 把组件库暴露为可查接口，可在 Skill 里写清如何连接，减少「猜 props / 猜变体」。
3. 业务上下文 Skill：用户画像、主流程、术语、业务线差异等——不必第一版就求全，先把最高频被问、最容易让产出脱离现实的那几段写进去。

---

🚀 如何起步：先装官方、再写自己的

Anthropic 官方仓库已经有不少现成的 Skill 可直接安装，办公文档相关如 xlsx / docx / pdf / pptx 等类型，装好后模型对这些格式的处理效果会明显提升。要自定义 Skill，可以使用 Anthropic 提供的 Skill Creator 本地快速创建和调试。建议先写一个简洁版（50~100 行即可），上线后观察几天实际表现，逐步找出执行不到位的点，持续迭代三到五轮。起草 Skill 时，也可以让 AI 先按你的要求提供初稿，然后你再聚焦在触发条件和禁止项的完善上。

---

🎯 特别适合做成 Skill 的东西（按场景）

1️⃣ 团队「默认值」：不讲就会错的那种

偏通用、跨仓库的规范（新建项目和老项目都同一套）很适合放 Skill：改一处 Skill 全局生效；若写进每个仓库的 README，容易漏改、版本对不齐。

典型内容与简例：

• 包管理器、Node 版本、脚本命令。例：Skill 写死「只认 pnpm；安装依赖用 pnpm install，禁止 npm install」，避免模型生成 npm i lodash 这样的安装命令。
• 目录约定。例：「页面只在 src/views/；请求封装只从 @/api/client import」，避免模型把新页面建在 pages/ 或随手 fetch。
• 错误处理。例：「业务错误抛 AppError，由全局过滤器转 JSON；禁止在 controller 里 console.log 吞掉异常」。
• 测试。例：「单测与源文件同目录：foo.ts ↔ foo.test.ts；用 vitest；mock 放 __mocks__/」。

经常错的地方：AI 默认用通用栈（axios、常见目录结构），和你们封装层不一致——这类错每一轮都在付学费，最适合 Skill 一次性钉死。

---

2️⃣ 高频脚手架：口头描述最费 token 的那种

典型内容与简例：

• 新接口骨架。例：Skill 规定「列表接口统一 GET /resources?cursor=&limit=，响应包一层 { data, next_cursor }，header 带 X-Request-Id」，用户只说「加个订单列表 API」即可对齐。
• 新页面骨架。例：「列表页默认 <PageLayout> + <ProTable> + useListQuery；空态用 <EmptyState type="list" />」，避免模型从裸 <table> 写起。
• PR / Migration 检查项。例：「PR 描述必须含：是否改 schema、是否需跑 pnpm migrate、是否影响移动端」——模型改完代码顺手按模板填，少一轮「补一下 PR 说明」。

价值：用户只说「加一个用户列表页」，Skill 把「列表页在你们项目里长什么样」补全，避免从空白组件开始拉扯。

---

3️⃣ 后端与微服务：用 Skill 补「架构地图」和挡板

Vibe Coding 工具写前端往往更顺眼，常见原因有两条：一是公开训练里单仓 SPA、组件库样例极多；二是前端代码相对集中在一个仓库、一层 UI，上下文容易「一眼看完」。后端则经常是多服务、多仓库、多套配置、多种中间件：网关后面是谁、同步调谁、异步 topic 叫什么、哪张表归哪个团队、staging 与 prod 差在哪——这些不在模型默认假设里，它就按「典型三层 CRUD」瞎补，看起来对、一跑就错。

值得单独做（或拆成两三个窄 Skill）的后端向内容：

• 服务清单与职责边界。例：表格列出 order-service / payment-service / inventory-service：各自仓库路径、对外暴露的 path 前缀、禁止在订单服务里直接写支付库表。
• 调用关系与「挡板」。例：开发环境调支付用 https://pay-stub.corp.internal（Wiremock / 自建挡板），禁止在本地直连真实收单网关；联调失败时先对照「是否误连 prod」。
• 数据库与 schema 归属。例：订单只读写 orders schema；金额冻结状态以 payment 服务为准，订单服务禁止 JOIN payment.transactions 跨库拼查询。
• 消息与异步。例：OrderPaid 事件从 payment 发出、order 消费；topic 名、重试与幂等 id 字段名写死，避免模型发明 topic。
• 配置分层。例：业务开关在 ConfigMap feature-xxx；密钥只在 Vault / 环境注入，不进仓库；各服务 application.yml 里不允许出现明文密码占位。

写法提示：这类 Skill 宁可像简版 C4 / 依赖表 + 禁止项，也不要贴整墙架构图 PNG（模型读不好、触发也难控）。改架构时记得改 Skill 版本或 CHANGELOG，「地图过期」比没有地图更坑。

---

4️⃣ 易踩坑清单：人类同事也要 onboarding 的那种

适合写成「遇到 X 先查 Y」的短表，每条都可带一句反例：

• 异步与竞态。例：禁止「在 watch 里直接 await 调接口不重入」；推荐「watch + 递增 requestId，过期响应直接丢弃」。
• 国际化。例：「用户可见文案只进 locales/zh-CN.json，key 用 module.feature.label；禁止在 <template> 里写死中文」。
• 安全。例：「禁止把 ${userInput} 拼进 SQL；.env 不进 git；内网地址只允许 *.corp.internal」。
• 性能。例：「列表 length > 200 必须上虚拟滚动；禁止在 computed 里 JSON.parse 大字符串」。

经常错的地方：模型会给出「技术上能跑」但和你们红线冲突的写法——Skill 用否定句 + 反例往往比长篇架构文管用。

---

5️⃣ Code review 口径：把「挑刺」变成「可引用条款」

把你们最常回的 review 意见收成条目，每条一句就够模型对齐：

• 命名与可读性。例：「函数动词开头、布尔用 is/has；超过三层嵌套必须抽函数」。
• 测试边界。例：「改 src/pure/** 纯函数可不加测；动 payment/ 或 auth/ 必须带单测」。
• 日志与可观测性。例：「对外接口入口打 request_id；禁止 logger.info 打整段 PII」。

价值：让 AI 在第一版就贴近「能过你们 PR」的样子，减少「改完再被说一遍」的往返。

---

6️⃣ 外部系统「对接咒语」：文档分散、每次都要搜的那种

每条写「稳定不变」的那一半，并给模型可直接套用的句式：

• 网关与错误码。例：「对外统一前缀 /gw/v1；40102 = token 过期，客户端应静默刷新一次」。
• 发布与回滚。例：「生产发布走 deploy-prod job；红则先 kubectl rollout undo deployment/api -n prod，再拉 release owner」。

注意：Skill 只写稳定子集，若信息强依赖实时状态（今天谁 oncall、当前限流阈值），这类动态信息用链接或 MCP，不要把 Skill 当成实时数据库。例：Skill 里写「oncall 排班见 wiki 固定页」，不要写「今晚是小王值班」。

---

7️⃣ 脱敏规则、安全边界、数据埋点（增长 / 数据同学也常问）

这三类都是高频、易写错、一错就合规或舆情风险的内容，特别适合固化成独立 Skill（可与研发 Skill 分开，避免 description 互相抢触发）。

• 脱敏（日志、截图、给模型的上下文、客服话术）。例：手机号展示为 138****8000；身份证只保留末6位；日志里禁止出现完整 token / Cookie / 银行卡号；把「哪些字段算 PII」列成表，模型生成示例数据时一律用假名假号。
• 安全边界。例：生产库连接串、签名私钥、KMS 口令永不粘贴进对话或 Skill 正文（Skill 只写「从哪类密钥管理取、变量名叫什么」）；内网管理后台 URL 禁止写进对外可见的文案；生成代码时禁止 eval / 动态 Function 解析用户输入。
• 数据埋点 / 分析。例：事件名命名 模块_页面_动作（如 order_list_expose）；公共属性固定 app_version、channel，禁止把手机号、openid 打进事件属性；首屏关键漏斗事件列表与可选参数表；与实验平台 AB 分流字段的拼法（若有）。

经常错的地方：模型随手造事件名、在 properties 里塞用户明文、或把脱敏规则当成「大概打码」——写成可对照的表 + 反例最有效。

---

8️⃣ 设计规范与交付：给设计师，也给「用 AI 画界面 / 写文案」的人

设计体系 Skill 的本质，就是让 AI 生成的稿件和你们平时在 Figma 画、用组件库做的一致，别画得很好看但风格完全不对。通常会拆成三部分一起用：交付前自查清单（提前查漏补缺）、组件和 token 体系小抄（直接和代码实现对得上）、业务背景和常用术语（不脱离实际流程）。

典型内容与简例：

• Token 与间距。例：「圆角只用 sm/md/lg 三档，对应设计 token；禁止在稿里手写 #1a1a1a 当主色，必须用 color.text.primary」。
• 组件与状态。例：「主按钮只有一种高度；空态、加载、错误必须各用指定组件，不要现场发明占位块」。
• 切图与标注。例：「导出 @2x PNG 或 SVG；图标统一 24px 网格；切图命名 ic_功能_状态」。
• 文案与语气。例：「错误提示用「请稍后重试」体，不用责备用户；标题不超过两行」。
• 无障碍底线。例：「正文与背景对比度不低于 WCAG AA；可点击区域不小于 44×44（或你们已定数值）」。

设计师可把 Skill 当作「给 Copilot / 对话模型的 briefing」：写需求、改稿、出多语言说明时，第一轮就带上栅格与 token 约束，少来回改像素和色值。

配套示例见下文表格中的 acme-privacy-redaction、acme-analytics-events、acme-design-system-handoff。

---

9️⃣ 要稳、要准：让 AI 做调度，计算和真相交给下一层

SKILL.md 很适合写流程、约束、入口命令；不适合把「必须算对、查对」的事交给模型在对话里现场完成。大数相加、复杂聚合、对账差额、正则边界、时区换算、权限判定结果等，模型会看起来合理却偶发错误，纠正又要多轮 token。

更稳的做法是：

• Skill 正文：写清「何时必须跑哪个脚本 / 调哪个 HTTP 或 MCP」「参数怎么传」「只如何解读返回的 JSON / 退出码」——AI 的角色是选路径、拼参数、总结输出，不是手算。
• scripts/（或仓库里已有 CLI）：把确定性逻辑放在 Node/Python/Shell 等可测试、可版本化的代码里；同一输入永远同一输出。
• 内部接口 / 只读查询服务：需要精确数字或实时数据时，让模型发起受控调用，用响应体当事实；不要让模型凭训练记忆「估一个数」。

例：用户问「这个 CSV 有多少行」——Skill 规定必须先执行 wc -l 或你们封装的 node scripts/count-lines.mjs，回答里引用的数字必须来自命令 stdout，禁止心算。例：对账——规定必须跑 scripts/reconcile.mjs --input ledger.json，模型只解释脚本打印的 diff_cents，不要自己在对话里重算一遍流水。

LLM 负责编排与说明，精确性由程序或数据库回答。 官方 Skills 形态里本来就支持在 Skill 目录挂 scripts/、references/ 等，正是为了把「会算错的部分」挪出去。

---

🚫 不太值得单独占一个 Skill 的（常见误判）

类型	为何	更好放哪	简例
一次性任务	用完即弃	当前对话里说清楚即可	例：「把这段 JSON 转成 CSV」只此一次，不必建 Skill。
整本架构白皮书	太长、触发难控	拆成多个窄 Skill，或放仓库 docs/	例：五十页的域模型说明 → 拆成 orders-api-conventions、billing-events 两个小 Skill。
每分钟变的排期	非稳定知识	日历 / 工单系统	例：「本周谁做需求 3721」问 Jira/日历，别写进 Skill。
纯数据查询	模型易幻觉	MCP、内部 API、只读查询工具	例：「上季度华东区 GMV」用 BI 或 MCP 查表，别让模型凭训练数据猜。（与下文 「要稳、要准：让 AI 做调度…」 一节同思路。）

---

📊 写好之后：怎么判断「真的省了轮次」

可以主观，也可以稍微量化，每条都举一个可观察的现象：

• Before。例：「加 CRUD 接口」平均要 4 轮：第 2 轮纠正分页，第 3 轮纠正错误体，第 4 轮补 request_id。
• After。例：同类任务第 1 轮输出里已经出现 cursor/limit 和统一错误体，纠正降到 0～1 轮。
• 触发抽查。各写几条用户原话：该加载的场景、易混淆不该加载的场景；换几种说法再测一轮（对齐官方「应触发 / 不应触发」思路）。
• 负面信号。例：design-tokens 在用户问「这段 SQL 怎么优化」时也被拉起来——说明 description 太宽或与别的 Skill 重叠，徒增 token。

省轮次 = 少重复加载同一段「纠正话术」= 少付无效上下文与重试成本。Skill 不是越长越好，能稳定减少纠正次数才是好 Skill。

---

📐 迷你结构模板

主文件必须名为 SKILL.md；技能目录名用 kebab-case；包内不要放 README.md（说明写进 SKILL.md 或 references/）。frontmatter 里 description 有长度上限；不要用尖括号包裹内容；技能名不要用 claude-、anthropic- 前缀（平台保留）。

写 Skill 时正文建议短而确定：触发条件在 frontmatter，正文放「必须 / 禁止 / 示例」。若有确定性步骤（统计、对账、格式化大文件），在正文写清要调用的 scripts/ 或 CLI 入口，不要让模型在对话里手算。

---
name: acme-api-new-endpoint
description: Acme 服务新增 HTTP 接口。当用户要加 REST 路由、controller、handler、或「暴露一个新 API」时使用。
---

# Acme 新接口 checklist

## 必须
- 路由前缀：`/api/v2`
- 分页：`limit` + `cursor`，禁止 `offset` 分页
- 错误体：`{ "code", "message", "request_id" }`

## 禁止
- 在 handler 里直接拼 SQL
- 未鉴权暴露内部 id

## 示例（片段）

```typescript
// POST /api/v2/orders — body 校验失败返回 422 + { code, message, request_id }
export async function createOrder(req: Request) {
  const requestId = req.headers.get("x-request-id") ?? randomUUID();
  // ...
}
```

description 尽量窄：宁可多几个小 Skill，也不要一个「全栈大全」和别的 Skill 抢触发。例：差写法——description 写「涉及后端、数据库、性能、安全时使用」；好写法——只写「新增或修改数据库 schema（如字段增删、表结构调整）时使用」。

---

📦 虚拟团队示例

下面虚构了一个 Acme 团队，列举了一下该团队可能涉及到的部分 Agent Skills，仅作为参考。

主题	常见文件名
团队默认值	acme-team-defaults
列表接口脚手架	acme-rest-list-endpoint
接口实现规范	acme-api-endpoint-guide
前端团队开发规范	acme-frontend-team-guide
Code review 口径	acme-pr-review-rubric
平台 / 发布稳定子集	acme-platform-runbook
定时任务与队列最佳实践	acme-scheduled-tasks-guide
脱敏与日志安全	acme-privacy-redaction
数据埋点命名与属性	acme-analytics-events
设计规范与交付（设计师）	acme-design-system-handoff
后端微服务地图与挡板	acme-backend-landscape

---

🧭 系列导航（姊妹篇）

篇	文章	在讲什么
1	痛点与动机	为什么需要 Skill
2	概念实战篇	SKILL.md 结构与渐进式披露
3	工具引入篇	skill-base / skb 分发安装
5	管理后台查询页案例	项目级 Skill 的落地改造样例
6	运维手册	触发、冲突与版本治理
延伸	碎片化困局	多工具并存下的触发与治理

---

📖 相关阅读

• DeepLearning.AI：Agent Skills with Anthropic：短课入口（与上文「对照」一节呼应）。
• Anthropic：Agent Skills 概览：官方对技能目录、description、测试与排错等要求的说明；若与其他渠道的写法不一致，以官方文档为准。
• 概念实战篇：SKILL.md 格式与渐进式披露；不知道正文怎么排时先看这篇。
• 碎片化困局：多 Skill 并存时的边界与触发；写得越多越要对齐这篇收紧 description。

---

✍️ 可以随手记一周「同一句纠正话对 AI 说了几次」：两周后回看，频率最高的几条往往就是下一个 Skill 的候选。例如连续几天都补「PR 没写迁移说明」，就可以考虑收编成 pr-checklist-db 一类窄 Skill。