Agent Skills 设计模式：从打包到多 Agent 编排的架构决策指南

当一个 Agent Skill 从几十行指令增长到数百行，并开始携带参考文档、脚本、模板和 Sub-agent 时，真正困难的问题不再是“怎样把提示词写得更长”，而是：

哪些内容应该始终进入上下文，哪些内容只在需要时加载？
连贯工作流应该拆成多个 Skill，还是保留一个统一入口？
什么时候单 Agent 已经足够，什么时候才值得引入 Sub-agent？
长时间运行的任务怎样保存进度，并在失败后恢复？

这些问题可以归纳为两个相互正交的架构维度：

打包（Packaging）：Skill 内部怎样组织，以及内容何时进入上下文。
编排（Orchestration）：任务怎样分阶段、拆分、并行和恢复。

生产级 Skill 往往是某种特定的“打包 × 编排”组合。本文给出一套可落地的模式语言和决策框架，帮助 Skill 作者从约束出发选择架构，而不是默认追求复杂设计。

核心原则：采用最简单的可行模式，只有明确约束出现时才升级复杂度。

一、先理解六类底层约束

架构模式不是模板集合，而是对技术约束的不同解法。只有先理解约束，后面的优缺点才具有决策价值。

1. 上下文预算与渐进式披露

Agent Skills 规范采用三层渐进式加载：

元数据层：所有已安装 Skill 的 name 和 description 在启动时进入上下文，用于发现和触发。
指令层：Skill 被触发后，完整的 SKILL.md 正文进入上下文。
资源层：references/、scripts/ 和 assets/ 等资源按需使用。

官方最佳实践建议将 SKILL.md 正文控制在约 500 行以内，并把细节移到直接引用的文件中。这个数字不是硬性解析限制，而是上下文效率和可维护性的经验边界。

因此，打包设计的本质不是“目录怎样摆放”，而是决定：

什么内容，在什么时刻，以什么成本进入模型上下文？

无关指令不只是浪费 Token，还会争夺模型注意力，增加误用规则和遗漏关键约束的概率。

2. 确定性与推理能力

模型推理适应性强，但具有非确定性，并且持续消耗 Token。脚本适合在上下文之外执行确定、可重复的操作，但面对未预期输入时往往更脆弱。

一个实用分工是：

模型负责判断：需求理解、方案选择、例外分析、定性审查。
脚本负责机械工作：解析、转换、验证、批处理、格式归一化。

如果 Agent 每次都在重新生成几乎相同的辅助代码，通常说明这段逻辑应该沉淀为脚本。

3. 上下文共享与隔离

单 Agent 在同一窗口内共享全部状态，不存在交接损失，但随着任务增长可能出现上下文污染、重点稀释和早期错误持续传播。

Sub-agent 则拥有独立、聚焦的上下文，可以选择不同模型和工具，并行处理相互独立的任务。不过隔离也有代价：

Sub-agent 看不到父 Agent 的隐含上下文；
提示必须自包含；
返回父 Agent 的通常是压缩摘要，而不是完整过程；
输入输出契约不清时，关键信息会在交接中丢失。

隔离只有在减少污染或带来并行收益时才有价值。紧耦合任务拆开后，协调成本可能大于上下文收益。

4. 短暂状态与持久状态

对话上下文是短暂状态。上下文压缩、进程中断、工具失败或会话重启，都可能让长流程失去进度。

高延迟或长时间运行的工作流，应把关键状态写入磁盘或外部存储，例如：

workflow_id: skill-build-20260901
current_stage: validation
completed_stages:
  - requirements
  - design
  - implementation
artifacts:
  design: artifacts/design.md
  implementation: artifacts/skill/
checks:
  structure: passed
  trigger_eval: pending
last_error: null

状态文件至少应回答：已经完成什么、产物在哪里、下一步是什么、哪些检查已通过、上次失败在哪里。

5. 触发机制

Skill 的 description 是发现和触发的关键入口。它需要同时说明：

Skill 做什么；
Agent 什么时候使用它。

顶层 Skill 越多，语义重叠和错误路由的风险越高。相比之下，单个 Skill 内部的阶段文件和 references 由已经触发的父 Skill 显式加载，不需要再次参与全局竞争。

6. 维护与复用

每增加一个文件、脚本、Agent、状态 schema 或交接协议，都会扩大：

