From 0817dc8649d923e506bb9e4f6c5c809b936cd264 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Mon, 20 Apr 2026 22:22:05 -0500 Subject: [PATCH 1/2] docs(customization): mention bmad-customize in author-facing guides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Skill authors opt into the customization surface knowing users will hand-write TOML against it. That's now not the default user path — BMad core ships bmad-customize, a conversational authoring helper that scans customizable skills, picks scope, writes the override, and verifies the merge. Authors should pick field names and defaults that read well when a user is walked through them in that flow. Updates two bmb docs: - explanation/customization-for-authors.md: intro paragraph on the downstream authoring path - how-to/make-a-skill-customizable.md: intro note + bullet in the "What You Get" user-experience list No changes to skill source or workflows. --- docs/explanation/customization-for-authors.md | 2 ++ docs/how-to/make-a-skill-customizable.md | 3 +++ 2 files changed, 5 insertions(+) diff --git a/docs/explanation/customization-for-authors.md b/docs/explanation/customization-for-authors.md index d2a0ce1..6898e97 100644 --- a/docs/explanation/customization-for-authors.md +++ b/docs/explanation/customization-for-authors.md @@ -5,6 +5,8 @@ description: How to decide whether your skill should support end-user customizat Shipping a `customize.toml` is opt-in per skill. This is the author-side counterpart to [How to Customize BMad](https://docs.bmad-method.org/how-to/customize-bmad/), which covers the end-user view. Read that first if you haven't; it shows what users experience when they override a skill. This guide is about deciding whether to give them that surface at all. +Downstream users don't hand-write TOML. BMad ships a core skill called `bmad-customize` that walks them through authoring overrides conversationally — it scans which skills are customizable, picks agent vs workflow scope, writes the override file, and verifies the merge. That affects the names and defaults you pick: a user being walked through `"set prd_template to your template path"` handles that fine; `tmpl_override` or `opt_2` makes the conversation awkward. Pick field names that read well out loud. + ## The Problem Every customization knob you ship is a promise. Users pin values to it, teams commit overrides to git, and future releases have to respect the shape you locked in. Over-exposing makes the skill harder to evolve and invites drift; under-exposing forces forks for changes that should have been a three-line TOML file. diff --git a/docs/how-to/make-a-skill-customizable.md b/docs/how-to/make-a-skill-customizable.md index 9e907c1..40974ae 100644 --- a/docs/how-to/make-a-skill-customizable.md +++ b/docs/how-to/make-a-skill-customizable.md @@ -5,6 +5,8 @@ description: Opt your skill into end-user customization during the build, name y This guide walks through opting a skill into end-user customization during a build. You'll hit the opt-in moment in the builder, pick names for the scalars you expose, and verify an override actually fires. Read [Customization for Authors](/explanation/customization-for-authors.md) first if you haven't decided whether to opt in. +Keep in mind that your users won't typically hand-write the override files you're enabling. The `bmad-customize` skill in BMad core walks them through authoring overrides conversationally. The names and defaults you pick here are what a user is walked through in that conversation, so pick scalar names that read well out loud. + ## When to Use This - You're building a workflow or stateless agent and want to let teams/org users inject overrides @@ -136,6 +138,7 @@ Users get: - Team-scoped overrides via `_bmad/custom/{skill-name}.toml` - Personal-scoped overrides via `_bmad/custom/{skill-name}.user.toml` - Automatic precedence handling from the resolver (user beats team beats defaults) +- A conversational authoring path: the `bmad-customize` core skill scans which skills are customizable, helps the user pick agent vs workflow scope, writes the override file, and verifies the merge. Users who prefer to hand-write TOML still can. ## Tips From cf937ccf13cf750c3c25a42688b12438c3c9000f Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Mon, 20 Apr 2026 22:31:36 -0500 Subject: [PATCH 2/2] docs(customization-for-authors): soften 'don't hand-write TOML' augmentcode review flagged the absolute phrasing as inconsistent with the sibling make-a-skill-customizable.md which says 'won't typically hand-write'. Aligning: add 'typically' and an explicit one-line note that hand-writing still works for users who prefer it. Keeps the naming-implication paragraph intact since that's the point of the note. --- docs/explanation/customization-for-authors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/explanation/customization-for-authors.md b/docs/explanation/customization-for-authors.md index 6898e97..1850ede 100644 --- a/docs/explanation/customization-for-authors.md +++ b/docs/explanation/customization-for-authors.md @@ -5,7 +5,7 @@ description: How to decide whether your skill should support end-user customizat Shipping a `customize.toml` is opt-in per skill. This is the author-side counterpart to [How to Customize BMad](https://docs.bmad-method.org/how-to/customize-bmad/), which covers the end-user view. Read that first if you haven't; it shows what users experience when they override a skill. This guide is about deciding whether to give them that surface at all. -Downstream users don't hand-write TOML. BMad ships a core skill called `bmad-customize` that walks them through authoring overrides conversationally — it scans which skills are customizable, picks agent vs workflow scope, writes the override file, and verifies the merge. That affects the names and defaults you pick: a user being walked through `"set prd_template to your template path"` handles that fine; `tmpl_override` or `opt_2` makes the conversation awkward. Pick field names that read well out loud. +Downstream users typically don't hand-write TOML. BMad ships a core skill called `bmad-customize` that walks them through authoring overrides conversationally — it scans which skills are customizable, picks agent vs workflow scope, writes the override file, and verifies the merge. Users who prefer to edit TOML directly still can, but the conversational flow is the default path. That affects the names and defaults you pick: a user being walked through `"set prd_template to your template path"` handles that fine; `tmpl_override` or `opt_2` makes the conversation awkward. Pick field names that read well out loud. ## The Problem