spec：自建 skill 写法合同——业界词、实践与规程分层、正面陈述（镜像 desk#152） #115

镜像 desk#152（机会 issue，三行结论已判「行」）。第 2 段方案对齐的产物；ADR 草稿在本 issue 的前两条评论。

问题（Problem Statement）

主人视角。对照 Matt Pocock 的 skills，自建 skill 读起来重：每条都自足（五节骨架、内联实践、路由边界表、自检、验证状态），核心词是自造词（来往、段、门、步、可选步、停靠记录、上线待办、硬问题、焦点、领域分支），禁令密度约为 Matt 的 3 到 5 倍。字符数上自建 skill 并不比 Matt 长（自建 1,008 到 5,221 字，Matt 147 到 11,777 字），差的是分层与用词：Matt 把实践（grilling、domain-modeling、tdd）写成独立的 model-invoked skill，规程 skill 只用一行组合它们；自建的八条工程规程每条把实践内联进正文。词汇表 plugins/CONTEXT.md 第 3 行写「不自造」，同一份里却有两条标「自造」。评测的 grader 判消息形状，正文只好带模板和例子来过 grader。

方案（Solution）

主人视角。写法合同改三条：术语只用有出处的业界词，中文用通行译名、首次附英文与出处；实践与规程分两层，实践 skill 装在 plugins/practices，薄步 skill 装在 plugins/flow-steps，flow 单独；正面陈述目标行为，禁令只留硬护栏且紧跟正面句。Matt 的四条实践正文（grilling、domain-modeling、tdd、code-review）按 MIT 复制入库改成中文，vendor 只当材料。骨架只必有「什么时候用」「步骤」两节。评测 grader 只判可观测行为，形状模板放 references。共用规则同步：第 60 行改成只用业界词，来往、焦点、领域分支三个词换掉，评测里的规则副本同步。分三批各一个 PR。

用户故事（User Stories）

1. 作为主人，我想读任何一条自建 skill 时遇到的每个术语都能在业界查到，以便不用先学一套私有词汇。
2. 作为主人，我想改一条实践（比如特征化测试怎么写）只改一个文件，以便不在八条规程里找同一段话。
3. 作为主人，我想规程 skill 一眼看出它点名了哪些实践，以便判断这一步的手法对不对。
4. 作为主人，我想 skill 正文说「做什么」而不是一串「不许」，以便 agent 的注意力落在目标行为上。
5. 作为主人，我想评测判的是 agent 做了什么，而不是消息长得像不像模板，以便正文不为过 grader 而变厚。
6. 作为主人，我想 plugins/ 目录名直接说出层次（practices、flow-steps、flow），以便仓库看起来不乱。
7. 作为主人，我想改动分批、每批一个 PR，以便每批都审得动、评测守得住。
8. 作为主人，我想常驻规则和 skill 用同一套词，以便两边不打架。

实现决定（Implementation Decisions）

1. 业界词的判据（Q1）：概念必须有可引用的既有名字（标准、书、知名框架或项目的文档），中文用通行译名，首次附英文原词和出处。查不到出处的概念不起名，用平语句子。

2. 替换表（Q7，两个 Sonnet 盲测后定）：

   现用	改成	出处
   来往	不设总称，说「请求」（request）	ITIL 4
   要答案	查询（query）	CQRS
   小改动	标准变更（standard change）	ITIL 4 变更使能
   改动落地	常规变更（normal change）	ITIL 4 变更使能
   段	阶段（stage）	Cooper Stage-Gate
   门	门（gate），保留字补出处	Stage-Gate
   步	活动（activity）	ISO 12207、PMBOK
   可选步	不起术语，「改旧代码时才开的活动」	12207 tailoring 为最近概念
   停靠记录	站会记录（standup update）	Scrum Guide 每日站会三问加阻塞项
   硬问题／判断题	违例（violation）／判断题（judgement call）	静态分析 rule violation；Google 代码审查指南
   上线待办	上线清单（rollout checklist）	发布工程通用
   焦点	在制品（WIP），上限 3 即 WIP limit	Kanban
   领域分支	主题（theme）	SAFe／通用敏捷层级
   路由 skill	保留，出处 router skill	Matt Pocock writing-for-agents
   手动／自动调用	user-invoked／model-invoked，中文「人敲的／模型可拿的」	Claude Code 文档 disable-model-invocation