测试范围；
版本一致性成本；
故障排查范围；
文档和示例的同步成本。

架构拆分是一项持续成本，而不只是首次开发成本。没有独立复用价值的抽象，通常不值得存在。

二、打包模式：内容怎样组织和加载

打包模式描述单个 Skill 的内部结构。它们可以组合使用，并且独立于编排模式。

P1：内联 Skill（Inline Skill）

所有指令都放在 SKILL.md 中，不包含外部资源。

1 2	skill-name/ └── SKILL.md

优点

架构开销最低；
逻辑集中，阅读和调试路径短；
触发后无需再次判断该加载哪些文件。

局限

每次触发都会加载全部正文；
机械步骤仍依赖模型重复推理；
内容增长后容易突破合理的上下文预算。

适用条件

能力范围窄、自包含、流程较短，不依赖大型知识库，也没有需要严格复现的转换逻辑。

反模式

复杂 schema、多领域规范、海量示例或要求严格一致的输出，不适合长期保留在 P1。

P2：Skill + References

保持 SKILL.md 精简，将专业资料按主题放入 references/，由主文件写明加载条件。

skill-name/
├── SKILL.md
└── references/
    ├── api-spec.md
    ├── examples.md
    └── edge-cases.md

优点

大型知识库不会一次性占满上下文；
只为当前任务需要的资料支付 Token；
新增知识时可以增量扩展。

局限

Agent 可能少读而遗漏关键约束；
也可能多读，重新制造上下文膨胀；
分散文件容易出现术语、规则和版本不一致。

设计建议

不要写“读取所有 references”，而应把触发条件直接写进主文件：

1
2
3

- For API parameter questions, read `references/api-spec.md`.
- For validation failures, read `references/error-guide.md`.
- For unusual input formats, read `references/edge-cases.md`.

引用应尽量保持在 SKILL.md 的下一层，避免 SKILL.md → A.md → B.md → C.md 这样的深层链路。较长的参考文件还应提供目录，让 Agent 即使只预览部分内容，也能先看到完整信息结构。

P3：Skill + Scripts

为确定性操作捆绑可执行代码，让 Agent 调用脚本完成机械步骤。

skill-name/
├── SKILL.md
└── scripts/
    ├── transform.py
    └── validate.py

优点

相同输入可以得到可重复输出；
脚本源码无需进入模型上下文；
解析和验证逻辑只实现一次。

局限

依赖运行时和环境配置；
未覆盖的输入可能导致硬失败；
把需要判断的步骤脚本化，会损失模型的适应能力。

适用条件

重复转换、格式验证、批量文件操作、静态检查、可计算规则和输出规范化。

设计边界

脚本应返回可操作的错误，而不是只返回非零退出码：

{
  "valid": false,
  "errors": [
    {
      "path": "frontmatter.description",
      "code": "MISSING_TRIGGER_CONDITION",
      "message": "Description must explain when the skill should be used."
    }
  ]
}

结构化错误能让 Agent 决定怎样修复；模糊错误只会触发新一轮猜测。

P4：Skill + Assets

把模板、样板代码、schema、字体或品牌资源作为静态资产捆绑。

skill-name/
├── SKILL.md
└── assets/
    ├── report-template.docx
    ├── schema.json
    └── brand.css

优点

提高固定格式和品牌输出的保真度；
避免模型反复生成不变的样板；
便于对输出骨架做版本管理。

局限

需求变化后，资产和指令必须同步升级；
强模板可能限制创意任务；
二进制资产不易审查和合并。

适用条件

正式报告、演示文稿、项目脚手架、品牌页面，以及必须符合固定 schema 的交付物。

P5：变体路由器（Variant Router）

入口 Skill 先识别目标变体，再加载互斥分支。

cloud-deploy/
├── SKILL.md
└── references/
    ├── aws.md
    ├── azure.md
    └── gcp.md

优点

一组相关能力只暴露一个入口；
不同变体不会同时污染上下文；
新增后端时可以增量扩展。

局限

选错分支可能造成隐蔽而高成本的失败；
共享逻辑较多时，各分支容易复制粘贴并逐渐漂移。

适用条件

云厂商、语言、框架或部署目标彼此互斥，并且不同分支的实现差异足够大。

