Agent Skills：能力如何封装、发现与按需加载

每次让 Agent 写技术文章，都在 Prompt 里重复一遍写作标准、资料来源、图片风格、审计命令和提交步骤，当然也能工作。问题是规则会散落在对话里：这一篇记得查官方资料，下一篇忘了；正文写完了，构建和页面验收没有做；换一个项目后，同一套要求还要重新解释。

Skill 解决的是这类重复行为的封装。它用一份可发现的元数据、一组执行指令和按需读取的资源，把“遇到某类任务时应该怎样做”放进 Agent 可以加载的能力包。模型仍负责理解当前任务，工具仍负责读写文件和访问外部系统，Skill 则规定怎样组织这些能力，以及怎样证明任务完成。

本文回答一个工程问题：怎样设计一套能被正确发现、只占用必要 Context、可以约束执行并能用真实任务验证的 Agent Skill 系统？

事实层主要来自 OpenAI 的 Build skills 文档、Agent Skills 规范，以及苏雄的《AI Agent 的 Skill 系统设计》。我还会使用这个博客真实采用的技术写作 Skill 作为贯穿案例。OpenAI 与 Agent Skills 规范描述的是当前公开格式和产品行为；文中的门控、评测与团队治理属于基于实际使用总结出的工程方法。

先看结论

Skill 是一份可加载的行为模块。最小形态是一座目录，其中 SKILL.md 用 YAML frontmatter 描述名称与触发范围，用 Markdown 正文规定执行方法。复杂 Skill 还可以附带脚本、参考资料、模板与产品元数据。

Skill 不执行真实动作。搜索代码、修改文件、调用 API 和生成图片仍由工具完成；权限、沙箱与审批仍属于 Harness。Skill 的工作是告诉 Agent 何时选哪些工具、按什么顺序使用、哪些条件没有满足就不能继续，以及用什么证据验收。

Skill 系统的核心约束来自 Context 预算。运行时先保留所有 Skill 的精简元数据，命中任务后才读取完整 SKILL.md，更细的参考文件继续按需加载。发现、指令和资源分成三层，才能让技能库增长而不把每轮模型输入塞满。

好 Skill 不能只靠作者读起来觉得合理。触发准确率、规则遵循率、工具轨迹、产物 diff、构建结果和失败恢复都可以测试。压力场景尤其重要，因为 Agent 最容易在时间紧、上下文长或工具报错时跳过验证。

上图给出本文的坐标：Skill 目录先参与路由，完整正文随后进入 Context，执行阶段再调用工具和资源，最后用外部证据验收。任何一层失败，都应该回到自己的责任边界处理。

一、Skill 处在 Agent 系统的哪一层

讨论 Skill 时，Prompt、工具、Workflow、知识库和 Memory 很容易混在一起。它们会在同一个任务中协作，但解决的问题不同。

概念	主要内容	何时进入运行过程	谁负责真实效果
Prompt	当前任务的目标、输入和约束	本轮调用前	模型与 Harness
Skill	某类任务可复用的行为规则与资源	匹配任务后加载	Agent 按规则编排工具，Harness 执行
Tool	可调用的外部能力	Agent 产生动作请求时	工具实现与执行环境
Workflow	预先确定的节点、分支和状态迁移	流程启动时	Workflow 引擎
Knowledge / RAG	可检索的事实、文档和业务资料	查询命中后	检索系统与数据源
Memory	跨步骤或跨会话保留的状态	写入和召回策略触发时	独立的记忆系统

一份 pdf-processing Skill 可以规定先检查文件、再选择提取或合并脚本、最后渲染页面验收。真正读取 PDF 的是脚本或 PDF 工具。Skill 里可以引用格式规范，却没有必要变成一座 PDF 知识库。它也可能读取用户偏好，但怎样保存和召回偏好属于 Memory 文章的范围，本文不展开。

Skill 与普通系统提示词的差别

两者最终都可能成为模型输入，差别在生命周期和组织方式。系统提示词通常每轮常驻，适合所有任务都必须遵守的身份、安全规则与交互约定。Skill 只在相关任务中展开，适合 PDF 处理、技术写作、故障排查等局部工作流。

