feat(skills): add TOML-based skill customization system by bmadcode · Pull Request #20 · bmad-code-org/bmad-module-game-dev-studio

bmadcode · 2026-04-14T16:04:12Z

Summary

Add customize.toml to all 35 skills: 7 agents with full persona + metadata sections, 28 workflows with stock fields
Include resolve-customization.py script in each skill's scripts/ directory for three-layer TOML merge (user > team > defaults)
Add customization resolve and inject points to all workflow SKILL.md files

Part of the cross-module skill customization initiative. See bmad-code-org/BMAD-METHOD#2262 for the core implementation.

Test plan

Verify agent customize.toml persona data matches existing manifests
Verify resolve-customization.py runs and returns JSON for each skill
Verify SKILL.md inject points reference correct skill names

🤖 Generated with Claude Code

Summary by CodeRabbit

New Features
- Global customization support: defaults + team + user overrides for agents and workflows.
- Injected content (before/after) and additional resource files can be applied at activation.
- Persona, greeting, and capabilities menu now honor resolved customizations and merge menu entries (replacements and additions).
Documentation
- Updated skill/workflow docs to describe the new customization and activation flow.
- Support contact updated in README.

Add customize.toml to all 35 skills (7 agents with full persona + metadata, 28 workflows with stock fields). Include resolve-customization.py script in each skill's scripts/ directory. Add customization resolve and inject points to all workflow SKILL.md files.

coderabbitai · 2026-04-14T16:04:21Z

Walkthrough

This pull request standardizes per-skill customization by adding default customize.toml files, new scripts/resolve-customization.py resolvers that merge defaults/team/user TOML layers into JSON (with menu-by-code merge and optional dotted-key extraction), and updates SKILL.md to apply resolved persona, inject, additional_resources, and menu during activation across many agents and workflows.

Changes

Cohort / File(s)	Summary
Agent SKILL docs `src/agents/gds-agent-game-architect/SKILL.md`, `src/agents/gds-agent-game-designer/SKILL.md`, `src/agents/gds-agent-game-dev/SKILL.md`, `src/agents/gds-agent-game-qa/SKILL.md`, `src/agents/gds-agent-game-scrum-master/SKILL.md`, `src/agents/gds-agent-game-solo-dev/SKILL.md`, `src/agents/gds-agent-tech-writer/SKILL.md`	Rewrote activation flow to call resolver script, apply resolved `persona`/`inject`/`additional_resources`, and merge resolved `menu` into capabilities table (replace by `code` or append).
Agent customize.toml `src/agents/gds-agent-*/customize.toml` (7 files)	Added default customization TOML for each agent: `additional_resources`, `[metadata]`, `[persona]`, and `[inject].before`.
Agent resolver scripts `src/agents/gds-agent-*/scripts/resolve-customization.py` (7 files)	Added Python resolver CLI: locate project root, load defaults/team/user TOML, deep-merge with special `[[menu]]`-by-`code` behavior, output pretty JSON, support repeatable `--key` dotted extraction.
Workflow SKILL docs (1-preproduction) `src/workflows/1-preproduction/.../SKILL.md` (3 files)	Added pre/post-workflow customization resolution steps and rules for applying `inject.before` and `additional_resources`.
Workflow customize.toml (1-preproduction) `src/workflows/1-preproduction/.../customize.toml` (3 files)	Added defaults: `additional_resources` and `[inject]` (`before`/`after`).
Workflow resolver scripts (1-preproduction) `src/workflows/1-preproduction/.../scripts/resolve-customization.py` (3 files)	Added resolver scripts following same merge/output/key semantics.
Workflow SKILL docs (2-design, 3-technical, 4-production, gametest, quick-flow, root areas) many `src/workflows/.../.../SKILL.md` files	Applied consistent documentation explaining running resolver, using `inject.before`/`additional_resources`, and `inject.after` post-workflow.
Workflow customize.toml & scripts (2-design, 3-technical, 4-production, gametest, quick-flow, root areas) `src/workflows/.../.../customize.toml`, `src/workflows/.../.../scripts/resolve-customization.py` (many files)	Added default TOML files and matching resolver scripts for workflows; consistent deep-merge logic, menu-by-code handling, JSON output and optional `--key`.
README.md `README.md`	Minor text change: updated sponsorship email formatting.

Sequence Diagram(s)

