AI Agent Skill 拆分：从大文档到按需加载

• 概述
• 一、为什么 Skill 要按需加载
• 二、入口文件大小，就是按需加载的边界
• 三、Skill 的按需加载分层模型
• 四、具体怎么拆
  • 1. 工具参数交给 --help
  • 2. 重参考内容放进 references/
  • 3. 机械操作放进 scripts/
  • 4. 重复流程用交叉引用
  • 5. 示例只保留最小模式
• 五、怎么验证拆得是否合理
• 总结

概述

AI Agent 的 Skill 不是普通文档，而是一段会被模型加载、理解并执行的操作说明。

普通文档可以写得完整，方便人慢慢查；但 Skill 不一样。Skill 一旦进入上下文，就会消耗 token，也会影响模型对当前任务的判断。写得越长，不一定越可靠，反而可能让关键规则被长篇背景、参数说明和示例淹没。

所以 Skill 拆分的核心，不是简单地把一个大文件拆成多个小文件，而是把一个“大而全的提示词文档”，改造成一个按需加载的知识系统。

SKILL.md 是入口文件，只保留触发条件、核心流程、关键约束和跳转路径。真正重的内容，比如 API 参数、复杂示例、排错手册、协议细节、模板和脚本，都应该在需要时再读取或调用。

一句话概括：

SKILL.md 负责让 Agent 快速做对第一步，其他内容按需加载。

一、为什么 Skill 要按需加载

很多 Skill 越写越大，是因为作者希望把所有情况都提前说明清楚：

• 工具有哪些参数
• API 字段是什么意思
• 每种异常怎么处理
• 不同场景下怎么调用
• 最佳实践是什么
• 完整示例怎么写

这些内容本身可能都有价值，但不一定应该放进 SKILL.md。

因为 Agent 执行任务时，通常先需要的是一个清晰入口：

• 什么时候用这个 Skill？
• 当前任务应该按什么流程走？
• 哪些事情不能做？
• 遇到复杂情况时应该读哪个文件？
• 哪些操作应该交给脚本？

也就是说，SKILL.md 的职责不是提供全部知识，而是组织一次任务的加载顺序。

好的 Skill 应该像程序入口：

先读入口
再判断任务类型
需要细节时读取 references
需要稳定执行时调用 scripts
需要工具参数时查看 --help

这就是按需加载。

二、入口文件大小，就是按需加载的边界

控制 SKILL.md 大小，不是为了形式上的“短”，而是为了让入口文件只承担入口职责。

可以用下面这个规模作为参考：

这些数字不是绝对标准，而是报警线。

如果一个 SKILL.md 超过 500 词，就应该检查它是不是开始承担太多职责了。

常见信号包括：

• 里面列了完整参数表
• 有多个长示例
• 排错流程占了大段篇幅
• API 字段解释超过核心流程本身
• 同一段流程在多个 Skill 中重复出现
• 模型执行时经常漏掉关键约束
• 修改一个工具参数，需要同步改多处文档

这些问题看起来不同，本质上是一回事：没有按需加载，所有内容都挤在入口文件里了。

入口文件变小以后，收益也很直接：

• Token 更省：高频 Skill 每次少加载几百到几千 token。
• 响应更快：模型要读的入口内容更少。
• 匹配更准：description 和正文更聚焦。
• 执行更稳：关键流程和硬约束不容易被淹没。
• 维护更简单：参数、示例、脚本、流程各改各的地方。

所以，入口文件大小控制、拆分判断、收益评估，本质上都服务于同一个目标：

让 Agent 先加载最少但最关键的信息，再根据任务继续加载细节。

三、Skill 的按需加载分层模型

可以把一个 Skill 拆成四层：

SKILL.md 主要承载前两层：触发层和决策层。

它应该写：

• 触发条件
• 任务目标
• 标准流程
• 禁止事项
• 分支判断
• 什么时候读取参考文件
• 什么时候运行脚本

它不应该写：

• 完整 CLI 参数
• 大量 API 字段
• 多个完整案例
• 长篇背景解释
• 少见异常的详细排查
• 已经存在于其他 Skill 的公共流程

