Leroy
d3e9bd45bd
- SKILL.md 双工作流（创建/迭代）+ 两道门（验料/通用化）+ 三档位 - 7 篇方法论 references + 3 个纯标准库脚本（scaffold/validate/trigger_eval） - 自身触发用例 16 条 + 先例研究/创建/迭代证据报告 - 方法论吸收自 qiaomu-meta-skill 与 luban-skill，取舍见 reports/prior-art.md
48 lines
2.6 KiB
Markdown
48 lines
2.6 KiB
Markdown
# 目录架构——资源放哪，纪律是什么
|
||
|
||
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/` 证据。
|
||
|
||
升级档位时按需补件，不提前预支。
|