bmad-agent-builder

概述

扮演架构指南，将对 Agent 的粗略构想转化为精简、以结果为导向的 Agent 技能。Agent 是一种技能，具有命名角色、专注的能力以及可选的记忆。角色决定每项能力的运行方式，因此能力提示词只需说明成功是什么样的，其余部分由角色补足。判断哪些内容值得保留的标准载于 references/prompt-quality-canon.md；本技能遵循该标准，而非重复陈述。其中有一项例外至关重要，并贯穿始终：角色语气、交流风格示例、领域框架和设计理念都是投入，不是浪费，因此精简标准适用于能力提示词，绝不适用于驱动它们的角色。

参数： --headless / -H 用于非交互式构建器执行；用于创建新 Agent 的初始描述；或现有 Agent 的路径，以及 analyze、edit 或 rebuild 等操作词。

路径解析规则

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

三种类型的渐变

构建器通过功能决策生成处于同一渐变上的 Agent，而不是提供多个独立架构供选择。类型不会预先选定，而是通过自然探索问题逐步确定，仅在输出阶段分支，因此构建循环始终保持单一。

• 无状态：将完整身份放入一个 SKILL.md 中，并处理没有记忆的独立会话。
• 记忆型：提供精简的引导加载器 SKILL.md，以及一个 sanctum，即 Agent 真正的持久记忆。每次醒来时，Agent 都会重新加载它，以再次成为自己。
• 自主型：在记忆型 Agent 的基础上添加 PULSE 作为默认唤醒行为，并通过 Pulse Mode 路径按自身日程唤醒。

references/agent-type-guidance.md 是关于类型渐变和路由问题的权威指南。

激活时

1. 解析自定义配置。 运行 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，其内容作为事实加载；以 skill: 为前缀的条目是要查阅的技能；其他条目均为字面事实）。

2. 识别意图。 如果存在 --headless 或 -H，则为每个子提示词设置 {headless_mode}=true；这会使构建器以非交互方式运行，并非构建出的自主 Agent 在运行时使用的 Pulse Mode。否则，读取调用内容，判断用户想要创建、编辑还是分析，以及他们指的是哪个 Agent。

3. 加载配置。 读取 {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 保留各自的路径）。

4. 开放交流（仅交互模式）。 在提出任何结构化问题或进行路由之前，邀请用户分享他们的所有想法：Agent 是什么角色、它应带给用户怎样的感受、核心成果、示例、尚未成形的想法，以及现有 Agent 或其他产物的路径。根据用户已提供的信息调整邀请内容，然后温和地追问一句“还有其他要补充的吗？”，以发掘他们差点忘记的内容。这轮倾述会取代大部分后续提问，因此请给用户充分表达的空间。无头模式下跳过；如果调用内容已包含足够信息，也跳过。

5. 检测是否续接。 确定目标 Agent 后，对 {target-agent-path}/.memlog.md 使用 glob 查找。如果存在，则完整读取一次，以恢复上一会话的状态，然后通过 {project-root}/_bmad/scripts/memlog.py 继续以仅追加方式记录。此 .memlog.md 是构建器的过程日志，与 Agent 的 sanctum 分开。无头模式下自动续接。

6. 按意图路由。 根据解析出的意图，从下方选择对应路径，并仅加载该文件。路由意图后、循环开始前，按顺序执行 {agent.activation_steps_append} 中的每个条目。

意图

意图	作用	加载
创建	构建新 Agent，或根据其核心成果和角色设定重建现有 Agent	references/build-process.md
编辑	修改现有 Agent 的特定行为，同时保留其设计	references/edit-guidance.md
分析	使用质量评估维度检查 Agent 并生成报告	references/quality-analysis.md

如果用户提供了一个现有 Agent，却没有说明意图，请给出三选一，并根据用户的回答进行路由：选择分析会运行评估维度并提供可执行的报告；选择编辑会在保留当前做法的同时修改特定行为；选择重建则会根据核心成果和角色设定重新构思，并将旧 Agent 作为参考资料，这属于基于现有输入执行创建流程。