bmad-customize

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

BMad Customize

BMad 自定义

Translate the user's intent into a correctly-placed TOML override file under

{project-root}/_bmad/custom/

for a customizable agent or workflow skill. Discover, route, author, write, verify.

Scope v1: per-skill

[agent]

overrides (

bmad-agent-<role>.toml

.user.toml

) and per-skill

[workflow]

overrides (

bmad-<workflow>.toml

.user.toml

). Central config (

{project-root}/_bmad/custom/config.toml

) is out of scope — point users at the How to Customize BMad guide.

When the target's

customize.toml

doesn't expose what the user wants, say so plainly. Don't invent fields.

将用户的意图转换为放置在

{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

）不在当前范围内——请引导用户查看BMad自定义指南。

当目标技能的

customize.toml

未提供用户所需的配置项时，请直接告知用户，不要自行新增字段。

Preflight

预检查

No
```
{project-root}/_bmad/
```
→ BMad isn't installed. Say so, stop.
```
{project-root}/_bmad/scripts/resolve_customization.py
```
missing → continue, but Step 6 verify falls back to manual merge.
Both present → proceed.

不存在
```
{project-root}/_bmad/
```
目录 → 未安装BMad。请告知用户并终止流程。
缺少
```
{project-root}/_bmad/scripts/resolve_customization.py
```
→ 继续执行，但步骤6的验证环节将回退到手动合并方式。
上述两项均存在 → 继续执行。

Activation

激活

Load

_bmad/config.toml

and

_bmad/config.user.toml

from

{project-root}

for

user_name

(default

BMad

) and

communication_language

(default

English

). Greet. If the user's invocation already names a target skill AND a specific change, jump to Step 3.

从

{project-root}

加载

_bmad/config.toml

和

_bmad/config.user.toml

，获取

user_name

（默认值为

BMad

）和

communication_language

（默认值为

English

）。向用户问候。如果用户的请求中已明确指定目标技能和具体修改内容，直接跳至步骤3。

Step 1: Classify intent

步骤1：意图分类

Directed — specific skill + specific change → Step 3.
Exploratory — "what can I customize?" → Step 2.
Audit/iterate — wants to review or change something already customized → Step 2, lead with skills that have existing overrides; read the existing override in Step 3 before composing.
Cross-cutting — could live on multiple surfaces → Step 3, choose agent vs workflow explicitly with the user.

定向型 — 指定具体技能和具体修改 → 步骤3。
探索型 — "我可以自定义哪些内容？" → 步骤2。
审核/迭代型 — 想要查看或修改已有的自定义配置 → 步骤2，优先展示已有覆盖配置的技能；在步骤3中先读取现有覆盖配置再进行编写。
跨领域型 — 修改内容可应用于多个场景 → 步骤3，明确与用户确认选择Agent还是工作流层面的配置。

Step 2: Discovery

步骤2：发现

python3 {skill-root}/scripts/list_customizable_skills.py --project-root {project-root}

Use

--extra-root <path>

(repeatable) if the user has skills installed in additional locations.

Group the returned

agents

and

workflows

for the user; for each show name, description, whether

has_team_override

has_user_override

is true. Surface any

errors[]

. For audit/iterate intents, lead with already-overridden entries.

Empty list: show

scanned_roots

, ask whether skills live elsewhere (offer

--extra-root

); otherwise stop.

python3 {skill-root}/scripts/list_customizable_skills.py --project-root {project-root}

如果用户在其他位置安装了技能，可使用

--extra-root <path>

参数（可重复使用）。

将返回的

agents

和

workflows

分组展示给用户；每个条目需显示名称、描述、

has_team_override

或

has_user_override

是否为true。展示所有

errors[]

信息。对于审核/迭代型意图，优先展示已有覆盖配置的条目。

若返回列表为空：展示

scanned_roots

，询问用户技能是否安装在其他位置（提供

--extra-root

选项）；否则终止流程。

Step 3: Determine the right surface

步骤3：确定合适的配置层面

Read the target's

customize.toml

. Top-level

[agent]

[workflow]

block defines the surface.

If a team or user override already exists, read it first and summarize what's already overridden before composing.

Cross-cutting intent — walk both surfaces with the user:

Every workflow a given agent runs → agent surface (e.g.
```
bmad-agent-pm.toml
```
with
```
persistent_facts
```
,
```
principles
```
).
One workflow only → workflow surface (e.g.
```
bmad-create-prd.toml
```
with
```
activation_steps_prepend
```
).
Several specific workflows → multiple workflow overrides in sequence, not an agent override.

Single-surface heuristic:

Workflow-level: template swap, output path, step-specific behavior, or a named scalar already exposed (
```
*_template
```
,
```
on_complete
```
). Surgical, reliable.
Agent-level: persona, communication style, org-wide facts, menu changes, behavior that should apply to every workflow the agent dispatches.

When ambiguous, present both with tradeoff, recommend one, let the user decide.

Intent outside the exposed surface (step logic, ordering, anything not in

customize.toml

): say so; offer

activation_steps_prepend

append

persistent_facts

as approximations, or recommend

bmad-builder

to create a custom skill.

读取目标技能的

customize.toml

文件。顶层的

[agent]

或

[workflow]

块定义了配置层面。

如果已存在团队或用户覆盖配置，先读取该配置并总结已有的自定义内容，再进行新配置的编写。

跨领域型意图 — 与用户逐一确认两个层面的配置：

某个Agent运行的所有工作流 → Agent层面（例如
```
bmad-agent-pm.toml
```
中的
```
persistent_facts
```
、
```
principles
```
）。
仅单个工作流 → 工作流层面（例如
```
bmad-create-prd.toml
```
中的
```
activation_steps_prepend
```
）。
多个特定工作流 → 依次创建多个工作流覆盖配置，而非Agent层面的覆盖配置。

单一层面配置的判断准则：

工作流层面：模板替换、输出路径、步骤特定行为，或已暴露的命名标量（
```
*_template
```
、
```
on_complete
```
）。精准、可靠。
Agent层面：角色设定、沟通风格、组织全局信息、菜单变更、该Agent调度的所有工作流都需应用的行为。

当存在歧义时，向用户展示两种选项的优缺点，给出推荐方案，由用户决定。

若用户的意图超出了已暴露的配置层面（步骤逻辑、顺序、

customize.toml

中未包含的任何内容）：告知用户；可提供

activation_steps_prepend

append

或

persistent_facts

作为近似方案，或推荐使用

bmad-builder

创建自定义技能。

Step 4: Compose the override

步骤4：编写覆盖配置

Translate plain-English into TOML against the target's

customize.toml

fields. If an existing override was read, frame the change as additive.

Merge semantics:

Scalars (
```
icon
```
,
```
role
```
,
```
*_template
```
,
```
on_complete
```
) — override wins.
Append arrays (
```
persistent_facts
```
,
```
activation_steps_prepend
```
/
```
append
```
,
```
principles
```
) — team/user entries append in order.
Keyed arrays of tables (menu items with
```
code
```
or
```
id
```
) — matching keys replace, new keys append.

Overrides are sparse: only the fields being changed. Never copy the whole

customize.toml

Template swap (

*_template

scalar): offer to copy the default template to

{project-root}/_bmad/custom/{skill-name}-{purpose}-template.md

, point the override at the new path, offer to help edit it.

将用户的自然语言需求转换为符合目标技能

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

，在覆盖配置中指向新路径，并可协助用户编辑该模板。

Step 5: Team or user placement

步骤5：选择团队或用户配置位置

Under

{project-root}/_bmad/custom/

```
{skill-name}.toml
```
— team, committed. Policies, org conventions, compliance.
```
{skill-name}.user.toml
```
— user, gitignored. Personal tone, private facts, shortcuts.

Default by character (policy → team, personal → user), confirm before writing.

在

{project-root}/_bmad/custom/

目录下：

```
{skill-name}.toml
```
— 团队配置，需提交到版本控制。适用于政策、组织规范、合规要求。
```
{skill-name}.user.toml
```
— 用户个人配置，会被Git忽略。适用于个人语气、私人信息、快捷操作。

根据配置内容的性质默认选择（政策类→团队配置，个人类→用户配置），写入前需与用户确认。

Step 6: Show, confirm, write, verify

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

Show the full TOML. If the file exists, show a diff. Never silently overwrite.
Wait for explicit yes.
Write. Create
```
{project-root}/_bmad/custom/
```
if needed.
Verify:
```
python3 {project-root}/_bmad/scripts/resolve_customization.py --skill <install-path> --key <agent-or-workflow>
```
Show the merged output, point out the changed fields.
Resolver missing or fails: read whichever layers exist —
```
<install-path>/customize.toml
```
(base),
```
{project-root}/_bmad/custom/{skill-name}.toml
```
(team),
```
{project-root}/_bmad/custom/{skill-name}.user.toml
```
(user) — apply base → team → user with the same merge rules (scalars override, tables deep-merge,
```
code
```
/
```
id
```
-keyed arrays merge by key, all other arrays append), describe how the changed fields resolve.
Verify shows override didn't land (field unchanged, merge conflict, file not picked up): re-enter Step 4 with the verify output as context. Usually wrong field name, wrong merge mode (scalar vs array), or wrong scope.
Summarize what changed, where the file lives, how to iterate. Remind the user to commit team overrides.

展示完整的TOML配置。如果文件已存在，展示差异内容。禁止静默覆盖。
等待用户明确确认。
写入配置。若
```
{project-root}/_bmad/custom/
```
目录不存在则创建。
验证：
```
python3 {project-root}/_bmad/scripts/resolve_customization.py --skill <install-path> --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数组）或范围错误导致。
总结修改内容、文件位置以及迭代方式。提醒用户提交团队配置到版本控制。

Complete when

完成条件

Override file written (or user explicitly aborted).
User has seen resolver output (or manual fallback merge summary).
User has acknowledged the summary.

Otherwise the skill isn't done — finish or tell the user they're exiting incomplete.

已写入覆盖配置文件（或用户明确终止）。
用户已查看解析器输出（或手动合并的总结内容）。
用户已确认总结信息。

否则技能未完成——需完成流程或告知用户当前流程未完成。

When this skill can't help

此技能无法处理的场景

Central config (
```
{project-root}/_bmad/custom/config.toml
```
) — see the How to Customize BMad guide.
Step logic, ordering, behavior not in
customize.toml
— open a feature request, or use
```
bmad-builder
```
to create a custom skill. Offer to help with either.
Skills without a
customize.toml
— not customizable.

中央配置（
```
{project-root}/_bmad/custom/config.toml
```
）—— 请查看BMad自定义指南。
步骤逻辑、顺序、
customize.toml
中未包含的行为—— 提交功能请求，或使用
```
bmad-builder
```
创建自定义技能。可协助用户完成其中任一操作。
无
customize.toml
文件的技能—— 不可自定义。