AI Agent 的 Skill 系统设计

本文系统阐述了 AI Agent Skill 系统的设计理念与工程实践，核心观点是将 Skill 视为“行为编程”而非文档，旨在通过结构化设计（YAML+Markdown、DOT 流程图、检查表）和严格的约束机制（门控、合理化防御、说服原则）来规范 AI 代理的行为。文章详细探讨了在有限上下文窗口下的 Token 经济策略，包括基于触发条件的发现机制、两阶段加载及声明式引用；提出了单向管道工作流编排、子代理上下文隔离及分级模型选择方案；强调了基于 TDD 理念的 Skill 测试方法，即通过压力场景观测并封堵代理的违规行为；最后总结了跨平台适配策略及从“建议”走向“强制”、从“手动”走向“自动”的演进教训，旨在构建高合规性、低成本且可维护的 AI 代理技能体系。

Skill 的价值是把期望行为转化成 Agent 能稳定执行的工作流。一个好的 Skill 要同时解决四件事： 

1. 让 Agent 在正确场景发现它

2. 用最少上下文加载必要信息

3. 按任务风险设置合适的自由度

4. 并通过真实任务验证它是否改变了行为。

本文的重点是如何写好能被 Agent 正确触发、正确执行、可持续维护的 Skill。

先定义目标：Skill 是能力包，不是知识库

Skill 可以被理解为一个自包含的能力包。它通过 SKILL.md、脚本、引用资料和资产，把一个通用 Agent 转化为在特定任务上更可靠的专用 Agent。

它通常提供四类能力：

Skill 面向的是 Agent，它会在上下文不足、任务复杂、目标冲突或执行压力下走捷径。因此，Skill 必须预设这些失败模式，并把正确路径写成更容易被执行的行为结构。

因此，Skill 不是把人类已经知道的背景知识完整搬进去，而是补充 Agent 完成任务时缺少的程序性知识、资源边界和验证方式。换句话说，写 Skill 不是“把说明写清楚”，而是“让 Agent 在复杂环境中更难走错”。

一个有效的 Skill 要影响 Agent 的完整行为链路：

• 什么时候发现这个 Skill

• 什么时候加载完整正文

• 哪些信息继续按需读取

• 哪些动作必须先做

• 哪些行为绝对不能发生

• 如何证明任务真的完成

• 什么时候需要停下来请求人类判断

如果一个 Skill 只在模型状态好、上下文充足、任务简单时生效，它更像提示词模板。高质量 Skill 应该能在任务复杂、信息不完整、执行压力和合理化冲动下，把 Agent 拉回正确路径。

Skill 设计的第一条工程原则是：上下文窗口是公共资源。

Agent 执行任务时，上下文窗口要同时容纳系统提示、用户请求、对话历史、已触发 Skill、工具结果、代码片段和中间推理。Skill 多占一个 token，其他上下文就少一个 token。所以写 Skill 时要默认 Agent 已经很聪明，只补充它不知道、但完成任务必须知道的内容。

每一段内容都应该经受两个问题的挑战：

• Agent 真的需要这段解释吗？

• 这段内容值得它占用的 token 成本吗？

这也是为什么 Skill 应该采用渐进披露，而不是把所有信息塞进一个长文件。

一个标准 Skill 目录通常长这样：

skill-name/SKILL.mdagents/openai.yamlscripts/references/assets/

其中只有 SKILL.md 是必需的，其余资源按需要添加。

SKILL.md 的 frontmatter 和正文要承担不同职责：

---name: create-skilldescription: 用于创建或更新包含工作流、工具集成、领域知识、脚本、参考资料或资产的 Agent Skill。---# 创建 Skill流程：1. 理解具体示例。2. 规划可复用资源。3. 初始化 Skill。4. 编辑 SKILL.md 和相关资源。5. 验证。6. 结合真实使用持续迭代。

name 和 description 是发现层。正文是执行层。这两层不要混在一起。

description 应该包含“这个 Skill 做什么”和“什么时候使用它”，因为 Agent 只有在触发后才会读取正文。如果把触发条件放在正文里的 When to Use，Agent 在决定是否触发时根本看不到。但 description 也不能变成完整工作流摘要。它的职责是让 Agent 正确加载正文，而不是让 Agent 读完描述就开始凭印象执行。

命名同样属于发现机制的一部分。一个好的 Skill 名称应该短、可触发、动词优先：

这些细节看起来像命名规范，本质上是路由质量。Agent 在一个不断增长的技能库里找能力，name 和 description 就是它的第一层索引。

创建 Skill 时，不应该一开始就写长篇 SKILL.md。更好的路径是先看具体例子，然后判断哪些东西值得变成可复用资源。

当同一段代码会被反复重写，或者任务需要确定性时，放进 scripts/：

