用途
writing-workflow-skills 是 pi-thinkrail-workflow 包中工作流技能的编写检查清单。它规定“做什么”，而概念模型、三种角色（路由器、工作者、概念）和元规则 1–15 等“为什么”内容统一记录在同目录的 skills/SPEC.md 规范中。使用前应先阅读该规范，若清单与规范冲突，以规范为准。
工作区守卫
该清单用于编辑 thinkrail 仓库中的 packages/pi-thinkrail-workflow。如果当前工作区不包含该包（例如 ThinkRail 管理的项目，其中这些技能是只读的暂存缓存），则无法从此处扩展技能家族：需用一行说明并停止——这是外部工作区的终止状态。
设计（编写前）
- 阅读 skills/SPEC.md：概念模型、三种角色、元规则 1–15。
- 将技能范围限定为一个外部可到达的工作流，或对于一个概念，限定为一个主题（规则 1）。内部 fork、分支、阶段和共享尾部是兄弟文档，在 fork 之前用文档（或主干）中的选择规则规划；当文档需要独立可寻址性（外部调用者、真正的自触发，或直接入口点如 /skill: 命令种子）时，才将其提升为独立技能——绝不能仅因形状或大小而提升。
- 选择角色（规则 2）：路由器（分类规则 + 交接，别无其他）、工作者（一个阶段的步骤）或概念（一个主题的可复用规则/心智模型——没有步骤，没有交接）。
- 对于概念：确认第二个技能需要它（规则 3）——只有一个消费者的参考细节应保持为兄弟文件，而不是概念技能。
- 选择结尾（规则 6）：路由器以命名下一步运行的内容结束；工作者以固定的后继、返回其调用者或声明的终止状态结束——内部 fork 的工作者以命名继续流程的兄弟文档结束，终止状态在流程结束的文档中声明；概念根本没有结尾——它不写结尾部分，控制权直接返回给读者。在编写正文之前要知道确切的措辞。
- 如果更改重塑了系统本身——新的角色、新的元规则、更改的入口模型或拓扑——请停止：先更新 skills/SPEC.md，然后回到这里（规则 13）。
编写
- 以动词优先、主动语态、kebab-case 命名技能（规则 15）：过程技能用动名词，概念用主题——命名工作或洞察，绝不命名产物或角色。目录名 = frontmatter 名称。
- 创建 skills/<name>/SKILL.md，包含 frontmatter 的 name + description。其他什么都不变——package.json 的 pi.skills 已指向 ./skills。
- description = 仅触发条件，“Use when …”（如果边界容易混淆，可加“Not for …”否定触发）——绝不要总结步骤（规则 5）。技能通过路由到达；自触发描述仅用于明确无误的触发（规则 4）。
- 保持每个文件约 150 行以内（规则 3）——SKILL.md 主干和每个兄弟文档。内部工作流节点（分支、阶段、共享尾部）和大量参考材料放在 skills/<name>/ 内的兄弟文档中，在交接给它们的准确步骤中命名；主干携带文档地图，每个内部节点文档以一行契约开头（入口状态、它保存什么、控制权下一步去哪里）。
- 每件事只说一次（规则 7）：按名称交叉引用其他技能；绝不要内联另一个技能的步骤，绝不强制加载其文件。
- 在纪律重要的地方设置门禁，使形式与失败匹配（规则 11）：对纪律违规使用禁令 + 红色标志，对输出形状使用正面配方。
- 持久输出到规范图（规则 8）。如果工作流需要临时工作文件——恢复状态、草稿计划——请声明它们（规则 9）：在技能中命名其形状，并将它们放在工作区 gitignored 的 .thinkrail/context/（所有临时文档的家）中，在工作落地时消费/删除它们，并在清理前将任何持久内容提升到规范。
- 正文结尾命名在设计中选定的结尾（规则 6）——概念跳过此：没有结尾部分。
注册（规则 12）
- 在拥有新技能的路由器中添加一条路由行：默认是根路由器（skills/choosing-a-workflow/SKILL.md），或者当技能是已路由工作流下的分支时，使用最近的子路由器（分形路由）。例外（规则 4）：不在任何路由器工作分类内的技能——仅自触发技能和概念技能——跳过路由行；这是技能的设计属性，绝不是大小调用，而是在 skills/SPEC.md 的家族表中命名为路由表之外。
- 在 skills/SPEC.md 的工作流家族表中添加或更新技能行，包括其 Routed from 条目（哪个路由器路由到它——或者它位于路由表之外）。
- 其他任何东西都不应改变形状——如果改变了，请重新审视设计中的规则 13。
通过使用验证（规则 14——当前暂停）
规则 14 目前是一个已知限制，而不是完成门禁（见 skills/SPEC.md）。在实践时，仍然通过新技能或更改的技能运行一个真实请求并观察其流动：路由器（或描述）触发它，遵循正文，结尾按设计触发。对于概念：引用技能（或其自触发）加载它并应用其规则。
无论哪种方式，保持家族表行诚实：在观察到一次运行之前，未通过使用验证；当观察到后更新行。
红色标志——停止并修复
- 描述提到了工作流的任何步骤。
- 名称是名词优先或命名产物/角色而不是工作（规则 15）。
- 路由器或工作者的正文结尾没有命名后继或终止状态。
- 概念技能包含步骤、路由、交接或结尾部分。
- 相同的规则被复制到两个技能中，而不是提取到概念中（规则 7）。
- 一个步骤重述另一个技能（或 skills/SPEC.md）的内容，而不是指向它。
- 技能外部无法到达的内部节点被做成自己的技能（或给予 frontmatter）——内部节点是兄弟文档，不是技能（规则 1）。
- “太小不需要路由器行/家族表行。”每个技能都注册（规则 12）；跳过路由行仅适用于规则 4 中的仅自触发技能和概念技能——大小绝不是原因。
- 在没有观察到真实请求流经技能的情况下称技能已验证——规则 14 作为完成门禁暂停，但未观察到的技能仍然未通过使用验证，绝不是“已验证”。
完成（终止状态）
此清单在此结束——没有后继技能。完成意味着：skills/<name>/SKILL.md 存在并通过上述检查，并且路由器行和家族表行已就位——该行诚实地标记为未通过使用验证，直到观察到真实请求流经技能（规则 14，当前作为完成门禁暂停）。