Reserve bmad- prefix for official BMad creations only

bmadcode · bmadcode · commit f44073d4c8df · 2026-04-06T01:13:43.000-05:00
Remove the enforced bmad- prefix from all builder templates, validation
scripts, references, and docs. User-created skills now use agent-{name}
or {name} for standalone, and {code}-agent-{name} or {code}-{name} for
module-based skills. The bmad- prefix is documented as reserved for
official BMad ecosystem skills only. Convert mode retains any existing
prefix unless the user requests a rename.

Updated across all three builders (agent, workflow, module), their
validation scripts, test fixtures, and six documentation files.
diff --git a/docs/explanation/module-configuration.md b/docs/explanation/module-configuration.md
@@ -38,7 +38,7 @@ The `bmad-help` skill reads `module-help.csv` to understand what capabilities ar
 
 | Path                  | When to Use                                               | How It Works                                                                    |
 | --------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| **Setup skill**       | Multi-skill modules (2+ skills)                           | A dedicated `bmad-{code}-setup` skill handles registration for all skills       |
+| **Setup skill**       | Multi-skill modules (2+ skills)                           | A dedicated `{code}-setup` skill handles registration for all skills            |
 | **Self-registration** | Single-skill standalone modules                           | The skill itself registers on first run or when user passes `setup`/`configure` |
 
 The Module Builder detects which path to use based on what you give it: a folder of skills triggers the setup skill approach, a single skill triggers the standalone approach.
diff --git a/docs/explanation/what-are-modules.md b/docs/explanation/what-are-modules.md
@@ -25,7 +25,7 @@ This also means you can include remote URL skills in your own module to combine
 | Component           | Multi-Skill Module                                      | Standalone Module                                          |
 | ------------------- | ------------------------------------------------------- | ---------------------------------------------------------- |
 | **Skills**          | Two or more agents/workflows                            | A single agent or workflow                                 |
-| **Registration**    | Dedicated `bmad-{code}-setup` skill                     | Built into the skill itself (`assets/module-setup.md`)     |
+| **Registration**    | Dedicated `{code}-setup` skill                          | Built into the skill itself (`assets/module-setup.md`)     |
 | **module.yaml**     | In the setup skill's `assets/`                          | In the skill's own `assets/`                               |
 | **module-help.csv** | In the setup skill's `assets/`                          | In the skill's own `assets/`                               |
 | **Distribution**    | Plugin with multiple skill folders                      | Plugin with single skill folder + `marketplace.json`       |
diff --git a/docs/how-to/distribute-your-module.md b/docs/how-to/distribute-your-module.md
@@ -90,7 +90,7 @@ my-module/
 │   ├── my-workflow/
 │   │   ├── SKILL.md
 │   │   └── prompts/
-│   └── bmad-mymod-setup/        # Generated by Create Module (CM)
+│   └── mymod-setup/             # Generated by Create Module (CM)
 │       ├── SKILL.md
 │       ├── assets/
 │       │   ├── module.yaml
@@ -134,7 +134,7 @@ my-marketplace/
 │   ├── module-a/
 │   │   ├── skill-one/
 │   │   ├── skill-two/
-│   │   └── bmad-moda-setup/
+│   │   └── moda-setup/
 │   └── module-b/
 │       └── standalone-skill/
 ├── README.md
