utility-pm-skill-builder

PM 技能构建器

此技能用于为 pm-skills 库创建新的 PM 技能。它会生成一份技能实施包——一份完整的设计文档，其中包含暂存区中的草稿文件，供审核后再移至规范位置。

适用场景

• 你有创建新 PM 技能的想法
• 你想为 pm-skills 库添加领域技能（特定阶段）、基础技能（跨领域）或实用技能（元技能/工具）
• 贡献者需要在引导下创建符合仓库规范的技能

不适用场景

• 修改或改进现有技能 → 使用 utility-pm-skill-iterate
• 根据规范审核现有技能 → 使用 utility-pm-skill-validate
• 为非 pm-skills 场景创建技能 → 使用通用 Agent 技能构建器
• 创建工作流 → 工作流应直接编写，而不是通过此构建器创建

说明

收到创建新 PM 技能的请求时，请遵循以下步骤：

步骤 1：了解想法

接受以下任一种形式的想法：

• 问题优先：“此技能要解决什么 PM 问题？谁会遇到这个问题？他们目前会产出什么（或无法产出什么）？”
• 技能优先：“描述你想创建的技能。它会产出什么成果？它支持什么 PM 活动？”

两种入口都会进入相同的后续流程。如果用户提供了其中一种形式，不要再询问另一种——提取所需信息并继续。

如果想法较模糊，只需追问一个问题，在继续之前明确成果类型和目标受众。

步骤 2：差距分析

检查所有现有技能是否有重叠。使用下方的当前库参考（从 skill-manifest.json 或 AGENTS.md 推导当前清单），并扫描 skills/ 目录以获取最新清单。涵盖全部四个类别——领域、基础、实用和工具；工具类别很容易被遗漏，因为它没有在常见对话中通用的阶段前缀模式。

具体呈现分析结果：

• 列出每个重叠的技能，并说明其涵盖的内容
• 指出此新技能要填补的具体差距
• 如果重叠度较高，触发“为什么”关卡（见下文）

“为什么”关卡（发现重叠时触发）： 询问用户：“请列出 2-3 个具体提示词或场景，说明现有技能在哪些情况下无法产出你需要的内容。”

淘汰关卡：如果用户无法清楚阐述令人信服的差距，请建议其他方案：

• “修改 [现有技能]，使其涵盖此情况”
• “创建一个结合 [技能 A] + [技能 B] 的工作流”
• “添加命令变体，而不是创建新技能”
• “这是文档改进，而不是新技能”

除非有令人信服的差距证据，或用户明确要求继续，否则不要越过淘汰关卡。

步骤 3：范围检查

评估这个想法应当作为一项技能，还是拆分为多项技能。

拆分信号：

• 该想法会产出多种不同类型的成果
• 该想法跨越 Triple Diamond 阶段（例如 Discover + Deliver）
• 描述中自然包含连接两项活动的“和”

如果适合拆分，请给出建议： “这似乎涵盖两种不同的 PM 活动：

1. [活动 A] → 产出 [成果 A]
2. [活动 B] → 产出 [成果 B] 将它们拆分为独立技能，再通过工作流串联，效果会更好。 你想现在先只继续处理 [活动 A] 吗？”

第 4 步：分类 + 仓库适配

确定技能的分类和命名：

领域技能（特定阶段的 PM 活动）：

• 阶段：discover | define | develop | deliver | measure | iterate
• 目录：{phase}-{skill-name}
• Frontmatter：phase: {phase}（必填），不包含 classification 字段

基础技能（跨阶段使用）：

• 不设阶段
• 目录：foundation-{skill-name}
• Frontmatter：classification: foundation（必填），不包含 phase 字段
• 适用情形：该技能同等适用于多个阶段

实用工具技能（元技能、仓库工具）：

• 不设阶段
• 目录：utility-{skill-name}
• Frontmatter：classification: utility（必填），不包含 phase 字段
• 适用情形：该技能用于操作仓库、工作流或其他技能

方言与范例选择： 首先，从 Skeleton Canon: The Three Sanctioned Dialects 中选择该技能的方言（classic、contract-shaped 或 tool-family）——这会确定必需的标题骨架，之后才能选择范例。不要默认采用“仿照最接近的范例”：范例本身可能存在偏差（大小写变体、多出或缺少章节），直接照搬会将这些偏差带入新技能。

