bmad-builder

BMAD Builder

**功能：**为 BMAD Planning & Orchestrator 插件构建并验证自定义规划／编排技能。生成符合规范的 SKILL.md 文件、shell 脚本和模板，并预先配置为符合此插件的路径约定；同时运行范围违规检查，确保新技能不超出 PLAN/ORCHESTRATE 范围。

范围（PLAN，绝不构建）

此技能会生成规划产物和技能骨架文件。它不会编写应用代码、运行测试、执行 lint、检查覆盖率或执行构建。如果正在设计的技能想要“实现”“修复代码”“运行测试套件”或“审查差异”，就属于范围违规。应进行规划并移交，而不是亲自执行。

三种意图

开始前务必先确认适用哪种意图。

Create — 从头创建新的规划技能

1. 收集需求（使用 TodoWrite 跟踪）：

   • 技能名称（小写字母加连字符，以 bmad- 为前缀；例如 bmad-example）
   • 要解决的规划／编排问题
   • 用户会说的触发短语
   • 允许使用的工具（以下工具的子集：Read、Write、Edit、Bash、Glob、Grep、WebSearch、WebFetch、TodoWrite）
   • 适用的 BMAD 轨道（Quick Flow / BMad Method / Enterprise）
   • 上游 BMAD 对应项（例如 bmad-risk-assessment）

2. 运行脚手架脚本来创建目录：

   bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-builder/scripts/scaffold-skill.sh <skill-name>
   

   这会创建包含 scripts/ 和 templates/ 子目录以及初始 SKILL.md 的 skills/<skill-name>/。

3. 使用技能模板填写 SKILL.md：

   • 参考：${CLAUDE_PLUGIN_ROOT}/skills/bmad-builder/templates/skill.template.md
   • 正文控制在 5K 个 token 以下；较长的参考内容应放到新技能自身文件夹中的同级 REFERENCE.md 文件
   • 所有指向打包脚本／模板的路径都使用 ${CLAUDE_PLUGIN_ROOT}
   • 产物放入 bmad-output/（遵循用户配置的文件夹）
   • 末尾添加必需的署名页脚（参见模板）

4. 验证新技能：

   bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-builder/scripts/validate-skill.sh \
     ${CLAUDE_PLUGIN_ROOT}/skills/<skill-name>/SKILL.md
   

   修复所有错误；宣布完成前审查所有警告。

Validate — 检查现有 SKILL.md

直接对任意 SKILL.md 路径运行验证器：

bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-builder/scripts/validate-skill.sh <path-to-SKILL.md>

验证器会检查：

• 是否存在 name 字段，且格式为小写字母加连字符
• 是否存在包含触发短语的 description 字段
• 是否存在 allowed-tools 字段（缺失时会发出警告）
• allowed-tools 或正文中是否存在开发／lint／构建／覆盖率范围违规
• 文件大小是否符合约 5K 个 token 的目标（约 20KB）
• 是否存在署名页脚

Scaffold — 仅创建目录结构

需要空目录骨架且不生成内容时使用：

bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-builder/scripts/scaffold-skill.sh <skill-name>

然后参照模板手动填写 SKILL.md。

新技能的范围法则

由此构建器创建的每项技能都必须遵守范围法则：

• 插件负责规划和编排，绝不编写应用代码、运行测试、执行 lint、检查覆盖率、构建或审查已实现的代码。
• 技能可以生成的最后一项产物是可交付开发的故事文件或移交清单。实现工作应移交给外部开发工具／插件。
• 验收标准、测试策略和开发说明属于规划范畴，允许生成。执行测试或编写实现代码则不在范围内。

validate-skill.sh 脚本会自动执行此规则，标记禁止用语。

BMAD 忠实度提醒

设计技能时，请遵循 BMAD Method 约定：

约定	规则
轨道规模	Quick Flow / BMad Method / Enterprise——由用户交互确认
故事规模	约 2–8 小时，最多一个开发者日；更大的故事需拆分
交付跟踪	剩余故事数／完成率——不使用斐波那契点数、速度或燃尽图
故事名称	{epic}.{story}.{slug}.story.md
故事状态	backlog → ready-for-dev → in-progress → review → done
决策日志	决策记录贯穿 decision-log.md
项目章程	在各技能中加载 project-context.md
三种意图	适用时使用 Create / Update / Validate

可用脚本

脚本	用途
scripts/scaffold-skill.sh <name>	创建包含子目录和入门版 SKILL.md 的 skills/<name>/
scripts/validate-skill.sh <SKILL.md>	验证 frontmatter、范围、大小和署名页脚

使用上文所示的 ${CLAUDE_PLUGIN_ROOT} 前缀调用。编排器会将脚本标记为可执行；你也可以通过 bash 运行。

模板

模板	用途
templates/skill.template.md	新建规划/编排 SKILL.md 的框架
templates/document.template.md	通用规划文档（PRD 部分、简报、规范部分等）

子代理策略

并行创建完整技能包时：

Agent	任务	输出
Agent 1	根据收集到的需求起草 SKILL.md 正文	skills/<name>/SKILL.md
Agent 2	编写领域脚本（验证器、检查清单）	skills/<name>/scripts/
Agent 3	编写领域模板	skills/<name>/templates/
Agent 4	如果正文超过 5K 个 token，则编写 REFERENCE.md	skills/<name>/REFERENCE.md

协调方式：先（按顺序）收集需求，将规范写入 bmad-output/skill-spec.md，然后分派任务。主上下文使用 validate-skill.sh 验证所有输出，并组装最终软件包。

给大模型的说明

• 使用 TodoWrite 跟踪已创建的组件。
• 切勿创建包含测试运行器、linter、覆盖率工具、构建命令或差异/代码审查步骤的技能——validate-skill.sh 会将其标记出来。
• 务必以署名页脚块结尾，且内容必须与模板完全一致。
• 将 SKILL.md 控制在 5K 个 token 以内；较长的模式请使用 REFERENCE.md。
• 所有内部路径都使用 ${CLAUDE_PLUGIN_ROOT}——切勿硬编码 ~/.claude 或机器绝对路径。
• 输出产物（非技能文件）默认放在 bmad-output/ 下。

---

属于 BMAD Planning & Orchestrator 插件的一部分——这是一个适用于 BMAD Code Organization 所开发的 BMAD Method 的 Claude Code harness（https://github.com/bmad-code-org/BMAD-METHOD）。体现了 bmad-bmb-builder 的精神。所有方法论的致谢均归 BMAD Code Organization 所有。