pdf-editor/SKILL.mdscripts/rotate_pdf.py

脚本的价值不是“让目录更丰富”，而是减少上下文消耗和行为漂移。让 Agent 每次临时生成 PDF 旋转代码，和让它调用一个已经验证过的脚本，是完全不同的可靠性水平。

当信息是任务执行时需要查阅的知识，而不是每次都必须读的流程，就放进 references/：

big-query/ SKILL.md references/ schema.md finance.md product.md

如果用户问销售指标，Agent 只需要读 sales.md 或对应领域文件，不应该同时加载财务、产品、市场的所有规则。这就是渐进披露在真实 Skill 中的价值：信息可发现，但不抢占上下文。

当文件不会被读入上下文，而是作为输出材料被复制、修改或引用时，放进 assets/：

frontend-webapp-builder/ SKILL.md assets/ hello-world/

例如模板工程、字体、图片、PPT 模板、品牌素材都属于资产。它们不是给 Agent 阅读的长文本，而是给最终产物使用的材料。

资源组织还有一个容易被忽略的原则：信息只放一个地方。不要在 SKILL.md 和 references/ 中重复同一段规则。重复会带来漂移，漂移会让 Agent 在两个版本之间自行解释，最后把维护成本转化成执行风险。

Skill 不是越详细越好，也不是越开放越好。关键是让自由度匹配任务的脆弱度和变化空间。

可以把 Skill 的控制方式分成三档：

例如： 

• 写技术文章：适合高自由度，用结构原则、语气规则和示例引导。

• 查询内部指标：适合中自由度，用 SQL 模板和字段说明控制口径。

• 旋转 PDF、转换格式、生成固定报告：适合低自由度，用脚本保证确定性。

一个常见错误是把脆弱操作写成开放建议，导致 Agent 每次重写一遍容易出错的逻辑。另一个错误是把本该依赖判断的任务写成死流程，导致 Skill 在真实场景里僵硬、不可迁移。

在低自由度任务里，门控尤其重要。Skill 如果只写“建议先做 A”，Agent 很可能直接进入 B。门控的作用是：在条件满足前，明确禁止后续动作。

HARD-GATE>在理解具体使用示例并规划好可复用资源之前，不要创建或编辑该 Skill。HARD-GATE>

常见门控包括：

门控不是语气问题，而是执行边界。它能减少 Agent 的解释空间，让 Skill 在关键路径上更像程序，而不是建议。

一个稳妥的 Skill 创建流程可以拆成六步：

1. 理解具体使用例子

2. 规划可复用资源

3. 初始化 Skill

4. 编辑 SKILL.md 和资源

5. 验证 Skill

6. 基于真实使用迭代

这条流程的重点不是“先写一个漂亮的说明”，而是先建立使用边界。

不要从抽象能力开始写 Skill。先问：

• 用户会怎么触发它？

• 哪些请求应该触发？

• 哪些请求不应该触发？

• 任务输入是什么？

• 成功输出是什么？

• 哪些步骤最容易出错？

例如做一个 pdf-editor Skill，应该先收集“旋转 PDF”“合并 PDF”“提取页面”等具体请求，再决定是否需要脚本。没有具体例子，很容易写出宽泛但不可执行的 Skill。

对每个例子，从零执行一遍，识别可复用部分：

当 Skill 包含非线性判断、循环、回退或容易提前终止的步骤时，流程图比纯文本更稳定。GraphViz DOT 是一个适合嵌入 Markdown 的轻量格式：

digraph {"是否有具体使用例子?" [shape=diamond];"收集或生成例子" [shape=box];"规划 scripts/references/assets" [shape=box];"编写 SKILL.md" [shape=box];"运行 quick_validate.py" [shape=box];"完成" [shape=doublecircle];"是否有具体使用例子?" -> "规划 scripts/references/assets" [label="yes"];"是否有具体使用例子?" -> "收集或生成例子" [label="no"];"收集或生成例子" -> "规划 scripts/references/assets";"规划 scripts/references/assets" -> "编写 SKILL.md";"编写 SKILL.md" -> "运行 quick_validate.py";"运行 quick_validate.py" -> "完成";}

复杂流程还需要编号检查表，并要求 Agent 外化进度。否则，Agent 很容易执行前几步后忘记后面的验证和迭代。

初始化 Skill 时，应使用初始化脚本，而不是手写目录结构：

scripts/init_skill.py my-skill --path"${CODEX_HOME:-$HOME/.codex}/skills"

如果需要资源目录：

scripts/init_skill.py my-skill --path"${CODEX_HOME:-$HOME/.codex}/skills" --resources scripts,references

初始化脚本的意义是减少结构错误，并生成符合规范的模板。之后再替换占位内容，删除不需要的示例文件。

