Agent Skill 推出以来，各个 AI 编程工具都已增加对它的支持，Codex、Claude Code、Cursor 等均可使用。本文不绑定具体工具，介绍如何在这些 Agent 中使用已有的成熟 Skill，以及自己按实际需求创建 Skill。

什么是 Skill

https://agentskills.io/home

在 AI 编程工具中， Skill（技能） 是一种可复用、模块化的 AI 能力增强包，本质是一份给 Agent 读的文档。它的作用是从随机系统中拧出确定性：让 Agent 每次走同一套流程（可预测性），而不是碰运气。可以把 Skill 理解为 “为 AI 预先安装的一套专业能力插件” ，通过 Skill 可避免重复写复杂 Prompt，增加项目的一致性和专业性。

Skill 的构成

一份 Skill 由两部分组成：

• 元信息（frontmatter）：name、description、disable-model-invocation 等，决定它何时、能被谁调用
• 正文：两类内容自由混合——
  • 步骤（Steps）：Agent 按顺序执行的动作，每一步都应有可检查的完成标准
  • 参考（Reference）：按需查阅的规则、定义、事实

此外通常还包含领域规则（Best Practices）、结构化指令、示例与模板、设计 / 编码 / 业务知识库，有时还带有脚本或 CLI 工具。

Skill 的类型：用户调用与模型调用

按调用方式，Skill 分为两种，取舍本质上是两种成本的交换——常驻上下文的 context load，和需要人记住的 cognitive load：

• 用户调用（user-invoked）：frontmatter 中设置 disable-model-invocation: true。只有你手动输入它的名字才会触发，Agent 不会自动调用，其他 Skill 也调不到它；description 只是一行给你看的人类简介。优点是不占上下文，代价是你得自己记住它存在。
• 模型调用（model-invoked）：不设置 disable-model-invocation。description 常驻上下文，Agent 在任务匹配时能自动调用，其他 Skill 也可以引用它（手动输入同样可以）。优点是 Agent 可自主发现，代价是 description 每轮对话都占用 token。

当用户调用的 Skill 多到记不住时，用 router skill（路由技能） 解决：一个用户调用的“导航”Skill，列出其他 Skill 及各自适用场景，让你只需要记住它一个。

获取与管理：skills CLI 与 skills.sh

skills CLI：npx 一键安装

https://github.com/vercel-labs/skills

skills 是一个用于管理和安装 AI Agent Skill 的跨平台 CLI 工具，可跨 Agent 兼容，无论使用的是 Codex、Claude Code 还是 Cursor，它都可以实现 Skill 的全局或项目级挂载。

比如安装 langchain-skills，只需要输入命令：

npx skills@latest add langchain-ai/langchain-skills --skill '*' --yes

skills.sh 平台

https://skills.sh/

在 skills.sh 网站上，可以以各种维度查看、搜索 Skill，了解最新动态，发现新能力。

• 查看 Skill 的热门、趋势、总排行榜单
• 查看各种主题的 Skill
• 查看各个机构的官方 Skill
• 查看经过安全审查的 Skill

找到合适的 Skill，一键复制安装，即可在自己的 Agent 中使用。

Matt Skills：真实工程的 Skill 集合示例

以 Matt Skills（mattpocock/skills）为例——它是 Matt Pocock 开源的 AI 编码 Skill 集合，定位是“给真实工程师用，而不是 Vibe Coding”。它不是单个 Skill，而是一条可自由拼装的开发流水线。Matt Skills 的完整实操指南作为补充内容发布于 https://heibaimeng.com/post/315（晚于本文）。

接触 Matt Skills 之后，我们对 Skill 有了重新认识：它不是零散的提示词模板，而是一套围绕「可预测性」设计的工程方法——让 Agent 每次走同一套流程，而不是碰运气。本文的「什么是 Skill」与「创建自定义 Skill」两节，就是在这个认识下重新优化过的。

它把一次模糊需求走成五个环节：

• 追问对齐：/grill-with-docs（有代码库）、/wayfinder（大而雾的需求）
• 规格化：/to-spec
• 任务切片：/to-tickets
• 实现：/implement（TDD 红绿循环）
• 双轴审查：/code-review（平行子进程）

安装同样是一行命令：

npx skills@latest add mattpocock/skills

使用场景示例：

• 输入 “这个需求还说不清楚，先帮我把问题理清楚”，/grill-with-docs 会一边追问一边沉淀 context.md 与 ADR
• 需求大到单次会话装不下，用 /wayfinder 画依赖图谱，拆成可逐个完成的 Ticket
• 每个 Ticket 在干净的新会话里 /implement，完成后自动触发 /code-review