3. 实践层用谁的（Q2）：Matt 的 grilling、domain-modeling、tdd、code-review 正文复制进 plugins/practices，改成中文与本仓写法；MIT 许可证要求保留版权与许可声明，放 plugins/practices/LICENSE-mattpocock。自建实践只写 Matt 没有的（特征化测试、EARS、golden master、金丝雀发布、影响分析、接口契约清单等，从 workcoding 八条里拆出）。

4. 骨架（Q3）：必有「什么时候用」「步骤」两节，每步带完成判据；「产出」「出口」「为什么在哪」按需；删「路由边界」表、「自检」、「验证状态」三类节。

5. 禁令（Q4）：每条禁令必须紧跟一句正面目标；机械守卫只守两条精确可判的：正文与词汇表不出现「自造」标记、词汇表每条带英文原词。

6. 评测（Q5）：eval-cases.md 加一条「grader 判可观测行为，不判消息形状；形状模板放 references，正文只引用」。

7. 共用规则（Q6）：第 60 行改「只用业界词」；第 23、35、45 行的来往、焦点、领域分支换掉；flow 与 flow-steps 评测里的十六份规则副本、25 份含「停靠」「门口」的 grader 与提示词同步。

8. 目录（Q10）：plugins/practices、plugins/flow-steps、plugins/flow 三个 plugin 按层分；skill-authoring、clarify、note 保持各自一个；workcoding 目录在第三批结束时归档（关联 agent-system#111）。manifest 按 skill 声明，不受目录影响。

9. 分批（Q8）：第一批合同（writing-rules、eval-cases、plugins/CONTEXT.md、共用规则、评测副本与 grader）；第二批 flow 与 flow-steps 五条改词；第三批 workcoding 八条拆成实践加薄步，顺手 clarify、note。三批各一个 issue、一个 PR；第一批跨 agent-system 与 agent-config 两个仓各一个 PR。

10. 工作方法地图：工具层条目按新目录与新词改；vendor 的 Matt 整套仍是「未接入」材料。

测试决定（Testing Decisions）

• plugins/tests/skills.test.ts 加两条：所有 SKILL.md 与 plugins/CONTEXT.md 不含「自造」；plugins/CONTEXT.md 每个词条标题带英文原词。
• 每批按 skill-authoring 第 7 步跑门评测；第一批之后 flow 与 flow-steps 的用例按新词重跑，结果提交。
• claude plugin eval plugins/practices --case <名>* 只跑改动那条实践的用例。

范围外（Out of Scope）

• 6 条未接入 skill（adaptive-problem-solving、knowledge-maintenance、orchestrated-collaboration、self-improvement、skill-appraisal、skill-maintenance）不动。
• vendor 目录本身不改。
• wiki 里除工作方法地图外的笔记里的旧词（术语表、vibeCoding 改动流转等）：第三批结束后另立 issue。
• 「仓库脏乱」里 plugins/ 以外的部分（_archive/、openspec/、tools/、work/、旧挂载票 实现通用私有挂载机制与 GitHub 公共面脱敏门禁 #56 到 接入 GitHub 公共面 fail-closed 门禁 #62）：另立 issue。

备注（Further Notes）

• Sonnet 盲测：把 14 条定义分别投给两个独立 Sonnet 会话报业界词。一致的：query、standard change、normal change、stage、gate、standup、WIP limit、theme；不一致的四行（来往、步、硬问题、上线待办）按 agent 推荐定。
• 自造词分布：flow 62 处、skill-authoring 24、worktree-baseline 16、wrap-up 15、review-response 5、verify-evidence 3；workcoding 八条 0 处。