然后，找出 1–2 个使用相同方言且结构最接近的现有技能：

• 相同阶段 > 相同类别 > 类似产物类型
• 阅读它们的 SKILL.md，确认指令风格、输出契约措辞和质量检查清单模式（规范确定必需标题；范例则为其他内容提供参考——语气、步骤粒度，以及技能特有的额外章节）
• 明确列出范例：“仿照 [skill]——相同阶段、[category] 类别、[dialect] 方言”

向用户说明分类、方言和范例选择，并征求确认。

步骤 4.5：评测就绪（评测契约）

新技能必须在交付时具备评测条件，确保覆盖始终跟得上：从第一天起，路由健康度和输出质量都可衡量。在此确定评测契约，然后在步骤 5 中生成相应资产。共四部分：

A. 最相近技能（C-2）。 列出与新技能最相近的 1-3 个技能，即触发条件重叠最多的现有技能。根据步骤 2 的差距分析，以及同阶段／同类别的同类技能来确定。这些技能将用于制定边界指引（见下文）、近似误触发测试用例（步骤 5）和冲突探测（步骤 7）。

B. 双向边界指引（C-3）。 草稿 SKILL.md MUST 包含一个 ## When NOT to Use 章节，列出每个相近技能，并说明何时应改用该技能。对于每个相近技能，还要添加反向指引：在其 SKILL.md 的 "When NOT to Use" 条目中指向新技能。如果重叠程度足以构成需要测量的冲突对，则将该技能对加入 scripts/check-trigger-fixtures.mjs 中的 COLLISION_PAIRS，以便互惠性检查门（check-reciprocal-boundary-pointers.mjs）和冲突探测都能覆盖该技能对。正是这些双向指引，确保了 v2.26.0 重写后没有冲突。

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 值。

D. 测试用例与场景计划（C-1、C-4）。 规划步骤 5 中生成的两个评测资产文件：trigger-fixtures.json（路由）和 output-scenarios/<id>.md（输出质量）。其格式详见步骤 5 第 13-14 项。

生成数据包前，请先向用户提交相近技能、类别和双向指引计划，供其确认。

步骤 5：生成技能实现包

使用 references/TEMPLATE.md 作为格式，生成完整的实现包。 实现包包括：

1. 决策 — 建议 + Why Gate 证据（如适用）
2. 分类 — 类型、阶段（如属于领域）、类别、目录名称
3. 重叠分析 — 找到了什么，以及为什么仍需要此技能
4. 范例技能 — 参考了哪些现有技能，以及原因
5. 草拟 Frontmatter — 完整且有效的 YAML 块。Frontmatter 必须以 --- 开头，并位于文件的第 0 字节处（前面不得有任何内容，包括 HTML 注释、BOM 或空白字符）。任何署名注释都必须放在结束的 --- 分隔符之后，绝不能放在之前。参考：library/skill-output-samples/SAMPLE_CREATION.md 第 5 节。
6. 草拟 SKILL.md — 完整内容（不是大纲），遵循第 4 步方言的规范标题骨架以及所选范例的指令风格
7. 草拟 TEMPLATE.md — 含指导性注释的章节标题
8. 草拟 EXAMPLE.md — 完整且切合实际的示例（150-300 行），包含具体的 PM 场景，填写每个章节，并演示可选章节的填写和跳过方式
9. 草拟命令 — 命令 frontmatter
10. AGENTS.md 条目 — 要添加的确切文本
11. 验证清单 — 根据草稿检查所有 CI 规则
12. 后续步骤 — 本地 CI、测试和贡献工作流
13. 草拟 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 项应是针对第 4.5 步邻近技能的近似请求（标记为 "near_miss_of": "{neighbor}"）。每类约按 60/40 的比例分配到 "split": "train" / "split": "validation"。这是 B-4 fixture 合约（scripts/check-trigger-fixtures.mjs）。
14. 草拟 output-scenario（C-4，输出质量评估）— evals/output-scenarios/{id}.md： frontmatter 为 scenario: {id} / skill: {name} / family: {family from Step 4.5} / created: {date}，随后提供切合实际的输入说明（正文至少 100 个字符），让技能路径和自由发挥对照组使用相同的原始材料。这是 B-7 资源合约（scripts/check-output-eval-assets.mjs）。只有在第 4.5 步尚未确定任何评估标准时，才省略 family。
15. 草拟 HISTORY.md — 包含摘要表格和该技能首个版本的一条基线记录（类型为 baseline）的 HISTORY.md，以及说明该版本所确立合约的 ## 1.0.0 章节。所有版本为 1.0.0 或更高的技能从首个版本起都必须附带此文件，因此 Release 列应记录随某个版本发布的每个版本（docs/internal/skill-versioning.md，“Skill History”）。在 Release 列中填写目标发布版本；如果尚未指定，则填写 -。

