bmad-customize

Authors TOML override files that customize installed BMad agent and workflow skills.

Updated Sep 3, 2026
One-click install
npx skills add https://github.com/watchthelight/shatterfish --skill bmad-customize-watchthelight
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: bmad-customize
Source: https://github.com/watchthelight/shatterfish/tree/main/.claude/skills/bmad-customize
Command: npx skills add https://github.com/watchthelight/shatterfish --skill bmad-customize-watchthelight

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Changing the behavior of installed BMad agent or workflow skills requires knowing which fields each skill exposes, where override files belong, and how team and user layers merge. This Skill translates plain-English customization requests into correctly placed, verified TOML override files under _bmad/custom/. ## Core Features & Use Cases - Discovery and routing: Scans installed skills via a Python script to list every customizable agent and workflow surface, including existing team and user overrides. - Override authoring: Composes sparse TOML overrides against each skill's customize.toml, applying correct merge semantics for scalars, append arrays, and keyed tables. - Verified writes: Shows a diff, waits for confirmation, writes the team (.toml) or user (.user.toml) file, then verifies the result with the BMad customization resolver or a manual merge fallback. - Use Case: A user says "make the PM agent always include our compliance checklist." The Skill locates bmad-agent-pm, reads its exposed fields, writes a team override adding the checklist to persistent_facts, and verifies the merged output. ## Quick Start Ask the assistant to customize a BMad skill, for example: change the PRD workflow to use a different output template for this project.

Frequently Asked Questions about bmad-customize

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I customize a BMad agent or workflow skill?

State the target skill and the change you want in plain English. The Skill reads the target's customize.toml, composes a sparse TOML override, and writes it to _bmad/custom/ after your confirmation, then verifies the merged result.

What is the difference between team and user overrides in BMad?

Team overrides live in {skill-name}.toml and are committed for shared policies and conventions. User overrides live in {skill-name}.user.toml, are gitignored, and hold personal tone, private facts, or shortcuts. User layers merge on top of team layers.

How do BMad customization overrides merge with defaults?

Scalars like icon or template paths are replaced by the override. Arrays such as persistent_facts and activation_steps append in order. Keyed arrays of tables merge by their code or id key, with matching keys replaced and new keys appended.

Can I customize a BMad skill that has no customize.toml?

No. Skills without a customize.toml expose no customization surface and cannot be overridden. The Skill will say so and suggest using bmad-builder to create a custom skill instead.

What happens if the BMad resolver script is missing?

The Skill falls back to a manual merge: it reads the base customize.toml plus any team and user override files, applies the same merge rules, and describes how the changed fields resolve.