Skill 不应该一次写完就冻结。它的质量来自真实行为反馈，而不是作者对流程的想象。

完成后首先运行基础验证：

scripts/quick_validate.py

基础验证至少应覆盖：

• YAML frontmatter 是否合法

• name 和 description 是否存在

• 命名是否符合规则

• 资源目录是否合理

• 脚本是否能运行

• UI 元数据是否与 SKILL.md 同步

格式验证不能证明 Skill 一定好用，但可以先排除低级错误。复杂 Skill 还需要前向测试。可以用子代理模拟真实用户任务，但要把它当成评估面，而不是审稿人。

正确做法：

使用位于 /path/to/skill-x 的 @skill-x 来解决问题 y。

不好的做法：

审查这个 Skill。我认为它存在问题 A，预期的修复方案是 B。

后者会泄露诊断和预期答案，测试结果会被污染。前向测试应该给子代理原始任务、原始材料和最少必要上下文，让它像真实使用者一样执行。

验证时应优先使用原始证据：

• 示例 prompt

• 输出文件

• diff

• 日志

• 行为轨迹

• 失败截图

• 测试结果

如果子代理只有在看到你的结论后才能成功，说明 Skill 本身还不够清楚，或者测试设置已经泄露答案。

这里还要处理一个 Agent 特有的问题：合理化。AI Agent 在压力下会给跳过规则找到听起来合理的理由。Skill 需要提前写出这些借口，并给出反驳。

审查循环也应该围绕真实失败风险，而不是措辞偏好：

写或修改 Skill-> 运行格式验证-> 用真实任务前向测试-> 是否存在会导致任务失败的问题？-> 是：修复并重测-> 否：交付

应该阻塞的问题包括触发条件模糊、资源引用缺失、脚本不可运行、验证流程缺失、自由度设置错误、关键信息重复且容易漂移。不应该阻塞的问题包括纯粹风格偏好、不影响执行的标题顺序、可以由 Agent 自行判断的轻微表达差异。

当技能库变大后，发现机制会成为第一瓶颈。description 是路由器，不是教程。

它应该覆盖：

• Skill 做什么

• 何时使用

• 典型触发词

• 相关症状

• 输入或任务类型

但不要写完整执行流程。

错误写法：

description: "创建 Skill 时先收集例子，再规划 scripts/references/assets，然后运行 init_skill.py，最后 quick_validate.py。"

更好的写法：

description: "用于创建或更新包含专用工作流、工具集成、领域知识、捆绑脚本、参考资料、资产、验证或迭代机制的 Agent Skill。"

前者让 Agent 可能只凭描述执行，跳过正文。后者让 Agent 知道应该触发，但仍需要加载正文获取完整流程。

Skill 之间也可以互相引用，但应该声明关系，而不是硬编码路径或强制加载大文件：

**必需子 Skill：** 创建新 Skill 前，先使用 skill-x。**推荐：** 如果要将其发布为开发者文章，使用 skill-y。**另见：** openai_yaml.md，了解 UI 元数据字段。

引⽤可以分为三层：

不要用一次性强制加载大量内容的方式组合 Skill。那会破坏渐进披露，也会让组合 Skill 的成本失控。

最后是平台适配。不同平台的工具名、hook、插件机制和子代理能力可能不同。Skill 应该尽量写行为规则，再用平台层适配具体工具。

例如：

- TodoWrite -> todowrite- Task tool -> @mention subagent system- Skill tool -> native skill tool

平台能⼒不⾜时，应优雅降级：

这能让 Skill 更可迁移，也更容易维护。真正应该稳定的是行为规则，而不是某个平台的私有工具名。

很多 Skill 失败，不是因为作者不知道领域知识，而是因为它把人类文档的写法带到了 Agent 执行系统里。

常见反模式如下：

交付前可以⽤这张表⾃查：

如果这张表里有多项答不上来，Skill 还不是能力包，只是一份草稿。

结论：好 Skill 是小而准的行为系统

写 Skill 不是把最佳实践整理成 Markdown。真正的 Skill 设计要回答三个问题：

1. Agent 在什么情况下应该发现并加载它？

2. Agent 应该获得多少⾃由度，哪些部分必须被脚本或⻔控固定？

3. 我们如何⽤真实任务证明它确实改变了⾏为？

核⼼的提醒是：Skill 要简洁、分层、可验证、可迭代。上下⽂窗⼝是公共资源， SKILL.md 只放核⼼流程；脚本承接确定性，引⽤承接领域知识，资产承接输出材料；复杂 Skill 要通过真实任务前向测试，⽽不是靠作者⾃信。

因此，Skill 是 Agent ⾏为设计的⼀种⼯程⽅法。它把触发、加载、执⾏、约束、验证和迭代组织在⼀起，让通⽤ Agent 在特定任务上获得更稳定的专业⾏为。