创建自定义 Skill

Skill 的编写目标只有一个：可预测性——让 Agent 每次走同一套流程，而不是碰运气。下面按 writing-for-agents 的推荐顺序，从调用方式写到修剪。

1. 决定调用方式（frontmatter）

一个 Skill 最少就是一个目录 + 一个 SKILL.md：

my-skill/
└── SKILL.md

调用方式写在 frontmatter 里，只有两种选择：

• 用户调用（user-invoked）：设置 disable-model-invocation: true。只有你手动输入名字才触发，Agent 和别的 Skill 都碰不到它；description 写一行给人看的简介。零上下文成本，代价是你自己得记得它。
• 模型调用（model-invoked）：不设置 disable-model-invocation。description 常驻上下文，Agent 能自动调用、别的 Skill 也能引用。可发现性高，但每轮都花 token。

默认原则：只有当 Agent 必须自己触发它、或别的 Skill 需要引用它时，才选模型调用；其余一律用户调用。

2. 写 description

• 模型调用：description 干两件事——说明 Skill 是什么，列出哪些分支应该触发它。每一条触发分支只写一次，同义词算重复要合并；把最核心的 leading word 放在前面；正文里已有的身份信息不要再写。
• 用户调用：一行人类简介即可，不需要触发分支。

3. 组织正文：步骤与参考

正文只有两类内容，按信息层级摆放：

• 步骤（Steps）：Agent 按顺序执行的动作。每一步都以**完成标准（completion criterion）**收尾——必须可检查（Agent 能判断做完没做完），尽量穷尽（“所有修改过的模型都覆盖到”，而不是“出一份变更清单”）。模糊的完成标准等于邀请 Agent 提前收工（premature completion）。
• 参考（Reference）：规则、定义、事实，按需查阅。所有分支都要用的留在 SKILL.md；只有部分分支用的拆到独立文件（如 GLOSSARY.md），在正文里留一个 context pointer——指针的措辞决定 Agent 何时会去取，而不是文件名。

同一概念的定义、规则、注意事项放在同一个标题下（co-location），不要散落。

4. 用 leading word 压缩

leading word 是模型预训练里已经熟悉的紧凑概念（如 lesson、tracer bullets）。把一段描述性短语换成这样一个词，既省 token，又给 Agent 一个更锐利的执行锚点。写完正文后通读一遍，找出重复出现的表述，能坍缩成词的都坍缩。

5. 修剪

• 单一事实来源：一个含义只写一处；环境里能查到的事实（package.json、CLI --help）不要抄进 Skill。
• 逐句做 no-op 测试：删掉某句后行为不变，就整句删除，而不是删几个词。
• 警惕沉淀（sediment）：新增容易、删除难，没有修剪纪律的 Skill 会越堆越厚。

6. 何时拆分

拆分的收益都来自渐进式披露：内容从“常驻”变成“按需”，只有指针命中时才被读入上下文。窗口里永远只放当前任务需要的东西——token 花得更少，注意力不被无关规则分散，后续步骤的信息也不会在眼前干扰当前判断。

• 按调用拆：出现一个独立触发词、或另一个 Skill 需要引用它时，拆成模型调用——但要确认常驻 description 的成本值得。
• 按序列拆：后面的步骤会诱惑 Agent 跳过当前步骤时，把后续步骤藏到真正的上下文边界之外（新会话、子代理），逼它先做完眼前这一步。

7. 对照失效模式自查

写完后逐项对照：premature completion（完成标准模糊）、duplication（同义多处）、sediment（没人敢删的旧层）、sprawl（太长）、no-op（写不写都一样）、negation（用“不要做 X”反而强化 X——一律写正面目标）。

一个符合上述规范的极简示例（模型调用）：

---
name: build-feature-with-tdd
description: 用测试驱动开发构建功能或修复 Bug。当用户要求先写测试、按红绿循环实现，或提到 test-first 时使用。
---

## 工作步骤
1. 理解需求（完成标准：能写出一句可验收的用户行为）
2. 写一个失败测试（完成标准：没有实现时测试确实报错——红灯）
3. 写最小实现（完成标准：测试通过——绿灯）
4. 重构（完成标准：行为不变，结构更干净）

## 参考
- 好测试与坏测试的判别：tests.md
- 不同场景的模拟策略：mocking.md