Skill：让 Agent 更懂你的工作流

最近在日常使用 AI Coding Agent 的过程中，一个问题越来越明显：

Agent 很聪明，但它并不天然理解你的团队规范、业务背景和工作流程。

举几个典型场景：

• 你希望它做代码审查时优先暴露风险，而不是输出一堆空泛的总结
• 你希望它生成的提交信息严格遵循团队约定的格式
• 你希望它处理某类任务时走一套固定流程，而不是每次自由发挥

当这些偏好只存在于脑子里，或者散落在历史聊天记录中时，Agent 的表现就会不稳定——今天效果很好，明天上下文一换，输出风格可能完全不同。

Skill 正是为了解决这个问题而存在的。

一、什么是 Skill

简单来说，Skill 是一份专门写给 Agent 的”任务说明书”。

它不是普通文档，也不是一段临时 Prompt，而是一套可以长期复用的能力描述，告诉 Agent：

• 这个能力是做什么的
• 在什么场景下应该启用
• 遇到这个任务时应该按什么方式处理
• 输出应该遵循什么风格和结构

换一种说法：

Skill 就是把你过去靠”临场提醒”才能做好的事，沉淀成 Agent 可以稳定复用的工作流。

它的本质不是”多一个配置”，而是把经验固化下来。

从技术实现上看，一个 Skill 就是一个包含指令、脚本和参考资料的文件夹。Agent 会在合适的时机加载它，从而以可重复、可预期的方式完成特定任务——无论是按照团队规范做代码审查，还是根据固定流程生成技术文档。

二、Skill 和普通 Prompt 有什么区别

很多人第一次接触 Skill，会觉得它和 Prompt 差不多，但两者有本质区别。

1. Prompt 是一次性的

比如你在对话框里说：

帮我审查一下这段代码，重点看边界条件和异常处理。

这当然有效，但问题在于：

• 只对当前对话生效
• 下一次还得重新描述
• 说法稍有变化，Agent 的执行重点就可能偏移

2. Skill 是可复用的

Skill 会把同一件事沉淀成稳定的能力，例如：

• 审查时优先找 bug、回归风险、缺失测试
• 问题靠前，总结靠后
• 反馈按严重程度排序
• 对性能、权限、异常分支做重点检查

一旦写好，只要场景匹配，Agent 就会自动进入你期望的工作方式。

一句话概括：

• Prompt 解决”这一次怎么说”
• Skill 解决”以后都怎么做”

三、哪些场景适合做成 Skill

并非所有任务都值得写成 Skill。判断标准很简单：高频、对质量敏感、且有相对稳定的方法论。

常见场景包括：

1. 代码审查

让 Agent 按团队标准审查代码，例如先看正确性，再看安全风险，最后看可维护性和测试覆盖。

2. 提交信息生成

统一提交信息风格，避免团队成员各写各的。

3. 文档写作

接口文档、技术方案、复盘文档、周报、项目总结等，都可以预设固定结构和输出要求。

4. 脚手架与初始化

新建页面、模块、组件时，要求遵循既定的目录结构和命名约束。

5. 特定领域任务

如果项目里有大量”通用模型并不知道”的知识——比如内部权限系统、公司网关、发布流程、特殊 RPC 接口——Skill 就是把这些领域知识补给 Agent 的最佳方式。

四、Skill 的基本结构

一个最小可用的 Skill，核心就是一个 SKILL.md 文件。典型目录结构如下：

your-skill/
├── SKILL.md              # 必需：主指令文件
├── reference.md          # 可选：详细参考资料
├── examples.md           # 可选：示例集
└── scripts/              # 可选：辅助脚本

1. frontmatter（元信息）

每个 SKILL.md 开头都有 YAML 格式的元信息，其中最关键的是 description——它直接决定 Agent 能否在合适的场景下识别并启用这个 Skill。

---
name: code-review
description: 按照团队标准审查代码的正确性、安全性和可维护性。当需要审查 PR、检查代码变更或用户要求做代码审查时使用。
---

一个好的 description 需要同时回答两个问题：这个 Skill 能做什么，以及什么时候该用它。写得越具体，Agent 触发得越准确。

2. 正文

正文一般包含：

• 任务目标
• 操作步骤
• 输出格式要求
• 示例
• 额外参考资料的链接

如果内容较多，不要全部塞进主文件。把细节拆到 reference.md 或 examples.md 里，保持主文件简洁，做渐进式展开。

五、怎么写出一个好的 Skill

Skill 不是越长越好。它的核心目标只有一个：让 Agent 稳定执行。好的 Skill 通常满足以下几个原则。

1. 描述要具体

很多 Skill 写不好，问题不在正文，而在描述太泛。

对比一下：

• 模糊：帮助处理文档
• 具体：生成结构化技术文档，适用于方案设计、模块说明、项目总结等场景