如果一条规则无论做什么都必须生效，它更适合系统层或程序策略。比如“外部发送消息前必须获得批准”，不能因为消息 Skill 没有触发就失效。反过来，把几十种文件格式的详细处理步骤塞进全局提示，会挤占 Context，也会让无关任务受到干扰。

Skill 让长指令获得了地址和边界。运行时知道它叫什么、何时加载、资源在哪里；维护者能给它版本、测试和所有者。单次对话里的长 Prompt 往往缺少这些工程属性。

Skill 与工具的差别

工具提供动作，Skill 提供使用动作的方法。git_diff 可以返回代码差异，技术写作 Skill 会规定修改文章后运行 git diff --check；浏览器可以打开本地页面，Skill 会规定检查标题、两侧目录、代码溢出和图片；apply_patch 可以改文件，Skill 则要求保留用户已有修改。

这个边界也解释了为什么 Skill 不能承担权限控制。Markdown 里写“禁止删除生产数据”只是一条模型指令。真正的禁止需要 Policy、凭据范围和执行环境拒绝相关调用。Skill 可以要求 Agent 先检查权限或请求确认，却不能把文字约束冒充系统边界。

二、运行时怎样发现并加载 Skill

一座技能库通常包含很多能力，而当前任务只需要其中少数。把所有 SKILL.md 全量塞给模型，会让无关规则争夺注意力。公开规范采用渐进披露，把加载过程拆成元数据、完整指令和资源三层。

OpenAI 文档说明，ChatGPT 和 Codex 启动时先看到 Skill 的名称与描述；决定使用后才读取完整 SKILL.md。Codex 的初始 Skill 列表还包含文件路径，并把列表限制在上下文窗口的 2%，无法得知窗口大小时上限为 8,000 个字符。技能过多时，系统会先缩短描述，也可能省略部分 Skill 并给出警告。

这带来一个直接结论：description 是路由索引，正文才是执行程序。把触发条件只写在正文里，运行时在决定是否读取正文时看不到它；把完整步骤写进描述，Agent 又可能只凭摘要开始工作。

显式调用与隐式匹配

OpenAI 文档列出两种入口。用户可以显式点名 Skill，例如在 Codex 中用 $skill-name；运行时也可以根据请求与 description 的匹配结果隐式选择。

显式调用适合用户知道准确能力、希望复现固定流程或正在调试 Skill。隐式匹配降低了使用门槛，但会出现两类路由错误：应该触发却没有触发，以及无关任务误触发。

一条可用的描述至少回答三个问题：Skill 做什么，哪些任务或输入应该触发，哪些相邻任务不属于它。描述要把最重要的触发词放在前面，因为长技能列表可能截断后部内容。

---
name: king-of-water-tech-writing
description: >
  Research, write, expand, or review long-form Chinese technical articles for
  the king-of-water Astro blog. Use for substantial posts in Agent, AI Coding,
  RAG, backend engineering, or project analysis; not for short status updates
  or minor typo fixes.
---

这段描述同时给出动作、内容领域和排除项。用户说“写一篇 Agent Skills 长文”时应命中；只让 Agent 改一个错别字时不该加载整套研究、配图与页面验收流程。

路由质量需要单独评测

执行成功率无法替代路由评测。一个优秀 Skill 如果从未被发现，对用户仍然没有价值；一个频繁误触发的 Skill 则会增加 Token 成本，还可能把不相关的硬门控带入任务。

可以准备三组请求测试描述：明确正例、容易混淆的边界例、明确反例。技术写作 Skill 的正例是“写一篇 Transformer 原理长文”，边界例是“评审这篇已有文章的论证”，反例是“告诉我构建是否通过”。每次修改 name 或 description 后重放这组样本，记录召回率、误触发率和用户显式纠正次数。

三、一个 Skill 包里应该放什么

Agent Skills 规范要求目录至少包含 SKILL.md，其中 frontmatter 必须有 name 与 description。scripts/、references/ 和 assets/ 是约定的可选目录。OpenAI 还支持 agents/openai.yaml，用于界面展示、隐式调用策略和工具依赖等产品元数据。

agent-skill/
├── SKILL.md              # 发现元数据与核心工作流
├── scripts/              # 可执行、可重复验证的确定性操作
├── references/           # 任务需要时再读取的规范与领域资料
├── assets/               # 模板、图片、样例工程等输出材料
└── agents/
    └── openai.yaml       # 可选的界面、策略与依赖信息

目录设计的判断标准不是文件类型，而是内容在运行时怎样被使用。核心步骤每次执行都需要，放在 SKILL.md；只对部分分支有用的长资料，放进 references/；需要确定性或会被反复生成的逻辑，放进 scripts/；产物要复制或修改的模板，放进 assets/。

SKILL.md 只保留共同主干

正文加载后会整体进入 Context。Agent Skills 规范建议完整指令少于 5,000 Token，并建议主文件控制在 500 行以内。数字不是质量线，但能提醒作者：一份覆盖十种互不相关任务的 Skill 很可能应该拆分。

主文件适合保存任务边界、输入输出、共同步骤、分支入口、禁止事项、验证条件和需要读取的资源索引。每个章节都应推动 Agent 做决定或行动。产品背景、团队历史和读完也不会改变执行的解释可以删掉。

文件引用应从 Skill 根目录使用相对路径，并尽量保持一层可达。SKILL.md 指向 references/article-standard.md 很清楚；再让后者指向另一座目录的第三个文件，会让加载路径难以观察，也提高缺失引用的概率。

脚本承接确定性

脚本适合两类任务。一类是机械操作，例如初始化目录、解析固定格式、旋转 PDF 和检查 frontmatter；另一类是结果需要稳定复现的验证，例如文章字数审计、链接检查和 Schema 校验。

脚本不会天然变得安全。它仍需要清楚的输入、依赖、退出码和错误信息，并受工作区、网络与权限策略约束。一个 Skill 附带 deploy.sh，不等于 Agent 获得部署权限。工具系统会按真实动作重新判断。

当任务需要开放判断时，硬塞脚本反而会损失能力。文章论证、故障归因和架构选择通常需要模型根据当前证据判断，Skill 可以给出检查框架和反例，不必把所有分支写成条件语句。

Reference 与 Asset 不要互相代替

Reference 是给 Agent 阅读的资料，例如文章标准、数据库 Schema、业务口径和 API 说明。Asset 是制作结果时使用的材料，例如文档模板、字体、图标和示例项目。Agent 可能只需要知道一个模板的路径，并不需要把整个二进制文件放进 Context。

同一条事实只保留一个权威位置。SKILL.md 与 Reference 各复制一份规范，几次修改后就会产生冲突。主文件写“什么时候读”，Reference 保存完整内容，能让维护责任更清楚。

四、把说明写成可执行的行为路径

人类文档经常解释原则，然后依赖读者自行补全操作。Agent 更需要明确的进入条件、动作顺序、分支和完成证据。Skill 的写法接近 Runbook 与程序之间的中间层：仍用自然语言表达，但每一步都能观察。

从真实请求反推工作流

先收集具体请求，再抽象 Skill。创建 PDF Skill 时，至少要看到“合并两份 PDF”“旋转第 8 页”“填写表单并保留可编辑字段”这类输入。它们会暴露不同工具、风险和验收方式。只从“处理 PDF”四个字出发，最后往往得到一份宽泛说明。

对每个样本从零执行一次，记录 Agent 需要的输入、正确工具、容易出错的步骤、产生的副作用、最终产物和验收证据。重复出现的判断进入主流程，确定性动作沉淀为脚本，偶尔需要的领域资料进入 Reference。

这一过程还会暴露拆分边界。若两组任务只有名称相似，却没有共同的输入、工具和验收方法，就不该留在一个 Skill 中。当前清单把 Skills 与 Memory 拆成两篇文章，也是同样的判断：能力加载和跨会话状态有不同的生命周期与故障模型。

自由度取决于任务的脆弱程度

写技术文章允许多种合理结构，Skill 应规定证据标准、必须覆盖的问题和验收步骤，保留表达空间。读取公司指标需要更严格的字段口径与查询模板。文件格式转换若已有稳定脚本，最合适的路径通常是调用脚本，而非让模型每次生成一段新代码。

可以把约束放在四个位置：原则给模型判断空间；模板固定输入输出形状；脚本固定算法；程序策略直接允许或拒绝动作。风险越高、判断越容易被程序确定，约束越应该向后两者移动。

硬门控要能被检查

“建议先运行测试”很容易在 Context 变长后退化为可选项。若测试是交付条件，Skill 应写成可检查的门控：没有测试结果，不得声称完成；测试无法运行时，必须报告具体阻塞和未验证范围。

<HARD-GATE>
提交前必须完成文章审计、站点构建和页面视觉检查。
任一检查失败时，不得提交；先修复失败，或明确请求用户决定是否接受未验证状态。
</HARD-GATE>

这仍是模型层约束，不能替代 CI 的分支保护。最稳妥的组合是 Skill 规定工作流，脚本产生机器可读结果，CI 或 Harness 阻止缺少证据的提交。

五、Skill 怎样与工具、MCP、Hook 和 Subagent 协作

上一章的工具系统文章把 Function Calling、CLI、浏览器、代码执行和 MCP 放进统一执行路径。Skill 位于这些工具之上，负责为某类任务选择路径。

技术写作 Skill 可以要求使用搜索查找官方资料，使用文件工具创建 Markdown，使用视觉工具制作架构图，使用 CLI 运行审计和构建，最后使用浏览器做页面验收。它没有重新实现任何工具，只规定组合方式和证据标准。

MCP Server 可以向 Agent 暴露 GitHub、Docs 或数据库能力，Skill 则描述什么任务需要这些能力，以及调用前后要检查什么。Server 返回的 Tool Annotation 依旧不能成为可信权限结论；Skill 引用某个 MCP 工具，也不能绕过 Host 的授权和审批。

Hook 适合处理不依赖模型判断的横切规则，例如每次文件修改后记录审计、提交前强制格式检查。把所有规则都写进 Skill，会让同一安全要求在多份文件中复制；把所有流程都写进 Hook，又会失去任务语义。通常由 Skill 说明任务路径，Hook 与 Policy 固化跨任务底线。

Subagent 适合隔离长调查和独立验证。Skill 可以定义何时拆分任务、子代理获得哪些材料、结果以什么格式回传。主 Agent 仍要核对证据并整合结果，不能因为“由子代理完成”就跳过验收。

六、用我们正在使用的写作 Skill 走一遍

这篇文章本身提供了一条真实轨迹。用户先提出写 Skill，并补充“可以借助我们经常使用的 Skill 工具来讲”。当前仓库的说明要求：只要新写或大改技术文章，就必须使用 king-of-water-tech-writing。

第一步：发现

运行时最初只需要知道写作 Skill 的名称、描述和路径。用户请求包含“Skill”“文章”和当前博客上下文，匹配到它的适用范围。若请求只是“Skill 是什么，用两句话回答”，则不需要启动长文流程。

同时，任务涉及 Codex 自身的 Skills 行为，因此匹配到 openai-docs。它要求先查找并读取官方文档，避免用过时记忆描述产品。文章还需要图示和最终语言清理，后续分别加载 documd-visuals 与 humanizer。

第二步：读取主指令和必要 Reference

技术写作 Skill 的正文规定先提出研究问题、优先使用一手资料、选择合适文章级别，并要求完成审计、构建和页面检查。只有在规划长文时，才继续读取 references/article-standard.md；没有必要加载它目录下所有资料。

视觉 Skill 也采用相同做法。主文件先按“系统架构、流程、对比”等目标路由，再读取对应 Goal 和一套 Editorial 配色。文章不需要图表分析，所以没有加载折线图、财务报告或地图相关说明。

第三步：执行工具并保留边界

官方资料通过文档页面读取，用户提供的微信正文作为第二来源。文件修改交给补丁工具，SVG 放进站点既有图片目录，审计和构建交给 CLI。每一种工具仍遵守自己的权限与输入规则。

这里能看到 Skill 与 Context Engineering 的关系。Skill 决定哪些资料值得进入当前任务，Context Engineering 还要负责实际内容的取舍、压缩和排序。载入一份 Skill 不代表其中所有资源永久驻留；完成某个分支后，中间输出仍可能被摘要或移出窗口。

第四步：验证

正文完成不等于任务完成。写作 Skill 要求运行文章审计、校验 SVG、执行 Astro 构建、检查 diff，并打开页面查看标题、目录、代码块和图片。最后的提交记录提供可追踪版本。

这条轨迹可以复现，也可以审计：为什么加载某个 Skill，读了哪些 Reference，调用过哪些工具，哪些证据支持“已完成”。如果文章失败，排查也能分层进行：路由没命中、指令含糊、资源缺失、工具失败或验收不足，各自有不同修复位置。

