From 459833ce752930769ac1eb041441ad5087a89b83 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Mon, 20 Apr 2026 21:27:30 -0500 Subject: [PATCH] docs(customization): point users at bmad-customize as the guided path Surface the new bmad-customize skill across the three customization docs so users know they don't need to hand-author TOML to benefit from the surface: - customize-bmad.md: prominent tip at the top introducing the skill as the guided authoring helper; updated the "Need to see what's customizable?" troubleshooting tip to recommend the skill first - expand-bmad-for-your-org.md: tip under prereqs noting every recipe can be applied via the skill, with the recipes remaining the reference for what to override - named-agents.md: short paragraph in the customization section and a link entry under the references list Hand-authoring still works the same way; the skill is additive. Central-config overrides are flagged as the current exception. --- docs/explanation/named-agents.md | 3 +++ docs/how-to/customize-bmad.md | 7 ++++++- docs/how-to/expand-bmad-for-your-org.md | 4 ++++ 3 files changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/explanation/named-agents.md b/docs/explanation/named-agents.md index 5f8a96774..e5a92511c 100644 --- a/docs/explanation/named-agents.md +++ b/docs/explanation/named-agents.md @@ -75,6 +75,8 @@ The customization model is what lets this scale beyond a single developer. Every agent ships a `customize.toml` with sensible defaults. Teams commit overrides to `_bmad/custom/bmad-agent-{role}.toml`. Individuals can layer personal preferences in `.user.toml` (gitignored). The resolver merges all three at activation time with predictable structural rules. +Most users never hand-author these files. The `bmad-customize` skill walks through picking the target, choosing agent vs workflow scope, authoring the override, and verifying the merge — so the customization surface stays accessible to anyone who understands their intent, not just those fluent in TOML. + Concrete example: a team commits a single file telling Amelia to always use the Context7 MCP tool for library docs and to fall back to Linear when a story isn't in the local epics list. Every dev workflow Amelia dispatches (dev-story, quick-dev, create-story, code-review) inherits that behavior, with no source edits or per-workflow duplication required. There's also a second customization surface for *cross-cutting* concerns: the central `_bmad/config.toml` and `_bmad/config.user.toml` (both installer-owned, rebuilt from each module's `module.yaml`) plus `_bmad/custom/config.toml` (team, committed) and `_bmad/custom/config.user.toml` (personal, gitignored) for overrides. This is where the **agent roster** lives — the lightweight descriptors that roster consumers like `bmad-party-mode`, `bmad-retrospective`, and `bmad-advanced-elicitation` read to know who's available and how to embody them. Rebrand an agent org-wide with a team override; add fictional voices (Kirk, Spock, a domain expert persona) as personal experiments via the `.user.toml` override — without touching any skill folder. The per-skill file shapes how Mary *behaves* when she activates; the central config shapes how other skills *see* her when they look at the field. @@ -83,6 +85,7 @@ For the full customization surface and worked examples, see: - [How to Customize BMad](../how-to/customize-bmad.md) — the reference for what's customizable and how merge works - [How to Expand BMad for Your Organization](../how-to/expand-bmad-for-your-org.md) — five worked recipes spanning agent-wide rules, workflow conventions, external publishing, template swaps, and agent roster customization +- `bmad-customize` skill — the guided authoring helper that turns intent into a correctly-placed, verified override file ## The Bigger Idea diff --git a/docs/how-to/customize-bmad.md b/docs/how-to/customize-bmad.md index 18a3a0bbb..3a7509df9 100644 --- a/docs/how-to/customize-bmad.md +++ b/docs/how-to/customize-bmad.md @@ -7,6 +7,10 @@ sidebar: Tailor agent personas, inject domain context, add capabilities, and configure workflow behavior -- all without modifying installed files. Your customizations survive every update. +:::tip[Don't want to hand-author TOML? Use `bmad-customize`] +The `bmad-customize` skill is a guided authoring helper for the customization surface described in this doc. It scans what's customizable in your installation, helps you choose the right surface (agent vs workflow) for your intent, writes the override file for you, and verifies the merge landed. Run it whenever you want to make a change; this doc is the reference for *what* the surface exposes and how merging works. +::: + ## When to Use This - You want to change an agent's personality or communication style @@ -383,7 +387,8 @@ For enterprise-oriented recipes (shaping an agent across every workflow it dispa **Need to see what's customizable?** -- Read the skill's `customize.toml` -- every field there is customizable (except `name` and `title`) +- Run the `bmad-customize` skill — it enumerates every customizable skill installed in your project, shows which ones already have overrides, and walks you through adding or updating one +- Or read the skill's `customize.toml` directly — every field there is customizable (except `name` and `title`) **Need to reset?** diff --git a/docs/how-to/expand-bmad-for-your-org.md b/docs/how-to/expand-bmad-for-your-org.md index ec3b571f9..966080fe1 100644 --- a/docs/how-to/expand-bmad-for-your-org.md +++ b/docs/how-to/expand-bmad-for-your-org.md @@ -14,6 +14,10 @@ BMad's customization surface lets an organization reshape behavior without editi - Python 3.11+ on PATH (for the resolver — stdlib only, no `pip install`) ::: +:::tip[Applying these recipes] +Every recipe below can be applied by running the `bmad-customize` skill and describing the intent — it will pick the right surface, author the override file, and verify the merge. The recipes here are the source of truth for *what* to override; `bmad-customize` handles the *how*. Hand-authoring still works the same way if you prefer it or need a pattern the skill doesn't cover yet (currently: central-config overrides). +::: + ## The Three-Layer Mental Model Before picking a recipe, know where your override lands: