1.1 Skill 的本质

Skill 是模块化、自包含的能力扩展单元，它通过专门知识、工作流程和工具集成来增强 AI Agent 的能力。可以把 Skill 理解为 AI Agent 的「岗位培训手册」——它把一个通用 AI 变成一个具备特定领域 procedural knowledge（程序性知识）的专业 Agent。

大模型本身拥有海量的常识性知识，但在以下场景中往往力不从心：

• 公司内部知识：内部系统、业务流程、数据 schema、合规规范
• 重复性工作流：每次都要从零推理，效率低且不一致
• 工具与格式集成：特定 API、文件格式、模板的使用细节
• 领域最佳实践：经过验证的操作步骤、判断标准、避坑指南

Skill 的价值，就是把这些「模型不知道、但执行任务必须知道」的知识，以结构化的方式打包，让 Agent 在需要时能精准调用。

1.2 一个「好用的 Skill」长什么样？

判断一个 Skill 好不好用，核心看三点：

二、Skill 设计的核心原则

2.1 原则一：简洁至上（Concise is Key）

上下文窗口是公共资源。Skill 会和系统提示词、对话历史、其他 Skill 的元信息、用户实际请求一起竞争有限的上下文空间。

设计心法：默认假设 AI Agent 已经非常聪明。 只添加 AI Agent 真正不知道的上下文。每一段信息都要经受拷问：「AI 真的需要这段解释吗？」「这几段话值得它消耗的 token 吗？」

实操建议：

• 能用一句话说清的，不用一段话
• 优先用简洁示例代替冗长解释
• 常识性内容一律删掉
• 详细内容放到 references 目录，按需加载

2.2 原则二：自由度匹配（Set Appropriate Degrees of Freedom）

Skill 的指令具体程度，应该和任务的「脆弱度」和「可变度」匹配：

类比思维：把 AI Agent 想象成在探索一条路——窄桥两边是悬崖，就需要具体的护栏（低自由度）；开阔的原野，可以走很多条路（高自由度）。

2.3 原则三：渐进式披露（Progressive Disclosure）

Skill 采用三级加载机制来高效管理上下文：

设计目标：SKILL.md 正文保持精简，控制在 500 行以内。接近上限时，把内容拆分到独立文件中。

常见拆分模式：

模式 1：高层指南 + 参考文件

Agent 只在需要时才加载对应的参考文件。

模式 2：按领域/子主题组织

用户问销售指标时，Agent 只读 sales.md。

模式 3：条件式详情

重要提醒：参考文件保持一层深度，不要嵌套太深。所有参考文件都应从 SKILL.md 直接链接。超过 100 行的参考文件，顶部加目录。

三、Skill 的结构组成

3.1 标准目录结构

每个 Skill 由一个必需的 SKILL.md 文件和可选的捆绑资源组成：

skill-name/
├── SKILL.md              # 必需：Skill 的入口和核心说明
│   ├── YAML Frontmatter  # 必需：name + description
│   └── Markdown 正文     # 必需：使用指引
│
├── scripts/              # 可选：可执行代码（Python/Bash 等）
├── references/           # 可选：参考文档，按需加载
└── assets/               # 可选：输出用的资源文件

3.2 SKILL.md：Skill 的灵魂

SKILL.md 是 Skill 唯一必需的文件，分为两部分：

Frontmatter（YAML 元数据）

写好 description 的黄金法则：

• 同时说明「做什么」和「什么时候用」——description 是 Skill 的主要触发机制
• 所有「何时使用」的信息都写在这里——正文在触发后才加载，写在正文里没用
• 列举具体触发场景——用 (1)(2)(3) 列出来，越具体越不容易误触发
• 覆盖所有使用方式——用户可能用各种说法表达同一个需求，都要覆盖到

正文（Markdown 指令）

正文是 Agent 触发 Skill 后才会读取的内容，应该包含：

• 核心工作流程和步骤
• 关键判断点和决策逻辑
• 各资源文件的使用说明和加载时机
• 常见问题和注意事项
• 质量标准和验收要求