sequenceDiagram
    participant Dev as Developer / CLI
    participant Resolver as scripts/resolve-customization.py
    participant FS as Project FS (defaults & _bmad/customizations/)
    participant Agent as Agent/Workflow Activation
    participant User as User

    Dev->>Resolver: run resolver (skill_name, --key ...)
    Resolver->>FS: read skill defaults (./customize.toml)
    Resolver->>FS: if project root found, read team and user overrides
    Resolver->>Resolver: deep_merge (dicts, menu-by-code, arrays override)
    Resolver->>Dev: emit merged JSON (or selected keys)
    Dev->>Agent: start activation with resolved JSON
    Agent->>Agent: apply persona, inject.before, load additional_resources
    Agent->>User: greet and present merged capabilities menu
    User->>Agent: select capability (must match exact registered code)

Note: rectangles/colors are implicit in Mermaid actors; interactions focus on resolver → filesystem → agent flow.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

Sync/upstream bmad method v6.3.0 #21 — Overlapping additions of per-skill customize.toml and resolve-customization.py plus activation/manifest changes affecting similar agent/workflow paths.

Poem

🐰 I stitched TOML layers, three deep and true,

defaults, team, and user — a customizable brew.
Personas donned, injections placed with care,
Menus merged by code — hop! now every skill's aware.
A little rabbit cheers: "Configured and ready to share!"

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch skill-customization

⚔️ Resolve merge conflicts

Resolve merge conflict in branch skill-customization

augmentcode · 2026-04-14T16:07:26Z

🤖 Augment PR Summary

Summary: Introduces a TOML-based customization system for GDS skills (agents + workflows), enabling per-user and per-team overrides on top of skill defaults.

Changes:

Added customize.toml defaults across all skills (agents include [metadata]/[persona]/[inject]; workflows include additional_resources and [inject]).
Added a per-skill scripts/resolve-customization.py utility that performs a three-layer TOML merge (user > team > defaults) and prints merged JSON.
Extended workflow SKILL.md files with “Resolve Customization” and “Post-Workflow Customization” steps to inject inject.before/inject.after and load additional_resources.

Technical Notes: Merge rules are recursive for tables, treat non-menu arrays as atomic replace, and support dotted key extraction via --key for partial JSON output.

_{🤖 Was this summary useful? React with 👍 or 👎}

augmentcode

Review completed. 3 suggestions posted.

Comment augment review to trigger a new review at any time.

augmentcode · 2026-04-14T16:07:27Z

+    user: dict[str, Any] = {}
+    if project_root is not None:
+        customizations_dir = project_root / "_bmad" / "customizations"
+        team = load_toml(customizations_dir / f"{args.skill_name}.toml")


defaults_path is derived from the script’s directory, but the override filenames are derived from user-provided skill_name; if the caller passes a mismatched name, this can silently merge defaults from one skill with overrides from another. Consider guarding against this to prevent hard-to-debug configuration mixups.

Severity: medium

Other Locations

src/agents/gds-agent-game-architect/scripts/resolve-customization.py:159

src/agents/gds-agent-game-designer/scripts/resolve-customization.py:159

src/agents/gds-agent-game-dev/scripts/resolve-customization.py:159

src/agents/gds-agent-game-qa/scripts/resolve-customization.py:159

src/agents/gds-agent-game-scrum-master/scripts/resolve-customization.py:159

src/agents/gds-agent-game-solo-dev/scripts/resolve-customization.py:159

src/agents/gds-agent-tech-writer/scripts/resolve-customization.py:159

src/workflows/1-preproduction/gds-create-game-brief/scripts/resolve-customization.py:159

src/workflows/1-preproduction/research/gds-domain-research/scripts/resolve-customization.py:159

src/workflows/2-design/gds-create-gdd/scripts/resolve-customization.py:159

src/workflows/2-design/gds-create-narrative/scripts/resolve-customization.py:159

src/workflows/2-design/gds-create-ux-design/scripts/resolve-customization.py:159

src/workflows/3-technical/gds-check-implementation-readiness/scripts/resolve-customization.py:159

src/workflows/3-technical/gds-create-epics-and-stories/scripts/resolve-customization.py:159

src/workflows/3-technical/gds-game-architecture/scripts/resolve-customization.py:159

src/workflows/3-technical/gds-generate-project-context/scripts/resolve-customization.py:159

src/workflows/4-production/gds-code-review/scripts/resolve-customization.py:159

src/workflows/4-production/gds-correct-course/scripts/resolve-customization.py:159

src/workflows/4-production/gds-create-story/scripts/resolve-customization.py:159

src/workflows/4-production/gds-dev-story/scripts/resolve-customization.py:159

src/workflows/4-production/gds-retrospective/scripts/resolve-customization.py:159

src/workflows/4-production/gds-sprint-planning/scripts/resolve-customization.py:159

src/workflows/4-production/gds-sprint-status/scripts/resolve-customization.py:159

src/workflows/gametest/gds-e2e-scaffold/scripts/resolve-customization.py:159

src/workflows/gametest/gds-performance-test/scripts/resolve-customization.py:159

src/workflows/gametest/gds-playtest-plan/scripts/resolve-customization.py:159

src/workflows/gametest/gds-test-automate/scripts/resolve-customization.py:159

src/workflows/gametest/gds-test-design/scripts/resolve-customization.py:159

src/workflows/gametest/gds-test-framework/scripts/resolve-customization.py:159

src/workflows/gametest/gds-test-review/scripts/resolve-customization.py:159

src/workflows/gds-document-project/scripts/resolve-customization.py:159

src/workflows/gds-quick-flow/gds-quick-dev-new-preview/scripts/resolve-customization.py:159

src/workflows/gds-quick-flow/gds-quick-dev/scripts/resolve-customization.py:159

src/workflows/gds-quick-flow/gds-quick-spec/scripts/resolve-customization.py:159

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

augmentcode · 2026-04-14T16:07:27Z

+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except Exception as exc:
+        print(f"warning: failed to parse {path}: {exc}", file=sys.stderr)


load_toml() returns {} on parse errors (only emitting a warning), which can make a broken customization file look like “customization doesn’t work” while still exiting successfully. Consider whether parse failures (especially for the defaults file) should be treated as hard errors to avoid silently dropping configuration.

Severity: medium

Other Locations

src/agents/gds-agent-game-architect/scripts/resolve-customization.py:51

src/agents/gds-agent-game-designer/scripts/resolve-customization.py:51

src/agents/gds-agent-game-dev/scripts/resolve-customization.py:51

src/agents/gds-agent-game-qa/scripts/resolve-customization.py:51

src/agents/gds-agent-game-scrum-master/scripts/resolve-customization.py:51

src/agents/gds-agent-game-solo-dev/scripts/resolve-customization.py:51

src/agents/gds-agent-tech-writer/scripts/resolve-customization.py:51

src/workflows/1-preproduction/gds-create-game-brief/scripts/resolve-customization.py:51

src/workflows/1-preproduction/research/gds-domain-research/scripts/resolve-customization.py:51

src/workflows/2-design/gds-create-gdd/scripts/resolve-customization.py:51

src/workflows/2-design/gds-create-narrative/scripts/resolve-customization.py:51

src/workflows/2-design/gds-create-ux-design/scripts/resolve-customization.py:51

src/workflows/3-technical/gds-check-implementation-readiness/scripts/resolve-customization.py:51

src/workflows/3-technical/gds-create-epics-and-stories/scripts/resolve-customization.py:51

src/workflows/3-technical/gds-game-architecture/scripts/resolve-customization.py:51

src/workflows/3-technical/gds-generate-project-context/scripts/resolve-customization.py:51

src/workflows/4-production/gds-code-review/scripts/resolve-customization.py:51

src/workflows/4-production/gds-correct-course/scripts/resolve-customization.py:51

src/workflows/4-production/gds-create-story/scripts/resolve-customization.py:51

src/workflows/4-production/gds-dev-story/scripts/resolve-customization.py:51

src/workflows/4-production/gds-retrospective/scripts/resolve-customization.py:51

src/workflows/4-production/gds-sprint-planning/scripts/resolve-customization.py:51

src/workflows/4-production/gds-sprint-status/scripts/resolve-customization.py:51

src/workflows/gametest/gds-e2e-scaffold/scripts/resolve-customization.py:51

src/workflows/gametest/gds-performance-test/scripts/resolve-customization.py:51

src/workflows/gametest/gds-playtest-plan/scripts/resolve-customization.py:51

src/workflows/gametest/gds-test-automate/scripts/resolve-customization.py:51

src/workflows/gametest/gds-test-design/scripts/resolve-customization.py:51

src/workflows/gametest/gds-test-framework/scripts/resolve-customization.py:51

src/workflows/gametest/gds-test-review/scripts/resolve-customization.py:51

src/workflows/gds-document-project/scripts/resolve-customization.py:51

src/workflows/gds-quick-flow/gds-quick-dev-new-preview/scripts/resolve-customization.py:51

src/workflows/gds-quick-flow/gds-quick-dev/scripts/resolve-customization.py:51

src/workflows/gds-quick-flow/gds-quick-spec/scripts/resolve-customization.py:51

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

augmentcode · 2026-04-14T16:07:27Z

+    """Merge-by-code: matching codes replace; new codes append."""
+    result_by_code: dict[str, dict] = {item["code"]: dict(item) for item in base}
+    for item in override:
+        result_by_code[item["code"]] = dict(item)


merge_menu() assumes every entry has a code key; since _is_menu_array() only checks the first element, a malformed later element can raise KeyError here and abort customization resolution. Consider whether this should be validated/handled more defensively to keep the resolver robust against partial user edits.

Severity: medium

Other Locations

src/agents/gds-agent-game-architect/scripts/resolve-customization.py:73

src/agents/gds-agent-game-designer/scripts/resolve-customization.py:73

src/agents/gds-agent-game-dev/scripts/resolve-customization.py:73

src/agents/gds-agent-game-qa/scripts/resolve-customization.py:73

src/agents/gds-agent-game-scrum-master/scripts/resolve-customization.py:73

src/agents/gds-agent-game-solo-dev/scripts/resolve-customization.py:73

src/agents/gds-agent-tech-writer/scripts/resolve-customization.py:73

src/workflows/1-preproduction/gds-create-game-brief/scripts/resolve-customization.py:73

src/workflows/1-preproduction/research/gds-domain-research/scripts/resolve-customization.py:73

src/workflows/2-design/gds-create-gdd/scripts/resolve-customization.py:73

src/workflows/2-design/gds-create-narrative/scripts/resolve-customization.py:73

src/workflows/2-design/gds-create-ux-design/scripts/resolve-customization.py:73

src/workflows/3-technical/gds-check-implementation-readiness/scripts/resolve-customization.py:73

src/workflows/3-technical/gds-create-epics-and-stories/scripts/resolve-customization.py:73

src/workflows/3-technical/gds-game-architecture/scripts/resolve-customization.py:73

src/workflows/3-technical/gds-generate-project-context/scripts/resolve-customization.py:73

src/workflows/4-production/gds-code-review/scripts/resolve-customization.py:73

src/workflows/4-production/gds-correct-course/scripts/resolve-customization.py:73

src/workflows/4-production/gds-create-story/scripts/resolve-customization.py:73

src/workflows/4-production/gds-dev-story/scripts/resolve-customization.py:73

src/workflows/4-production/gds-retrospective/scripts/resolve-customization.py:73

src/workflows/4-production/gds-sprint-planning/scripts/resolve-customization.py:73

src/workflows/4-production/gds-sprint-status/scripts/resolve-customization.py:73

src/workflows/gametest/gds-e2e-scaffold/scripts/resolve-customization.py:73

src/workflows/gametest/gds-performance-test/scripts/resolve-customization.py:73

src/workflows/gametest/gds-playtest-plan/scripts/resolve-customization.py:73

src/workflows/gametest/gds-test-automate/scripts/resolve-customization.py:73

src/workflows/gametest/gds-test-design/scripts/resolve-customization.py:73

src/workflows/gametest/gds-test-framework/scripts/resolve-customization.py:73

src/workflows/gametest/gds-test-review/scripts/resolve-customization.py:73

src/workflows/gds-document-project/scripts/resolve-customization.py:73

src/workflows/gds-quick-flow/gds-quick-dev-new-preview/scripts/resolve-customization.py:73

src/workflows/gds-quick-flow/gds-quick-dev/scripts/resolve-customization.py:73

src/workflows/gds-quick-flow/gds-quick-spec/scripts/resolve-customization.py:73

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

Change except Exception to except (tomllib.TOMLDecodeError, OSError) for clearer failure signaling in user-facing tooling.

Refactor all 7 GDS agent SKILL.md files to resolve persona, inject, additional_resources, and menu from customize.toml at activation. Remove hardcoded Identity, Communication Style, and Principles sections. Preserve Critical Actions sections where present.

- Drop ./ prefix from script paths (use scripts/ not ./scripts/) - Use python3 instead of python for explicitness - Add Available Scripts listing to all SKILL.md files

