AI Agent 的 Skill 系统设计
本文系统阐述了 AI Agent Skill 系统的设计理念与工程实践,核心观点是将 Skill 视为“行为编程”而非文档,旨在通过结构化设计(YAML+Markdown、DOT 流程图、检查表)和严格的约束机制(门控、合理化防御、说服原则)来规范 AI 代理的行为。文章详细探讨了在有限上下文窗口下的 Token 经济策略,包括基于触发条件的发现机制、两阶段加载及声明式引用;提出了单向管道工作流编排、子代理上下文隔离及分级模型选择方案;强调了基于 TDD 理念的 Skill 测试方法,即通过压力场景观测并封堵代理的违规行为;最后总结了跨平台适配策略及从“建议”走向“强制”、从“手动”走向“自动”的演进教训,旨在构建高合规性、低成本且可维护的 AI 代理技能体系。
Skill 的价值是把期望行为转化成 Agent 能稳定执行的工作流。一个好的 Skill 要同时解决四件事:
让 Agent 在正确场景发现它
用最少上下文加载必要信息
按任务风险设置合适的自由度
并通过真实任务验证它是否改变了行为。
本文的重点是如何写好能被 Agent 正确触发、正确执行、可持续维护的 Skill。
先定义目标:Skill 是能力包,不是知识库
Skill 可以被理解为一个自包含的能力包。它通过 SKILL.md、脚本、引用资料和资产,把一个通用 Agent 转化为在特定任务上更可靠的专用 Agent。
Skill 可以被理解为一个自包含的能力包。它通过 SKILL.md、脚本、引用资料和资产,把一个通用 Agent 转化为在特定任务上更可靠的专用 Agent。
它通常提供四类能力:
专用工作流 | 多步骤、可复用的任务流程 | 写技术方案、处理 PR 评论、生成报告 |
工具集成 | 使用特定文件格式、API 或 CLI 的方法 | 处理 PDF、调用 GitHub、操作表格 |
领域知识 | 业务规则、数据口径、组织约定 | 公司指标口径、内部权限边界 |
捆绑资源 | 脚本、模板、参考资料、素材 | scripts/、references/、assets/ |
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/: