本文系统介绍Skill的开发规范，帮助开发者创建高质量的结构化知识与工作流封装单元。
什么是Skill？
Skill是一种结构化的知识与工作流封装单元，它告诉AI在特定任务场景下应该如何思考、使用哪些工具、遵循哪些步骤，以及输出什么格式。可以理解为给AI安装的"专业技能包"。
Skill解决的核心问题是：AI是泛化模型，在某些专业场景中仅靠预训练知识往往存在细节偏差。Skill提供了一个可注入的、可维护的补充上下文层。
三个核心属性
- 条件触发：只在匹配的任务场景下被调用，不污染无关对话
- 内容注入：SKILL.md正文作为额外上下文送入AI的上下文窗口
- 渐进加载：只有必要的内容会被加载，保持上下文窗口高效
设计哲学：Skill不是对AI能力的替代，而是减少环境特异性知识的摩擦。它回答的是"在这个具体环境里，正确的做法是什么"，而非"如何完成通用任务"。
目录结构与文件规范
每个Skill是一个以Skill名称命名的目录，其中SKILL.md是唯一必需文件，其余均为可选的辅助资源。
标准目录结构
skill-name/
├── SKILL.md # 必需：核心说明文件
├── scripts/ # 可选：可执行脚本（Python/Bash）
│ ├── generate.py # 生成类脚本
│ └── validate.sh # 校验类脚本
├── references/ # 可选：按需加载的参考文档
│ ├── aws.md # 分领域的详细参考
│ ├── gcp.md
│ └── azure.md
└── assets/ # 可选：模板、字体、图标等
├── template.docx
└── styles.css
各目录职责
- scripts/：存放确定性任务或重复性操作的可执行脚本。适合文件转换、格式校验、批量操作
- references/：存放大型参考文档，在SKILL.md中通过明确指引按需读取。每个文件最好聚焦单一主题
- assets/：存放Skill输出时所需的静态资源，如Office模板、CSS样式表、示例图片等
命名约定：Skill目录名和name字段应使用小写字母+连字符的kebab-case格式，如pdf-reading、frontend-design。
SKILL.md写作指南
SKILL.md由两部分组成：YAML Front Matter（元数据头）和Markdown正文（指令内容）。
完整模板
---
name: my-skill # 必需：唯一标识符，kebab-case
description: | # 必需：触发说明
当用户需要做X时使用此Skill。
具体触发词包括：X、Y、Z。
compatibility: # 可选：环境依赖声明
tools: [bash, python3]
requires: [pandoc, libreoffice]
---
# Skill正文Markdown内容
## 工作流程
...
## 关键约束
...
字段说明
- name（必需）：Skill的唯一标识符，与目录名保持一致
- description（必需）：触发判断的主要依据，决定何时读取SKILL.md正文
- compatibility.tools（可选）：此Skill依赖的AI工具名
- compatibility.requires（可选）：运行环境所需的外部命令或库
触发机制与Description设计
触发机制是Skill系统的核心。AI拿到用户请求后，会扫描所有已安装Skill的name+description，判断是否需要读取完整内容。
五个设计要素
1. 明确说明Skill做什么（What）
用一句话概括Skill的能力范围，动词优先。例如："创建、读取、编辑或操作Word文档"。
2. 枚举高频触发词和场景（Triggers）
列出用户最可能说出的词汇：文件格式名、动词短语、任务类型。
3. 覆盖隐式场景（Implicit Triggers）
用户不说关键词，但需求本质上属于此Skill的情况。例如："即使用户没有明说Word，只要需要生成格式化的可下载文档，也应使用此Skill"。
4. 声明不触发的边界（Exclusions）
减少误触发。例如："不适用于PDF、Google Docs或与文档无关的编码任务"。
5. 加入"推动性"表述（Push）
在description末尾加一句主动鼓励。例如："如果不确定是否需要，优先使用此Skill"。
对比示例
❌ 太简短：description: 处理Word文档。
✅ 完整版本：
description: |
当用户需要创建、读取、编辑或操作Word文档时使用此Skill。
触发词包括：'Word doc'、'.docx'、'报告'、'备忘录'。
即使用户未提到Word，只要需要生成带格式的专业文档，
也应使用此Skill。不适用于PDF或电子表格。
遇到"文档"类需求时优先使用。
渐进式信息披露
Skill系统采用三级加载机制，在保持上下文窗口高效的同时提供丰富信息。
三级加载系统
- Level 1 - 元数据：name+description，始终在上下文中，≤100词
- Level 2 - SKILL.md正文：完整的工作流、约束、示例，Skill触发时自动加载
- Level 3 - 捆绑资源：scripts/、references/、assets/，按需主动读取或执行
内容分配决策
- 是否用于触发判断？→ 放在description（Level 1）
- 是否每次执行都需要？→ 放在SKILL.md正文（Level 2）
- 是否只在特定子场景需要？→ 放在references/（Level 3）
- 是否是可执行的确定性操作？→ 封装成脚本放在scripts/（Level 3）
超过500行时：在正文中简述各分支场景，明确写出"遇到X情况时，读取references/x.md"，而非继续堆砌内容。
内容编写规范
最小意外原则
Skill内容应该是对AI的补充，而非颠覆。专注于描述当前环境的特异性约束。
- ✅ 在此环境中应使用python-docx库，而非pandoc
- ✅ 输出文件应保存到指定目录
- ✅ 字体嵌入时注意兼容性问题
- ❌ 告诉AI什么是Word文档（它已经知道）
结构化写作
SKILL.md正文应遵循清晰的Markdown结构：
- # Skill名称：与name字段一致
- ## 概述（可选）：简述此Skill解决什么特定问题
- ## 工作流程（核心）：明确的步骤序列，使用编号列表
- ## 关键约束：环境特异性限制
- ## 代码示例（如适用）：具体的、可直接参考的代码片段
- ## 常见错误与解决方案（如适用）：已知的坑和对应的处理方式
工作流描述要点
- 步骤原子化：每步只做一件事，可被独立验证
- 包含检查点：在关键步骤后标注"应验证X"
- 提供失败处理：说明步骤失败时的备选方案
- 引用具体命令：不写"安装依赖"，写"运行pip install python-docx"
语言与语气
用命令式写作（"读取X"、"执行Y"、"验证Z"），避免描述性语气（"可以考虑读取X"）。Skill是执行指令，不是建议。
脚本与资源使用规范
Scripts编写规范
- 单一职责：每个脚本只做一件明确的事
- 参数化设计：通过命令行参数接收输入，避免硬编码路径
- 清晰的退出码：成功返回0，失败返回非零并打印错误信息
- Python优先：环境中Python3通常已安装
- 依赖显式声明：脚本头部注释中列出所需的第三方包
References组织规范
- 多平台/多框架场景：每个平台一个文件
- 复杂API场景：每个模块一个文件
- 超过300行的参考文件：必须在文件开头提供目录
Assets管理规范
- 模板文件使用语义化命名：template-report.docx而非doc1.docx
- 在SKILL.md中明确说明assets的用途和使用时机
- 二进制资源需说明来源和授权
测试、评估与迭代流程
Skill写完之后必须经过系统性测试和至少一轮迭代，才能投入使用。
标准流程
- 设计测试用例集：5-15个覆盖典型场景和边界场景的测试Prompt
- 执行测试并收集输出：逐一运行测试Prompt，记录实际输出
- 人工审阅：重点关注输出是否符合预期格式、约束是否被正确遵循
- 修订Skill并重新测试：根据反馈修改，重复循环直到质量达标
- 扩大测试集：扩展到20+个用例，进行更大规模验证
Description优化：避免欠触发
AI在处理简单任务时倾向于不调用Skill，即使描述匹配度很高。这是因为AI会优先用自身能力解决问题。
提升触发率的策略
- 强调环境特异性："在此环境中，标准做法是X，而非AI通常使用的Y"
- 指出已知坑："不使用此Skill会导致常见错误Z"
- 使用主动语气："无论何时遇到X，都必须使用此Skill"
- 反复强调边界扩展："即使用户没有说X，只要场景涉及A/B/C，也应触发"
质量检查清单
结构与文件
- 目录名与name字段一致，使用kebab-case
- SKILL.md存在且包含完整的YAML Front Matter
- scripts/中的脚本有执行权限且有头部注释
- references/超过300行的文件有目录
- assets/中的文件在SKILL.md中有明确引用
Description质量
- 包含Skill做什么的清晰说明
- 枚举了至少5个触发词/场景
- 覆盖了隐式触发场景
- 声明了不适用的边界
- 包含"推动性"表述，鼓励优先使用
- 字数在100词以内，信息密度高
正文质量
- 工作流步骤原子化，使用编号列表
- 引用外部资源时提供了明确的触发条件和路径
- 代码示例使用了具体命令
- 约束条件使用命令式语气
- 正文不超过500行（或已引入references/分层）
测试与验证
- 至少设计了5个覆盖典型场景的测试Prompt
- 经过人工审阅，输出符合预期
- 至少进行了一轮修订迭代
- Skill在明显相关的任务上能被正确触发
- Skill在不相关任务上不会被误触发
总结
衡量一个Skill是否成功的标准：它让AI在这个特定场景下的表现，明显好于没有Skill时的默认行为。如果差别不大，说明Skill没有提供足够的环境特异性价值，需要重新审视定位。