步骤 6：写入暂存区

将所有生成的文件写入暂存区：

_staging/pm-skill-builder/{skill-name}/
├── SKILL.md               ← draft skill file
├── HISTORY.md             ← draft version history (baseline row)
├── references/
│   ├── TEMPLATE.md        ← draft template
│   └── EXAMPLE.md         ← draft example
├── evals/
│   ├── trigger-fixtures.json        ← draft routing fixtures (C-1)
│   └── output-scenarios/{id}.md     ← draft output-quality scenario (C-4)
└── command.md             ← draft command

注意：_staging/ 已被 gitignore 忽略——草拟产物不会随发行版发布。 晋升后会丢弃暂存文件夹。

报告写入了哪些内容，以及写入位置。

第 7 步：推广（确认后）

询问：“请检查上面的资料包。准备好后，我会将文件推广到其规范位置。继续吗？[yes/no]”

如果回答 yes，则将每个文件从暂存目录复制到其规范路径：

暂存文件	规范位置
_staging/pm-skill-builder/{skill-name}/SKILL.md	skills/{dir-name}/SKILL.md
_staging/pm-skill-builder/{skill-name}/HISTORY.md	skills/{dir-name}/HISTORY.md
_staging/pm-skill-builder/{skill-name}/references/TEMPLATE.md	skills/{dir-name}/references/TEMPLATE.md
_staging/pm-skill-builder/{skill-name}/references/EXAMPLE.md	skills/{dir-name}/references/EXAMPLE.md
_staging/pm-skill-builder/{skill-name}/evals/trigger-fixtures.json	skills/{dir-name}/evals/trigger-fixtures.json
_staging/pm-skill-builder/{skill-name}/evals/output-scenarios/{id}.md	skills/{dir-name}/evals/output-scenarios/{id}.md
_staging/pm-skill-builder/{skill-name}/command.md	commands/{command-name}.md

其中，{dir-name} 是带分类前缀的目录（例如，deliver-change-communication）。

然后：

1. 创建目标目录：skills/{dir-name}/references/ 和 skills/{dir-name}/evals/output-scenarios/
2. 将每个文件复制到其规范位置
3. 在 AGENTS.md 中追加资料包里的条目；如果第 4.5 步声明了一组冲突配对，则将其添加到 scripts/check-trigger-fixtures.mjs 中的 COLLISION_PAIRS，并在每个相邻技能的 SKILL.md 中添加相互对应的“何时不要使用”条目
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. 如果验证失败，报告错误并保留暂存内容以便修复

设计理由应保留在 GitHub issue、PR 或工作简报中，而不是永久性资料包文件中。

推广后提供以下指导：

• “在本地运行 CI：bash scripts/lint-skills-frontmatter.sh”
• “测试技能：使用真实场景尝试 /{command-name}”
• “如果要贡献：使用 skill-proposal 模板创建 GitHub issue，然后提交 PR”

当前库参考

不要在此文件中手动维护技能清单。 此处的静态表格过去曾与实际目录不一致（最近一次是：整个技能系列未被跟踪，另一个系列缺少一行），因为每新增或移除一个技能，都需要在此处手动编辑。相反，每次运行时都应从以下来源之一获取实时清单：