如果大部分逻辑共享，仅有少数参数不同，在一个文件中使用条件规则通常更简单。

三、架构粒度：统一 Skill 还是同级 Skill

“Skill 越窄，触发越准确、上下文越小”只对真正解耦的逻辑成立。相互依赖的领域被强行拆开后，常见失败包括：

拆分假设	实际风险
更窄的 description 只会加载正确 Skill	语义重叠可能触发错误的同级 Skill
Skill 间引用可以引导 Agent 跳转	引用通常只是提示，不等于强制激活
粒度越细，Token 一定越低	统一 Skill 配合 P2 也能按需加载
中央入口可保证组件完整	缺少原子安装机制时，部分安装会静默损坏
拆出模块即可跨工作流复用	没有稳定输入输出契约的模块并不真正独立

过度合并同样有风险。把彼此独立的任务塞进一个厚重单体，会让无关规则争夺注意力。

真正的判断单位不是“主题”，而是任务面（task surface）：

如果多个子主题经常共同出现在一次真实执行中，它们属于同一个任务面；如果它们服务不同用户、按不同节奏运行，而且输入输出契约独立，才适合拆成同级 Skill。

例如，一条视频分析流水线可能同时涉及解码、批处理、推理、跟踪、可视化和消息发送。这些虽然是不同技术主题，却共同构成一次端到端任务。按主题拆成六个同级 Skill，会让每次流水线修改都经过多次不可靠的触发和交接。

相反，“导入模型”和“分析流水线性能”可能拥有独立入口、独立产物和不同执行节奏，因此可以拆分。

三种主要结构

厚单体（Thick Monolith）

大量规则和知识直接内联，导航延迟最低，但基础 Token 成本和干扰风险最高。

薄路由器（Thin Router）

SKILL.md 保留承重规则、通用流程和参考索引，细节通过 P2 按需加载。这通常是耦合领域的推荐默认结构。

拆分同级 Skill（Split Siblings）

多个 Skill 独立参与全局触发，只适合真正不重叠的任务面。

薄路由器也不能过度“瘦身”。如果主文件只剩链接目录，Agent 在加载具体资料前就缺少判断依据，会产生上下文饥饿。安全约束、不可违反的规则、主流程和路由逻辑应始终留在 SKILL.md 中。

四、编排模式：任务怎样执行

编排模式与打包方式相互独立。一个分阶段单 Agent 可以使用 references，一个多 Agent 编排器也可以为每个 worker 配置 scripts 和 assets。

“父 Skill + 子 Skill”这个说法并不精确，因为“子 Skill”可能指：

同一 Agent 在共享上下文中加载的阶段指令；
父 Agent 创建的、拥有隔离上下文的 Sub-agent。

前者属于 O2，后者属于 O4，二者成本和行为完全不同。

O1：单 Agent、单次执行

一个 Agent 在连续流程中端到端完成任务。

优点

协调开销最低；
所有信息共享，不存在交接损失；
最容易调试和复现。

局限

长任务会持续膨胀上下文；
无法通过并行缩短等待时间；
中途失败后通常缺少恢复点。

适用条件

流程线性、规模可控，能够稳定放入一个上下文窗口。

O2：分阶段单 Agent

一个 Agent 依次经过明确状态，例如：

1	SETUP -> REQUIREMENTS -> DESIGN -> PLAN -> IMPLEMENT -> VALIDATE -> SUMMARY

每个阶段可以按需加载不同指令，但始终共享一个上下文。

优点

在不引入多 Agent 的前提下提供可预测结构；
后续阶段可以完整看到先前决策；
容易加入阶段检查点和用户确认。

局限

上下文仍会线性增长；
早期错误会传播到后续阶段；
阶段退出条件不清时，Agent 可能跳步或提前合并。

适用条件

多步骤、严格顺序、需要状态连续性的工作流，例如需求访谈到方案交付、代码迁移或报告生产。

许多看起来“复杂”的流程首先应该尝试 O2。只有出现明确的上下文、并行或隔离约束时，才需要升级到 Sub-agent。

O3：交互式或访谈式

O3 是 O2 的专门变体：流程在关键阶段暂停，通过用户回答获取隐性知识或确认高风险决策。

优点

能补齐文档中不存在的目标、偏好和业务约束；
保持人在回路中，降低错误假设带来的返工。

局限

依赖用户响应，不能完全自治；
过多、过散的问题会造成提问疲劳。

设计建议

不要逐条追问所有细节。先读取现有上下文，再把真正影响架构的决策聚合成少量问题，并提供推荐默认值。

O4：编排器 + Sub-agent

父 Agent 将任务拆成多个自包含子任务，交给隔离的 Sub-agent 并行执行，最后汇总结构化结果。

1
2
3

                    ┌-> Worker A - research  -┐
Orchestrator ------├-> Worker B - analysis  -├-> Synthesis
                    └-> Worker C - validation -┘

优点

独立上下文减少相互污染；
可并行任务能够缩短实际等待时间；
可以按角色选择模型、工具和权限；
安全审查、事实核验等角色可以形成独立门禁。

局限

每个任务提示都必须自包含；
父 Agent 接收的是压缩结果，存在信息损失；
并行 worker 可能重复劳动或产生冲突结论；
组件数量增加后，测试和故障定位更困难。

适用条件

子任务确实独立，或者隔离、并行、角色专用模型和独立审查带来的收益明显超过协调成本。

Anthropic 的多 Agent 研究系统采用 orchestrator-worker 模式：主 Agent 规划研究方向，多个 Sub-agent 在独立上下文中并行搜索并返回压缩结果。这个模式很适合广度优先研究，但不能直接推导为“所有复杂任务都应该多 Agent 化”。代码修改、连续迁移和强共享状态流程通常比研究任务更紧耦合。

O5：带恢复能力的门禁流水线

O5 在多阶段流程中加入持久状态、质量门禁、重试和断点恢复。

1 2	Stage A -> Gate A -> Persist -> Stage B -> Gate B -> Persist -> Stage C \-> Retry \-> Resume

优点

进程中断后可从最近验证点继续；
具有可审计的输入、产物和检查记录；
硬性门禁能阻止低质量结果继续传播。

局限

需要明确的状态 schema、幂等策略和迁移方案；
编排器成为关键单点；
重试策略不当可能形成高成本循环。

适用条件

小时级或更长的自治任务、昂贵计算、多阶段数据处理，以及必须保留部分进度的生产流程。

最小可靠性要求

采用 O5 前至少要定义：

每个阶段的输入和输出；
完成条件与失败条件；
状态写入的原子性；
阶段是否幂等；
可重试错误与不可重试错误；
最大重试次数和退出策略；
恢复时需要重新验证的前置条件。

短小、交互式任务不应使用 O5，因为重新运行的成本往往低于维护恢复系统的成本。

五、横切原则：可组合的单一职责能力

单一职责不是第六种编排模式，而是一项可以叠加在各种模式上的设计原则。

格式化、验证、通知和静态检查等通用能力，适合做成具有稳定契约的原子组件。它们可以被不同工作流复用，也更容易单独测试。

但“原子化”不等于把每一步都变成顶层 Skill。一个能力只有满足以下条件时才真正可组合：

输入格式明确；
输出格式稳定；
不依赖调用方的隐含上下文；
失败语义清晰；
可以独立测试；
在多个工作流中确实存在复用需求。

如果多个步骤严格顺序执行并大量共享本地状态，保留为 O2 分阶段单 Agent 通常更简单。

六、打包与编排的组合矩阵

两个维度应独立决策。例如，选择 O2 并不意味着必须使用 P2；选择 O4 也不意味着每个 Sub-agent 都要拥有复杂目录。

场景	推荐组合	原因
简短、自包含的辅助能力	P1 + O1	最低架构成本
知识密集型问答或开发助手	P2 + O1	按需加载专业资料
连续的多阶段交付流程	P2 + O2	保持状态连续并控制每阶段上下文
需要用户补充隐性需求	P2 + O3	先路由资料，再进行聚合式访谈
大量独立研究方向	P2 + O4	独立上下文并行探索
固定格式报告生产	P2 + P3 + P4 + O2	资料、验证脚本和模板共同保证质量
长时自治生产流水线	P2 + P3 + O5	按需知识、确定性执行和可恢复状态
多个互斥目标平台	P5 + O1 或 O2	先路由变体，再执行单次或分阶段流程

这张表只是起点，而不是硬性规定。真正的选择仍取决于任务耦合度、失败成本和运行时能力。

七、可执行的架构决策流程

第一步：确定任务面边界

先列出真实用户任务，而不是文档主题：

Task A: Create a pipeline from source to sink
Task B: Diagnose a pipeline configuration error
Task C: Import a new model
Task D: Profile runtime performance

然后记录任务共同使用的知识、产物和状态。如果多个任务经常共同出现，并共享大量前提，应优先放在统一 Skill 中，通过 P2 路由资料。

只有受众、运行节奏、输入输出和触发语义都明显独立时，才拆成同级 Skill。

第二步：自上而下选择编排

按以下顺序判断：

能否在单个上下文中端到端完成？能则使用 O1。
是否多步骤、顺序执行且要求共享状态？是则使用 O2。
是否缺少只能由用户提供的隐性知识？是则加入 O3。
是否存在真正独立、可并行的子任务，或必须隔离的角色？是则使用 O4。
是否长时自治运行，并且失败后必须保留进度？是则使用 O5。

不要因为“阶段很多”就直接选择 O4。阶段多只说明需要结构，通常首先指向 O2；只有独立性、隔离或并行要求才指向 O4。

第三步：独立选择打包

内容短且总是需要：P1。
大量知识只在部分场景需要：P2。
可重复的机械计算：P3。
固定模板或输出骨架：P4。
互斥后端或技术变体：P5。

第四步：定义升级证据

每次提高复杂度前，记录可观测理由：

SKILL.md 接近合理长度上限；
任务中只有少量内容真正相关；
相同转换逻辑被重复生成；
单 Agent 因上下文污染出现可复现错误；
独立任务可以并行并显著降低延迟；
中途失败造成不可接受的重算成本。

如果无法指出升级解决了哪个可测问题，就应保留更简单的架构。

八、案例一：DeepStream 开发 Skill 的粒度选择

NVIDIA DeepStream 公开仓库中的 deepstream-dev 是 reference-rich Skill，用于辅助编写和完善 pyservicemaker 或 GStreamer DeepStream 流水线。相关生态覆盖推理、跟踪、消息、容器和性能分析等多个方面。

设想将统一开发 Skill 按解码、推理、跟踪、消息等主题拆成多个同级 Skill，表面上可以缩小每个 Skill 的范围，但真实任务很少只触及一个主题：

1	Source -> Mux -> Infer -> Track -> OSD -> Sink

即使只修改一个推理参数，也必须理解批处理、输入尺寸、元数据传播和下游组件的假设。按主题拆分会引入多次触发和交接，而单一入口配合 P2 references 已经可以获得近似的按需加载收益。

更合理的边界是按任务面拆分：

流水线开发与故障排查保持统一；
模型导入作为独立任务面；
性能分析作为独立任务面。

NVIDIA 当前公开的 DeepStream Skills 也体现了类似划分，例如 deepstream-dev、deepstream-import-vision-model 和 deepstream-profile-pipeline 面向不同工作入口。

某些实践材料报告，面向独立任务拆分后可获得约 24% 的准确率提升和约 30% 的 Token 降低。但公开资料不足以证明这是跨模型、跨执行环境的通用基准，因此更适合将它视为特定评测条件下的案例结果，而不是架构定律。

对应原则是：按任务面拆分，而不是按主题拆分。

九、案例二：DEFT 长时流程的单 Agent 与 Sub-agent 取舍

DEFT 类 Agentic 微调和数据增强工作流可能持续数小时，并经过多个子模块。直觉上，把每个模块放到独立 Sub-agent 可以获得干净上下文，但如果运行环境不能可靠传播后台失败，隔离会制造新的问题：

worker 静默失败；
失败原因没有返回编排器；
父 Agent 误判阶段已完成；
恢复时缺少可用状态，只能从头运行。

在这种基础设施条件下，一个工程化良好的单 Agent 可能更可靠：

使用 O2 明确阶段状态；
把进度和产物位置持久化；
上下文压缩或恢复后重新读取状态与核心 Skill；
用 P2 控制每个阶段加载的知识；
在正式运行前执行 preflight；
通过 smoke test 检查编排器与阶段指令是否冲突。

关键判断不是“Sub-agent 是否先进”，而是：

失败能否被可靠检测、传递、记录和恢复？

如果答案是否定的，多 Agent 隔离并不会自动带来可靠性。随着运行时的后台任务监控、目标管理和失败传播能力成熟，O4 或 O5 才可能重新成为更好的选择。