- Fix merge_menu KeyError crash when menu items missing 'code' key - Fix _is_menu_array to check ALL elements, not just first - Remove unused import os from resolve-customization.py - Remove inject.after from agent activation and customize.toml

coderabbitai

Note

Due to the large number of review comments, Critical severity comments were prioritized as inline comments.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (3)

src/agents/gds-agent-game-dev/SKILL.md (1)
45-57: ⚠️ Potential issue | 🔴 Critical

Fix capabilities table: Two skill names are not registered.

The verification reveals that the Capabilities table references two skills that do not exist in the codebase:

gds-quick-prototype — not found

bmad-advanced-elicitation — not found

Three skills are correctly registered:

gds-dev-story ✓

gds-code-review ✓

gds-quick-dev ✓

Since the documentation states "invoke the corresponding skill by its exact registered name" and "DO NOT invent capabilities on the fly," remove or replace the unregistered skills or ensure they are implemented before documenting them.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@src/agents/gds-agent-game-dev/SKILL.md` around lines 45 - 57, The
Capabilities table lists two unregistered skills (gds-quick-prototype and
bmad-advanced-elicitation); update SKILL.md to either remove those two entries
or replace them with the exact registered skill names, ensuring the table
entries and the "CRITICAL Handling" instruction still reference only exact,
implemented skill names (e.g., keep gds-dev-story, gds-code-review,
gds-quick-dev) and do not invent new IDs unless the corresponding skill
implementations (matching the exact names) are added to the codebase.
src/agents/gds-agent-game-designer/SKILL.md (1)
44-56: ⚠️ Potential issue | 🔴 Critical

Remove or register the gds-quick-prototype skill.

The capabilities table references gds-quick-prototype, but this skill is not registered in the system. Four of the five referenced skills exist at their expected locations in src/workflows/, but gds-quick-prototype has no corresponding directory. Since the SKILL.md instructions state "invoke the corresponding skill by its exact registered name" and "DO NOT invent capabilities on the fly", users will encounter an error if they attempt to invoke this capability. Either remove the entry from the capabilities table or create the missing skill directory.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@src/agents/gds-agent-game-designer/SKILL.md` around lines 44 - 56, The
Capabilities table in SKILL.md lists gds-quick-prototype but that skill isn't
registered; either remove the "QP | Rapid game prototyping |
gds-quick-prototype" row from the table or create and register the missing skill
with the exact name gds-quick-prototype (add its workflow/handler,
manifest/registration entry and any expected exports so it can be invoked by
name), and verify SKILL.md and the skill registry reference the identical string
"gds-quick-prototype".
src/agents/gds-agent-game-solo-dev/SKILL.md (1)
40-54: ⚠️ Potential issue | 🔴 Critical

Two referenced skills are unregistered and unavailable: remove them from the capabilities table or implement them.

The capabilities table references gds-quick-prototype and bmad-advanced-elicitation, but neither skill has a registered implementation in the codebase. Only 5 of the 7 listed skills exist:

✗ gds-quick-prototype — NO DIRECTORY FOUND

✓ gds-quick-dev — exists at src/workflows/gds-quick-flow/gds-quick-dev/

✓ gds-quick-spec — exists at src/workflows/gds-quick-flow/gds-quick-spec/

✓ gds-code-review — exists at src/workflows/4-production/gds-code-review/

✓ gds-test-framework — exists at src/workflows/gametest/gds-test-framework/

✓ gds-quick-dev-new-preview — exists at src/workflows/gds-quick-flow/gds-quick-dev-new-preview/

✗ bmad-advanced-elicitation — NO DIRECTORY FOUND

Per the instruction "invoke the corresponding skill by its exact registered name... DO NOT invent capabilities on the fly," this breaks the contract—users cannot invoke non-existent skills.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@src/agents/gds-agent-game-solo-dev/SKILL.md` around lines 40 - 54, The
Capabilities table references two unregistered skills ("gds-quick-prototype" /
code QP and "bmad-advanced-elicitation" / code AE) which breaks the
invoke-by-exact-name contract; either remove the QP and AE rows from the table
in SKILL.md or implement and register those skills under the exact names
gds-quick-prototype and bmad-advanced-elicitation (ensuring their workflow
directories and registration match the other entries like gds-quick-dev,
gds-quick-spec, gds-code-review, gds-test-framework, and
gds-quick-dev-new-preview) so users can invoke them exactly as listed.

♻️ Duplicate comments (6)

src/workflows/3-technical/gds-create-epics-and-stories/SKILL.md (1)