如何写好一个Skill

没有Skill的团队，每个人都在重复造轮子。工程师的提示词散落各处，PM的需求表述每次让Agent重新猜，管理层的经验则随着人员流动悄悄蒸发。表面上看，工程师、PM、管理层关心的事情完全不同。但在Agent工具的使用层面，他们面对的是同一个困境：经验无法积累，质量依赖个人。

Skill的本质——隐性知识的代码化封装：理解Skill，需要先理解它解决的是一个知识管理问题，而不只是一个AI工具问题。

管理学里有一个经典概念：隐性知识（Tacit Knowledge）。工程师知道“怎么和 Agent 沟通才能拿到高质量的代码审查”，这是隐性知识——他能做到，但说不清楚，也很难直接教给别人。与之对应的是显性知识——写在文档里、能被读取和传播的知识。

组织的知识管理目标，是尽可能多地把隐性知识转化为显性知识。传统方式是写文档、写SOP、做培训。但这些方式有一个致命的缺陷：文档会过期，SOP会被绕开，培训效果难以量化。更重要的是，文档描述的是人应该怎么做，而不是Agent应该怎么做——在Agent大量介入工作流的今天，这个区别至关重要。

Skill是更彻底的答案。它不是描述最佳实践的文档，而是将最佳实践直接编码进Agent的执行路径。当你把“竞品分析的标准框架”写成一个Skill，团队里任何人打开Agent说“帮我分析一下这个竞品”，Agent都会按照那套经过验证的框架来执行，而不是即兴发挥。

与普通提示词相比，Skill的核心差异有如表1所示的三个维度。

这个差异意味着：Skill不只是更好用的提示词，它更是一种知识的制度化存储形式，能让个人智慧变成组织能力。

从案例看效果：标准化如何发生

某产品团队有8名PM，日常工作中竞品分析报告是高频输出物。在引入Skill之前，8个人的报告风格各异：有人擅长写功能对比，有人专注用户体验，有人把重点放在商业模式——质量参差不齐，管理层每次阅读都要先适应一套新的框架。团队的一位资深PM花了两天时间，把自己总结出的竞品分析框架封装成一个Skill：包含功能矩阵、用户旅程差异、定价策略、市场定位四个维度，每个维度都有标准的分析视角和输出格式。

上线三周之后，变化非常具体：

• 全团队的竞品分析报告开始采用统一框架，管理层的阅读时间从平均20分钟降到8分钟。
• 新来的两名PM在第一周就能产出与资深PM相当质量的分析。
• 资深PM的经验从此不再是“他个人的事”，而是团队的基础能力。

这就是Skill让标准化发生的路径：不是靠培训和规范约束人，而是把最佳实践直接内置到工具里，让每次使用都自然地沿着最优路径走。

理解Skill不需要先读代码——它更像是一份交给Agent的“岗位说明书”：告诉它什么情况下上岗、上岗后怎么干。本节拆解Skill的三个核心组成，展示渐进式加载的三层架构。

Skill的三个核心组成：一个最简单的Skill，只需要三样东西，name、description与执行指令

• name（技能标识符）：name是Skill的唯一ID，也是它在系统和日志里被引用的方式。命名原则很简单，即动词+名词，清晰表达这个Skill做什么。“review-code”、“analyze-competitor”、“generate-prd”是好名字。“helper”、“assistant”、“tool1”是坏名字——模糊的名字在Skill库里会成为维护噩梦。
• description（技能描述）：description是整个Skill里最关键、也最容易被轻视的部分。Agent在决定“要不要激活这个Skill”时，唯一依赖的判断依据就是description。写得模糊等于白写——如果description没能在正确的场景触发Skill，再精妙的执行指令也毫无用处。
• 执行指令：具体执行剧本。指令是Skill被激活之后Agent实际执行的内容。它可以是一段结构化的步骤说明，也可以包含具体的分析框架、输出格式要求、边界条件处理方式。正文指令对Agent的作用，相当于一份详细的操作手册——越具体，执行越稳定。

以一个代码审查Skill为例，完整的三要素大概长这样：

yaml
name: review-code

description: |
  当用户提交代码请求审查、或要求对代码质量进行评估时激活。
  适用场景包括：Pull Request 审查、单文件代码质量检查、
  重构前的质量基线评估。不适用于代码调试或功能开发。

instructions: |
  ## 代码审查执行步骤
  
  ### 1. 首先评估整体结构
  - 模块划分是否清晰
  - 命名规范是否一致
  - 注释覆盖率是否达标
  
  ### 2. 逐项检查以下维度
  - **可读性**：代码是否容易理解，复杂逻辑是否有注释
  - **安全性**：是否存在常见漏洞（SQL 注入、XSS 等）
  - **性能**：是否有明显的性能问题
  - **测试覆盖**：关键路径是否有测试
  
  ### 3. 输出格式
  按以下结构输出审查报告：
  - 总体评分（1-10）
  - 必须修改项（Blocker）
  - 建议改进项（Suggestion）
  - 亮点记录（Highlight）

渐进式加载的三层架构：Skill的设计里有一个重要的工程决策，不是所有内容都需要始终驻留在Agent的上下文窗口里。一个团队可能有几十个甚至上百个Skill，如果每个Skill的全部内容都常驻上下文，会造成严重的上下文污染和性能损耗。Skill采取渐进式加载的三层架构来解决这一问题。

• 第一层：元数据——只包含name和description，体积极小，始终在Agent的视野内。Agent靠这一层来判断“有没有合适的Skill可以用”。
• 第二层：SKILL.md正文——包含完整的执行指令。只在Skill被激活（即description匹配成功）之后才读入上下文。这一层是Skill的主体，包含了所有的“怎么做”。
• 第三层：捆绑资源——脚本、参考文档、输出模板等附属材料。只在执行过程中需要引用时才按需加载，不会无谓地占用上下文空间。

这个架构的好处是：Skill数量的增加，不会线性增加Agent的上下文负担。一个团队有50个Skill，Agent的常驻上下文里只有50条轻量的description摘要，真正消耗上下文的内容，只有当前任务实际激活的那一两个Skill。

可附带的资源类型与设计原则：除了最基本的三个元素外，Skill的第三层可以携带三类资源，各有适用场景。

• 自动化脚本：适合处理固定的、无需每次判断的机械性操作。比如一个“生成API文档”的Skill，可以附带一个从代码注释自动提取接口信息的脚本，Agent在执行时直接调用，而不是每次手动描述提取逻辑。
• 参考文档：适合需要大量背景知识支撑的Skill。比如“合规检查”Skill可以附带公司的合规手册摘要，“技术方案评审”Skill可以附带架构设计规范。长篇参考文档建议加目录索引，方便Agent定向检索而不是全文扫描。
• 输出模板：适合对输出格式有严格要求的场景。比如周报生成Skill附带固定的Markdown模板，竞品分析Skill附带标准的表格结构。模板能大幅减少Agent在格式上的“自由发挥”，让输出更一致。