十、常见反模式与修正方法

反模式 1：按文档目录拆 Skill

问题：文档主题不等于用户任务边界。

修正：统计真实任务中哪些知识经常共同出现，按任务面决定边界。

反模式 2：依赖跨 Skill 引用

问题：一个 Skill 提到另一个 Skill，不保证后者会被激活。

修正：强依赖内容放入同一 Skill 的 references，或由显式编排器调用具有稳定契约的组件。

反模式 3：把薄路由器做成空路由器

问题：主文件缺少承重规则，Agent 尚未加载参考资料就已经做出错误判断。

修正：把安全约束、主流程、决策规则和文件索引保留在 SKILL.md。

反模式 4：脚本吞掉判断逻辑

问题：高度变化的输入被强行放入确定性程序，导致脆弱分支快速膨胀。

修正：脚本只处理明确、可测试的机械步骤，把例外判断留给 Agent。

反模式 5：复杂任务默认多 Agent

问题：复杂度不等于可分离性。紧耦合任务会因摘要交接丢失信息。

修正：先使用 O2；只有并行、隔离、角色优化或独立门禁有明确收益时才升级 O4。

反模式 6：持久化了状态，却没有恢复协议

问题：磁盘上虽然有文件，但 Agent 不知道哪个状态可信，也不知道从哪里继续。

修正：为状态增加 schema 版本、阶段完成条件、产物校验、最后错误和明确的 next_action。

十一、怎样评估 Skill 架构

不要只看 Skill 数量或文件大小。至少应测量以下指标：

1. 触发质量

应触发时的召回率；
不应触发时的克制率；
语义相近 Skill 之间的误路由率。

2. 流程遵循

必需步骤完成率；
禁止步骤违反率；
references 的正确加载率；
脚本和资产的正确使用率。

3. 结果质量

任务成功率；
事实和配置准确率；
输出格式合规率；
人工返工次数。

4. 成本与性能

每个成功任务的 Token；
端到端延迟；
Sub-agent 重复劳动比例；
失败后的重算成本。

5. 韧性

可检测失败比例；
可恢复阶段比例；
平均恢复时间；
静默跳步次数。

评价目标应是“每个真实任务成本下的成功率”，而不是“一个 Skill 塞入了多少能力”。

十二、生产落地检查清单

在发布 Skill 前，可以按以下清单审查。

边界

Skill 边界依据真实任务面，而不是文档主题
同级 Skill 的 description 没有明显语义重叠
可复用组件具有明确输入输出契约

打包

SKILL.md 保留主流程和不可违反的规则
可选知识通过 references 按需加载
文件引用直接、清晰，没有深层引用链
机械逻辑由经过测试的脚本处理
模板和 schema 作为版本化资产维护

编排

选择了满足约束的最简单模式
O2 各阶段有明确进入和退出条件
O4 子任务相互独立，提示可以自包含
O5 定义了持久状态、幂等和重试边界

验证

使用正例、负例和相似意图测试触发
测试 references 是否被正确加载
测试脚本异常输入和错误信息
测试阶段失败、超时和恢复路径
记录任务成功率、Token 和延迟，而不是只做主观评审

总结

Agent Skill 架构可以用“打包 × 编排”两个维度清晰描述：

从 P1 + O1 开始，以最低成本验证能力；
内容增长或知识具有条件性时，升级到 P2 References；
把重复、机械、可验证的步骤交给 P3 Scripts；
固定输出骨架使用 P4 Assets；
互斥技术分支使用 P5 Variant Router；
连贯多步骤任务优先使用 O2 分阶段单 Agent；
只有并行、隔离、角色优化或独立门禁有明确收益时才使用 O4；
只有长时自治任务确实需要断点恢复时才承担 O5 的工程成本。

最重要的粒度原则是：按任务面拆分，而不是按主题拆分。 耦合子主题应保留统一入口，并通过 P2 渐进式披露控制上下文；只有真正自治的任务面才值得成为同级 Skill。

每增加一层 reference、script、asset、Sub-agent 或持久状态，都应能回答一个具体问题：它解决了哪个可观测约束？如果没有明确答案，简单架构通常更可靠。

参考资料

本文由 AI 辅助生成，如有错误或建议，欢迎指出。