如何组织和管理多个 Skill？

核心回答

多个 Skill 应按任务职责、发现与加载、版本依赖、组合执行和效果反馈来管理，不能只把文件放进同一个目录。

1. 职责清楚：每个 Skill 对应一类可复用任务，写明适用条件、输入输出和资源；重叠能力要合并或划清边界。
2. 可发现、按需加载：维护名称、描述和位置组成的目录，让当前 Agent 只看到适用的能力；命中后读取正文，资源按需使用，避免全量塞进上下文。
3. 版本成套管理：说明、脚本和模板一起版本化，记录维护人、依赖和变更；同名覆盖规则明确，更新后确认宿主实际使用了新版本。
4. 组合有衔接：多个 Skill 协作时约定中间结果和依赖关系，明确失败后继续、停止还是换方案。
5. 分别检查选择和执行：既测试该不该触发、会不会选错，也检查最后的产物是否符合要求，根据失败记录调整描述或步骤。

少量 Skill 用目录和 Git 就能管理；数量、团队和分发范围扩大后，再考虑搜索目录、发布服务等能力。

展开说明

1. 按完整任务划分，而不是每个小动作建一个 Skill

例如“审查代码变更”和“生成周报”可以各自成一个 Skill；读文件、查接口等动作通常由 Tool 提供。Skill 正文组织完成任务的方法，必要时引用脚本、样例和模板。

名称应能稳定识别任务，描述应说明对象、动作和触发条件。如果同时有“文档审查”和“代码审查”，就要说明它们分别审什么，避免都写成“帮助提高质量”。共享的字段规范或模板可放在公共资源中引用，减少多份副本各自修改。

每份 Skill 都有明确维护归属；某个 Skill 长期不再适用时，应从可用目录中移除或标记停用，避免模型继续选到旧方法。

2. 文件目录、可用目录和已经加载的正文是三个层次

文件存在，表示能力包已经存放；宿主发现并提供名称、描述等信息后，模型才知道它可用；激活后，完整指令才进入当前上下文。具体实现可以是模型读取文件，也可以是宿主提供专用加载工具，不能假定所有平台都调用同一个 load_skill()。

自建宿主时，可以维护名称到实际资源位置的映射。模型选择的名称应在当前可用集合中，资源引用相对于对应 Skill 的基目录解析。同名能力来自项目、个人或组织目录时，要有确定的覆盖顺序，并能查到最终生效位置，不能依赖偶然的扫描顺序。

例如当前 DeepAgents SDK 只加载显式配置的 Skill 来源，同名时后面的来源覆盖前面的来源；其他宿主应按自己的发现和优先级规则处理。按角色或业务范围提供不同目录，也能减少无关选项。目录筛选控制可见性，实际工具访问仍由运行时授权。

完整的发现、激活和执行过程可结合Agent 调用 Skill 的流程理解，这里重点是让多份能力长期可维护。

3. 更新的不只是 SKILL.md，还包括它依赖的资源

一个“报告生成”Skill 可能同时依赖字段说明、图表脚本和输出模板。只更新正文却继续运行旧脚本，仍会产生不兼容。可以把它们作为同一发布单元，用 Git 提交、发布标签或内容哈希标识，并记录依赖环境和变更内容；这些属于管理设计，不必都塞进标准 frontmatter。

重要任务宜固定本次使用的能力版本及资源位置，便于复查和重跑。更新可以先用于新任务；需要让长任务采用新规则时，应同时处理目录元数据、缓存和已经进入上下文的旧说明，避免新旧指令混用。不能根据磁盘文件改了，就断言运行中的 Agent 已经切换。

运行记录可关联任务、选中的 Skill、版本、实际工具和产物。重复激活时也要避免把同一份指令反复注入。这里维护的是任务说明和资源的版本，不应把每次执行产生的日志、用户数据和中间文件写回共享 Skill 包。

4. 多 Skill 组合，要明确交付物和失败含义

以“分析报表并导出报告”为设计示例，可以由数据分析 Skill 产出结论、证据和图表文件，再由报告 Skill 生成文档。两者需要约定字段含义、单位、文件位置和必要条件；关键中间数据可以用 Schema 校验，格式不同则明确转换。

报告依赖分析结果，应在分析完成后进行。若没有取得数据，报告 Skill 可以输出“数据缺失”的说明或停止生成，但不能把缺失当成零值继续下结论。执行脚本超时后是否可重试，则取决于真实操作及其幂等设计，不是因为包装成 Skill 就自然安全。

如果任务必须按固定顺序完成，显式 Workflow 可以负责依赖、状态和重试，Skill 负责各阶段的方法。没有必要为了管理多个 Skill，再让每个 Skill 都自带一套调度器。

5. 用具体失败定位该改哪里

准备明确要求使用、隐含需求、相近但不该触发三类输入，检查选择是否正确；再检查实际工具和最终产物。例如“解释这段代码”不一定应该启动完整代码审查，而“检查这个 diff 的边界问题”应能匹配审查能力。

选错通常先检查可用目录、描述和职责重叠；选对但结果差，则检查正文步骤、资源版本、工具结果和输出要求。这样的记录比只统计“加载了多少 Skill”更能指导维护。

常见追问

Skill 很多时，能不能再做一层检索？

可以先按业务范围过滤，再检索候选描述或通过分类缩小目录。但候选漏掉后模型就无从选择，所以要同时检查目录召回和最终激活结果，并保留用户明确指定 Skill 的入口。数量不多、描述足够清楚时，直接提供精简目录更简单。

文件已经更新，为什么 Agent 仍按旧说明执行？

先查实际命中的路径和覆盖顺序，再看目录元数据、正文是否已在当前会话中缓存。不同宿主刷新方式不同；例如当前 DeepAgents 在配置 checkpointer 时会沿用线程中的 Skill 元数据，新版本提供刷新机制。长期运行的任务还可能保留旧正文，因此刷新目录与更新已加载指令需要分别处理。

两个 Skill 的指令冲突怎么办？

优先减少职责重叠，在描述和正文中明确适用范围及交付关系。任务确实同时需要二者时，明确当前任务采用哪份输出规则；影响执行顺序或业务结果的冲突应由宿主编排或用户需求解决，不能靠最后读到的那段文字碰运气。

对应教程

参考资料