在 pm-skills 库中从零创建符合规范的新 PM…

当你有一个新 PM 技能想法，需要按 pm-skills 仓库约定完成差距分析、分类、生成草稿文件并暂存审核时使用。

适用场景

解决思路

1. 接受两种形式的想法输入：问题优先（该技能解决什么 PM 问题、谁遇到、目前产出或缺失什么）或技能优先（想创建什么技能、产出什么工件、支持什么 PM 活动）；用户只给一种形式时不要追问另一种，直接提取所需信息继续。
2. 如果想法模糊，只问一个后续问题来澄清工件类型和目标受众，然后继续。
3. 对全部现有技能做重叠检查：从 skill-manifest.json 或 AGENTS.md 派生实时清单，并扫描 skills/ 目录获取最新清单，覆盖 domain、foundation、utility、tool 四个家族（tool 家族最易遗漏）。
4. 具体呈现发现：点名每个重叠技能及其覆盖范围，指出新技能要填补的具体空白；若重叠度高则触发 Why Gate。
5. Why Gate 触发时问用户：『举出 2-3 个现有技能无法产出你所需内容的具体提示或场景。』
6. Kill Gate：若用户无法给出有说服力的空白证据，建议替代方案——修订现有技能、创建组合技能的工作流、添加命令变体而非新技能、或将其作为文档改进；未获得有说服力的空白证据或用户明确覆盖前不得越过 Kill Gate。
7. 做范围检查，判断应为一个技能还是多个技能；拆分信号包括：产出多种不同工件类型、跨越 Triple Diamond 阶段（如 Discover + Deliver）、描述中自然出现连接两个活动的『and』。
8. 若需拆分，给出建议：『这似乎覆盖两个不同的 PM 活动：1. [活动 A] → 产出 [工件 A]；2. [活动 B] → 产出 [工件 B]。它们更适合作为可通过工作流串联的独立技能。是否先只处理 [活动 A]？』
9. 确定分类与命名：domain 技能按阶段（discover|define|develop|deliver|measure|iterate）命名目录为 {phase}-{skill-name}，frontmatter 必填 phase 且无 classification；foundation 技能目录为 foundation-{skill-name}，frontmatter 必填 classification: foundation 且无 phase；utility 技能目录为 utility-{skill-name}，frontmatter 必填 classification: utility 且无 phase。
10. 先按 Skeleton Canon 的三种认可方言（classic、contract-shaped、tool-family）选定技能方言，以固定必需的标题骨架；不要默认『照搬最接近的范例』，因为范例本身可能带有漂移（大小写变体、多余或缺失章节），直接照搬会把漂移复制进新技能。
11. 再挑选 1-2 个同方言、结构最接近的现有技能作为范例（同阶段 > 同类别 > 相似工件类型），阅读其 SKILL.md 确认指令风格、输出契约措辞和质量清单模式；明确点名范例：『参照 [skill]——同阶段、[category] 类别、[dialect] 方言』。
12. 向用户确认分类、方言和范例选择。
13. Eval 就绪（eval 契约）四部分：A. 最近邻（C-2）——点名新技能的 1-3 个最近邻（触发条件最重叠的现有技能），由差距分析加同阶段/同类别兄弟技能推导，用于边界指针、近失触发夹具和碰撞探测。
14. B. 互惠边界指针（C-3）——草稿 SKILL.md 必须包含 `## When NOT to Use` 章节，点名每个最近邻并说明何时改用该邻居；对每个邻居还要在其 SKILL.md 中添加反向的『When NOT to Use』条目指向新技能；若重叠强到构成可测量的碰撞对，把该对加入 scripts/check-trigger-fixtures.mjs 的 COLLISION_PAIRS，使互惠门禁（check-reciprocal-boundary-pointers.mjs）和碰撞探测都覆盖它。
15. C. 输出评估家族（C-4）——按阶段/类别把技能映射到输出评估家族评分表：framing（define-* 问题/假设/jtbd/机会/优先级 + foundation-okr-writer/persona/lean-canvas）、specification（deliver-* prd/acceptance-criteria/user-stories/edge-cases/launch-checklist）、discovery（discover-* interview-synthesis/competitive/market-sizing/journey/stakeholder）、technical（develop-* adr/design-rationale/solution-brief/spike-summary）、measurement（measure-* experiment-design/results/okr-grader/dashboard/instrumentation/survey）、learning（iterate-* retrospective/lessons-log/pivot-decision/refinement-notes）、communication（面向受众：deliver-release-notes、foundation-stakeholder-update）；评分表位于 docs/internal/eval-rubrics/{family}.md，若技能属于已有评分表的家族则在场景 frontmatter 使用该 family 值，若开启新家族则注明『尚无家族评分表——在技能进入输出评估名册前先编写一份』并跳过 family 值。
16. D. 夹具 + 场景计划（C-1、C-4）——规划 Step 5 产出的两个评估资产文件：trigger-fixtures.json（路由）和 output-scenarios/<id>.md（输出质量）。
17. 在生成实现包前，向用户确认最近邻 + 家族 + 互惠指针计划。
18. 用 references/TEMPLATE.md 作为格式生成完整技能实现包，包含 14 项：1. Decision（建议 + Why Gate 证据）；2. Classification（类型、阶段、类别、目录名）；3. Overlap Analysis；4. Exemplar Skills；5. Draft Frontmatter（完整有效 YAML，必须以 `---` 位于文件字节 0 处，前面不得有任何内容包括 HTML 注释、BOM 或空白；署名注释放在闭合 `---` 之后，参考 library/skill-output-samples/SAMPLE_CREATION.md 第 5 节）；6. Draft SKILL.md（完整内容而非大纲，遵循所选方言的规范标题骨架和范例指令风格）；7. Draft TEMPLATE.md（章节标题加指导注释）；8. Draft EXAMPLE.md（完整真实示例 150-300 行，含具体 PM 场景、每节填满、可选节同时演示填写与跳过）；9. Draft Command（命令 frontmatter）；10. AGENTS.md Entry（要添加的确切文本）；11. Validation Checklist（对照草稿检查所有 CI 规则）；12. Next Steps（本地 CI、测试、贡献流程）；13. Draft trigger-fixtures.json（C-1 路由评估，位于 evals/trigger-fixtures.json，JSON 对象 { "schema": 1, "skill": "{name}", "runs_per_query": 3, "trigger_threshold": 0.5, "queries": [...] }，queries 数组需 >= 16 条总数、>= 8 条 "expect": "trigger"（来自技能真实意图而非仅工件关键词，包含仅意图的请求）、>= 8 条 "expect": "no-trigger"（其中 >= 2 条为针对 Step 4.5 最近邻的近失，标记 "near_miss_of": "{neighbor}"），每类按约 60/40 拆分到 "split": "train" / "split": "validation"，这是 B-4 夹具契约 scripts/check-trigger-fixtures.mjs）；14. Draft output-scenario（C-4 输出质量评估，位于 evals/output-scenarios/{id}.md，frontmatter 为 scenario: {id} / skill: {name} / family: {Step 4.5 的 family} / created: {date}，然后是一段真实输入简报（正文 >= 100 字符），给技能臂和自由手控制臂相同原始材料，这是 B-7 资产契约 scripts/check-output-eval-assets.mjs；仅当 Step 4.5 尚无评分表时省略 family）。
19. 把所有生成文件写入暂存区 _staging/pm-skill-builder/{skill-name}/，结构为：SKILL.md、references/TEMPLATE.md、references/EXAMPLE.md、evals/trigger-fixtures.json、evals/output-scenarios/{id}.md、command.md；注意 _staging/ 已被 gitignore，草稿工件不会随发布出货，晋升后丢弃暂存文件夹；报告写了什么、写在哪里。
20. 晋升（确认后）：询问『请审阅上述实现包。准备好后我会把文件晋升到规范位置。继续？[yes/no]』；若同意，按映射表从暂存复制到规范位置：SKILL.md → skills/{dir-name}/SKILL.md，references/TEMPLATE.md → skills/{dir-name}/references/TEMPLATE.md，references/EXAMPLE.md → skills/{dir-name}/references/EXAMPLE.md，evals/trigger-fixtures.json → skills/{dir-name}/evals/trigger-fixtures.json，evals/output-scenarios/{id}.md → skills/{dir-name}/evals/output-scenarios/{id}.md，command.md → commands/{command-name}.md；其中 {dir-name} 是带分类前缀的目录（如 deliver-change-communication）。
21. 晋升后：1. 创建目标目录 skills/{dir-name}/references/ 和 skills/{dir-name}/evals/output-scenarios/；2. 复制每个文件到规范位置；3. 追加实现包中的 AGENTS.md 条目，若 Step 4.5 声明了碰撞对则加入 scripts/check-trigger-fixtures.mjs 的 COLLISION_PAIRS，并向每个邻居的 SKILL.md 添加互惠『When NOT to Use』条目；4. 运行 CI 校验：bash scripts/lint-skills-frontmatter.sh && bash scripts/validate-agents-md.sh && bash scripts/validate-commands.sh，然后运行评估资产门禁 node scripts/check-trigger-fixtures.mjs、node scripts/check-output-eval-assets.mjs、node scripts/check-reciprocal-boundary-pointers.mjs，以及碰撞探测 node scripts/check-new-skill-collision.mjs --skill={name}（C-2，确认新技能能召回自身触发且不抢占邻居的触发）；重新生成目录表面：node scripts/gen-skill-manifest.mjs && node scripts/gen-skill-manifest.mjs --agents；5. 若校验通过，删除暂存文件夹 _staging/pm-skill-builder/{skill-name}/；6. 若校验失败，报告错误并保留暂存以便修复。
22. 设计理由放在 GitHub issue、PR 或工作简报中，不要放在永久实现包文件里。
23. 提供晋升后指导：『本地运行 CI：bash scripts/lint-skills-frontmatter.sh』『测试技能：用真实场景尝试 /{command-name}』『若要贡献：用 skill-proposal 模板创建 GitHub issue，然后开 PR』。
24. 不要在本文件中手工维护技能清单；每次运行时从 skill-manifest.json（仓库根，生成的机器可读文件，含每个技能的名称、分类、阶段、类别、描述）或 AGENTS.md（生成的人类可浏览文件，按家族分组）派生实时清单；两者由 node scripts/gen-skill-manifest.mjs（及 --agents）在技能增删改时重新生成，精确跟踪磁盘上的 skills/，不会漂移。
25. 最终确定实现包前，验证两层质量清单。CI 校验（必须通过）：name 与目录名匹配；描述 20-100 词（单行，无多行 YAML）；version、updated、license 均存在；分类正确（domain → phase:，foundation/utility → classification:）；目录名遵循 {phase/classification}-{skill-name} 约定；TEMPLATE.md 有 >= 3 个 `##` 章节；命令文件引用正确的技能路径；AGENTS.md 条目使用 `####` + `**Path:**` 格式。
26. 质量检查（应当通过）：差距分析检查了所有现有技能（不只同阶段）；Why Gate 证据具体（点名提示/场景，不模糊）；EXAMPLE.md 是完整工件（150-300 行）而非大纲；草稿 SKILL.md 中存在输出契约；草稿 SKILL.md 中存在质量清单。
27. Eval 契约（C-1..C-4，评估就绪）：最近邻已点名（C-2）且 `When NOT to Use` 章节指向每个邻居；每个邻居已添加反向『When NOT to Use』指针（C-3），强重叠时已加入 COLLISION_PAIRS；evals/trigger-fixtures.json 存在且满足 B-4 契约（>=16 查询、每类 >=8、>=2 近失、train/validation 拆分）；evals/output-scenarios/{id}.md 存在且 scenario/skill/family frontmatter 映射到现有评分表（或注明原因推迟 family）；碰撞探测已运行且无需密钥：check-new-skill-collision.mjs --skill={name} --emit-tasks，然后对发出的查询派发 pm-skill-router 子代理（Haiku）并应用裁决，确认新技能召回自身触发且不抢占邻居的触发（无人值守 CI 可改用带 ANTHROPIC_API_KEY 的 Messages-API 路径）。

适用边界 · 注意事项

• 修改或改进现有技能时，改用 utility-pm-skill-iterate。
• 审计现有技能是否符合约定时，改用 utility-pm-skill-validate。
• 为非 pm-skills 上下文创建技能时，改用通用 agent 技能构建器；创建 workflow 时直接编写，不通过本构建器。