# 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；已核的模式场景
未做: 因会伤功能而没搬的内容
```