* feat(core-skills): add bmad-customize for authoring _bmad/custom overrides
A conversational guide skill that helps users author or update TOML overrides
in _bmad/custom/ for customizable BMad agents and workflows. Covers per-skill
agent and workflow surfaces; central config is out of scope for v1.
- SKILL.md: six-step flow (intent, discover, route, compose, team-vs-user,
show-confirm-write-verify) with baked-in agent-vs-workflow routing heuristic
and a template-swap subroutine
- scripts/list_customizable_skills.py: stdlib-only scanner that enumerates
customizable skills across standard IDE install paths, reports surface type
and override status, PEP 723, 10 unit tests
- Reuses _bmad/scripts/resolve_customization.py for post-write verification
- Registered in core-skills/module-help.csv with menu code BC
* refactor(bmad-customize): apply QA pass (top 3 recommendations)
Applies the three highest-payoff themes from the quality analysis:
- Labeling + completion contracts: rename ## Purpose to ## Overview,
add domain framing (what customization means in BMad, typical user
arrival shapes), add an explicit Completion block with testable
conditions for "skill run is done"
- Hostile-environment robustness: add On-Activation preflight that
classifies no-BMad / BMad-without-resolver / full-install states,
instruct Step 2 to surface scanner errors[] and scanned_roots on
empty results, add resolver-missing fallback to Step 6.4, add a
re-enter-Step-4 recovery loop when verify shows the override didn't
take effect
- Returning-user and iteration experience: add "Audit / iterate"
intent class in Step 1, lead discovery with already-overridden
skills for that intent, read existing overrides in Step 3 before
composing, frame Step 4 as additive-on-top rather than fresh
authoring, give Cross-cutting intent an explicit Step 3 branch
that walks agent-vs-workflow with the user
Resolves 12 of 18 observations from the quality report. Lint clean
(scan-path-standards and scan-scripts both 0 findings). Unit tests
still 10/10.
* refactor(bmad-customize): derive skills root from install location
Previously the scanner hardcoded a list of IDE skill directories
(.claude/skills, .cursor/skills, .cline/skills, .continue/skills) and
scanned them relative to the project root. That was wrong: skills can
be installed either project-local or user-global, the IDE determines
the convention, and the set of valid locations is open-ended.
The scanner now derives its primary skills root from __file__ — the
running skill's own install directory is the authoritative location
for finding siblings. --skills-root overrides the default; --extra-root
(repeatable) adds additional locations for the rare mixed-install case.
Changes:
- list_customizable_skills.py: remove SKILL_ROOTS constant, add
default_skills_root() derived from __file__, rename scan_project
to scan_skills(skills_roots, project_root), add --skills-root and
--extra-root flags, de-dupe skills when the same name appears in
multiple roots (first wins)
- SKILL.md: update Step 2 to describe the scanner's derive-from-install
behavior and when to use --extra-root; drop the hardcoded IDE path
list from Notes
- tests: refactor setUp to place skills under a generic skills root
(not .claude/skills), add 3 new tests for multiple-roots merge,
duplicate-name precedence, and missing-root error reporting
* 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(bmad-customize): steer users at bmad-builder instead of 'forking'
* fix(bmad-customize): reword description to pass file-ref validator
* refactor(bmad-customize): tighten description and expand module-help entry
- SKILL.md description: drop the catch-all 'or asks how to change the
behavior of a specific BMad skill' trigger clause that would fire in
casual discussion; keep the four explicit phrase triggers.
- module-help.csv: rewrite the description so bmad-help has real
routing material — names the concrete capabilities (persistent
facts, template swaps, activation hooks, menus), the scope routing,
and the value prop (no TOML hand-authoring). Matches the 'Use
when...' pattern other Core entries use.
* fix(module-help): quote bmad-customize description field that contains commas
* fix(bmad-customize): address PR #2289 review findings
- SKILL.md preflight: load root config from _bmad/config.toml and
config.user.toml (not .yaml) — the installer emits TOML; the YAML
references would have made the skill silently miss real user config
- SKILL.md resolver fallback (Step 6.4): read all three merge layers
when present (base / team / user) and describe the merge in
base → team → user order; the prior wording could describe the wrong
effective merge when the user wrote .user.toml on top of an existing
team .toml
- SKILL.md: replace bare 'docs/how-to/customize-bmad.md' references
(3 locations) with the public docs URL so users installing the skill
aren't pointed at a path they don't have locally
- list_customizable_skills.py: catch UnicodeDecodeError in
read_frontmatter_description so a non-UTF-8 SKILL.md can't abort
the whole scan
- list_customizable_skills.py: clarify exit-code contract in the
module docstring — errors[] is non-fatal by design, exit 2 is
reserved for invocation errors
- customize-bmad.md: tighten the tip to scope bmad-customize to the
per-skill surface; central-config is out of scope v1
- expand-bmad-for-your-org.md: same scoping — Recipes 1-4 can be
applied by the skill; Recipe 5 (central config) stays hand-authored
* fix(bmad-customize): markdownlint MD034 and validate-file-refs
- Wrap the three docs.bmad-method.org references as
[text](url) markdown links instead of bare URLs (MD034)
- Drop the {project-root}/ prefix on line 41's config.toml
references. validate-file-refs strips the template prefix and
tries to resolve 'config.toml' as 'src/config.toml'; sibling
skills (party-mode, retrospective, advanced-elicitation) all
reference '_bmad/config.toml' bare and pass CI — match that
pattern. The '(root level under {project-root}, installer-owned)'
parenthetical preserves the disambiguation.
* refactor(bmad-customize): cut token-wasting prose from SKILL.md
Down from 175 lines to 110. Removed:
- 'What customization means in BMad' architecture backgrounder — the
LLM reads the live customize.toml in Step 3; doesn't need the lore
- 'Desired Outcomes' section — retrospective narration of what the
6 steps already instruct
- 'Role' section — fluff; the flow itself defines the role
- 'Notes' section — sparse-override rule already in Step 4, IDE-path
note is commentary, docs link duplicates the out-of-scope section
- 'The scanner derives its skills directory from...' and 'returns JSON
with...' — commentary the LLM doesn't need; it runs the script and
sees the output
- 'that file IS the schema' and similar editorial asides throughout
- Explanatory clauses like 'silently drifts on every release' and
'trust the user's domain knowledge'
Kept everything that's load-bearing: preflight conditionals, intent
classification, routing heuristic, merge semantics, template-swap
subroutine, team-vs-user defaults, verify fallback and recovery loop,
completion conditions, out-of-scope list.
b63086f22e