写作风格：始终使用祈使句/不定式（「做 X」「使用 Y」），不要用描述性语言（「这个 Skill 可以做 X」）。

3.3 三类捆绑资源

Scripts（脚本）

什么时候放 scripts/：

• 同样的代码被反复重写
• 需要确定性的、可重复的结果
• 操作复杂、容易出错

例子：scripts/rotate_pdf.py 用于 PDF 旋转任务

优势：token 效率高、结果确定、可以不读入上下文直接执行

注意：脚本可能仍需要 Agent 读取来做环境适配或修补

References（参考文档）

什么时候放 references/：

• Agent 工作时需要查阅的文档
• 详细的领域知识、规范、schema

例子：

• references/finance.md — 财务指标定义
• references/api_docs.md — API 接口文档
• references/policies.md — 公司政策

最佳实践：

• 文件大（>10k 字）时，在 SKILL.md 中写明 grep 搜索模式
• 信息要么在 SKILL.md，要么在 references，不要重复
• SKILL.md 只保留核心流程指引，详细内容放 references

Assets（资产）

什么时候放 assets/：

• 最终输出产物中需要用到的文件
• 模板、图片、字体、样板代码

例子：

• assets/logo.png — 品牌 Logo
• assets/slides-template.pptx — PPT 模板
• assets/frontend-boilerplate/ — 前端项目脚手架

特点：不加载到上下文，而是在输出中被使用/复制/修改

3.4 什么不该放进 Skill

Skill 应该只包含直接支撑其功能的必要文件。不要创建这些多余文件：

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md
• 等等

Skill 是给 AI Agent 用的，不是给人看的开源项目。额外的文档只会造成混乱和上下文浪费。

四、从问题到 Skill：创建方法

4.1 第一步：用具体例子理解需求

跳过这一步的前提：你已经非常清楚 Skill 的使用模式。即使是改造现有 Skill，这一步也很有价值。

要创建一个有效的 Skill，必须先清楚地理解它会被如何使用——用具体的、真实的用户场景来定义。

关键问题清单：

1. 这个 Skill 要支持哪些功能？
2. 用户会怎么说？能举几个典型的用户提问例子吗？
3. 什么样的用户输入应该触发这个 Skill？
4. 期望的输出是什么样的？有格式或质量要求吗？

示例：设计一个图片编辑 Skill

• ? 模糊理解：「用户要编辑图片」
• ? 具体理解：
  • 「把这张图里的红眼去掉」→ 触发图片修复功能
  • 「把这个 PDF 转成图片」→ 触发格式转换功能
  • 「帮我把这张图旋转 90 度」→ 触发旋转功能
  • 「给这张图加个水印」→ 触发水印功能

沟通技巧：不要一次问太多问题，先从最重要的开始，逐步深入。

4.2 第二步：规划可复用的内容

把具体例子转化为 Skill 内容，对每个例子做分析：

1. 如果从零开始执行这个任务，需要怎么做？
2. 反复执行这些工作流时，哪些脚本/参考/资产会有帮助？

分析示例：PDF 编辑器 Skill

分析示例：前端应用构建 Skill

分析示例：数据查询 Skill

通过这个分析，你就能列出 Skill 需要包含的所有可复用资源：scripts、references、assets。

4.3 第三步：初始化 Skill 结构

用初始化脚本快速创建标准目录结构：

脚本会自动创建：

• Skill 目录
• 带 frontmatter 和 TODO 占位符的 SKILL.md 模板
• scripts/、references/、assets/ 示例目录和文件

初始化后，根据需要自定义或删除生成的示例文件。

4.4 第四步：实现 Skill 内容

先做资源，再写文档——先实现 scripts/references/assets 中的内容，再更新 SKILL.md。这样写文档时你已经清楚有哪些资源可用、怎么用。

实现脚本的注意事项

• 每个脚本都要实际运行测试，确保没有 bug、输出符合预期
• 脚本很多时，至少测试代表性样本
• 不需要的示例文件和目录都删掉

写 SKILL.md 的注意事项

