# 目录架构——资源放哪，纪律是什么

Skill 是一个目录，`SKILL.md` 是唯一入口。其余一切按"模型什么时候需要它"分层。

## 标准布局

```text
<skill-name>/
├── SKILL.md            # 必需。路由 + 最简工作流，≤500 行
├── references/         # 判断类知识：方法论、决策树、评分表。正文说"做 X 前读 references/x.md"
├── scripts/            # 确定性工具：体检、测试、脚手架。能算的不让模型目测
├── evals/              # 回归用例：触发用例、输出样例。改动前后都跑它
├── assets/             # 模板、占位物：起草时复制出去改，本身不被读进上下文
└── reports/            # 运行证据：触发报告、handoff、迭代记录。给未来复查用
```

## 三层加载模型

1. `name` + `description`：常驻上下文，必须精短。
2. `SKILL.md` 正文：触发后加载，≤500 行预算。
3. `references/` 等附属文件：模型按需读取，原则上不限大小。

判断一个文件该不该存在，就看它能不能明确回答：**它提高了哪方面的稳定性？**

| 资源 | 提高的稳定性 | 不该存在的信号 |
|---|---|---|
| references/x.md | 判断质量 | 内容可以内联进正文而正文仍 <300 行 |
| scripts/x.py | 确定性、可回归 | 逻辑靠模型目测也能一次做对 |
| evals/*.json | 可回归 | skill 从不修改、或无触发风险 |
| assets/* | 起草一致性 | 从不新建同类产物 |
| reports/* | 证据、可复查 | 一次性过程记录，没人会回头看 |

## 资源纪律

- **不造仪式性目录。** 档位用不到的目录不建；scaffold 生成的空目录里要有 README 说明用途或干脆删掉。
- **不重复表达。** README 面向安装者，SKILL.md 面向模型——两份内容各说各的话，不互相复制。
- **正文引用必须可达。** 正文里出现的每个 `references/xxx.md` 链接都要真实存在（`validate_skill.py` 会检查悬空引用）。
- **单一入口。** 一个 skill 一个根 `SKILL.md`；内嵌的示例/fixture 用 `SKILL.example.md` 命名，避免被当成第二个入口发现。
- **密钥与私有路径零容忍。** 任何文件里出现 API key、token、私有绝对路径（`/Users/<你的用户名>/…`）都是 FAIL。

## 与档位的对应

- **draft**：只有 `SKILL.md`。其余都不建。
- **shared**：+ `evals/trigger_cases.json` + README（价值钩子、触发方式、安全边界三节起步）。
- **rigorous**：+ `references/` 分层 + `scripts/`（若有确定性工作）+ `reports/` 证据。

升级档位时按需补件，不提前预支。