skill-forge

把「写一个技能」变成一条可执行、可验证、可复用的流水线。
它融合两套方法论：结构化规范（分层 · 契约 · 边界）与经验闭环（真跑对照 · 量化 · 迭代）。

本技能以「Agent 装 Skill」形态使用：常驻的编写 agent 装载本规程，
正文只负责决策与调度，规范细节与工具按需加载。

0. 权责优先级表（遇到分歧先查这里）

| 主题 | 权威来源 | 依据 | | ------------------------- | -------------------------------------------------------------------- | ------------------- | | 契约 / 边界 / 元数据 / 命名 / 落盘路径 | references/authoring-spec.md、contract-spec.md、boundary-spec.md | 要被机器校验、被调度器解析，不能留歧义 | | 验证 / 度量 / 迭代 / 触发优化 | references/eval-spec.md、trigger-spec.md + scripts/ + agents/ | 有工具链与实测数据支撑 | | 覆盖轴（任务变体 / 能力板块 / 覆盖缺口） | references/coverage-spec.md | 与质量轴正交，混写会两边都判错 | | 范例轴（规范配套的成品靶子） | references/exemplar-spec.md | 与质量轴、覆盖轴都正交——门禁全绿仍可能没有靶子 | | 存量探查（接手已有技能先体检） | scripts/survey_skill.py + scripts/check_*.py | 不体检就改 = 盲改；先看报告再分诊 | | 指令风格 | 分区：对外契约与边界用硬规约；对内正文与流程解释 why | 前者给机器读，后者给模型推理 |

风格问题只在这里裁决一次。不要在文档其它地方再讨论「该不该用 MUST」。

1. 定位与适用边界

适用：

新建一个 skill
接手 / 体检一个已有 skill（先跑 Step 0 体检，再决定改什么）
改写 / 优化已有 skill
为 skill 跑评测、基准测试、触发优化
判断某件事该做 Skill 还是 Agent
诊断一个膨胀的 skill 并拆分

不适用（明确转交，不要硬做）：

写业务代码 → 交给对应开发角色
只是问「skill 是什么」→ 直接解释，不必启动本流程
用户说「不用评测，随便聊聊」→ 按其节奏直接起草，跳过 Step 5–6

2. 两个正交的「层」，别混

本体系有两套「层」，它们正交，混用会误判：

| 体系 | 回答什么 | 内容 | | ---------- | ---- | ------------------------------------------------------------------------- | | 上下文预算层 | 读多少 | metadata（常驻 ~100 词）→ SKILL.md 正文（触发即读，理想 <500 行）→ 打包资源（按需读；脚本可直接执行，不进上下文） | | 职责层级 | 谁干什么 | L1 原语 → L2 专项 → L3 工程 → L4 编排 |

一句话区分：上下文层决定「进不进上下文」，职责层决定「干不干活」。
把「L3 工程层」误当成「第三层加载」，是最常见的新手错误。

3. 职责分层与选型

3.1 四层定义

| 层级 | 代号 | 典型步骤 | 上下文 | 典型角色 | solo_runnable | | --- | -- | ----- | --- | --------------- | --------------- | | 原语层 | L1 | 1–2 | 极低 | 单工具封装、通用方法论 | true | | 专项层 | L2 | 3–7 | 中 | 主力干活单元 | true | | 工程层 | L3 | 8–20+ | 高 | 复杂长任务、需中间状态 | true（建议拆） | | 编排层 | L4 | 5–10 | 中 | 分发 / 聚合，不干活 | true |

3.2 选型决策树

是否只做路由/聚合，不含业务工具调用？
├── 是 → L4 编排层
└── 否 → 能否在当前对话一口气跑完 ≤10 步？
    ├── 否 → L3 工程层（或拆为 L2 + L4）
    └── 是 → 是否只封装单工具/单动作？
        ├── 是 → L1 原语层
        └── 否 → L2 专项层