• 始终使用祈使句
• Frontmatter 的 description 要精心打磨
• 正文按工作流组织，不是按资源类型组织
• 明确告诉 Agent 什么时候读哪个 reference 文件
• 包含质量标准和验收要求

4.5 第五步：收尾和交付

开发完成后，确认以下事项：

1. ? 目录包含必需的 SKILL.md 文件
2. ? 所有需要的 scripts/、references/、assets/ 文件都在
3. ? 删除了占位文件、未使用的示例资源、缓存和临时输出
4. ? 运行了需要测试的脚本（或说明为什么没测）
5. ? 运行了验证脚本检查 frontmatter 和命名

交付形式：Skill 文件夹本身就是交付物。不要打包成 zip，也不要创建 .skill 文件。保持完整目录结构，这样可以直接作为文件夹加载。

五、确保 Skill 「好用」的设计技巧

5.1 触发准确率优化

触发不准是 Skill 最常见的问题。以下是优化 description 的几个技巧：

技巧 1：覆盖多种表达方式

技巧 2：明确边界，减少误触发

技巧 3：用具体动词和名词

5.2 执行质量保障

技巧 1：给出明确的质量标准

不要只说「生成一份报告」，要说「报告应包含 X/Y/Z 三个部分，每部分不少于 500 字，数据需标注来源」

技巧 2：提供正反示例

• 好的输出长什么样，差的输出长什么样，对比展示
• 对容易出错的地方特别强调

技巧 3：预设常见错误和应对

• 列出 Agent 可能犯的错误
• 给出检测和纠正的方法

技巧 4：加入自检步骤

• 在工作流的关键节点加入检查点
• 告诉 Agent 完成后要做哪些验证

5.3 上下文效率优化

技巧 1：信息分层

• 最常用的 20% 内容放 SKILL.md
• 偶尔用的放 references
• 几乎不用的放更深层的 reference 或干脆不放

技巧 2：用表格代替大段文字

• 结构化信息用表格，信息密度更高
• 决策逻辑用流程图式的判断树

技巧 3：代码和配置用代码块

可执行的内容用代码块，Agent 更容易识别和使用

六、常见陷阱与避坑指南

陷阱 1：把 Skill 写成了教程

问题：花大量篇幅解释概念、讲背景知识，Agent 根本不需要。

解法：直接给操作指令，假设 Agent 已经理解基础概念。需要背景知识的放 references，按需加载。

陷阱 2：description 太短或太泛

问题：description 只有一句话，导致触发不准。

解法：description 是 Skill 最重要的部分，值得花时间打磨。要包含功能描述 + 具体触发场景 + 边界说明。

陷阱 3：所有内容都塞在 SKILL.md

问题：SKILL.md 写了几千行，触发一次就占满大半上下文。

解法：遵循渐进式披露原则，按使用频率和场景拆分到 references。

陷阱 4：没有实际测试脚本

问题：脚本写了但没跑过，实际用的时候全是 bug。

解法：每个脚本都要实际运行测试，至少用一个真实用例验证。

陷阱 5：过度设计

问题：还没验证需求就做了一大堆功能，结果大部分用不上。

解法：先做最小可用版本，在真实使用中迭代。从最常见的 2-3 个用例开始。

七、总结：好 Skill 的设计清单

创建 Skill 前，用这份清单检查你的设计：

需求理解

• 有至少 3 个具体的用户使用场景
• 清楚用户会用什么说法触发这个 Skill
• 明确了 Skill 的边界（做什么、不做什么）

结构设计

• SKILL.md 控制在 500 行以内
• 详细内容拆分到了 references
• 重复代码封装成了 scripts
• 输出模板放在了 assets

内容质量

• description 写得具体、全面、边界清晰
• 正文用祈使句，直接给指令
• 有明确的质量标准和验收要求
• 包含了常见问题和注意事项

可交付性

• 所有脚本都经过实际运行测试
• 删除了所有占位文件和示例资源
• 目录结构清晰，命名规范
• 通过了基础验证检查

Skill 设计是一个持续迭代的过程。第一版不需要完美，先让它跑起来，在真实使用中发现问题、持续优化，才是打造高质量 Skill 的正确路径。