前者过于空泛，后者既说明了能力范围，也点明了适用场景。

2. 内容要精炼

Agent 本身已经很强了，不需要在 Skill 里重复它本来就知道的常识。

真正该写进去的是：

• 团队偏好和约定
• 这个任务的固定流程
• 容易出错的关键点
• 输出结构要求

切忌把 Skill 写成面向人的入门教程。

3. 给默认方案，减少歧义

如果你在 Skill 里写：

你可以这样做，也可以那样做，或者用另一种方式。

Agent 的自由度就太高了，实际执行时反而不稳定。

更好的做法是给出一个明确的默认方案，只有在特定条件下才切换备选路径。

4. 复杂任务拆成步骤

对于复杂任务，最好拆成清晰的流程：

1. 识别任务类型
2. 收集必要上下文
3. 按检查清单逐项执行
4. 输出结果
5. 自检验证

步骤越清晰，Agent 的执行就越稳定、越可预期。

5. 用示例锚定风格

很多时候，一个好示例胜过一百句描述。

比如你想让 Agent 生成某种固定格式的总结，最好的方式不是写”请按照简洁专业的风格输出”，而是直接给出一个高质量示例——示例会把风格、颗粒度和结构一步到位地锚定下来。

六、常见反模式

写 Skill 时，有几个特别常见的坑值得注意。

1. 名字太泛

像 helper、utils、tools 这样的命名几乎没有信息量。好的名字应该一眼能看出用途：

• code-review（代码审查）
• write-tech-doc（技术文档生成）
• generate-commit-message（提交信息生成）

2. 描述太虚

如果描述只有一句”帮助完成开发任务”，那和没写差别不大。Agent 无法从这种描述中判断何时该启用它。

3. 正文太长

Skill 的目标是提升执行质量，不是把所有背景知识讲一遍。正文一旦过长，重要信息就会被淹没，上下文开销也会变大，实际效果反而下降。建议主文件控制在 500 行以内。

4. 术语不统一

同一个概念，一会儿叫”接口”，一会儿叫”路由”，一会儿叫”服务入口”——Agent 会更难稳定理解你的意图。选定一个术语，全文统一使用。

5. 包含容易过时的信息

如果 Skill 里写了太多依赖时间、环境、版本的内容，很快就会失效。这类信息应该放到外部参考文件中，并保持定期维护。

七、一个最小可用 Skill 示例

下面是一个简化版的代码审查 Skill，它不长，但已经具备了最核心的信息：

---
name: code-review
description: 按照团队标准审查代码的正确性、安全性和可维护性。当需要审查 PR、检查代码变更或用户要求做代码审查时使用。
---

# 代码审查

## 检查清单

1. 检查逻辑正确性和边界条件
2. 检查安全风险
3. 检查可读性和可维护性
4. 检查测试覆盖情况

## 输出格式

- 问题放在最前面
- 按严重程度排序
- 总结保持简短

四个核心要素一个不少：做什么、什么时候用、按什么顺序检查、结果怎么输出。这就是一个可以直接使用的最小版本。

八、团队里如何管理 Skill

如果 Skill 只是个人使用，它更像是你的 AI 工作习惯沉淀；一旦放进项目仓库，它就成了团队协作的一部分。

1. 区分个人 Skill 和项目 Skill

• 个人 Skill（~/.cursor/skills/）：沉淀自己的通用工作流，跨项目生效
• 项目 Skill（.cursor/skills/）：沉淀团队共享的规范和业务知识，随代码一起维护

2. 从小而具体的场景切入

不要一上来就想做一个”万能开发助手”。更好的起点是：

• 一个代码审查 Skill
• 一个提交信息生成 Skill
• 一个技术文档生成 Skill

先把单点场景跑通、验证有效，再逐步扩展。

3. 持续迭代

Skill 和代码一样，需要迭代。当你发现 Agent 在某类任务上经常偏离预期，说明 Skill 需要补充更多约束或示例。

最好的 Skill 往往不是第一次就写出来的，而是在反复使用中逐渐打磨成型的。

九、总结

Skill 的价值，不在于”多了一个配置文件”，而在于它让 Agent 从”会做事”变成”按你期望的方式做事”。

它适合沉淀那些：

• 高频出现的任务
• 对质量要求高的任务
• 有固定流程或规范的任务
• 依赖领域知识的任务

如果把 Prompt 看成一次性的即时沟通，那 Skill 更像是把经验、标准和方法论正式交付给 Agent。

长远来看，真正拉开效率差距的，往往不是”某次提问写得多巧”，而是你有没有把可复用的经验系统地沉淀下来。

如果想开始尝试，建议很简单：

先从一个最痛、最重复、最容易跑偏的场景开始。

当第一个 Skill 真正跑顺之后，你会自然而然地想把第二个、第三个也沉淀下来。