七、验证 Skill 是否真的改变了行为

格式校验只能证明文件可被读取。Agent Skills 规范提供 skills-ref validate ./my-skill 检查 frontmatter 与命名约束；产品或项目还可以使用自己的验证脚本。真正困难的是验证 Agent 在任务压力下是否按 Skill 行动。

测试分成四层

层次	要回答的问题	证据
结构	Skill 能否被加载，引用与脚本是否存在	validator、文件检查、脚本退出码
路由	正确任务是否触发，边界任务是否误触发	正反例 Prompt 集、触发日志
行为	Agent 是否执行关键步骤并遵守门控	工具轨迹、检查表、产物 diff
结果	最终任务是否成功，成本是否可接受	测试、构建、人工评分、Token 与耗时

这四层不能互相替代。Skill 能被加载，不代表描述足以路由；路由正确，不代表正文能阻止 Agent 跳步；轨迹合规，也可能产出一篇事实错误的文章。

前向测试不要泄露答案

给测试 Agent 一份真实用户请求、原始输入和可用工具，让它从任务开始执行。不要先告诉它“这个 Skill 会漏掉构建，请检查第六步”，否则测试测到的是提示后的服从性。

一组有区分度的用例应包含正常任务、边界任务和压力任务。压力可以是官方页面打不开、脚本返回非零、Context 已经很长、用户要求立刻提交，或者任务中途补充新约束。观察 Agent 是否报告证据不足，还是为跳过规则找出一段听起来合理的解释。

失败要写成回归用例

某次 Agent 在图片没有渲染时仍提交文章，修复不应止于给 Skill 增加一句“注意检查图片”。保留失败输入和轨迹，把验收规则改成可观察条件，再重放同一用例。若能用脚本识别空 SVG 或坏链接，就把判断移到脚本或 CI。

长期指标可以包括 Skill 触发准确率、关键步骤完成率、首次验收通过率、用户接管次数、每个成功任务的 Token、Reference 实际读取率，以及版本升级后的旧任务回归率。指标用于定位改动方向，不该被压成一个脱离任务难度的总分。

八、组合 Skill 时避免上下文失控

真实任务经常同时命中多个 Skill。本文用到了技术写作、OpenAI 官方资料、视觉表达和语言清理。简单地把四份全文一次性加载，会破坏渐进披露。

组合关系可以分为三种：必需依赖、条件依赖和推荐协作。必需依赖会阻塞当前流程，例如写 OpenAI 产品事实必须先读取官方资料；条件依赖只在文章需要架构图时加载；推荐协作用于提高质量，即使缺失也能降级完成。

Skill 之间应引用稳定名称或由运行时解析能力，避免把另一个 Skill 的绝对安装路径写死。不同客户端的目录、工具名和调用方式会变化，行为契约比平台私有名称更适合作为组合接口。

还要防止循环依赖。A 要求先用 B，B 又要求先用 A，Agent 会重复加载或无法确定入口。运行时可以记录当前调用栈和已激活集合，检测循环；设计层则应抽出两者共同依赖的基础 Skill，或者把一方降为可选 Reference。

缺少依赖时怎样降级

降级策略应写在会遇到缺口的节点上。没有视觉工具时，文章可以保留文字与表格，并明确缺少图示；缺少 PDF 渲染器时，不应声称版式已验收；官方资料无法访问时，可以停止涉及当前产品行为的断言，或请求用户提供正文。

“继续完成”与“假装验证过”是两件事。Skill 应说明哪些能力缺失仍可交付，哪些会让任务失去完成条件。

九、版本、作用域与分发

Skill 会像代码一样演化。触发描述、步骤顺序、脚本参数和验收条件都会改变既有行为，因此需要版本、变更记录和回归集。一次看似轻微的描述扩展，可能让它开始抢占相邻任务。

OpenAI 文档列出了 Codex 的多个本地作用域：仓库目录及其父级的 .agents/skills、用户级目录、管理员位置和系统内置 Skill。仓库 Skill 适合与代码共同版本化的工作流，用户 Skill 适合个人偏好与跨项目方法，管理员 Skill 适合组织统一能力，系统 Skill 提供通用基础功能。

