bmad-customize

BMad Customize

将用户意图转换为位于 {project-root}/_bmad/custom/ 下、位置正确的 TOML 覆盖文件，用于可自定义的 Agent 或工作流技能。发现、路由、撰写、写入、验证。

v1 范围：按技能的 [agent] 覆盖（bmad-agent-<role>.toml / .user.toml）以及按技能的 [workflow] 覆盖（bmad-<workflow>.toml / .user.toml）。中央配置（{project-root}/_bmad/custom/config.toml）不在范围内——请将用户引导至 How to Customize BMad guide。

当目标的 customize.toml 未暴露用户想要的内容时，请如实说明。不要臆造字段。

Preflight

• 不存在 {project-root}/_bmad/ → 此处未设置 BMad。提议运行 bmad 技能的 setup，如果尚未安装 bmad，请先安装（npx skills add bmad-code-org/BMAD-METHOD --skill bmad）。如果用户拒绝，则停止。
• 缺少 {project-root}/_bmad/scripts/resolve_customization.py → 继续，但 Step 6 的验证回退为手动合并。
• 两者均存在 → 继续。

Activation

向用户问好。如果用户的调用已经同时指明了目标技能和具体变更，跳到 Step 3。

Step 1: Classify intent

• Directed——具体技能 + 具体变更 → Step 3。
• Exploratory——“我可以自定义什么？” → Step 2。
• Audit/iterate——想要查看或更改已经自定义过的内容 → Step 2，优先列出已有覆盖的技能；在 Step 3 中于撰写之前先读取现有覆盖。
• Cross-cutting——可能落在多个层面 → Step 3，与用户明确选择 Agent 还是工作流。

Step 2: Discovery

uv run {skill-root}/scripts/list_customizable_skills.py --project-root {project-root}

如果用户在额外位置安装了技能，请使用 --extra-root <path>（可重复）。

将返回的 agents 和 workflows 分组展示给用户；对于每一项，显示名称、描述，以及 has_team_override 或 has_user_override 是否为 true。呈现任何 errors[]。对于 audit/iterate 意图，优先列出已被覆盖的条目。

列表为空：显示 scanned_roots，询问技能是否位于其他位置（提供 --extra-root）；否则停止。

Step 3: Determine the right surface

读取目标的 customize.toml。顶层 [agent] 或 [workflow] 块定义了层面。

如果团队或用户覆盖已存在，请先读取它，并在撰写之前总结已被覆盖的内容。

Cross-cutting 意图——与用户一起走查两个层面：

• 某个 Agent 运行的每个工作流 → Agent 层面（例如 bmad-agent-pm.toml 配合 persistent_facts、principles）。
• 仅一个工作流 → 工作流层面（例如 bmad-prd.toml 配合 activation_steps_prepend）。
• 若干具体工作流 → 依次使用多个工作流覆盖，而非 Agent 覆盖。

单一层面启发式：

• 工作流级别：模板替换、输出路径、特定步骤行为，或已暴露的具名标量（*_template、on_complete）。精准、可靠。
• Agent 级别：人设、沟通风格、组织范围的事实、菜单变更、应适用于该 Agent 调度的每个工作流的行为。

当存在歧义时，呈现两者及其权衡，推荐其一，让用户决定。

意图超出已暴露层面（步骤逻辑、顺序、任何不在 customize.toml 中的内容）：如实说明；提供 activation_steps_prepend/append 或 persistent_facts 作为近似方案，或者，如果已安装 BMad Builder 模块，推荐使用 bmad-workflow-builder 创建自定义技能。

第 4 步：编写覆盖配置

将通俗英语翻译为符合目标 customize.toml 字段的 TOML。如果读取到了已有的覆盖配置，则将变更描述为增量式。

合并语义：

• 标量（icon、role、*_template、on_complete）——覆盖配置优先。
• 追加数组（persistent_facts、activation_steps_prepend/append、principles）——团队/用户条目按顺序追加。
• 带键的表数组（带 code 或 id 的菜单项）——键匹配则替换，新键则追加。

覆盖配置是稀疏的：仅包含正在变更的字段。切勿复制整个 customize.toml。

模板替换（*_template 标量）：主动提出将默认模板复制到 {project-root}/_bmad/custom/{skill-name}-{purpose}-template.md，将覆盖配置指向新路径，并主动提出帮助编辑它。

第 5 步：团队或用户放置位置

在 {project-root}/_bmad/custom/ 下：

• {skill-name}.toml —— 团队，纳入提交。策略、组织约定、合规要求。
• {skill-name}.user.toml —— 用户，被 gitignore。个人语气、私密事实、快捷方式。

按性质设定默认值（策略 → 团队，个人 → 用户），写入前先确认。

第 6 步：展示、确认、写入、验证

1. 展示完整的 TOML。如果文件已存在，展示 diff。切勿静默覆盖。

2. 等待明确的 yes。

3. 写入。如需要，创建 {project-root}/_bmad/custom/。

4. 验证：

   uv run {project-root}/_bmad/scripts/resolve_customization.py --skill <install-path> --project-root {project-root} --key <agent-or-workflow>
   

   展示合并后的输出，指出已变更的字段。

   解析器缺失或失败： 读取存在的各层——<install-path>/customize.toml（基础）、{project-root}/_bmad/custom/{skill-name}.toml（团队）、{project-root}/_bmad/custom/{skill-name}.user.toml（用户）——按基础 → 团队 → 用户应用相同的合并规则（标量覆盖、表深度合并、code/id 键控数组按键合并、所有其他数组追加），描述已变更字段如何解析。

   验证显示覆盖配置未生效（字段未变、合并冲突、文件未被读取）：以验证输出为上下文重新进入第 4 步。通常是字段名错误、合并模式错误（标量 vs 数组）或作用域错误。

5. 总结变更内容、文件位置、如何迭代。提醒用户提交团队覆盖配置。

完成条件

• 覆盖文件已写入（或用户明确中止）。
• 用户已看到解析器输出（或手动回退合并摘要）。
• 用户已确认摘要。

否则该技能不算完成——请完成它，或告知用户他们正在不完整地退出。

此技能无法提供帮助的情况

• 中央配置（{project-root}/_bmad/custom/config.toml）——参见如何自定义 BMad 指南。
• 步骤逻辑、顺序、行为不在 customize.toml 中——提交功能请求，或者，如果已安装 BMad Builder 模块，使用 bmad-workflow-builder 创建自定义技能。可主动提出帮助处理其中任一情况。
• 没有 customize.toml 的技能——不可自定义。