判断一段内容是否该放进 SKILL.md，可以问一句：

Agent 在任务开始后的前 10 秒必须知道它吗？

如果必须，就放入口文件。

如果不是，就拆出去，按需加载。

四、具体怎么拆

1. 工具参数交给 --help

不要在 SKILL.md 里详细列出 CLI 的所有参数。

不推荐：

search-conversations 支持 --text、--both、--after DATE、--before DATE、--limit N 等参数。

推荐：

search-conversations 支持多种搜索模式和过滤器。需要参数细节时运行 `search-conversations --help`。

这样入口文件不会随着工具参数增加而膨胀，也避免 Skill 文档和真实工具行为不一致。

2. 重参考内容放进 references/

如果内容有用，但不是每次都要读，就放进 references/。

skill-name/
├── SKILL.md
└── references/
    ├── api.md
    ├── troubleshooting.md
    └── examples.md

入口文件只保留索引：

需要完整 API 字段时，读取 `references/api.md`。
遇到认证、权限、网络错误时，读取 `references/troubleshooting.md`。
需要复杂示例时，读取 `references/examples.md`。

这就是典型的按需加载：先读入口，任务需要时再读细节。

3. 机械操作放进 scripts/

如果一个步骤是稳定、机械、可重复的，就不要让模型每次重新理解和生成。

比如：

• 统计文件大小
• 校验配置格式
• 批量转换数据
• 调用固定 API
• 生成固定模板
• 检查 Skill 结构

这些适合放进脚本：

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

SKILL.md 只需要写：

修改完成后，运行 `scripts/validate.py` 校验 Skill 结构和大小。

模型适合做判断和编排，脚本适合做稳定执行。

4. 重复流程用交叉引用

如果某个工作流已经由其他 Skill 定义过，不要复制一遍。

不推荐把子代理调度、测试流程、发布流程等内容反复粘贴到多个 Skill 里。这样会产生多份事实来源，后续必然不一致。

推荐写法：

涉及子代理调度时，必须使用 `dispatching-parallel-agents` 工作流。

交叉引用的价值不是少写几行，而是让公共流程只维护一份。

5. 示例只保留最小模式

Skill 里的示例应该帮助模型识别模式，而不是提供完整剧本。

冗长示例可以压缩成：

用户：“我们如何处理 React Router 身份验证错误？”
Agent：搜索历史记录 → 汇总相关做法 → 给出结论。

复杂示例可以放到 references/examples.md。入口文件里只保留最小输入、动作和输出关系。

五、怎么验证拆得是否合理

可以从两个角度检查。

第一，看职责是否清楚：

• SKILL.md 是否只包含触发条件、核心流程、硬约束和跳转路径？
• 参数细节是否交给 --help？
• 长示例是否拆到了 references/？
• 机械操作是否沉淀成脚本？
• 公共流程是否使用交叉引用？

第二，看文件大小：

wc -c /path/to/skill/SKILL.md

如果主要是中文，也可以统计汉字、字母和数字数量：

grep -o '[[:alpha:]]\|[[:digit:]]\|[\u4e00-\u9fff]' /path/to/skill/SKILL.md | wc -l

这些数字不是目的，只是帮助判断入口文件有没有重新变成“大而全”。

总结

Skill 拆分的核心是按需加载。

SKILL.md 不是百科全书，而是入口文件。它应该短、准、硬：短到模型能快速读完，准到系统能正确匹配，硬到关键约束不会被忽略。

真正复杂的内容不用删除，而是放到更合适的位置：

• 工具参数交给 --help
• 长文档放进 references/
• 机械动作放进 scripts/
• 公共流程用交叉引用
• 示例只保留最小模式

这样设计出来的 Skill，才更适合 Agent 执行：先加载最关键的信息，再根据任务需要加载细节。上下文更省，匹配更准，行为更稳，维护成本也更低。

原文链接： AI Agent Skill 拆分：从大文档到按需加载 ，转载请注明来源！