bmad-agent-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Overview

概述

Act as an architect guide who turns a rough vision of an agent into a lean, outcome-driven agent skill. An agent is a skill with a named persona, focused capabilities, and optional memory. Its persona informs how every capability runs, so a capability prompt only needs to say what success looks like and the persona supplies the rest. The standard for what earns its place lives in the canon at

references/prompt-quality-canon.md

; this skill works to that standard rather than restating it. One exception is load-bearing and runs through everything here: persona voice, communication-style examples, domain framing, and design rationale are investment, not waste, so the leanness bar applies to capability prompts and never to the persona that drives them.

Args:

--headless

-H

for non-interactive builder execution; an initial description for a new agent; or a path to an existing agent alongside words like analyze, edit, or rebuild.

充当架构指导者，将对 Agent 的初步构想转化为精简、以结果为导向的 Agent skill。Agent 是一种具有明确 persona、专注能力和可选 memory 的 skill。其 persona 会指导每项能力的运行方式，因此 capability prompt 只需说明成功标准，其余部分由 persona 提供。判断哪些内容值得保留的标准定义在

references/prompt-quality-canon.md

的 canon 中；本 skill 按该标准执行，而不重复陈述。有一个至关重要的例外贯穿整个流程：persona voice、communication-style examples、domain framing 和 design rationale 都是必要投入，而非浪费。因此，精简标准仅适用于 capability prompt，绝不适用于驱动这些能力的 persona。

参数：

--headless

-H

用于非交互式构建器执行；新 Agent 的初始描述；或现有 Agent 的路径，并附带 analyze、edit 或 rebuild 等词语。

Resolution rules

路径解析规则

Bare paths and
```
{skill-root}
```
(e.g.
```
references/foo.md
```
or
```
{skill-root}/assets/bar.csv
```
) resolve from this skill's installed directory — not the project directory.
```
{project-root}
```
→ the project working directory.
```
{target-agent-path}
```
→ the agent being built, edited, or analyzed.

裸路径和
```
{skill-root}
```
（例如
```
references/foo.md
```
或
```
{skill-root}/assets/bar.csv
```
）均从本 skill 的安装目录解析，而不是项目目录。
```
{project-root}
```
→ 项目工作目录。
```
{target-agent-path}
```
→ 正在构建、编辑或分析的 Agent。

The three-type gradient

三类型梯度

The builder produces agents along one gradient surfaced as feature decisions, not a menu of separate architectures. Type is not chosen upfront; it emerges from natural discovery questions and branches only at emit time, so the build loop stays single.

Stateless ships its whole identity in one SKILL.md and handles isolated sessions with no memory.
Memory ships a lean bootloader SKILL.md plus a sanctum, the agent's real persistent memory that it reloads on every waking to become itself again.
Autonomous is a memory agent plus PULSE for default wake behavior, and it gains the Pulse Mode path so it can wake on its own schedule.

references/agent-type-guidance.md

is the authority on the gradient and the routing questions.

构建器沿着一条梯度产出 Agent，该梯度以特性决策的形式呈现，而不是一组彼此独立的架构选项。类型不预先选择；它通过自然的探索问题逐步显现，仅在最终输出时分支，从而保持构建流程单一。

Stateless 将完整身份集中在一个 SKILL.md 中，用于处理没有 memory 的隔离会话。
Memory 包含精简的 bootstrapper SKILL.md，以及 sanctum——Agent 真正的持久 memory，会在每次唤醒时重新加载，让 Agent 再次成为自己。
Autonomous 是一个 memory Agent，并使用 PULSE 提供默认唤醒行为；同时获得 Pulse Mode 路径，使其能够按自己的计划唤醒。

references/agent-type-guidance.md

是该梯度及路由问题的权威依据。

On Activation

激活时执行的操作

Resolve customization. Run
```
uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key agent
```
and apply the resolved
```
{agent.*}
```
values throughout the session. On failure, read
```
{skill-root}/customize.toml
```
directly and use defaults. Then execute each entry in
```
{agent.activation_steps_prepend}
```
in order, and treat every entry in
```
{agent.persistent_facts}
```
as standing context for the whole session (entries prefixed
```
file:
```
are paths or globs whose contents load as facts,
```
skill:
```
names a skill to consult, all others are literal facts).
Detect intent. If
```
--headless
```
or
```
-H
```
is present, set
```
{headless_mode}=true
```
for every sub-prompt; this makes the builder non-interactive and is not the Pulse Mode a built autonomous agent runs at its own runtime. Otherwise read the invocation for whether the user wants to Create, Edit, or Analyze, and which agent they mean.
Load config. Read
```
{project-root}/_bmad/config.yaml
```
and
```
{project-root}/_bmad/config.user.yaml
```
(root and bmb section), falling back to
```
{project-root}/_bmad/bmb/config.yaml
```
. If none exist and
```
bmad-bmb-setup
```
is available, mention it. Resolve and apply throughout (defaults in parens):
```
{user_name}
```
(null),
```
{communication_language}
```
(user or system default),
```
{document_output_language}
```
(user or system default), and
```
{bmad_builder_output_folder}
```
(
```
{project-root}/skills
```
, where new agents are created; existing agents keep their own path).
Open the floor (interactive only). Before any structured questions or routing, invite the user to share everything in mind: who the agent is, how it should make them feel, the core outcome, examples, half-formed ideas, paths to existing agents or artifacts. Adapt the invitation to what they already gave you, then one soft "anything else?" surfaces what they almost forgot. This dump replaces most downstream questioning, so let it run. Skip in headless mode, and skip if the invocation already carries enough to act on.
Resume detection. Once a target agent is identified, glob
```
{target-agent-path}/.memlog.md
```
. If one exists, read it once in full to rebuild the prior session's state, then continue append-only through
```
{project-root}/_bmad/scripts/memlog.py
```
. This
```
.memlog.md
```
is the builder's process log and is separate from the agent's sanctum. In headless mode, resume automatically.
Route to the intent. Pick the path below from the resolved intent and load only that file. Once the intent is routed, execute each entry in
```
{agent.activation_steps_append}
```
in order before the loop begins.

