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.
80 lines
3.5 KiB
Markdown
80 lines
3.5 KiB
Markdown
# 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 的规则：正文删复述，保留调用命令。
|
|
|
|
## 改造顺序
|
|
|
|
1. 去重：`SKILL.md` 复述某份 reference 或脚本契约 → 改成指针。
|
|
2. 按模式拆：初始化 / 检查 / 工作 / 其它模式的步骤离开正文。
|
|
3. 把无条件加载改成「若 X 则读 Y」。
|
|
4. 缩短 `description`。
|
|
5. 不主动改全局安装范围。
|
|
|
|
已在硬顶内、无复述、无无条件加载清单：报告 Keep，不改文件。一次只改用户点名的那一个 skill。
|
|
|
|
## 验证
|
|
|
|
1. `pouch check <name>` 通过。
|
|
2. 对每个模式写一句用户原话，核对该模式的必做步骤仍在「正文短清单」或「该模式明确要求读取的那一份 reference」里；fail-closed 仍在 `SKILL.md`。
|
|
3. 若某条规则被搬出去后，按那句原话走会漏读，把该规则搬回正文。
|
|
|
|
## 报告格式
|
|
|
|
```text
|
|
## pouch 结构优化：<name>：完成 | 无需改 | 阻塞
|
|
|
|
预算: SKILL.md 行数/token 前→后；description token 前→后
|
|
搬出: 模式或段落 → 目标文件
|
|
保留: 仍留在 SKILL.md 的 fail-closed / 触发限制
|
|
加载: 改掉的无条件读取清单（若有）
|
|
验证: pouch check；已核的模式场景
|
|
未做: 因会伤功能而没搬的内容
|
|
```
|