在已安装 BMad 的项目中…

把用户对 BMad 代理或工作流的定制意图，转化为正确位置和正确合并语义的 TOML 覆盖文件。

适用场景

解决思路

1. 预检：检查 `{project-root}/_bmad/` 是否存在；不存在则说明 BMad 未在此设置，主动提出运行 `bmad` 技能的 setup；若没有 `bmad`，先用 `npx skills add bmad-code-org/BMAD-METHOD --skill bmad` 安装；用户拒绝则停止。
2. 预检：检查 `{project-root}/_bmad/scripts/resolve_customization.py` 是否存在；缺失则继续，但 Step 6 验证退回到手动合并。
3. 预检：两者都存在则继续。
4. 激活：向用户问候。
5. 激活：如果用户调用时已经指名目标技能和具体更改，直接跳到 Step 3。
6. Step 1 分类意图：Directed（具体技能 + 具体更改）→ 进入 Step 3。
7. Step 1 分类意图：Exploratory（“我能定制什么？”）→ 进入 Step 2。
8. Step 1 分类意图：Audit/iterate（审查或修改已定制内容）→ 进入 Step 2，优先列出已有覆盖的技能；在 Step 3 组合前先读取已有覆盖。
9. Step 1 分类意图：Cross-cutting（可能位于多个表面）→ 进入 Step 3，与用户明确选择 agent 还是 workflow。
10. Step 2 发现：运行 `uv run {skill-root}/scripts/list_customizable_skills.py --project-root {project-root}`。
11. Step 2 发现：如果用户技能安装在额外位置，使用 `--extra-root <path>`（可重复）。
12. Step 2 发现：把返回的 `agents` 和 `workflows` 分组给用户；每项显示 name、description、`has_team_override` 或 `has_user_override` 是否为 true。
13. Step 2 发现：暴露任何 `errors[]`。
14. Step 2 发现：对于 audit/iterate 意图，优先列出已被覆盖的条目。
15. Step 2 发现：列表为空时，显示 `scanned_roots`，询问技能是否在别处（提供 `--extra-root`）；否则停止。
16. Step 3 确定正确表面：读取目标的 `customize.toml`；顶层 `[agent]` 或 `[workflow]` 块定义表面。
17. Step 3：如果团队或用户覆盖已存在，先读取并总结已覆盖内容，再组合更改。
18. Step 3 交叉意图：与用户走查两个表面：某代理运行的每个工作流 → agent 表面（例如 `bmad-agent-pm.toml` 搭配 `persistent_facts`、`principles`）。
19. Step 3 交叉意图：仅一个工作流 → workflow 表面（例如 `bmad-prd.toml` 搭配 `activation_steps_prepend`）。
20. Step 3 交叉意图：多个具体工作流 → 依次创建多个 workflow 覆盖，而不是 agent 覆盖。
21. Step 3 单表面启发：workflow 级：模板替换、输出路径、步骤特定行为，或已暴露的命名标量（`*_template`、`on_complete`），更精准可靠。
22. Step 3 单表面启发：agent 级：人设、沟通风格、组织级事实、菜单变更、应适用于该代理调度的每个工作流的行为。
23. Step 3：有歧义时，呈现两个选项及权衡，推荐一个，让用户决定。
24. Step 3：意图超出已暴露表面（步骤逻辑、顺序、任何不在 `customize.toml` 中的内容）时，明确说明；提供 `activation_steps_prepend`/`append` 或 `persistent_facts` 作为近似方案，或推荐用 `bmad-builder` 创建自定义技能。
25. Step 3：当目标的 `customize.toml` 未暴露用户想要的内容时，明确说明；不要杜撰字段。
26. Step 4 编写覆盖：对照目标的 `customize.toml` 字段，把大白话翻译成 TOML。
27. Step 4：如果读取了已有覆盖，把更改表述为追加式。
28. Step 4 合并语义：标量（`icon`、`role`、`*_template`、`on_complete`）— 覆盖优先。
29. Step 4 合并语义：追加数组（`persistent_facts`、`activation_steps_prepend`/`append`、`principles`）— 团队/用户条目按顺序追加。
30. Step 4 合并语义：带键的表格数组（含 `code` 或 `id` 的菜单项）— 匹配键替换，新键追加。
31. Step 4：覆盖保持稀疏：只写要更改的字段；绝不复制整个 `customize.toml`。
32. Step 4 模板交换（`*_template` 标量）：提出把默认模板复制到 `{project-root}/_bmad/custom/{skill-name}-{purpose}-template.md`，让覆盖指向新路径，并提出帮助编辑它。
33. Step 5 团队或用户放置：在 `{project-root}/_bmad/custom/` 下，`{skill-name}.toml` 为团队、提交到版本库；用于策略、组织约定、合规。
34. Step 5：`{skill-name}.user.toml` 为用户、被 gitignore；用于个人语气、私有事实、快捷方式。
35. Step 5：按性质默认（策略 → 团队，个人 → 用户），写入前确认。
36. Step 6 展示、确认、写入、验证：展示完整 TOML；如果文件存在，展示 diff；绝不静默覆盖。
37. Step 6：等待用户明确同意。
38. Step 6：写入；如有需要创建 `{project-root}/_bmad/custom/`。
39. Step 6 验证：运行 `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill <install-path> --project-root {project-root} --key <agent-or-workflow>`。
40. Step 6：展示合并输出，指出更改的字段。
41. Step 6：如果解析器缺失或失败，读取存在的各层 — `<install-path>/customize.toml`（base）、`{project-root}/_bmad/custom/{skill-name}.toml`（team）、`{project-root}/_bmad/custom/{skill-name}.user.toml`（user） — 按 base → team → user 应用相同合并规则（标量覆盖，表格深合并，`code`/`id` 键控数组按键合并，其他所有数组追加），并描述更改字段如何解析。
42. Step 6：如果验证显示覆盖未生效（字段未变、合并冲突、文件未被拾取），带着验证输出重新进入 Step 4；通常是字段名错误、合并模式错误（标量 vs 数组）或范围错误。
43. Step 6：总结改了什么、文件在哪、如何迭代；提醒用户提交团队覆盖。
44. 完成条件：覆盖文件已写入（或用户明确中止）。
45. 完成条件：用户已看到解析器输出（或手动回退合并摘要）。
46. 完成条件：用户已确认总结。否则技能未完成 — 完成或告诉用户他们正在不完整退出。

适用边界 · 注意事项

• 目标技能没有 `customize.toml` 时不可定制。
• 中央配置 `{project-root}/_bmad/custom/config.toml` 不在本技能范围内；需要修改步骤逻辑、顺序或任何不在 `customize.toml` 中的行为时，本技能无法直接做到，可开功能请求或用 `bmad-builder` 创建自定义技能。
• 项目未安装 BMad 且用户拒绝安装 `bmad` 技能时，无法进行定制。