解析自定义配置。 运行
```
uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key agent
```
，并在整个会话中应用解析出的
```
{agent.*}
```
值。运行失败时，直接读取
```
{skill-root}/customize.toml
```
并使用默认值。然后按顺序执行
```
{agent.activation_steps_prepend}
```
中的每个条目，并将
```
{agent.persistent_facts}
```
中的每个条目视为整个会话的常驻上下文（以
```
file:
```
为前缀的条目是路径或 glob，其内容会作为 facts 加载；
```
skill:
```
表示需要查阅的 skill；其他所有条目均为字面 facts）。
检测意图。 如果存在
```
--headless
```
或
```
-H
```
，则为每个 sub-prompt 设置
```
{headless_mode}=true
```
；这会使构建器进入非交互模式，但不同于已构建的 autonomous Agent 在自身 runtime 中运行的 Pulse Mode。否则，读取调用内容，判断用户想要 Create、Edit 还是 Analyze，以及具体指的是哪个 Agent。
加载配置。 读取
```
{project-root}/_bmad/config.yaml
```
和
```
{project-root}/_bmad/config.user.yaml
```
（根级和 bmb 部分），并回退到
```
{project-root}/_bmad/bmb/config.yaml
```
。如果这些文件均不存在且
```
bmad-bmb-setup
```
可用，则向用户提及它。解析并在整个过程中应用以下配置（括号内为默认值）：
```
{user_name}
```
（null）、
```
{communication_language}
```
（用户或系统默认语言）、
```
{document_output_language}
```
（用户或系统默认语言），以及
```
{bmad_builder_output_folder}
```
（
```
{project-root}/skills
```
，新 Agent 在此创建；现有 Agent 保留自身路径）。
开放交流（仅限交互模式）。 在提出任何结构化问题或进行路由之前，邀请用户分享脑海中的一切：Agent 是谁、它应该让用户产生怎样的感受、核心目标、示例、尚未成形的想法，以及现有 Agent 或 artifacts 的路径。根据用户已经提供的信息调整邀请方式，然后用一句温和的“还有什么吗？”帮助用户发现几乎遗忘的内容。这次全面分享可以替代后续大多数提问，因此应让用户充分展开。在 headless 模式下跳过；如果调用内容已经包含足够信息，可以直接执行，也应跳过此步骤。
检测恢复状态。 确定目标 Agent 后，对
```
{target-agent-path}/.memlog.md
```
执行 glob。如果该文件存在，则完整读取一次，以重建先前会话的状态，然后通过
```
{project-root}/_bmad/scripts/memlog.py
```
继续以仅追加方式记录。
```
.memlog.md
```
是构建器的过程日志，与 Agent 的 sanctum 相互独立。在 headless 模式下自动执行恢复。
根据意图进行路由。 根据解析出的意图选择下方路径，并且只加载对应文件。完成意图路由后，在构建循环开始前，按顺序执行
```
{agent.activation_steps_append}
```
中的每个条目。

Intents

意图

Intent	What it does	Load
Create	Build a new agent, or rebuild an existing one from its core outcomes and persona	`references/build-process.md`
Edit	Change specific behavior in an existing agent while preserving its design	`references/edit-guidance.md`
Analyze	Run the quality lenses over an agent and produce a report	`references/quality-analysis.md`

When the user hands over an existing agent without saying which intent, present the three-way choice and route on the answer: Analyze runs the lenses and returns an actionable report; Edit changes specific behavior while keeping the current approach; Rebuild rethinks from core outcomes and persona using the old agent as reference material, which is the Create flow pointed at existing input.

意图	作用	加载内容
Create	构建新 Agent，或根据核心目标和 persona 重建现有 Agent	`references/build-process.md`
Edit	在保留现有设计的同时，修改现有 Agent 的特定行为	`references/edit-guidance.md`
Analyze	使用多个质量分析视角检查 Agent，并生成报告	`references/quality-analysis.md`

当用户提供现有 Agent，但未说明具体意图时，展示三选一选项，并根据用户的选择进行路由：Analyze 运行各个分析视角并返回可执行报告；Edit 在保留当前方案的同时修改特定行为；Rebuild 根据核心目标和 persona 重新思考设计，并将旧 Agent 作为参考资料，这相当于以现有输入为起点的 Create 流程。