经验法则：新手 90% 落 L2。L1 只有通用基建才写；L3 只有真实复杂项目沉淀后才提炼；L4 只有专项簇 ≥3 个时才写。

3.3 广度标签

| 标签 | 含义 | 触发条件写法 | | ---------------- | ----------- | ----------------- | | breadth=narrow | 一类问题的一个切面 | 「用户显式说『做 X』」 | | breadth=medium | 一个领域的端到端子流程 | 「任务标签含『前端/后端/设计』」 | | breadth=wide | 横切多领域、通用方法论 | 「用户显式说『用六维拆解』」 |

4. 工作流

每一步都标了读哪个文件。不读对应文件就动手，等于凭印象。

Step 0 · 存量体检（接手已有技能时，先跑这一步）

新写一个技能从 Step 1 开始；接手/维护一个已有技能，必须先体检再动手 —— 否则你不知道它哪里已经病了，改起来是盲改。

python scripts/survey_skill.py <技能目录>

一条命令跑完 7 项探查，出「体检报告」：

| # | 项 | 脚本 | 性质 | | --- | --- | --- | --- | | ① | 结构门禁 | quick_validate.py | 确定性（有 FAIL 即拦） | | ② | 死引用 | package_self_check.py | 确定性 | | ③ | 包完整性 | package_self_check.py | 确定性 | | ④ | 叙事污染密度 | check_narrative_pollution.py | 只报数 | | ⑤ | 追加化石 | check_integration_on_write.py | 只报数 | | ⑥ | 记录死期 | check_record_lifecycle.py | 只报数 | | ⑦ | 容量 | package_self_check.py | 只报数 |

读完报告先分诊：

有硬错误（①②③） → 先修硬错误，别急着改内容。病在结构/打包，改文本治不了（见 §9.1 缺陷分层）。
只有探雷器读数（④⑤⑥⑦） → 按 §9.2–9.4 三层治法处置，逐个人判。 不许按数字机械清剿 —— 同样密度在不同定位下结论相反（反例库带病例 = 本分，见 §9.2）。

单独复查某一项（体检报告只是汇总，细则要单跑）：

python scripts/check_narrative_pollution.py <技能目录> --top 30
python scripts/check_integration_on_write.py <技能目录>
python scripts/check_record_lifecycle.py <技能目录>
python scripts/package_self_check.py <技能目录>

Step 1 · 分层定性

定 L1–L4（§3.2 决策树），填「执行画像」五项：depth breadth est_steps est_tokens solo_runnable。
判断是否需要新建 L4 入口（专项簇 ≥3 且共用入口）。

Step 2 · 锁契约

读 references/contract-spec.md。写 input / output / error，选定错误码，确定产出落盘路径。
契约先行的理由：接口先定，才知道哪些内容是必需的、哪些只是装饰。

Step 3 · 填骨架

读 references/layered-templates.md，只读当前层级那一节（写 L2 就不读 L1/L3/L4）。
正文按 references/writing-style.md 的风格写。

Step 4 · 静态合规校验（机器门禁）

python scripts/quick_validate.py <skill-path>

校验执行画像、契约完整性、错误码合法性、触发反例、summary 长度。不合格拒绝注册。

Step 5 · 分级验证

按 depth 决定强度（见 §6）。L3/L4 需要读 references/eval-spec.md。

Step 5b · 覆盖审计（覆盖轴）

与 Step 5 正交，不能互相替代。 读 references/coverage-spec.md，跑三步法：
任务变体采样（≥3 类，带出处）→ 能力板块反查 → 双向补集交叉。产出《覆盖缺口》，并构造 ≥1 条覆盖 case。
与触发 eval 的分工：触发 eval 测「该不该用」，Step 5 测「干得好不好」，本步测「这类活接不接得住」。

Step 5c · 范例轴（规范必须配成品）

产出带隐性质量要求（语感 / 体量 / 颗粒度 / 版式）的技能必须做这一步。 读 references/exemplar-spec.md：

写 ① 需求原文 → ② 完整成品 → ③ 逐条命中规范的对照 → ④ 机器校验，并至少配一组反面对照。范例集要单源 + 可脚本校验（md 里用 ```json / ```json:xfail 约定承载期望值），改 md 就跑该技能的范例校验器（本仓库自身的实例是 scripts/validate_spec_examples.py）。

别把"有规范"当成"有靶子"：条款能验的（禁词 / 格式）会被满足，条款验不了的（语感 / 节奏）会被自由发挥—— 而那恰恰是质量的主要来源。只转述案例不收录原文，不算范例。

Step 6 · 人审与迭代

生成审阅界面，先给人看，再自己评估。

python scripts/aggregate_benchmark.py <workspace>/iteration-N --skill-name <name>
python eval-viewer/generate_review.py <workspace>/iteration-N \
  --skill-name <name> --benchmark <workspace>/iteration-N/benchmark.json

读 feedback.json 后，按 writing-style.md 的「改进四原则」修改。

落笔任何一条知识/经验前，四个前置必读（顺序即管线）：

| 序 | 读 | 管什么 | |---|---|---| | 1 | references/carrier-separation.md | 放哪（规程 / 记忆 / 出库） | | 2 | references/knowledge-form.md | 写成什么样（思路 vs 操作记录；拨出多余描述） | | 3 | references/integration-on-write.md | 怎样进（补全 / 收紧 / 取代 / 分叉，不是追加） | | 4 | references/record-lifecycle.md | 何时出（固化 / 门禁化 / 暂存 / 废弃） |

Step 7 · 触发优化与注册

读 references/trigger-spec.md，跑 scripts/run_loop.py 拿最优 description。
按 authoring-spec.md 的目录约定注册到技能清单。

5. 资源索引（加载画像）

