laily
2be0964d73
Teach pouch to optimize a named skill's loading layout: keep SKILL.md as a router, move mode-specific steps to references, and measure footprint with an audit script instead of dumping the whole skill into context.
3.5 KiB
3.5 KiB
Skill 分层加载与结构预算
改结构是为了少灌上下文，不是删能力。功能回归不过就停，把刚搬出去的必做规则搬回 SKILL.md。
三层加载
| 层 | 内容 | 何时进入上下文 | 备注 |
|---|---|---|---|
| 1 | frontmatter name + description |
每个会话，所有已安装 skill | 只负责点名 |
| 2 | SKILL.md 正文 |
skill 被点中 | 所有模式会一起进来 |
| 3 | references/、scripts/、templates/ |
读到具体文件或执行脚本时 | 脚本应执行、不要 cat 源码 |
| — | README.md |
不应被 Agent 主动读取 | 给人看 |
文件拆了不等于省 token。SKILL.md 或 kickoff 写「每次都读 A、B、C」，等于把第 3 层又变成第 2 层。
预算
以本文件为准。scripts/audit_skill_structure.py 只测量，超标按这里判断。
| 对象 | 目标 | 硬顶 |
|---|---|---|
description |
60–100 token；做什么、何时用、触发词 | 约 1024 字符（规范上限） |
SKILL.md 正文 |
约 200 行 / 2500 token | 500 行 / 5000 token |
| 单份 reference | 按需加载；>100 行时文首加目录 | 只与 SKILL.md 相距一层 |
description 不要写流程。显式触发限制（例如「仅在用户调用 /ack」）值得保留，能避免误触发后灌入整包。漏触发比 description 多 40 token 更贵。
默认项目级安装；不要为省事对项目专用 skill 加 -g。安装范围只在用户明确要求优化安装时才动。
SKILL.md 只留
- 模式路由：用户这句话走哪一模式。
- 所有模式都成立的 fail-closed。
- 带条件的指针：「若 X，读
references/Y.md」。禁止空的「见references/」。
搬到 references/ 或脚本
- 只在某一模式才走的步骤。
- 已在
references/或脚本里的正文复述。 - 长命令、schema、示例：改成脚本输出或
templates/。 - 「每次都读」的清单：改成按任务条件加载。
引用只保持一层：SKILL.md → references/foo.md。不要 SKILL.md → A → B。同一事实只留一个家。
不要删
- 不可逆操作的 fail-closed（上传、部署、发版、关 worker）。
- 禁止把完整 yaml / 任务板 / 知识库灌进上下文的规则。
- 显式触发限制。
- 脚本已经 enforce 的规则：正文删复述，保留调用命令。
改造顺序
- 去重：
SKILL.md复述某份 reference 或脚本契约 → 改成指针。 - 按模式拆：初始化 / 检查 / 工作 / 其它模式的步骤离开正文。
- 把无条件加载改成「若 X 则读 Y」。
- 缩短
description。 - 不主动改全局安装范围。
已在硬顶内、无复述、无无条件加载清单：报告 Keep，不改文件。一次只改用户点名的那一个 skill。
验证
pouch check <name>通过。- 对每个模式写一句用户原话，核对该模式的必做步骤仍在「正文短清单」或「该模式明确要求读取的那一份 reference」里；fail-closed 仍在
SKILL.md。 - 若某条规则被搬出去后，按那句原话走会漏读，把该规则搬回正文。
报告格式
## pouch 结构优化：<name>：完成 | 无需改 | 阻塞
预算: SKILL.md 行数/token 前→后；description token 前→后
搬出: 模式或段落 → 目标文件
保留: 仍留在 SKILL.md 的 fail-closed / 触发限制
加载: 改掉的无条件读取清单（若有）
验证: pouch check；已核的模式场景
未做: 因会伤功能而没搬的内容