如何编写高质量的 Skill

什么是 Skill？

Skill（技能） 本质上是一个标准化的文件夹结构，里面包含了让 AI 能够胜任某项特定工作所需的全部资源：指令文档、参考材料、可执行脚本和模板文件。

你可以把它理解为 AI 的能力插件——加载后，AI 就多了一项专长；卸载后，AI 恢复为通用助手。和大模型的单次对话，可以按需加载skill，就可以避免上下文过长的问题。

最小形态

一个 Skill 最少只需要一个文件：

my-skill/
└ SKILL.md

SKILL.md 的结构分为两部分：

---
name: my-skill                    # 上半部分：元数据
description: >-                   # AI 靠这里判断是否激活这个技能
  当用户需要做某件事时，使用这个技能。
---

# 下半部分：操作指令
按照以下步骤执行...

• 上半部分（Frontmatter）：包含 name 和 description。AI 在每次对话时都会扫描所有已安装技能的元数据，仅依靠 description 来决定是否激活该技能。
• 下半部分（Body）：技能被激活后才会加载的操作指令。如果技能未被触发，AI 永远不会读取这部分内容，从而节省 Token。

完整结构

当技能变得复杂时，完整的目录结构如下：

skill-name/
├ SKILL.md                  # [必需] 入口文件：元数据 + 操作指令
├ agents/
│  └ openai.yaml           # [推荐] 技能的"名片"，用于 UI 展示
├ scripts/                  # [可选] 可执行脚本（Python/Bash 等）
├ references/               # [可选] 参考文档、API 说明、领域知识
└ assets/                   # [可选] 产出物模板、静态资源

• scripts/：写好的程序。AI 不需要理解代码逻辑，直接调用 Shell 执行即可。适合结果必须精确、不能让 AI 自由发挥的操作（如格式转换、复杂计算）。
• references/：AI 在工作过程中需要查阅的资料。与 scripts 的区别是：references 是给 AI 阅读的，scripts 是给 AI 执行的。
• assets/：直接用在最终产出里的文件（如模板、Logo、字体）。AI 不需要"读懂"它们，只需要知道何时引用或复制它们。

---

核心原则：给 AI 写指令，而不是给人

Skill 不是"人类团队文档"，不需要包含背景介绍、版本记录和模糊的原则。
AI 的思维方式不同：

• “基于多年经验总结”：AI 不关心历史，只关心现在该怎么做。
• “保持专业语气”：对人类是提示，对 AI 是模糊指令，会导致输出不稳定。
• “全面审查，给出建议”：AI 需要的是明确的步骤：先检查什么？标准是什么？

正确的写法是：精准、具体、可执行。

---

Skill 设计的三大支柱

1. 根本约束：简洁 (Conciseness)

AI 的上下文窗口（Context Window）是共享资源。系统提示、对话历史、其他技能的元数据都在占用空间。

核心原则：默认 AI 已经很聪明了，只补充它不知道的东西。

禁止放入 Skill 的文件：

• README.md、INSTALLATION_GUIDE.md、CHANGELOG.md
• 任何面向人类开发者的辅助文档

实操建议：用简洁的示例代替冗长的解释。一个好的代码示例胜过三段文字描述。

防御性编程（Negative Constraints）：
告诉 AI"不要做什么"往往比"做什么"更精确。例如，与其说"请用温暖的语气写作"，不如列出反模式清单：

• ❌不要使用绝对化词汇（“永远”、“一定”）
• ❌不要直接讲大道理，先铺陈场景
• ❌不要角色堆砌，保留核心冲突

2. 信息分层：三级渐进式加载 (Progressive Disclosure)

为了解决 Token 限制，Skill 采用三级架构管理信息：

层级	内容	何时加载	Token 成本
L1	Frontmatter (name + description)	始终在上下文中	~100 词
L2	SKILL.md Body (操作指令)	技能触发后加载	< 5k 词
L3	scripts/, references/, assets/	按需加载/执行	无上限

关键规则：

• L1 是过滤器：description 必须清晰说明"做什么"和"何时使用 (When to use)"。不要把这些信息放在 Body 里，因为那时 AI 已经决定使用技能了，为时已晚。
• L2 是操作手册：保持精炼，复杂细节通过链接指向 L3。
• L3 是工具箱：其中 scripts/ 最高效，因为执行脚本不消耗上下文 Token。

实战模式：

• 按领域拆分：如 bigquery-skill 可将 finance.md, sales.md 分开，AI 只加载当前任务相关的领域文档。
• 避免深层嵌套：所有 reference 文件应从 SKILL.md 直接链接，不要 A 引用 B，B 引用 C。

3. 自由度光谱：AI 做什么，脚本做什么？

不是所有任务都适合让 AI 自由发挥。根据任务的"脆弱性"（出错后果和正确解法的数量），分配不同的自由度：

• 高自由度（文字指令）：任务灵活，多种解法均可（如创意写作、代码重构）。
• 低自由度（脚本锁死）：任务脆弱，格式/长度/命名要求严格（如生成 YAML 配置、数据清洗）。

判断标准：

1. 做错了后果多严重？ 越严重 → 自由度越低 → 用脚本。
2. 有多少种"正确"的做法？ 越多 → 自由度越高 → 用文字。

什么时候该封装成脚本？

• 每次执行结果必须一致
• 涉及精确格式、长度约束或命名规范转换
• 同样的代码逻辑每次都要重新写（消耗 Token 且易错）

---

落地指南：六步创建流程

Step 1：理解技能

明确具体的使用场景。问自己：用户会用什么话触发这个技能？期望的输出是什么？

Step 2：规划可复用内容

分析任务流程，找出重复出现的部分：

• 需要反复执行的代码 → scripts/
• 需要频繁查阅的数据/文档 → references/
• 固定的模板/素材 → assets/

Step 3：初始化技能

使用脚手架工具（如 init_skill.py）生成标准目录结构。这能确保命名规范（hyphen-case）和文件格式正确，避免手动创建的脆弱性。

Step 4：编辑技能

1. 先实现资源：编写 scripts/ 并实际运行测试，确保无 Bug。
2. 编写 Frontmatter：

   ---
   name: skill-name
   description: >-
     描述技能做什么。
     明确列出触发条件：当用户需要 X、Y 或 Z 时使用。
   ---
   

3. 编写 Body：使用祈使语气（Imperative mood）。只写 AI 不知道的程序性知识和领域细节。

Step 5：校验技能

使用校验脚本（如 quick_validate.py）检查：

• YAML 格式是否合法
• name 是否符合规范（小写、连字符、长度限制）
• description 是否清晰且无非法字符

Step 6：迭代

在真实任务中运行 Skill，观察 AI 是否误解了指令或遗漏了步骤。根据实际表现调整 SKILL.md 或补充 references/。好的 Skill 是迭代出来的，不是一次写成的。

---

总结

编写高质量 Skill 的核心在于：用最少的 Token，在正确的层级，给 AI 最精准的约束。

1. 简洁：只写 AI 不知道的信息，多用示例和反模式清单。
2. 分层：利用 Frontmatter 触发，Body 指导，References/Scripts 扩展。
3. 确定性：脆弱操作交给脚本，创造性工作留给 AI。

遵循这些原则，你就能构建出稳定、高效且可复用的 AI 能力模块。