| 文件 | ---------------------------------------------------- | references/authoring-spec.md | references/contract-spec.md | references/layered-templates.md | references/writing-style.md | references/trigger-spec.md | references/eval-spec.md | references/coverage-spec.md | references/exemplar-spec.md | references/carrier-separation.md | references/integration-on-write.md | references/record-lifecycle.md | references/knowledge-form.md | references/boundary-spec.md | schemas/evals-schema.md | agents/grader.md / | scripts/survey_skill.py | scripts/*.py | assets/ | 何时读 | 体量 | 读完产出 | | ---------------------- | -- | ------------------------------- | | 建新 skill 前通读一次 | 中 | 分层 / 命名 / 目录 / 反模式 / 边界的判断依据 | | Step 2 | 小 | input / output / error 定义 | | Step 3 | 中 | 只读对应层级那一节 | | Step 3 与 Step 6 | 小 | 正文写法与改进依据 | | Step 7（或 Step 1 设计触发时） | 小 | 触发条件与 description | | Step 5（L3/L4 才需要） | 中 | 测试用例与断言（质量轴） | | Step 5b（L2 及以上都读） | 中 | 任务变体 / 能力板块 / 覆盖缺口 / 覆盖 case（覆盖轴） | | Step 5c（产出型技能都读） | 中 | 范例四件套 / 单源+机器校验机制 / 范例反模式（范例轴） | | Step 6 迭代与维护既有 skill 时（每次改都读） | 中 | 规程/记忆载体归属判据、三向搬运、六种失败模式（防 skill 变流水账） | | Step 6 每次落笔新经验前（强制前置） | 中 | 四种关系判据（补全/收紧/取代/分叉）、追加式标记黑名单、成品范例（防"只加不整合"） | | Step 6 维护记录库 / 规则落地后（收尾必读） | 中 | 记录的两个作用、四个出口（固化/门禁化/暂存/废弃）、六种失败模式（防"只进不出"） | | Step 6 落笔任何一条知识前（强制前置） | 小 | 三要件（问题/思路/落点）、可迁移判据、三类多余描述（证据/修辞/论证）、六种失败模式（防"知识写成操作流水账"） | | 不确定是 Skill 还是 Agent 时 | 小 | 形态判决 | | 手工生成评测 JSON 时 | 中 | 各 JSON 的确切字段名 | comparator.md / analyzer.md | 需要 spawn 对应子代理时 | 中 | 子代理指令 | | Step 0（接手存量技能第一步） | — | 一条命令跑完 7 项探查（体检报告入口，不占上下文） | | 直接执行 | — | 不占上下文 | | 新 skill 自带的评估集与静态素材 | — | 触发评估集（trigger-eval.json）等配套资产 |

6. 分级验证（按 depth 投入，别一刀切）

| 层级 | 强度 | 跑什么 | | ------- | -- | ----------------------------------------------- | | L1 / L2 | 轻量 | quick_validate + 3 条触发冒烟 + 产出 schema 校验 | | L3 | 中 | 上述 + 1–2 个真实用例跑通 + 逐例人审 + ≥1 条覆盖 case（Step 5b） | | L4 | 重型 | with-skill vs baseline 对照 + benchmark 统计 + 人审迭代 + 覆盖 case 全覆盖 |

理由：重型对照循环对 L1/L2 是浪费——它们逻辑确定、产出固定，静态门禁已能拦住大部分问题。

覆盖 case 是硬要求，不是加分项。 L3 及以上若评估资产只有 assets/trigger-eval.json （触发轴）而无可执行的质量／覆盖用例，Step 5b 不算通过 —— 那是「只考学过的科目」。

「产出 schema 校验」由谁做：新 skill 若产出结构化文件（剧本 / 报告 / 数据表），
应在自己的 scripts/ 里带一个校验脚本，把该产出的格式规范编译成断言——
不要复用 quick_validate，后者校验的是 skill 自身是否合规，不校验它的产出。
（实战样例：screenplay-draft/scripts/script_check.py）

7. 依赖映射（本规程落地到具体运行环境）

本规程的部分步骤依赖外部能力。落地到某个具体运行环境时，按下表做等效替换即可，不要求环境与本规程开发时所用的完全一致：

| 参考实现 | 等效替换方式 | | ------------------------------ | ------------------------- | | claude -p CLI（触发测试） | 环境内可用的 LLM 调用方式（CLI / API / 本地模型） | | subagent 并行执行 | 环境内的子代理 / 任务并行机制 | | 浏览器 viewer | 本地静态 HTML 预览，或运行环境提供的查看面板 | | .skill 打包产物 | 目录形态 + 在环境内注册为可用技能 | | grader / comparator / analyzer | 落地为环境内的子代理角色，或就地人工评 |

8. 执行纪律（易被忽略，但最影响成败）

先给人看结果，再自己评估。 人看一眼输出，比你写十行分析更有信息量。
验证流程不要中途停。 跑到一半停下，等于没跑。
timing 数据随到随存。 token 与耗时只在任务通知里出现一次，错过无法恢复。
加 TodoList。 多步流程最怕漏掉 Step 4 或 Step 6。
能力探测。 打包前先确认当前环境有对应工具；没有就跳过并说明，不要静默失败。

9. 维护既有 skill

保留原名。 目录名与 frontmatter 的 name 不改，否则会变成另一个技能。
先复制到可写位置再改。 已安装路径可能只读。
快照旧版本作 baseline。 改之前 cp -r 一份，否则无法回答「新版真的更好吗」。
先体检再改。 跑 scripts/survey_skill.py <技能目录>（Step 0）。

9.0 探查入口是必备能力，不是可选项

「有规范」≠「有能力」。 一个写技能的技能，必须同时具备三件东西： ① 写新的（Step 1–7）② 探查旧的（Step 0）③ 两边的工具都真的存在。

缺任何一项，使用者就会退回"凭印象改"：手边有个膨胀的 skill 要改 → 没有体检步骤 → 凭印象直接动刀 → 三条治法的判据都在，但没人先去看病灶在哪。

判据：If a method is worth writing down, its tool must exist and be runnable. 声明一个脚本路径之前，先确认那个文件真的在。改完跑一次 survey_skill.py 自证。这正是 D6 型漂移（注脚声明了工具、正文却没实现）的防治点。

9.1 缺陷分层（先分类，再修）

修之前先问一句：这是实例缺陷，还是方法缺陷？

| 层级 | 定义 | 修法 | | --- | --- | --- | | 实例缺陷 | 单点错字、单条参数写错、某个文件路径错 | 就地改掉，收工 | | 方法缺陷 | 同一类错会再发生的规则缺陷（正则过严、白名单过窄、阈值拍脑袋） | 回写规则本身，而不是再加一条特例补丁 |

判据：如果这次修完，下一次同类问题还会以「又一个特例」的形态出现 → 是方法缺陷。 只修实例不追方法 = 同类翻车必复发。

门禁报误报时：先归类。若为方法缺陷则改规则、并在注释里写明「这是规则缺陷，不是特例」；不要新增 # 第三处 式的补丁 —— 那是追加化石，不是修复。

★ 变更记录是追加化石的最大温床。 ## 变更记录 一节几乎必然长成流水账（- v1.2（日期）：新增… ×N），因为追加它永远不像是错的 —— 那是"记录"嘛。但它对使用者零价值：没人读一个 skill 的版本史来决定下一步怎么做。

| 判断 | 处置 | | --- | --- | | 这条写了「下次该怎么做」 | 留 —— 搬进正文对应位置（不是留在变更记录里） | | 这条写了「我这次做了什么」 | 删 —— 过程取证属记忆载体 | | 需要版本号才能读懂 | 删 —— 规程永远现在时，不含时态指针 |

替代形态：把变更记录改写成规则速查表（规则 | 判据 两列）。判据是「不看任何版本号，能不能知道现在该怎么做」——不能，就还没整合完。

探雷器认得出它：check_integration_on_write.py 的 CHANGELOG_LINE 抓 - v1.2（2026-10-03）： 形态的裸版本标签行（必须带日期戳，避免误伤正文里的版本引用）。例外：CHANGELOG.md 这类独立变更记录文件是正当载体，整文件豁免。

9.2 载体分层：skill 被改着改着变成了经验流水账

这是维护既有 skill 时最高频的方法缺陷，且它伪装成「认真」。

症状：迭代几轮后，SKILL.md / skills/*.md 里塞满了 2026-09-02 v1.2 新增…、 依据：XX 复盘、第 N 次复发、来源：xxx.md。规程变成一份版本变更史 + 病例集。

为什么必然发生（不是自律问题）：踩坑时那个 skill 就在上下文里，改它成本最低；记忆库不在上下文里，写进去要"跳出去"。于是每次迭代都只加不搬 → 单调膨胀 → 自我强化（越厚越显"完善"，越舍不得删）。

为什么严重：这不是"不够简洁"，是三条实质损伤 —— ① 稀释（实测最坏文件纯指令句仅 ~21%）；② 歧义（旧版判据时态指向旧行为）； ③ 冲突（版本并存 → 取哪个不确定，与"包中包取哪层不确定"同源）。

判据一句话：规程永远现在时，只回答「现在怎么做」；记忆才回答「为什么/以前怎样」。

| 该留（规程） | 该走（记忆） | | --- | --- | | 祈使句、判据、触发线、处置、字段表 | 日期、版本号、"曾经/第N次"、出处、病例叙事 |

关键陷阱：不能只看密度就判死。 同样 11/千字，counter-examples.md 是本分（它就是记忆载体），methodology-core.md 是错位（它该是共同知识层）。

修法：三向搬运（不是压缩 —— 压缩丢信息，搬运保信息） | 污染形态 | 搬去哪 | 留什么 | | --- | --- | --- | | 版本修订流水 | CHANGELOG.md | > 版本沿革见 CHANGELOG.md | | 证据/出处/依据 | 该条脚注或 knowledge/ | 判据本身 | | 病例/反例 | knowledge/counter-examples.md | 判据依据见 E1 |

搬运后必须跑保全核验（否则丢的就是防重蹈的关键）： scripts/check_narrative_pollution.py（扫描）+ scripts/verify_carrier_migration.py（保全）。

实战证据：首次搬运 methodology-core.md 时漏掉 v2.1/v2.2.1/v5.5 与「v2.2.1 起冻结加刀」约束 —— 正是保全核验抓出来的。密度 14.6 → 1.2，29 个原子 0 丢失。

9.3 写入即整合（新经验不许追加，必须先判关系）

这是本条规范治的第二个病，也是"经验污染"的主刀点（前一条管"内容该放哪"，这条管"内容怎样进来"）。

症状：新经验/新坑在"优化 skill"时被追加 —— 末尾加一段「【v1.3 新增】…」、判据表单元挂版本标签、写「（补充）」「另：」「注意：额外…」。 → 同一件事被说了很多遍，文件从"清单"变成"辩论"。庞杂 ≠ 字多，庞杂 = 语义重叠未消解。

一句话判据：追加是「往文件里加」，整合是「往规则里加」。

为什么必然退化成追加：① 追加是在末尾粘一段，整合要先读懂原规则再重写（成本差一个量级）； ② 粘完有"已完成"的错觉；③ 追加"感觉安全"（不动存量）——实际是在让存量腐烂。

落笔前必须先判：这条新经验与已有规则是什么关系？

| 关系 | 判定问句 | 动作 | 错误做法 | | --- | --- | --- | --- | | ① 补全 | 原规则对，只是缺一种情形？ | 在原判据处补一行 | 末尾加「补充：还有 XX」 | | ② 收紧 | 原判据太宽/太松？ | 改原判据本体 | 末尾加「注意：上条 XX 时例外」 | | ③ 取代 | 新经验使旧规则失效？ | 删旧写新 | 新旧并存靠版本标签区分 | | ④ 分叉 | 是另一回事？ | 拆成两处各归其位 | 硬塞进同一节 |

判不出关系 → 不许写。 绝大多数被误判成"新增"，实际是 ② 收紧。

整合四步：定位（说的是哪个已有规则）→ 判定（①/②/③/④）→ 动刀 → 验残（grep 同主题，确认没有两处说同一件事）。第四步不可省 —— 它是"整合"与"追加"的最终区别。

门禁：scripts/check_integration_on_write.py（只报数不判定）。范例（正/反两版机器校验，见 integration-on-write.md §9）：同样是"不通过分派"，追加式是 5 条各挂版本标签且同受方出现 4 次；整合式归并成「命中项 / 回谁 / 为什么」三列表，删掉全部版本标签。

追加的签名：版本标签挂在行尾、同一受方重复出现、用「补充/新增」起头。见一个判一个。

9.4 记录生命周期（记录有死期，规则落地即叙事出库）

这是第三层，也是"经验污染"的出口治理（前两层管"放哪/怎样进"，这层管"何时出"）。

症状：记录只进不出 —— 坑记下来 → 规则改了 → 记录还在 → 明年又有人读它、又被它误导；或者记录堆到几百条，再没人看。

核心认识：记录不参与犯错那一刻的决策。 踩坑时上下文里是"正在做的事"，记录在 knowledge/ 里 —— 不在现场。所以「防止再犯」寄托在记录上是让一个不在场的东西干活。记录只是过渡，门禁才是终点。

记录只有两个作用，且都是过程性的（都能"用完"）： ① 改规则的证据（判断做完即用完）；② 修不了门禁时的临时警示（能拦住即用完）。

判据：记录有死期。规则进了规程，叙事就该出库。

| 出口 | 条件 | 动作 | | --- | --- | --- | | ① 固化 | 规则已写进规程 | 删叙事；规程留一行指针 | | ② 门禁化 | 能做成脚本断言 | 写断言，删记录（优于 ①） | | ③ 暂存 | 暂时做不成门禁 | 留，但必挂 复审 YYYY-MM-DD | | ④ 废弃 | 规则已改，教训失效 | 删（留着会误导） |

出库前必须确认：① 规则真的可执行（「规则进规程」≠「规则能自动拦住」——D6 型漂移；不能执行就该走 ②，不是直接删）；② grep 有无别处引用；③ ③必须带日期（否则"暂存"= 永久堆积）。

门禁：scripts/check_record_lifecycle.py（只报数不判定；扫"无日期"与"逾期"）。

9.5 改一处 → 全链对账

改任何一条被多处引用的内容（错误码 / 步骤号 / 字段名 / 目录约定 / 阈值）， 提交前必须全链 grep 对账，把同一概念的所有落点一次改齐：

grep -rn "<被改的字符串>" <skill-dir>          # 正文、references、scripts、assets 全扫

漏一处的代价不是「不一致」，而是下游按旧约定执行 —— 静态门禁不会报（每个文件单独看都合规），只有真跑时才暴露。改完在变更记录里写明改了哪几处。

本技能自身的实例：错误码白名单同时存在于 quick_validate.py 与 references/contract-spec.md 的规范表 —— 只改一处，门禁与文档立刻互相矛盾。

10. 反模式速查（完整版见 `authoring-spec.md`）

| 反模式 | 一句修正 | | -------- | ---------------------------------------------- | | 伪 L1 | 步骤 >2 或含业务判断 → 拆成 L2 | | 入口干活 | L4 里直接调业务工具 → 全部下沉 L2 | | 专项互调 | skill-A 调 skill-B → 共用逻辑下沉 _shared/ | | 契约靠口头 | 参数名对不上、缺 summary → 写进头部契约并由 Step 4 校验 | | 产出随意 | 格式不一 → 强制 artifact_path + summary + metadata | | 无兜底 | 工具失败直接卡死 → 每个外部依赖加一行兜底 | | 过度设计 | 首版就写 30 步 → 先 MVP 跑通核心路径 | | 只考学过的科目 | 评估资产只有触发 eval → 执行 Step 5b 覆盖审计，补覆盖 case | | 有规范没靶子 | 条款齐全但产出"合规不好用" → 执行 Step 5c，补完整成品范例 + 反面对照 | | 转述当范例 | 写"XX 案例把…写死了"却不给原文 → 收录原文，或删掉转述 | | 没验证就宣布成功 | 拿真实用例跑 Step 4–5 再说话 |

11. 版本速查

只记「当前版本里有哪些成文规则」，不记版本演化史。 演化过程、实测数据、验收结果属记忆载体，不进规程（见 references/carrier-separation.md 与 record-lifecycle.md）。每条的格式固定为：规则 → 判据。

| 规则 | 判据（什么时候用） | | --- | --- | | 结构规范 · 经验闭环双方法论，按加载时机分层 | 一切技能创作 | | frontmatter 严格合法：定界符、name/version/description 齐备 | 注册前字节级校验 | | 覆盖审计（coverage-spec.md） | 只有触发 eval、怀疑整块能力未覆盖时 → Step 5b | | 范例轴（exemplar-spec.md）：范例四件套 + 单源机器校验 | 有规范但产出"合规不好用"时 → Step 5c | | 载体分离（carrier-separation.md） | 规程里出现过去时 / 溯源 / 验收数据 → N1–N6 | | 写入即整合（integration-on-write.md） | 想"加一条"而非"改一条"时 → 判四种关系，判不出不许写 | | 记录生命周期（record-lifecycle.md） | 存量记录 → 四出口：固化 / 门禁化 / 暂存带复审日 / 废弃 | | 知识形态（knowledge-form.md）：三要件「问题/思路/落点」 | 判断知识可迁移 → 「换个场景还能用吗」 | | 探查梳理：scripts/survey_skill.py 一条命令 7 项体检 | 接手存量技能 → Step 0 |

落笔前四读（Step 6）：载体分离 → 知识形态 → 写入即整合 → 记录生命周期。

四面治法：载体（放哪）→ 形态（写成什么）→ 整合（怎样进）→ 生命周期（何时出）。