# 如何写好一个Skill
没有Skill的团队，每个人都在重复造轮子。工程师的提示词散落各处，项目经理（Project Manager）的需求表述每次让智能体重新猜，管理层的经验则随着人员流动悄悄蒸发。表面上看，工程师、项目经理、管理层关心的事情完全不同。但在智能体工具的使用层面，大家面对的是同一个困境：经验无法积累，质量依赖个人。
**Skill的本质------隐性知识的代码化封装**：理解Skill，需要先理解它解决的是一个知识管理问题，而不只是一个AI工具问题。
管理学里有一个经典概念：隐性知识（Tacit Knowledge）。工程师知道"怎么和智能体沟通才能拿到高质量的代码审查"，这是隐性知识------他能做到，但说不清楚，也很难直接教给别人。与之对应的是显性知识------写在文档里、能被读取和传播的知识。
组织的知识管理目标，是尽可能多地把隐性知识转化为显性知识。传统方式是写文档、写SOP、做培训。但这些方式有一个致命的缺陷：文档会过期，SOP会被绕开，培训效果难以量化。更重要的是，文档描述的是人应该怎么做，而不是智能体应该怎么做------在智能体大量介入工作流的今天，这个区别至关重要。
Skill是更彻底的答案。它不是描述最佳实践的文档，而是**将最佳实践直接编码进智能体的执行路径**。当你把"竞品分析的标准框架"写成一个Skill，团队里任何人打开智能体说"帮我分析这个竞品"，智能体都会按照那套经过验证的框架来执行，而不是即兴发挥。
与普通提示词相比，Skill的核心差异有如[表1]所示的三个维度。
 表1Skill与普通提示词对照表 
| 维度   | 普通提示词         | Skill        |
|:---|:---|:---|
| 存储位置 | 个人笔记/对话历史。    | 团队共享库，结构化存储。 |
| 激活方式 | 用户手动粘贴。       | 智能体按需自动加载。   |
| 迭代机制 | 无版本管理，难以跟踪变化。 | 版本化管理，可回滚。   |
   
这个差异意味着：Skill不只是更好用的提示词，它更是一种知识的制度化存储形式，能让个人智慧变成组织能力。
**从案例看效果：标准化如何发生**
某产品团队有8名项目经理，日常工作中竞品分析报告是高频输出物。在引入Skill之前，8个人的报告风格各异：有人擅长写功能对比，有人专注用户体验，有人把重点放在商业模式------质量参差不齐，管理层每次阅读都要先适应一套新的框架。团队有经验的一位项目经理花了两天时间，把自己总结出的竞品分析框架封装成一个Skill：包含功能矩阵、用户旅程差异、定价策略、市场定位四个维度，每个维度都有标准的分析视角和输出格式。
上线三周之后，变化非常具体：
- 全团队的竞品分析报告开始采用统一框架，管理层的阅读时间从平均20分钟降到8分钟。
- 新来的两名项目经理在第一周就能产出与有经验的项目经理相当质量的分析。
- 项目经理的经验从此不再是"他个人的事"，而是团队的基础能力。
这就是Skill让标准化发生的路径：**不是靠培训和规范约束人，而是把最佳实践直接内置到工具里**，让每次使用都自然地沿着最优路径走。
理解Skill不需要先读代码------它更像是一份交给智能体的"岗位说明书"：告诉它什么情况下上岗、上岗后怎么干。本节拆解Skill的三个核心组成，展示渐进式加载的三层架构。
**Skill的三个核心组成：**一个最简单的Skill，仅需要name、description与执行指令三个要素。
- name（技能标识符）：name是Skill的唯一ID，也是它在系统和日志里被引用的方式。命名原则很简单，即动词+名词，清晰表达这个Skill做什么。"review-code"、"analyze-competitor"、"generate-prd"是好名字。"helper"、"assistant"、"tool1"是坏名字------模糊的名字在Skill库里会成为维护噩梦。
- description（技能描述）：description是整个Skill里最关键、也最容易被轻视的部分。智能体在决定"要不要激活这个Skill"时，唯一依赖的判断依据就是description。写得模糊等于白写------如果description没能在正确的场景触发Skill，再精妙的执行指令也毫无用处。
- 执行指令：具体执行剧本。指令是Skill被激活之后智能体实际执行的内容。它可以是一段结构化的步骤说明，也可以包含具体的分析框架、输出格式要求、边界条件处理方式。正文指令对智能体的作用，相当于一份详细的操作手册------越具体，执行越稳定。
以一个代码审查Skill为例，完整的三要素大概长这样：
```
yaml
name: review-code
description: |
  当用户提交代码请求审查、或要求对代码质量进行评估时激活。
  适用场景包括：Pull Request 审查、单文件代码质量检查、重构前的质量基线评估。
  不适用于代码调试或功能开发。
instructions: |
  ## 代码审查执行步骤
  
  ### 1. 首先评估整体结构
  - 模块划分是否清晰
  - 命名规范是否一致
  - 注释覆盖率是否达标
  
  ### 2. 逐项检查以下维度
  - **可读性**：代码是否容易理解，复杂逻辑是否有注释
  - **安全性**：是否存在常见漏洞（SQL 注入、XSS 等）
  - **性能**：是否有明显的性能问题
  - **测试覆盖**：关键路径是否有测试
  
  ### 3. 输出格式
  按以下结构输出审查报告：
  - 总体评分（1-10）
  - 必须修改项（Blocker）
  - 建议改进项（Suggestion）
  - 亮点记录（Highlight）
```
**渐进式加载的三层架构**：Skill的设计里有一个重要的工程决策，不是所有内容都需要始终驻留在智能体的上下文窗口里。一个团队可能有几十个甚至上百个Skill，如果每个Skill的全部内容都常驻上下文，会造成严重的上下文污染和性能损耗。Skill采取渐进式加载的三层架构来解决这一问题。
- 第一层：元数据------只包含name和description，体积极小，始终在智能体的视野内。智能体靠这一层来判断"有没有合适的Skill可以用"。
- 第二层：SKILL.md正文------包含完整的执行指令。只在Skill被激活（即description匹配成功）之后才读入上下文。这一层是Skill的主体，包含了所有的"怎么做"。
- 第三层：捆绑资源------脚本、参考文档、输出模板等附属材料。只在执行过程中需要引用时才按需加载，不会无谓地占用上下文空间。
这个架构的好处是：Skill数量的增加，不会线性增加智能体的上下文负担。一个团队有50个Skill，智能体的常驻上下文里只有50条轻量的description摘要，真正消耗上下文的内容，只有当前任务实际激活的那一两个Skill。
**可附带的资源类型与设计原则**：除了最基本的三个元素外，Skill的第三层可以携带三类资源，各有适用场景。
- 自动化脚本：适合处理固定的、无需每次判断的机械性操作。比如一个"生成API文档"的Skill，可以附带一个从代码注释自动提取接口信息的脚本，智能体在执行时直接调用，而不是每次手动描述提取逻辑。
- 参考文档：适合需要大量背景知识支撑的Skill。比如"合规检查"Skill可以附带公司的合规手册摘要，"技术方案评审"Skill可以附带架构设计规范。长篇参考文档建议加目录索引，方便智能体定向检索而不是全文扫描。
- 输出模板：适合对输出格式有严格要求的场景。比如周报生成Skill附带固定的Markdown模板，竞品分析Skill附带标准的表格结构。模板能大幅减少智能体在格式上的"自由发挥"，让输出更一致。