作用域不是简单的覆盖链。OpenAI 文档指出，同名 Skill 不会合并，两份都可能出现在选择器里。团队应使用清楚的名称和所有权，避免用户不知道哪一份正在生效。

本地目录适合开发与项目协作。需要跨团队安装、组合多个 Skill 或同时分发连接器时，OpenAI 建议使用 Plugin。agents/openai.yaml 还可以声明界面名称、图标、默认提示、是否允许隐式调用，以及 MCP 等工具依赖。这里的依赖声明用于发现和安装体验，真实权限仍由 Host 决定。

发布前至少记录以下内容：所有者、适用客户端、运行依赖、外部网络需求、可能产生的副作用、验证命令、已覆盖用例和最近一次回归时间。脚本与模板也要检查许可证和敏感数据，不能因为藏在 Skill 包里就绕过供应链审查。

十、哪些情况不值得创建 Skill

一次性任务通常不需要 Skill。请求不会重复、步骤很短、没有专用资源时，直接 Prompt 成本更低。把每个偏好都建成独立目录，会让路由列表膨胀，也增加命名冲突。

稳定、确定、无需模型判断的流程更适合普通程序或 Workflow。每天固定导出一张报表，如果输入输出和步骤都已确定，用定时任务调用脚本更可靠；Skill 只在需要 Agent 理解临时要求、选择分支或解释异常时有价值。

安全策略也不应只存在于 Skill。数据删除、付款、生产部署和权限变更需要程序化授权与审批。Skill 可以组织确认界面前的准备工作，却不能成为唯一防线。

最后，纯知识集合不一定需要 Skill。大量产品文档更适合知识库与检索系统；只有当这些资料伴随清楚的任务入口、操作方法和验收条件时，才值得包装成能力包。

十一、从零设计一个 Skill 的实用流程

第一步收集五到十个真实请求，其中要有不应该触发的相邻任务。为每个请求写清初始输入、期望产物、可用工具、风险和完成证据。

第二步抽出共同主干，判断哪些环节需要模型判断，哪些可以交给模板、脚本或 Policy。此时先画流程，不急着写长说明。

第三步编写最小 frontmatter 和核心正文。描述负责发现，正文保留输入输出、步骤、门控、资源入口和验收。详细资料按需移到 Reference。

第四步补齐可复用资源。重复生成的确定性代码进入 scripts/，任务中查询的规则进入 references/，产物材料进入 assets/。删除重复内容和无用示例。

第五步运行结构验证和脚本测试，再用原始用户请求做前向测试。保存触发结果、工具轨迹、产物和失败证据。

第六步上线到最小作用域。先放在单个仓库或少量用户中，观察误触发、跳步和 Context 成本；问题稳定后再扩大分发。每个真实失败都进入回归集。

十二、交付检查表

检查面	需要回答的问题
目标	这份 Skill 是否只负责一类有共同工作流的任务？
发现	name 和 description 能否覆盖正例、边界例与反例？
Context	哪些内容常驻元数据，哪些激活后读取，哪些继续按需加载？
流程	每一步是否有明确输入、动作、分支和输出？
自由度	原则、模板、脚本与程序策略是否放在合适层级？
工具	Skill 是否只编排能力，没有冒充执行与权限边界？
资源	Script、Reference 与 Asset 是否各司其职且没有重复事实？
门控	关键条件未满足时，Agent 是否知道必须停止或请求判断？
失败	依赖缺失、工具错误、取消和部分完成怎样报告？
测试	是否有路由集、前向任务、压力场景和历史回归？
治理	谁维护、怎样版本化、在哪个作用域分发？
验收	能否用外部证据证明行为和结果都达标？

结语

Skill 把一类任务的触发、执行方法、资源入口和验收标准放进同一个可加载单元。它让通用 Agent 在遇到特定任务时获得程序性知识，同时保留模型处理开放问题的空间。

这套机制能否长期工作，取决于几个朴素条件：描述能正确路由，正文只保留共同主干，详细资源按需读取，确定性步骤交给脚本，风险动作继续接受 Harness 控制，所有规则用真实任务验证。满足这些条件后，Skill 才从一份 Markdown 说明变成可维护的行为系统。

参考资料

• OpenAI：Build skills
• Agent Skills：Specification
• 苏雄：AI Agent 的 Skill 系统设计
• OpenAI：Plugins