diff --git a/docs/reference/builder-commands.md b/docs/reference/builder-commands.md
@@ -15,6 +15,19 @@ Reference for the three core BMad Builder skills: the Agent Builder (`bmad-agent
 
 Both capabilities support autonomous/headless mode via `--headless` / `-H` flags.
 
+## Skill Naming
+
+| Context        | Agent Pattern              | Workflow Pattern       |
+| -------------- | -------------------------- | ---------------------- |
+| **Standalone** | `agent-{name}`             | `{name}`               |
+| **Module**     | `{modulecode}-agent-{name}`| `{modulecode}-{name}`  |
+
+Names must be kebab-case and match the folder name. Agents should include `agent` in the name. For module-based skills, the user chooses the module code prefix during the build.
+
+:::caution[Reserved Prefix]
+The `bmad-` prefix is reserved for official BMad creations. User-built skills should not include it. If converting a skill that already has a `bmad-` prefix, retain it unless the user requests a rename.
+:::
+
 ## Build Process (BP)
 
 The core creative path. Six phases of conversational discovery take you from a rough idea to a complete, tested skill folder.
@@ -354,7 +367,7 @@ Packages built skills as an installable BMad module. Auto-detects single-skill v
 5. Captures configuration variables and external dependencies
 6. Scaffolds the module infrastructure
 
-**Multi-skill output:** A dedicated `bmad-{code}-setup/` folder with merge scripts, cleanup scripts, and a generic SKILL.md.
+**Multi-skill output:** A dedicated `{code}-setup/` folder with merge scripts, cleanup scripts, and a generic SKILL.md.
 
 **Standalone output:** `assets/module-setup.md`, `assets/module.yaml`, and `assets/module-help.csv` embedded in the skill, plus merge scripts in `scripts/` and a `.claude-plugin/marketplace.json` for distribution. The skill's SKILL.md is updated to check for registration on activation.
 
diff --git a/docs/reference/workflow-patterns.md b/docs/reference/workflow-patterns.md
@@ -109,5 +109,5 @@ Module membership is orthogonal to skill type. Any type can be standalone or par
 
 | Context          | Naming                          | Init                                                               |
 | ---------------- | ------------------------------- | ------------------------------------------------------------------ |
-| **Module-based** | `bmad-{modulecode}-{skillname}` | Loads config from module config.yaml                              |
-| **Standalone**   | `bmad-{skillname}`              | Loads config from module config.yaml; simple utilities may opt out |
+| **Module-based** | `{modulecode}-{skillname}` | Loads config from module config.yaml                              |
+| **Standalone**   | `{skillname}`              | Loads config from module config.yaml; simple utilities may opt out |
diff --git a/docs/tutorials/build-your-first-module.md b/docs/tutorials/build-your-first-module.md
@@ -29,7 +29,7 @@ A BMad module bundles skills so they're discoverable and configurable. The Modul
 
 | Approach              | When to Use                                  | What Gets Generated                                             |
 | --------------------- | -------------------------------------------- | --------------------------------------------------------------- |
-| **Setup skill**       | Folder of 2+ skills                          | Dedicated `bmad-{code}-setup` skill with config and help assets |
+| **Setup skill**       | Folder of 2+ skills                          | Dedicated `{code}-setup` skill with config and help assets      |
 | **Self-registration** | Single standalone skill                      | Registration embedded in the skill's own `assets/` folder       |
 
 Both produce the same registration artifacts: `module.yaml` (identity and config variables) and `module-help.csv` (capability entries), which register with `bmad-help`.
@@ -92,7 +92,7 @@ The builder generates a dedicated setup skill:
 
 ```
 your-skills-folder/
-├── bmad-{code}-setup/           # Generated setup skill
+├── {code}-setup/                # Generated setup skill
 │   ├── SKILL.md                 # Setup instructions
 │   ├── scripts/                 # Config merge and cleanup scripts
 │   │   ├── merge-config.py
diff --git a/skills/bmad-agent-builder/assets/SKILL-template-bootloader.md b/skills/bmad-agent-builder/assets/SKILL-template-bootloader.md
@@ -1,5 +1,5 @@
 ---
-name: bmad-{module-code-or-empty}agent-{agent-name}
+name: {module-code-or-empty}agent-{agent-name}
 description: {skill-description}
 ---
 
diff --git a/skills/bmad-agent-builder/assets/SKILL-template.md b/skills/bmad-agent-builder/assets/SKILL-template.md
@@ -4,7 +4,7 @@
   For memory/autonomous agents, use SKILL-template-bootloader.md instead.
 -->
 ---
-name: bmad-{module-code-or-empty}agent-{agent-name}
+name: {module-code-or-empty}agent-{agent-name}
 description: { skill-description } # [4-6 word summary]. [trigger phrases]
 ---
 
diff --git a/skills/bmad-agent-builder/references/build-process.md b/skills/bmad-agent-builder/references/build-process.md
@@ -81,7 +81,7 @@ Gather through conversation: identity, capabilities, activation modes, memory ne
 
 Key structural context:
 
-- **Naming:** Standalone: `bmad-agent-{name}`. Module: `bmad-{modulecode}-agent-{name}`
+- **Naming:** Standalone: `agent-{name}`. Module: `{modulecode}-agent-{name}`. The `bmad-` prefix is reserved for official BMad creations only.
 - **Activation modes:** Interactive only, or Interactive + Headless (schedule/cron for background tasks)
 - **Memory architecture:** Agent memory at `{project-root}/_bmad/memory/{skillName}/`
 - **Access boundaries:** Read/write/deny zones stored in memory
diff --git a/skills/bmad-agent-builder/references/sample-init-sanctum.py b/skills/bmad-agent-builder/references/sample-init-sanctum.py
@@ -17,7 +17,7 @@
     skill-path:   Path to the skill directory (where SKILL.md, references/, assets/ live)
 
 Example:
-    uv run scripts/init-sanctum.py /Users/me/myproject /path/to/bmad-agent-creative-muse
+    uv run scripts/init-sanctum.py /Users/me/myproject /path/to/agent-creative-muse
 """
 
 import sys
@@ -26,7 +26,7 @@
 from datetime import date
 from pathlib import Path
 
-SKILL_NAME = "bmad-agent-creative-muse"
+SKILL_NAME = "agent-creative-muse"
 SANCTUM_DIR = SKILL_NAME
 
 # Files that stay in the skill bundle (only used during First Breath)
diff --git a/skills/bmad-agent-builder/references/script-opportunities-reference.md b/skills/bmad-agent-builder/references/script-opportunities-reference.md
@@ -74,7 +74,7 @@ All scripts use PEP 723 and `--help`. When a skill's prompt needs to invoke a sc
 
 ### 1. Frontmatter Validator
 
-> **Status: IMPLEMENTED** in `./scripts/prepass-structure-capabilities.py`. Handles frontmatter parsing, name validation (kebab-case, bmad-agent naming convention), description presence, and field validation as part of the structure prepass.
+> **Status: IMPLEMENTED** in `./scripts/prepass-structure-capabilities.py`. Handles frontmatter parsing, name validation (kebab-case, agent naming convention), description presence, and field validation as part of the structure prepass.
 
 **What:** Validate SKILL.md frontmatter structure and content
 
diff --git a/skills/bmad-agent-builder/references/standard-fields.md b/skills/bmad-agent-builder/references/standard-fields.md
@@ -6,7 +6,7 @@ Only these fields go in the YAML frontmatter block:
 
 | Field         | Description                                       | Example                                         |
 | ------------- | ------------------------------------------------- | ----------------------------------------------- |
-| `name`        | Full skill name (kebab-case, same as folder name) | `bmad-agent-tech-writer`, `bmad-cis-agent-lila` |
+| `name`        | Full skill name (kebab-case, same as folder name) | `agent-tech-writer`, `cis-agent-lila` |
 | `description` | [What it does]. [Use when user says 'X' or 'Y'.]  | See Description Format below                    |
 
 ## Content Fields
diff --git a/skills/bmad-agent-builder/references/template-substitution-rules.md b/skills/bmad-agent-builder/references/template-substitution-rules.md
@@ -4,7 +4,7 @@ The SKILL-template provides a minimal skeleton: frontmatter, overview, agent ide
 
 ## Frontmatter
 
-- `{module-code-or-empty}` → Module code prefix with hyphen (e.g., `cis-`) or empty for standalone
+- `{module-code-or-empty}` → Module code prefix with hyphen (e.g., `cis-`) or empty for standalone. The `bmad-` prefix is reserved for official BMad creations; user agents should not include it.
 - `{agent-name}` → Agent functional name (kebab-case)
 - `{skill-description}` → Two parts: [4-6 word summary]. [trigger phrases]
 - `{displayName}` → Friendly display name
@@ -17,7 +17,7 @@ The SKILL-template provides a minimal skeleton: frontmatter, overview, agent ide
 - `{if-module}` ... `{/if-module}` → Keep the content inside
 - `{if-standalone}` ... `{/if-standalone}` → Remove the entire block including markers
 - `{module-code}` → Module code without trailing hyphen (e.g., `cis`)
-- `{module-setup-skill}` → Name of the module's setup skill (e.g., `bmad-cis-setup`)
+- `{module-setup-skill}` → Name of the module's setup skill (e.g., `cis-setup`)
 
 ### For Standalone Agents
 
diff --git a/skills/bmad-agent-builder/scripts/prepass-structure-capabilities.py b/skills/bmad-agent-builder/scripts/prepass-structure-capabilities.py
@@ -6,7 +6,7 @@
 - Frontmatter parsing and validation
 - Section inventory (H2/H3 headers)
 - Template artifact detection
-- Agent name validation (bmad-{code}-agent-{name} or bmad-agent-{name})
+- Agent name validation (kebab-case, must contain 'agent')
 - Required agent sections (stateless vs memory agent bootloader detection)
 - Memory path consistency checking
 - Language/directness pattern grep
@@ -118,12 +118,11 @@ def parse_frontmatter(content: str) -> tuple[dict | None, list[dict]]:
             'severity': 'high', 'category': 'frontmatter',
             'issue': f'Name "{name}" is not kebab-case',
         })
-    elif not (re.match(r'^bmad-[a-z0-9]+-agent-[a-z0-9]+(-[a-z0-9]+)*$', name)
-              or re.match(r'^bmad-agent-[a-z0-9]+(-[a-z0-9]+)*$', name)):
+    elif 'agent' not in name.split('-'):
         findings.append({
             'file': 'SKILL.md', 'line': 1,
             'severity': 'medium', 'category': 'frontmatter',
-            'issue': f'Name "{name}" does not follow bmad-{{code}}-agent-{{name}} or bmad-agent-{{name}} pattern',
+            'issue': f'Name "{name}" should contain "agent" (e.g., agent-{{name}} or {{code}}-agent-{{name}})',
         })
 
     # description check
diff --git a/skills/bmad-module-builder/references/create-module.md b/skills/bmad-module-builder/references/create-module.md
@@ -147,7 +147,7 @@ python3 ./scripts/scaffold-setup-skill.py \
   --module-csv "{bmad_builder_reports}/{module-code}-temp-help.csv"
 ```
 
-This creates `bmad-{code}-setup/` in the user's skills folder containing:
+This creates `{code}-setup/` in the user's skills folder containing:
 
 - `./SKILL.md` — Generic setup skill with module-specific frontmatter
 - `./scripts/` — merge-config.py, merge-help-csv.py, cleanup-legacy.py
@@ -232,7 +232,7 @@ In headless mode: skip interactive questions, scaffold immediately, and return s
   "status": "success|error",
   "approach": "standalone|setup-skill",
   "module_code": "...",
-  "setup_skill": "bmad-{code}-setup",
+  "setup_skill": "{code}-setup",
   "skill_dir": "/path/to/skill/",
   "location": "/path/to/...",
   "files_created": ["..."],
diff --git a/skills/bmad-module-builder/references/ideate-module.md b/skills/bmad-module-builder/references/ideate-module.md
@@ -56,7 +56,7 @@ Don't rush to structure. Just listen, ask follow-ups, and capture.
 - **Module code** — 2-4 letter abbreviation (e.g., "cs3"). All skill names and memory paths derive from this. Changing it later means a find-and-replace across the entire plan.
 - **Description** — One-line summary of what the module does
 
-Write these to the plan document frontmatter immediately. All subsequent skill names use `bmad-{modulecode}-{skillname}`.
+Write these to the plan document frontmatter immediately. All subsequent skill names use `{modulecode}-{skillname}` (or `{modulecode}-agent-{name}` for agents). The `bmad-` prefix is reserved for official BMad creations.
 
 - **Standalone or expansion?** If expansion: which module does it extend? How do the new capabilities relate? Even expansion modules should provide value independently — the parent module being absent shouldn't break this one.
 
@@ -154,7 +154,7 @@ For each planned skill (whether agent or workflow), build a **self-contained bri
 
 **For agents:**
 
-- **Name** — following `bmad-{modulecode}-{skillname}` convention
+- **Name** — following `{modulecode}-agent-{name}` convention (agents) or `{modulecode}-{skillname}` (workflows)
 - **Persona** — who is this agent? Communication style, expertise, personality
 - **Core outcome** — what does success look like?
 - **The non-negotiable** — the one thing this agent must get right
diff --git a/skills/bmad-module-builder/references/validate-module.md b/skills/bmad-module-builder/references/validate-module.md
@@ -12,7 +12,7 @@ You are a module quality reviewer. Your job is to verify that a BMad module's st
 
 Ask the user for the path to their module's skills folder (or a single skill folder for standalone modules). The validation script auto-detects the module type:
 
-- **Multi-skill module:** Identifies the setup skill (`bmad-*-setup`) and all other skill folders
+- **Multi-skill module:** Identifies the setup skill (`*-setup`) and all other skill folders
 - **Standalone module:** Detected when no setup skill exists and the folder contains a single skill with `assets/module.yaml`. Validates: `assets/module-setup.md`, `assets/module.yaml`, `assets/module-help.csv`, `scripts/merge-config.py`, `scripts/merge-help-csv.py`
 
 ### 2. Run Structural Validation
diff --git a/skills/bmad-module-builder/scripts/scaffold-setup-skill.py b/skills/bmad-module-builder/scripts/scaffold-setup-skill.py
@@ -4,7 +4,7 @@
 # ///
 """Scaffold a BMad module setup skill from template.
 
-Copies the setup-skill-template into the target directory as bmad-{code}-setup/,
+Copies the setup-skill-template into the target directory as {code}-setup/,
 then writes the generated module.yaml and module-help.csv into the assets folder
 and updates the SKILL.md frontmatter with the module's identity.
 """
@@ -51,7 +51,7 @@ def main() -> int:
     args = parser.parse_args()
 
     template_dir = Path(__file__).resolve().parent.parent / "assets" / "setup-skill-template"
-    setup_skill_name = f"bmad-{args.module_code}-setup"
+    setup_skill_name = f"{args.module_code}-setup"
     target = Path(args.target_dir) / setup_skill_name
 
     if not template_dir.is_dir():
diff --git a/skills/bmad-module-builder/scripts/scaffold-standalone-module.py b/skills/bmad-module-builder/scripts/scaffold-standalone-module.py
@@ -146,15 +146,15 @@ def main() -> int:
 
     skill_dir_name = skill_dir.name
     marketplace_data = {
-        "name": f"bmad-{args.module_code}",
+        "name": args.module_code,
         "owner": {"name": ""},
         "license": "",
         "homepage": "",
         "repository": "",
         "keywords": ["bmad"],
         "plugins": [
             {
-                "name": f"bmad-{args.module_code}",
+                "name": args.module_code,
                 "source": "./",
                 "description": module_description,
                 "version": module_version,
diff --git a/skills/bmad-module-builder/scripts/tests/test-scaffold-setup-skill.py b/skills/bmad-module-builder/scripts/tests/test-scaffold-setup-skill.py
@@ -29,7 +29,7 @@ def run_scaffold(tmp: Path, **kwargs) -> tuple[int, dict]:
         kwargs.get(
             "csv_content",
             "module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs\n"
-            f'{module_name},bmad-{module_code}-example,Example,EX,An example skill,do-thing,,anytime,,,false,output_folder,artifact\n',
+            f'{module_name},{module_code}-example,Example,EX,An example skill,do-thing,,anytime,,,false,output_folder,artifact\n',
         )
     )
 
@@ -60,9 +60,9 @@ def test_basic_scaffold():
         code, data = run_scaffold(tmp, target_dir=str(target_dir))
         assert code == 0, f"Script failed: {data}"
         assert data["status"] == "success"
-        assert data["setup_skill"] == "bmad-tst-setup"
+        assert data["setup_skill"] == "tst-setup"
 
-        setup_dir = target_dir / "bmad-tst-setup"
+        setup_dir = target_dir / "tst-setup"
         assert setup_dir.is_dir()
         assert (setup_dir / "SKILL.md").is_file()
         assert (setup_dir / "scripts" / "merge-config.py").is_file()
@@ -87,8 +87,8 @@ def test_skill_md_frontmatter_substitution():
         )
         assert code == 0
 
-        skill_md = (target_dir / "bmad-xyz-setup" / "SKILL.md").read_text()
-        assert "bmad-xyz-setup" in skill_md
+        skill_md = (target_dir / "xyz-setup" / "SKILL.md").read_text()
+        assert "xyz-setup" in skill_md
         assert "XYZ Studio" in skill_md
         assert "{setup-skill-name}" not in skill_md
         assert "{module-name}" not in skill_md
@@ -115,11 +115,11 @@ def test_generated_files_written():
         )
         assert code == 0
 
-        yaml_content = (target_dir / "bmad-abc-setup" / "assets" / "module.yaml").read_text()
+        yaml_content = (target_dir / "abc-setup" / "assets" / "module.yaml").read_text()
         assert "ABC Module" in yaml_content
         assert "Custom desc" in yaml_content
 
-        csv_content = (target_dir / "bmad-abc-setup" / "assets" / "module-help.csv").read_text()
+        csv_content = (target_dir / "abc-setup" / "assets" / "module-help.csv").read_text()
         assert "bmad-abc-thing" in csv_content
         assert "DT" in csv_content
 
@@ -133,7 +133,7 @@ def test_anti_zombie_replaces_existing():
 
         # First scaffold
         run_scaffold(tmp, target_dir=str(target_dir))
-        stale_file = target_dir / "bmad-tst-setup" / "stale-marker.txt"
+        stale_file = target_dir / "tst-setup" / "stale-marker.txt"
         stale_file.write_text("should be removed")
 
         # Second scaffold should remove stale file
diff --git a/skills/bmad-module-builder/scripts/tests/test-validate-module.py b/skills/bmad-module-builder/scripts/tests/test-validate-module.py
diff --git a/skills/bmad-module-builder/scripts/validate-module.py b/skills/bmad-module-builder/scripts/validate-module.py
diff --git a/skills/bmad-workflow-builder/assets/SKILL-template.md b/skills/bmad-workflow-builder/assets/SKILL-template.md
diff --git a/skills/bmad-workflow-builder/references/build-process.md b/skills/bmad-workflow-builder/references/build-process.md
diff --git a/skills/bmad-workflow-builder/references/classification-reference.md b/skills/bmad-workflow-builder/references/classification-reference.md
diff --git a/skills/bmad-workflow-builder/references/quality-scan-workflow-integrity.md b/skills/bmad-workflow-builder/references/quality-scan-workflow-integrity.md
diff --git a/skills/bmad-workflow-builder/references/standard-fields.md b/skills/bmad-workflow-builder/references/standard-fields.md
diff --git a/skills/bmad-workflow-builder/references/template-substitution-rules.md b/skills/bmad-workflow-builder/references/template-substitution-rules.md
diff --git a/skills/bmad-workflow-builder/scripts/prepass-workflow-integrity.py b/skills/bmad-workflow-builder/scripts/prepass-workflow-integrity.py
