Write Skill 指南
spec-write-skill 是编写 skill 的公开 workflow。Claude 入口是 spec-write-skill，Codex 入口是 spec-write-skill。它把明确的 skill authoring 目标转成 spec-first source patch：先判断是否值得做成 skill，再更新 SKILL.md 的触发、边界、I/O、渐进披露、resources/evals、治理和验证。
入口
| 场景 | Claude Code | Codex |
|---|---|---|
| 新建 source skill | spec-write-skill | spec-write-skill |
| 改写或迁移已有 skill | spec-write-skill skills/<name> | spec-write-skill skills/<name> |
| 按 audit findings 修复 | spec-write-skill skills/<name> | spec-write-skill skills/<name> |
执行逻辑图
text
用户提出 skill authoring 目标
|
v
资格判断：这是否值得做成 skill？意图是否清晰？
|
+-- 不值得 --> 返回 do-not-create-skill 或 near-neighbor route
|
v
确定 mode / tier / entry surface（workflow_command 或 standalone_skill）
|
v
写 source patch：skills/<name>/SKILL.md 的触发、边界、I/O、渐进披露、resources/evals
|
v
更新治理 JSON、runtime catalog、tests、docs、CHANGELOG
|
v
跑匹配风险的验证 gate；generated runtime mirror 只由 spec-first init 投影写什么
| 维度 | 说明 |
|---|---|
| 复用价值 | 这个能力是否高频、值得沉淀为 durable skill |
| Trigger precision | 触发条件是否清晰、是否容易误路由 |
| Scope boundary | 何时使用、何时不使用、是否跨 workflow 越权 |
| Input/output contract | 输入、输出、失败模式和产物路径是否明确 |
| Progressive disclosure | 入口锚点轻量，细节放 references |
| Governance & entry surface | skills-governance.json 投递、entry surface 归属 |
| Verification | 变更后跑哪些匹配风险的 gate |
产物
| 产物 | 作用 |
|---|---|
skills/<skill-name>/SKILL.md | skill source truth |
| resources / evals | 渐进披露的细节与评估素材 |
| 治理 JSON | entry surface 与投递声明 |
| tests、docs、CHANGELOG | 契约测试与用户可见记录 |
generated runtime mirror（.claude/、.codex/、.agents/skills/）不是 source，只由 spec-first init 投影，不要手改。
什么时候不该用
- 一次性回答、解释、总结、翻译。
- 只做只读审计诊断，不落地 source patch。
- 文档导出、第三方 skill 安装。
- 普通代码评审、普通实现或调试 workflow 执行。
- 手改 generated runtime mirror 来"刷新"行为。