• skill-manifest.json（仓库根目录）——生成的机器可读文件；包含每个技能的名称、分类、阶段（如有）、类别和描述。
• AGENTS.md——生成的、便于人工浏览的文件；包含按系列分组的同一份目录，每个技能附有简短描述。

每当新增、修改或移除技能时，都会通过 node scripts/gen-skill-manifest.mjs（以及 --agents）重新生成这两个文件，因此它们会与磁盘上的 skills/ 完全一致——不像手写表格，它们不会发生偏差。

以下系列供参考（此处特意不记录数量——请查看清单获取当前总数）：

系列	是否限定阶段？	目录前缀	涵盖内容
领域	是（discover/define/develop/deliver/measure/iterate）	{phase}-	限定于单个 Triple Diamond 阶段的 PM 活动
基础	否	foundation-	跨阶段使用的横切产物（画布、角色、OKR、会议产物、利益相关者沟通、构建前风险审查）
实用工具	否	utility-	对仓库、工作流或其他技能进行操作的元技能/工具类技能（本技能即属此类）
工具	否	tool-	工作坊引导形式（Foundation Sprint 系列、Design Sprint 系列、独立引导形式）

进行差距分析（步骤 2）时，请完整阅读 skill-manifest.json 或 AGENTS.md——涵盖全部四个系列，而不仅是领域和基础系列——再判断是否存在重叠。工具系列最容易被忽略，因为其中没有任何技能与提议中的想法共享阶段名称。

输出约定

构建器 MUST 为新技能生成草稿文件：

• SKILL.md——完整的技能说明（包括一个列出相邻技能的 When NOT to Use 部分，C-3）
• HISTORY.md——版本历史，首个版本须有基线行
• references/TEMPLATE.md——带有指导性注释的输出模板
• references/EXAMPLE.md——完整的演示示例（150-300 行）
• evals/trigger-fixtures.json——路由评测样例（C-1；B-4 约定）
• evals/output-scenarios/{id}.md——输出质量场景 + 系列评分标准（C-4；B-7 约定）
• command.md——斜杠命令文件

所有草稿都写入 _staging/pm-skill-builder/{skill-name}/（已加入 gitignore）。

晋升时，文件会被复制到规范位置，AGENTS.md 会更新，暂存文件夹则会被丢弃。

质量检查清单

完成资料包前，请核实以下两个层级中的所有项目：

CI 验证（必须通过）

• name 与目录名称一致
• 描述为 20-100 个词（单行，不使用多行 YAML）
• 顶层存在 license，且 version 和 updated 存在于 metadata: 下，绝不能位于顶层（lint-skills-frontmatter.sh 会拒绝顶层的 version、updated、phase 或 classification）
• 分类正确，位于 metadata: 下（domain → phase:，foundation/utility/tool → classification:，不得同时存在）
• 目录名称遵循约定：{phase/classification}-{skill-name}
• TEMPLATE.md 至少有 3 个 ## 小节
• 命令文件引用了正确的技能路径
• AGENTS.md 条目使用 #### + **Path:** 格式

质量检查（应通过）

• 差距分析检查了所有现有技能（不只检查同阶段技能）
• Why Gate 的证据具体（指出提示词/场景，而非含糊其辞）
• EXAMPLE.md 是完整产物（150-300 行），而非大纲
• HISTORY.md 为首个版本设置了基线行，并包含匹配的 ## 1.0.0 小节
• 草稿 SKILL.md 中包含输出约定
• 草稿 SKILL.md 中包含质量检查清单

评估契约（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 个近似误报项，并划分训练集/验证集）
• 存在 evals/output-scenarios/{id}.md，其 frontmatter 中的 scenario/skill/family 映射到现有评分标准（或者注明原因，将 family 延后处理）
• 运行碰撞探测（无需密钥）：check-new-skill-collision.mjs --skill={name} --emit-tasks，然后让 pm-skill-router 子 Agent（Haiku）处理生成的查询并应用判定；新技能能够识别自身的触发条件，且不会抢占任何最近邻的触发条件。（无人值守 CI 也可以改用 Messages-API 路径，并设置 ANTHROPIC_API_KEY。）

示例

请参阅 references/EXAMPLE.md，其中提供了完整的技能实现包， 展示了如何创建一个切合实际领域的技能。