Agent identity (name, title) and the Overview prose are now baked into
each SKILL.md rather than resolved from customize.yaml. This anchors
skill-discovery (description keywords still match), protects brand
identity (Mary is Mary), and leaves the customize.yaml surface for
behavior changes only.
customize.yaml slimming:
- Dropped metadata.title (hardcoded in SKILL.md heading + Overview)
- Dropped metadata.capabilities (dead field; nothing downstream read it)
- Luminary-anchored identity strings (Porter+Minto, Evans+Tufte,
Cagan+Torres+Bezos, Norman+Cooper, Fowler+Vogels, Beck+Pragmatic
Programmer) — higher signal density, ~55% token savings per persona
- Preserved distinctive communication_style voice beats per agent
- Principles trimmed to 3-4 cite-worthy heuristics each
SKILL.md changes (all 6 agents):
- New top-of-body heading: `# Name — Title`
- New `## Overview` section with hardcoded capability prose
- Step 2 (Adopt Persona) rewritten to layer customized persona on top
of the Overview-established identity
- bmad-agent-dev gains an `## Operating Rules` section containing its
8 non-negotiable behavioral invariants (moved from customize.yaml
critical_actions, since they're brand-protected invariants, not
team-customizable startup steps)
customize.yaml now defines per-agent:
- icon (cosmetic)
- persona.{role, identity, communication_style, principles} (customizable)
- critical_actions (empty by default, extensibility hook for teams)
- memories (empty by default, extensibility hook for teams)
- menu (default items, mergeable by code)
manifest-generator.js: dropped `capabilities` column from
agent-manifest.csv header, write, and read paths (field was write-only
noise — no consumer ever read it back).
Docs: customize-bmad.md now notes agent names are fixed by design so
skills can be reliably invoked by role or default name.
Workflow customization:
- bmad-product-brief adopts the customize.yaml pattern with new standard
keys (activation_steps_prepend, activation_steps_append, skill_end)
that apply to any skill type, not just workflows.
- SKILL.md resolves customization as the first activation step, executes
prepend items immediately, retains append for after greeting, and
re-resolves skill_end after Stage 5 (Finalize).
- Added {skill-root} to the Conventions block.
- Normalized all sub-prompt path references to bare-from-skill-root
(../agents/ -> agents/, sibling filenames -> prompts/<file>).
Metadata:
- Added "DO NOT EDIT -- overwritten on every update." header to all 6
agent customize.yaml files.
Resolver:
- find_project_root now walks from skill_dir first, then falls back to
cwd. Nested-workspace setups where an ancestor of cwd has an unrelated
_bmad/ would previously bind the resolver to the wrong project.
Installer:
- Added 'memory' to the nonModuleDirs sets at all three filter sites so
sidecar-generated _bmad/memory/<agent>/ folders aren't treated as
modules and don't receive a generated config.yaml.
- detectCustomFiles now skips the entire _memory/ and memory/ subtrees
generically, replacing the old v6.1-specific -sidecar substring check.
Agent runtime state is never flagged as custom/modified noise on update.
- Replace per-skill TOML defaults with customize.yaml using v6.1-compatible
schema (agent.metadata / agent.persona, snake_case fields)
- Port resolve-customization.py to resolve-customization.js (Node); one
shared copy at src/scripts/, invoked via --skill with three-layer merge
- Restore v6.1 fields: critical_actions, memories, menu; drop start_prompt
- Simplify menu items to {code, description, skill|prompt}; no action field
- Flatten SKILL.md to 8 atomic activation steps, boilerplate below frontmatter
- Tech-writer menu items reference skill-root prompt files via {skill-root}
- Dev agent Critical Actions moved from SKILL.md into customize.yaml
- Add {skill-name} path convention for portable fallback instructions
- Rewrite docs/how-to/customize-bmad.md for the new system
Brian Madison