@clfhhc/bmad-methods-skills 0.2.3 → 0.3.1

package/README.md

@@ -24,7 +24,9 @@ This installs `bootstrap-bmad-skills` and `enhance-bmad-skills`. Then open your
 1. **Fetches** the latest BMAD-METHOD from GitHub
 2. **Converts** agents and workflows to Claude Skills format
 3. **Installs** skills to your AI tool's directory
-4. **Generates** module config files (core, bmm)
+4. **Generates** module config files (default flat: `_config/bmm.yaml`, `_config/core.yaml`)
+
+Output uses a **flat** layout by default (`bmm-analyst/`, `core-bmad-master/`, etc.) so AI tools can discover all skills. See [Technical Reference](docs/technical-reference.md) for nested layout and options.
 
 ## Supported Tools
 

package/bin/bmad-skills.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import fs from 'fs-extra';
@@ -51,7 +52,9 @@ async function install(args) {
   const toolInfo = await detectTool(args);
   if (!toolInfo) return;
 
-  console.log(`📦 Installation Target: ${toolInfo.name} (${toolInfo.path})`);
+  console.log(
+    `📦 Installation Target: ${toolInfo.name} (${toolInfo.path})${toolInfo.scope === 'global' ? ' [global]' : ''}`
+  );
   console.log(`📂 Source: ${sourcePath}`);
 
   // Get skills from source
@@ -71,12 +74,12 @@ async function install(args) {
 
   console.log(`\nFound ${validSkills.length} modules to install.`);
 
-  // Install
+  // Install (toolInfo.path is absolute)
   for (const skillName of validSkills) {
     await installSkill(
       skillName,
       path.join(sourcePath, skillName),
-      path.join(process.cwd(), toolInfo.path, skillName),
+      path.join(toolInfo.path, skillName),
       force
     );
   }
@@ -105,7 +108,14 @@ async function init(args) {
     // We filter out init-specific args to avoid confusion, but keep repo/branch overrides
     const convertArgs = args.filter(
       (a) =>
-        !['init', '--bootstrap', '--force', '--tool'].some((x) => a.includes(x))
+        ![
+          'init',
+          '--bootstrap',
+          '--force',
+          '--tool',
+          '--scope',
+          '--global',
+        ].some((x) => a === x || a.startsWith(`${x}=`))
     );
 
     // Temporarily override argv for the imported module
@@ -145,12 +155,16 @@ async function init(args) {
 
     // 2. Install
     console.log(`\n--- Step 2: Installing to ${toolInfo.name} ---`);
-    await install([
+    const installArgs = [
       'install',
       `--from=${tempDir}`,
-      `--tool=${toolInfo.name.toLowerCase()}`, // Ensure generic name match
-      '--force', // Always force in bootstrap mode? Or respect args? Let's use force for bootstrap convenience
-    ]);
+      `--tool=${toolInfo.name.toLowerCase()}`,
+      '--force',
+    ];
+    const scopeArg = args.find((a) => a.startsWith('--scope='));
+    if (scopeArg) installArgs.push(scopeArg);
+    else if (args.includes('--global')) installArgs.push('--global');
+    await install(installArgs);
 
     // 3. Install bundled skills (bootstrap-bmad-skills, enhance-bmad-skills)
     // We reuse the logic from the standard init, but silence it slightly or just run it
@@ -162,7 +176,7 @@ async function init(args) {
           await installSkill(
             skill,
             path.join(skillsDir, skill),
-            path.join(process.cwd(), toolInfo.path, skill),
+            path.join(toolInfo.path, skill),
             true
           );
         }
@@ -212,7 +226,7 @@ async function init(args) {
   try {
     for (const skillName of skillsToInstall) {
       const sourceDir = path.join(skillsDir, skillName);
-      const targetDir = path.resolve(process.cwd(), toolInfo.path, skillName);
+      const targetDir = path.join(toolInfo.path, skillName);
 
       await installSkill(skillName, sourceDir, targetDir, force);
     }
@@ -230,7 +244,7 @@ async function init(args) {
 }
 
 /**
- * Helpher to copy skill with checks
+ * Helper to copy skill with checks
  */
 async function installSkill(name, source, target, force) {
   if (await fs.pathExists(target)) {
@@ -249,53 +263,96 @@ async function installSkill(name, source, target, force) {
 }
 
 /**
- * Helper to detect AI tool
+ * Tool definitions: project path (relative to cwd) and global path (relative to home).
+ * Paths match bootstrap-bmad-skills SKILL: .cursor/skills, .agent/skills, .claude/skills (project);
+ * ~/.cursor/skills, ~/.gemini/antigravity/skills, ~/.claude/skills (global).
+ */
+const TOOLS = [
+  {
+    name: 'Antigravity',
+    projectPath: '.agent/skills',
+    globalPath: '.gemini/antigravity/skills',
+    active: () => fs.pathExists('.agent'),
+  },
+  {
+    name: 'Cursor',
+    projectPath: '.cursor/skills',
+    globalPath: '.cursor/skills',
+    active: () => fs.pathExists('.cursor'),
+  },
+  {
+    name: 'Claude Code (Local)',
+    projectPath: '.claude/skills',
+    globalPath: '.claude/skills',
+    active: () => fs.pathExists('.claude'),
+  },
+];
+
+/**
+ * Resolve scope: --scope=global|project or --global (shorthand for --scope=global).
+ * Default is project.
+ */
+function parseScope(args) {
+  const scopeArg = args.find((a) => a.startsWith('--scope='))?.split('=')[1];
+  if (scopeArg && scopeArg !== 'global' && scopeArg !== 'project') {
+    console.warn(`⚠ Unknown --scope=${scopeArg}, using 'project'.`);
+  }
+  if (scopeArg === 'global' || scopeArg === 'project') return scopeArg;
+  if (args.includes('--global')) return 'global';
+  return 'project';
+}
+
+/**
+ * Detect AI tool and return { name, path, scope }.
+ * @param {string[]} args - CLI args (e.g. from process.argv.slice(2))
+ * @returns {Promise<{ name: string, path: string, scope: 'project'|'global' }|null>}
+ *   path is the absolute directory to install skills into (project or global).
  */
 async function detectTool(args) {
   const toolArg = args.find((a) => a.startsWith('--tool='))?.split('=')[1];
   const force = args.includes('--force');
+  const scope = parseScope(args);
 
-  const tools = [
-    {
-      name: 'Antigravity',
-      path: '.agent/skills',
-      active: await fs.pathExists('.agent'),
-    },
-    {
-      name: 'Cursor',
-      path: '.cursor/skills',
-      active: await fs.pathExists('.cursor'),
-    },
-    {
-      name: 'Claude Code (Local)',
-      path: '.claude/skills',
-      active: await fs.pathExists('.claude'),
-    },
-  ];
-
-  let selectedTool = tools.find((t) => t.active);
-
+  let selected = null;
   if (toolArg) {
-    selectedTool = tools.find((t) =>
+    selected = TOOLS.find((t) =>
       t.name.toLowerCase().includes(toolArg.toLowerCase())
     );
   }
-
-  if (!selectedTool) {
-    if (force) {
-      // Default to antigravity if forced and not found
-      return tools[0];
+  if (!selected && scope === 'project') {
+    for (const t of TOOLS) {
+      if (await t.active()) {
+        selected = t;
+        break;
+      }
     }
+  }
 
-    console.log('❌ No AI tool directory detected (.agent, .cursor, .claude).');
-    console.log(
-      '   Use --tool=<name> to force installation or ensure you are in the project root.'
-    );
-    console.log('   Available tools: antigravity, cursor, claude');
-    return null;
+  if (!selected) {
+    if (scope === 'global') {
+      console.log('❌ For --scope=global, --tool=<name> is required.');
+      console.log('   Example: --tool=cursor');
+      console.log('   Available tools: antigravity, cursor, claude');
+    } else if (force) {
+      selected = TOOLS.find((t) => t.name === 'Cursor') || TOOLS[0];
+    } else {
+      console.log(
+        '❌ No AI tool directory detected (.agent, .cursor, .claude).'
+      );
+      console.log(
+        '   Use --tool=<name> to force installation or ensure you are in the project root.'
+      );
+      console.log('   Available tools: antigravity, cursor, claude');
+    }
+    if (!selected) return null;
   }
 
-  return selectedTool;
+  const absPath =
+    scope === 'global'
+      ? path.join(os.homedir(), ...selected.globalPath.split('/'))
+      : path.resolve(process.cwd(), selected.projectPath);
+
+  return { name: selected.name, path: absPath, scope };
 }
 
 function printHelp() {
@@ -308,8 +365,10 @@ Commands:
   [no command]     Run the BMAD-to-Skills converter (proxy to convert.js)
 
 Options (for init/install):
-  --tool=<name>    Specify tool (antigravity, cursor, claude)
-  --force          Overwrite existing skills / Force installation
+  --tool=<name>    Specify tool (antigravity, cursor, claude). Required for --scope=global.
+  --scope=<s>      Install destination: project (default) or global
+  --global         Shorthand for --scope=global (installs to ~/.cursor/skills, etc.)
+  --force          Overwrite existing skills. With no tool dir, defaults to Cursor.
   --bootstrap      Automatically fetch, convert, and install full suite
   --from=<path>    (install only) Source directory containing skills
 

package/config.json

@@ -4,6 +4,12 @@
   "outputDir": "./skills",
   "tempDir": "./.temp/bmad-method",
   "modules": ["bmm", "core"],
+  "outputStructure": "flat",
+  "sourcePathPrefixesToStrip": ["src/modules/", "src/"],
+  "moduleExtractionPatterns": [
+    { "pattern": "^src\\/modules\\/([^/]+)\\/", "group": 1 },
+    { "pattern": "^src\\/([^/]+)\\/", "group": 1 }
+  ],
   "agentPaths": ["src/*/agents"],
   "workflowPaths": ["src/*/workflows"],
   "enhancements": {
@@ -20,28 +26,33 @@
     {
       "src": "src/bmm/agents/tech-writer/tech-writer-sidecar/documentation-standards.md",
       "dest": "bmm/tech-writer/data/documentation-standards.md",
+      "destFlat": "bmm-tech-writer/data/documentation-standards.md",
       "name": "Documentation Standards"
     },
     {
       "src": "src/bmm/testarch/tea-index.csv",
       "dest": "bmm/tea/tea-index.csv",
+      "destFlat": "bmm-tea/tea-index.csv",
       "name": "TEA Index"
     },
     {
       "src": "src/bmm/testarch/knowledge",
       "dest": "bmm/tea/knowledge",
+      "destFlat": "bmm-tea/knowledge",
       "name": "TEA Knowledge Base",
       "isDirectory": true
     },
     {
       "src": "src/core/resources/excalidraw",
       "dest": "core/resources/excalidraw",
+      "destFlat": "_resources/excalidraw",
       "name": "Excalidraw Resources",
       "isDirectory": true
     },
     {
       "src": "src/bmm/workflows/excalidraw-diagrams/_shared",
       "dest": "bmm/excalidraw-diagrams/_shared",
+      "destFlat": "_resources/bmm-excalidraw-shared",
       "name": "Excalidraw Diagrams Shared (templates, library)",
       "isDirectory": true
     }
@@ -54,9 +65,24 @@
   "pathPatterns": [
     {
       "pattern": "\\{project-root\\}/_bmad/bmm/workflows/workflow-status/init/workflow\\.(yaml|md)",
-      "replacement": "{skill-root}/bmm/init/SKILL.md",
+      "replacement": "{skill-root}/bmm/workflow-init/SKILL.md",
       "description": "Init nested workflow (must run before workflow-status dir)"
     },
+    {
+      "pattern": "\\{project-root\\}/_bmad/bmm/workflows/workflow-status/init",
+      "replacement": "{skill-root}/bmm/workflow-init",
+      "description": "Init nested workflow dir (source path; must run before workflow-status pattern)"
+    },
+    {
+      "pattern": "\\{skill-root\\}/bmm/workflow-status/init",
+      "replacement": "{skill-root}/bmm/workflow-init",
+      "description": "Init nested workflow dir (nested layout; fix workflow-status/init)"
+    },
+    {
+      "pattern": "\\{skill-root\\}/bmm/init",
+      "replacement": "{skill-root}/bmm/workflow-init",
+      "description": "Init nested workflow (nested; bmm/init -> bmm/workflow-init)"
+    },
     {
       "pattern": "\\{project-root\\}/_bmad/bmm/workflows/document-project/workflows",
       "replacement": "{skill-root}/bmm/document-project",
@@ -252,5 +278,227 @@
       "replacement": "{skill-root}/core/{workflow-name}/",
       "description": "Template {workflow-name}"
     }
+  ],
+  "pathPatternsFlat": [
+    {
+      "pattern": "\\{project-root\\}/_bmad/bmm/workflows/workflow-status/init/workflow\\.(yaml|md)",
+      "replacement": "{skill-root}/bmm-workflow-init/SKILL.md",
+      "description": "Init nested workflow (must run before workflow-status dir)"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/bmm/workflows/workflow-status/init",
+      "replacement": "{skill-root}/bmm-workflow-init",
+      "description": "Init nested workflow dir (source path; must run before workflow-status pattern)"
+    },
+    {
+      "pattern": "\\{skill-root\\}/bmm-workflow-status/init",
+      "replacement": "{skill-root}/bmm-workflow-init",
+      "description": "Init nested workflow dir (flat; fix workflow-status/init)"
+    },
+    {
+      "pattern": "\\{skill-root\\}/bmm/workflow-status/init",
+      "replacement": "{skill-root}/bmm-workflow-init",
+      "description": "Init nested workflow dir (flat; fix nested-form when using pathPatternsFlat)"
+    },
+    {
+      "pattern": "\\{skill-root\\}/bmm-init",
+      "replacement": "{skill-root}/bmm-workflow-init",
+      "description": "Init nested workflow (flat; legacy bmm-init -> bmm-workflow-init)"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/bmm/workflows/document-project/workflows",
+      "replacement": "{skill-root}/bmm-document-project",
+      "description": "document-project workflows dir"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/core/workflows/([^/\\s'\"]+)/workflow\\.(yaml|md|xml)",
+      "replacement": "{skill-root}/core-$1/SKILL.md",
+      "description": "Core workflow files"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/bmm/workflows/(?:\\d-[^/]+/)?([^/\\s'\"]+)/workflow\\.(yaml|md|xml)",
+      "replacement": "{skill-root}/bmm-$1/SKILL.md",
+      "description": "BMM workflow files (incl. category folders)"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/bmm/(?:workflows/)?testarch/([^/\\s'\"]+)/workflow\\.(yaml|md|xml)",
+      "replacement": "{skill-root}/bmm-testarch-$1/SKILL.md",
+      "description": "Testarch workflow files"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/bmm/workflows/excalidraw-diagrams/([^/\\s'\"]+)/workflow\\.(yaml|md|xml)",
+      "replacement": "{skill-root}/bmm-$1/SKILL.md",
+      "description": "Excalidraw-diagrams workflow files"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/bmm/workflows/bmad-quick-flow/([^/\\s'\"]+)/workflow\\.(yaml|md)",
+      "replacement": "{skill-root}/bmm-$1/SKILL.md",
+      "description": "bmad-quick-flow workflow files"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/core/tasks/workflow\\.xml",
+      "replacement": "{skill-root}/core-tasks/SKILL.md",
+      "description": "Core tasks workflow.xml"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/core/resources/excalidraw/([^/\\s'\"]+)",
+      "replacement": "{skill-root}/_resources/excalidraw/$1",
+      "description": "Excalidraw helper resources"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/bmm/workflows/excalidraw-diagrams/_shared/([^/\\s'\"]+)",
+      "replacement": "{skill-root}/_resources/bmm-excalidraw-shared/$1",
+      "description": "Excalidraw-diagrams _shared files"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/bmm/workflows/excalidraw-diagrams/_shared(?!/)",
+      "replacement": "{skill-root}/_resources/bmm-excalidraw-shared",
+      "description": "Excalidraw-diagrams _shared directory"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/(core|bmm)/workflows/(?:\\d-[^/]+/)?([^/\\s'\"]+)/([^/\\s'\"]+\\.(md|csv|yaml|xml))",
+      "replacement": "{skill-root}/$1-$2/$3",
+      "description": "Files within workflow dirs"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/(core|bmm)/workflows/(?:\\d-[^/]+/)?([^/\\s'\"]+)/steps/([^/\\s'\"]+)",
+      "replacement": "{skill-root}/$1-$2/steps/$3",
+      "description": "Step files within workflows"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/bmm/workflows/\\d-[^/]+/([^/\\s'\"]+)(?=['\\s`])",
+      "replacement": "{skill-root}/bmm-$1",
+      "description": "BMM workflows dir with category"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/bmm/workflows/([a-z][-a-z0-9]+)(?=['\\s`])",
+      "replacement": "{skill-root}/bmm-$1",
+      "description": "BMM workflows dir (no category)"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/bmm/workflows/bmad-quick-flow/([^/\\s'\"]+)(?=['\\s`])",
+      "replacement": "{skill-root}/bmm-$1",
+      "description": "bmad-quick-flow directory refs"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/bmm/workflows/testarch/([^/\\s'\"]+)(?=['\\s`])",
+      "replacement": "{skill-root}/bmm-testarch-$1",
+      "description": "Testarch directory refs"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/bmm/workflows/workflow-status(?=['\\s`/])",
+      "replacement": "{skill-root}/bmm-workflow-status",
+      "description": "workflow-status directory"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/(bmm|core)/config\\.yaml",
+      "replacement": "{skill-root}/_config/$1.yaml",
+      "description": "Module config files"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/_config/agent-manifest\\.csv",
+      "replacement": "{skill-root}/agent-manifest.csv",
+      "description": "Agent manifest"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/bmm/testarch/tea-index\\.csv",
+      "replacement": "{skill-root}/bmm-tea/tea-index.csv",
+      "description": "TEA tea-index.csv"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/bmm/testarch/knowledge/",
+      "replacement": "{skill-root}/bmm-tea/knowledge/",
+      "description": "TEA Knowledge Base (migrated)"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/bmm/data/documentation-standards\\.md",
+      "replacement": "{skill-root}/bmm-tech-writer/data/documentation-standards.md",
+      "description": "documentation-standards (migrated to tech-writer)"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/_memory/([^/\\s'\"]+)",
+      "replacement": "{runtime-memory}/$1",
+      "description": "Runtime memory"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/core/tasks/([^/\\s'\"]+\\.xml)",
+      "replacement": "{skill-root}/core-tasks/$1",
+      "description": "Core tasks XML files"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/(bmm|core)/tasks/([^/\\s'\"]+)",
+      "replacement": "{skill-root}/$1-tasks/$2",
+      "description": "Module tasks"
+    },
+    {
+      "pattern": "\\{project-root\\}/_data/([^/\\s'\"]+)",
+      "replacement": "{project-data}/$1",
+      "description": "Project data files"
+    },
+    {
+      "pattern": "\\{project-root\\}/src/modules/(bmm|core)/workflows/(?:\\d-[^/]+/)?([^/\\s'\"]+)",
+      "replacement": "{skill-root}/$1-$2",
+      "description": "src/modules workflow refs"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/cis/workflows/([^/\\s'\"]+)/workflow\\.(yaml|md|xml)",
+      "replacement": "{skill-root}/cis-$1/SKILL.md",
+      "description": "CIS workflow files"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/(bmm|core|cis)/workflows/([a-z][-a-z0-9]+)(?=['\\s`]|$)",
+      "replacement": "{skill-root}/$1-$2",
+      "description": "Generic workflow fallback (only when no extra path segment)"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/\\{module-code\\}/workflows/",
+      "replacement": "{skill-root}/{module-code}/",
+      "description": "Template {module-code}"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/\\{module-id\\}/workflows/",
+      "replacement": "{skill-root}/{module-id}/",
+      "description": "Template {module-id}"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/\\{module\\}/",
+      "replacement": "{skill-root}/{module}/",
+      "description": "Template {module}"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/\\{module_code\\}/workflows/",
+      "replacement": "{skill-root}/{module_code}/",
+      "description": "Template {module_code}"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/\\[module\\]/",
+      "replacement": "{skill-root}/[module]/",
+      "description": "Template [module]"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/\\[module-path\\]/workflows/",
+      "replacement": "{skill-root}/[module-path]/",
+      "description": "Template [module-path]"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/\\[MODULE FOLDER\\]/",
+      "replacement": "{skill-root}/[MODULE FOLDER]/",
+      "description": "Template [MODULE FOLDER]"
+    },
+    {
+      "pattern": "\\{project-root\\}/\\.\\.\\./([^/\\s'\"]+)/workflow\\.(yaml|md|xml)",
+      "replacement": "{skill-root}/.../$1/SKILL.md",
+      "description": "Ellipsis workflow in docs"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/\\.\\.\\./",
+      "replacement": "{skill-root}/.../",
+      "description": "Ellipsis in documentation"
+    },
+    {
+      "pattern": "\\{project-root\\}/_bmad/core/workflows/\\{workflow-name\\}/",
+      "replacement": "{skill-root}/core-{workflow-name}/",
+      "description": "Template {workflow-name}"
+    }
   ]
 }

package/convert.js

@@ -96,35 +96,52 @@ async function getModuleConfigContent(moduleName, bmadRoot = null) {
 }
 
 /**
- * Generate config.yaml for each module in the output directory
- * Checks BMAD repo for config templates, falls back to defaults
+ * Generate config for each module in the output directory
+ * Nested: outputDir/{module}/config.yaml. Flat: outputDir/_config/{module}.yaml
  * @param {string} outputDir - Output directory containing skills
  * @param {string|null} bmadRoot - Optional path to BMAD repo for template lookup
+ * @param {string[]} modules - Module names (e.g. config.modules)
+ * @param {string} outputStructure - 'flat' | 'nested'
  */
-async function generateModuleConfigs(outputDir, bmadRoot = null) {
+async function generateModuleConfigs(
+  outputDir,
+  bmadRoot = null,
+  modules = ['bmm', 'core'],
+  outputStructure = 'flat'
+) {
   console.log('📝 Generating module configs...');
 
-  const modules = await fs.readdir(outputDir);
-
-  for (const moduleName of modules) {
-    const modulePath = path.join(outputDir, moduleName);
-
-    // Skip if not a directory
-    if (!(await fs.stat(modulePath)).isDirectory()) {
-      continue;
+  if (outputStructure === 'flat') {
+    const configDir = path.join(outputDir, '_config');
+    await fs.ensureDir(configDir);
+    for (const moduleName of modules) {
+      const configPath = path.join(configDir, `${moduleName}.yaml`);
+      if (await fs.pathExists(configPath)) {
+        console.log(`  ⏭ _config/${moduleName}.yaml (exists)`);
+        continue;
+      }
+      const configContent = await getModuleConfigContent(moduleName, bmadRoot);
+      await fs.writeFile(configPath, configContent, 'utf8');
+      console.log(`  ✓ _config/${moduleName}.yaml`);
     }
-
-    const configPath = path.join(modulePath, 'config.yaml');
-
-    // Don't overwrite existing config
-    if (await fs.pathExists(configPath)) {
-      console.log(`  ⏭ ${moduleName}/config.yaml (exists)`);
-      continue;
+  } else {
+    for (const moduleName of modules) {
+      const modulePath = path.join(outputDir, moduleName);
+      if (
+        !(await fs.pathExists(modulePath)) ||
+        !(await fs.stat(modulePath)).isDirectory()
+      ) {
+        continue;
+      }
+      const configPath = path.join(modulePath, 'config.yaml');
+      if (await fs.pathExists(configPath)) {
+        console.log(`  ⏭ ${moduleName}/config.yaml (exists)`);
+        continue;
+      }
+      const configContent = await getModuleConfigContent(moduleName, bmadRoot);
+      await fs.writeFile(configPath, configContent, 'utf8');
+      console.log(`  ✓ ${moduleName}/config.yaml`);
     }
-
-    const configContent = await getModuleConfigContent(moduleName, bmadRoot);
-    await fs.writeFile(configPath, configContent, 'utf8');
-    console.log(`  ✓ ${moduleName}/config.yaml`);
   }
 
   console.log();
@@ -161,6 +178,7 @@ function parseArgs() {
   const args = process.argv.slice(2);
   const options = {
     outputDir: null,
+    outputStructure: null,
     repoUrl: null,
     branch: null,
     identityCharLimit: null,
@@ -176,6 +194,8 @@ function parseArgs() {
 
     if (arg === '--output-dir' && i + 1 < args.length) {
       options.outputDir = args[++i];
+    } else if (arg.startsWith('--output-structure=')) {
+      options.outputStructure = arg.split('=')[1];
     } else if (arg === '--repo' && i + 1 < args.length) {
       options.repoUrl = args[++i];
     } else if (arg === '--branch' && i + 1 < args.length) {
@@ -224,6 +244,7 @@ Usage: pnpm convert [options]
 Options:
   --output-dir <path>        Custom output directory (default: ./skills)
                             Use a non-version-controlled folder for custom configs
+  --output-structure=flat|nested   Override config (default: flat)
   
   --repo <url>              Override BMAD repository URL
   --branch <name>           Override BMAD branch (default: main)
@@ -285,6 +306,10 @@ try {
     config.bmadBranch = cliOptions.branch;
     console.log(`ℹ️  Overriding BMAD Branch: ${config.bmadBranch}`);
   }
+  if (cliOptions.outputStructure) {
+    config.outputStructure = cliOptions.outputStructure;
+    console.log(`ℹ️  Overriding output structure: ${config.outputStructure}`);
+  }
 
   // Initialize enhancements config if not present
   if (!config.enhancements) {
@@ -348,14 +373,23 @@ async function main() {
     );
     console.log(`✓ Repository ready at: ${bmadRoot}\n`);
 
+    const outputStructure = config.outputStructure ?? 'flat';
+    const pathPatternsEffective =
+      outputStructure === 'flat'
+        ? config.pathPatternsFlat || []
+        : config.pathPatterns || [];
+    if (outputStructure === 'flat' && !pathPatternsEffective.length) {
+      console.warn(
+        '⚠️  outputStructure is "flat" but pathPatternsFlat is missing or empty. Path rewriting may be incorrect.'
+      );
+    }
+
     // Pre-compile path pattern regexes for performance
-    if (config.pathPatterns && config.pathPatterns.length > 0) {
-      for (const item of config.pathPatterns) {
-        try {
-          item.regex = new RegExp(item.pattern, 'g');
-        } catch (e) {
-          console.warn(`⚠️  Invalid path pattern in config: ${e.message}`);
-        }
+    for (const item of pathPatternsEffective) {
+      try {
+        item.regex = new RegExp(item.pattern, 'g');
+      } catch (e) {
+        console.warn(`⚠️  Invalid path pattern in config: ${e.message}`);
       }
     }
 
@@ -367,7 +401,8 @@ async function main() {
     const { agents, workflows } = await findAgentsAndWorkflows(
       bmadRoot,
       config.agentPaths,
-      config.workflowPaths
+      config.workflowPaths,
+      { moduleExtractionPatterns: config.moduleExtractionPatterns }
     );
 
     stats.agents.total = agents.length;
@@ -399,28 +434,31 @@ async function main() {
     // Maps source file paths (relative to bmadRoot) to destination skill paths
     const skillMap = new Map();
 
-    for (const agent of agents) {
-      let relPath = path.relative(bmadRoot, agent.path);
-      // Normalize path to match BMAD content conventions
-      if (relPath.startsWith('src/modules/')) {
-        relPath = relPath.replace('src/modules/', '');
-      } else if (relPath.startsWith('src/')) {
-        relPath = relPath.replace('src/', '');
+    const stripPrefixes = config.sourcePathPrefixesToStrip;
+    const normalizeRelPath = (p) => {
+      if (Array.isArray(stripPrefixes)) {
+        for (const prefix of stripPrefixes) {
+          if (p.startsWith(prefix)) return p.slice(prefix.length);
+        }
+        return p;
       }
+      if (p.startsWith('src/modules/')) return p.replace('src/modules/', '');
+      if (p.startsWith('src/')) return p.replace('src/', '');
+      return p;
+    };
+
+    for (const agent of agents) {
+      const relPath = normalizeRelPath(path.relative(bmadRoot, agent.path));
       skillMap.set(relPath, { module: agent.module, name: agent.name });
     }
 
     for (const workflow of workflows) {
-      let relPath = path.relative(bmadRoot, workflow.path);
-      // Normalize path to match BMAD content conventions
-      if (relPath.startsWith('src/modules/')) {
-        relPath = relPath.replace('src/modules/', '');
-      } else if (relPath.startsWith('src/')) {
-        relPath = relPath.replace('src/', '');
-      }
+      const relPath = normalizeRelPath(path.relative(bmadRoot, workflow.path));
       skillMap.set(relPath, { module: workflow.module, name: workflow.name });
     }
 
+    const skillMapOptions = { ...(config.skillMap || {}), outputStructure };
+
     // Step 4: Convert agents
     if (agents.length > 0) {
       console.log('🤖 Converting agents...');
@@ -437,8 +475,9 @@ async function main() {
           });
           await writeSkill(outputDir, agent.module, agent.name, skillContent, {
             skillMap,
-            pathPatterns: config.pathPatterns,
-            skillMapOptions: config.skillMap || {},
+            pathPatterns: pathPatternsEffective,
+            skillMapOptions,
+            outputStructure,
           });
           stats.agents.converted++;
           console.log(`  ✓ ${agent.module}/${agent.name}`);
@@ -469,9 +508,6 @@ async function main() {
             {
               ...workflowOptions,
               isMarkdown: workflow.isMarkdown || false,
-              bmadRoot,
-              bmadRepo: config.bmadRepo,
-              bmadBranch: config.bmadBranch,
             }
           );
           await writeSkill(
@@ -482,8 +518,9 @@ async function main() {
             {
               workflowDir: workflow.workflowDir,
               skillMap,
-              pathPatterns: config.pathPatterns,
-              skillMapOptions: config.skillMap || {},
+              pathPatterns: pathPatternsEffective,
+              skillMapOptions,
+              outputStructure,
             }
           );
           stats.workflows.converted++;
@@ -508,14 +545,20 @@ async function main() {
       bmadRoot,
       outputDir,
       config.auxiliaryResources || [],
-      config.pathPatterns
+      pathPatternsEffective,
+      outputStructure
     );
 
     // Step 7: Generate module configs (checks BMAD repo for templates)
-    await generateModuleConfigs(outputDir, bmadRoot);
+    await generateModuleConfigs(
+      outputDir,
+      bmadRoot,
+      config.modules || ['bmm', 'core'],
+      outputStructure
+    );
 
     // Step 8: Generate summary
-    await printSummary();
+    await printSummary(outputStructure);
   } catch (error) {
     console.error(`\n❌ Fatal error: ${error.message}`);
     console.error(error.stack);
@@ -525,8 +568,9 @@ async function main() {
 
 /**
  * Prints conversion summary
+ * @param {string} [outputStructure] - 'flat' | 'nested'. For flat, per-module breakdown is omitted.
  */
-async function printSummary() {
+async function printSummary(outputStructure = 'flat') {
   console.log('📊 Conversion Summary\n');
   console.log('Agents:');
   console.log(`  Total: ${stats.agents.total}`);
@@ -572,11 +616,9 @@ async function printSummary() {
     );
   }
 
-  // Print per-module breakdown
-  if (totalConverted > 0) {
+  // Print per-module breakdown (nested only; flat uses top-level dirs)
+  if (totalConverted > 0 && outputStructure === 'nested') {
     console.log('\n📦 Per-module breakdown:');
-
-    // Count by module from output structure
     const outputDir = path.resolve(process.cwd(), config.outputDir);
     if (await fs.pathExists(outputDir)) {
       const modules = await fs.readdir(outputDir);
@@ -584,7 +626,6 @@ async function printSummary() {
         const modulePath = path.join(outputDir, module);
         if ((await fs.stat(modulePath)).isDirectory()) {
           const items = await fs.readdir(modulePath);
-          // Only count directories (skills), not files like config.yaml
           let skillCount = 0;
           for (const item of items) {
             const itemPath = path.join(modulePath, item);

package/docs/getting-started.md

@@ -29,10 +29,11 @@ This single command:
 4. ✅ Generates `config.yaml` for each module (core, bmm)
 5. ✅ Cleans up temporary files
 
-**After installation**, customize the generated config files at:
-- `{skills-dir}/core/config.yaml` - User preferences
-- `{skills-dir}/bmm/config.yaml` - Project settings
-- `{skills-dir}/{module}/config.yaml` - Module specific configuration
+**After installation**, customize the generated config files. With the default **flat** layout:
+- `{skills-dir}/_config/core.yaml` - User preferences
+- `{skills-dir}/_config/bmm.yaml` - Project settings
+
+With `outputStructure: "nested"`: `{skills-dir}/bmm/config.yaml`, `{skills-dir}/core/config.yaml`.
 
 ### Option B: AI-Guided Workflow
 
@@ -121,6 +122,7 @@ pnpm convert --no-examples --no-best-practices --no-related-skills
 - `--output-dir <path>` - Custom output directory (default: `./skills`)
   - Use a non-version-controlled folder for custom configs
   - Default `./skills` directory is version controlled with default settings
+- `--output-structure=flat|nested` - Override `config.json` (default: flat)
 
 - `--identity-limit <num>` - Character limit for identity in description
   - Default: no limit (recommended)

package/docs/technical-reference.md

@@ -2,7 +2,30 @@
 
 ## Output Structure
 
-The converter generates skills organized by module in the `skills/` directory at the project root:
+The converter supports two output layouts controlled by `config.json` → `outputStructure` (default: **`"flat"`**). Flat layout is required for AI tools (Claude Code, Cursor) that discover skills only in immediate subfolders of `skills/`.
+
+### Flat (default)
+
+skills/
+├── bmm-analyst/
+│   └── SKILL.md
+├── bmm-architect/
+│   └── SKILL.md
+├── core-bmad-master/
+│   └── SKILL.md
+├── core-brainstorming/
+│   └── SKILL.md
+├── _config/
+│   ├── bmm.yaml             # Module config (was bmm/config.yaml)
+│   └── core.yaml            # Module config (was core/config.yaml)
+├── _resources/
+│   ├── excalidraw/          # excalidraw-helpers.md, validate-json-instructions.md, etc.
+│   └── bmm-excalidraw-shared/   # excalidraw-templates.yaml, excalidraw-library.json
+├── bootstrap-bmad-skills/
+└── enhance-bmad-skills/
+```
+
+### Nested (`outputStructure: "nested"`)
 
 skills/
 ├── bmm/
@@ -11,14 +34,14 @@ skills/
 │   ├── pm/
 │   │   └── SKILL.md
 │   ├── excalidraw-diagrams/
-│   │   └── _shared/         # excalidraw-templates.yaml, excalidraw-library.json
-│   ├── config.yaml          # Project configuration
-│   └── (skills...)          # BMM methodology skills (includes create-excalidraw-*)
+│   │   └── _shared/
+│   ├── config.yaml
+│   └── (skills...)
 ├── core/
-│   ├── config.yaml          # Core user settings
+│   ├── config.yaml
 │   ├── resources/
-│   │   └── excalidraw/      # excalidraw-helpers.md, validate-json-instructions.md, etc.
-│   └── (skills...)          # Core system skills
+│   │   └── excalidraw/
+│   └── (skills...)
 ```
 
 Each skill folder contains:
@@ -99,22 +122,25 @@ Migrated resources are processed recursively. Any text-based files within these
 
 To make skills portable, path rewriting uses **config-driven regex patterns** plus a dynamic map of discovered skills:
 
-- **Source of truth**: All path-rewrite rules are defined in `config.json` under `pathPatterns`. Each entry has `pattern` (regex string), `replacement`, and optional `description`. Order in the array matters—specific rules (e.g. init, document-project) must come before generic ones.
-- **skillMap options**: The dynamic skillMap block (exact file and directory rewrites from discovered agents/workflows) uses `config.skillMap`: `sourcePrefix` (regex fragment for `{project-root}/_bmad/`), `dirLookahead` (lookahead so directory matches don’t over-match, e.g. space/quote/backtick or end), and `replacementPrefix` (e.g. `{skill-root}`). Omit `skillMap` to use built-in defaults.
+- **Source of truth**: Path-rewrite rules are in `config.json` under `pathPatterns` (nested) and `pathPatternsFlat` (flat). Each entry has `pattern` (regex), `replacement`, and optional `description`. **`outputStructure`** chooses which set is used: `"flat"` (default) uses `pathPatternsFlat`; `"nested"` uses `pathPatterns`. Only `replacement` differs (e.g. flat: `{skill-root}/bmm-analyst/`, `{skill-root}/_config/{module}.yaml`, `{skill-root}/_resources/excalidraw/`).
+- **skillMap options**: The dynamic skillMap (exact rewrites for discovered agents/workflows) uses `config.skillMap`: `sourcePrefix`, `dirLookahead`, `replacementPrefix`. `outputStructure` in `skillMapOptions` controls `/{module}/{name}/` (nested) vs `/{module}-{name}/` (flat).
 - **Pattern optimization**: Regexes are pre-compiled at startup for performance.
-- **Exact skill resolution**: A `skillMap` of discovered agents/workflows is applied after `pathPatterns` to resolve exact source paths to destination skills.
-- **Skill root variable**: Output uses `{skill-root}` instead of fragile relative paths.
-- **Standardized paths** (from `pathPatterns`): Cross-skill `{skill-root}/{module}/{skill}/SKILL.md`; resources under `data/`; Excalidraw under `core/resources/excalidraw/` and `bmm/excalidraw-diagrams/_shared/`.
-- **Migrated resources**: Paths inside files migrated via `auxiliaryResources` are rewritten using the same `pathPatterns`.
+- **Exact skill resolution**: `skillMap` is applied with `pathPatterns`/`pathPatternsFlat` to resolve source paths to destination skills.
+- **Skill root variable**: Output uses `{skill-root}`.
+- **Standardized paths**: Flat: `{skill-root}/{module}-{skill}/SKILL.md`, `{skill-root}/_config/{module}.yaml`, `{skill-root}/_resources/...`. Nested: `{skill-root}/{module}/{skill}/SKILL.md`, `{skill-root}/{module}/config.yaml`, etc.
+- **Migrated resources**: `auxiliaryResources` supports optional `destFlat`; when `outputStructure === "flat"` and `destFlat` is set, it is used instead of `dest`. Migrated content is rewritten with the active path patterns.
 
 This ensures skills work correctly regardless of where the root `skills` directory is installed and that cross-skill references are robust.
 
-The converter creates `config.yaml` files for each module. The generation logic prioritizes templates from the BMAD repository:
+The converter creates module config files. The generation logic prioritizes templates from the BMAD repository:
 
 1. **BMAD Template**: Checks for `config-template.yaml` within the module directory in the BMAD repo.
 2. **Fallback Defaults**: If no template exists in the repo, hardcoded defaults from `convert.js` are used.
 
-Skills reference these configs using `{skill-root}/{module}/config.yaml`. Users should customize these files for their project settings.
+- **Flat**: configs are `{skill-root}/_config/bmm.yaml` and `{skill-root}/_config/core.yaml`.
+- **Nested**: configs are `{skill-root}/bmm/config.yaml` and `{skill-root}/core/config.yaml`.
+
+Users should customize these files for their project.
 
 ## Placeholder Variables
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clfhhc/bmad-methods-skills",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "Convert BMAD-METHOD agents and workflows to Claude Skills format",
   "type": "module",
   "repository": {
@@ -23,7 +23,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node tests/path-rewriter.test.js",
+    "test": "node --test tests/path-rewriter.test.js tests/workflow-converter.test.js",
     "convert": "node convert.js",
     "clean": "node -e \"import('fs-extra').then(fs => { try { fs.removeSync('./.temp'); console.log('Cleaned temp directory'); } catch(e) { console.error('Error:', e.message); } })\"",
     "clean:all": "node -e \"import('fs-extra').then(fs => { try { fs.removeSync('./skills'); fs.removeSync('./.temp'); console.log('Cleaned skills and temp directories'); } catch(e) { console.error('Error:', e.message); } })\"",

package/skills/bootstrap-bmad-skills/SKILL.md

@@ -11,9 +11,15 @@ description: Bootstrap and install BMAD-METHOD skills for Claude Code, Cursor, A
 
 ---
 
-## Quick Start
+## When You Run BS (Guided Flow)
 
-Run the one-liner to install everything automatically:
+For **`BS`** or **`bootstrap-skills`**: (1) Ask Step 1 (Tool), Step 2 (Scope), and **Configure Installation**—offer defaults. (2) Summarize and **confirm** before running commands. (3) Run the one-liner or Manual (Steps 3–5) as appropriate; write the user’s config to `{skill-root}/_config/core.yaml` and `{skill-root}/_config/bmm.yaml` after install.
+
+---
+
+## Quick Start (Unattended)
+
+Use only when the user explicitly wants to **skip prompts** (e.g. “just run it” or “use defaults”):
 
 ```bash
 npx @clfhhc/bmad-methods-skills init --tool=[TOOL] --bootstrap
@@ -21,13 +27,13 @@ npx @clfhhc/bmad-methods-skills init --tool=[TOOL] --bootstrap
 
 Replace `[TOOL]` with `antigravity`, `cursor`, or `claude`.
 
-Then proceed to **Configure Installation** below.
+Afterward, the user can edit `{skill-root}/_config/core.yaml` and `{skill-root}/_config/bmm.yaml`, or you can run the **Configure Installation** questions and apply the answers to those files.
 
 ---
 
 ## Manual Workflow
 
-Use this when you need more control or want a guided experience.
+Use when the user wants a guided experience, needs **global** install, or when you must run Fetch & Convert and Install as separate steps.
 
 ### Step 1: Tool Selection
 
@@ -47,6 +53,8 @@ Ask whether to install skills **globally** or **project-specific**:
 | **Global** | Skills available across all projects | Cursor: `~/.cursor/skills/`; Antigravity: `~/.gemini/antigravity/skills/`; Claude Code: `~/.claude/skills/` |
 | **Project-Specific** | Skills limited to current repo | Cursor: `.cursor/skills/`; Antigravity: `.agent/skills/`; Claude Code: `.claude/skills/` |
 
+**Note:** On **install**, use `--scope=project` (default) or `--scope=global` / `--global`. Project: `.{tool}/skills/` under cwd (run from project root). Global: `~/.cursor/skills` etc.; `--tool` required.
+
 ### Step 3: Fetch & Convert
 
 ```bash
@@ -55,10 +63,20 @@ npx @clfhhc/bmad-methods-skills --output-dir .temp/converted-skills
 
 ### Step 4: Install
 
+**Project-specific** (default; run from project root):
+
 ```bash
 npx @clfhhc/bmad-methods-skills install --from=.temp/converted-skills --tool=[TOOL] --force
 ```
 
+**Global** (`--tool` required; works from any directory):
+
+```bash
+npx @clfhhc/bmad-methods-skills install --from=.temp/converted-skills --tool=[TOOL] --force --scope=global
+```
+
+(`--global` = `--scope=global`.)
+
 ### Step 5: Clean up
 
 ```bash
@@ -71,7 +89,7 @@ rm -rf .temp
 
 Prompt the user for each configuration setting. Offer the defaults shown:
 
-### Core Configuration (`{skill-root}/core/config.yaml`)
+### Core Configuration (`{skill-root}/_config/core.yaml`)
 
 | Setting | Question | Default |
 |---------|----------|---------|
@@ -80,7 +98,7 @@ Prompt the user for each configuration setting. Offer the defaults shown:
 | `document_output_language` | Preferred document output language? | English |
 | `output_folder` | Where should output files be saved? | `_bmad-output` |
 
-### BMM Configuration (`{skill-root}/bmm/config.yaml`)
+### BMM Configuration (`{skill-root}/_config/bmm.yaml`)
 
 | Setting | Question | Default |
 |---------|----------|---------|
@@ -95,12 +113,12 @@ Prompt the user for each configuration setting. Offer the defaults shown:
 ## Verify
 
 1. Skills installed at the correct destination
-2. Config files exist (core, bmm)
-3. Paths use `{skill-root}` variable
+2. Config files exist: `_config/core.yaml`, `_config/bmm.yaml`
+3. Paths under `_config` use the `{skill-root}` variable
 
 ## Guidelines
 
-- **Guided Flow**: If the user starts with `BS`, prioritize asking the questions in Steps 1, 2, and the Configuration section before running commands.
+- **Guided Flow**: For `BS`, follow **When You Run BS (Guided Flow)** above.
 - **Confirmation**: Always summarize the plan and ask for confirmation before executing automated installation commands.
-- **Defaults**: Offer defaults - don't force user to answer every question if they are happy with the suggested values.
+- **Defaults**: Offer defaults—don’t force the user to answer every question if they accept the suggested values.
 - **Overwrite**: Ask before overwriting existing skills unless `--force` is used.

package/src/converters/workflow-converter.js

@@ -19,11 +19,8 @@ export async function convertWorkflowToSkill(
   _instructionsType = null,
   options = {}
 ) {
-  const { isMarkdown, bmadRoot, bmadRepo, bmadBranch } = {
+  const { isMarkdown } = {
     isMarkdown: false,
-    bmadRoot: null,
-    bmadRepo: null,
-    bmadBranch: 'main',
     ...options,
   };
 
@@ -123,16 +120,9 @@ export async function convertWorkflowToSkill(
 
       // Read instructions if available
       if (instructionsPath && (await fs.pathExists(instructionsPath))) {
-        // Create link to instructions instead of embedding
-        if (bmadRoot && bmadRepo) {
-          const relativePath = path.relative(bmadRoot, instructionsPath);
-          const repoBase = bmadRepo.replace(/\.git$/, '');
-          const link = `${repoBase}/blob/${bmadBranch}/${relativePath}`;
-          instructionsContent = `See instructions at: [${path.basename(instructionsPath)}](${link})`;
-        } else {
-          // Fallback if no repo info
-          instructionsContent = `See instructions in: ${path.basename(instructionsPath)}`;
-        }
+        // Link to local auxiliary file (instructions are copied into the skill dir by writeSkill)
+        const basename = path.basename(instructionsPath);
+        instructionsContent = `See instructions at: [${basename}](${basename})`;
       } else {
         instructionsContent = 'No instructions available.';
       }

package/src/utils/file-finder.js

@@ -8,12 +8,14 @@ import yaml from 'js-yaml';
  * @param {string} bmadRoot - Root path of BMAD-METHOD repository
  * @param {string[]} agentPaths - Glob patterns for agent paths
  * @param {string[]} workflowPaths - Glob patterns for workflow paths
+ * @param {{ moduleExtractionPatterns?: Array<{ pattern: string, group: number }> }} [options] - Optional. moduleExtractionPatterns from config for extractModule.
  * @returns {Promise<{agents: Array, workflows: Array}>}
  */
 export async function findAgentsAndWorkflows(
   bmadRoot,
   agentPaths,
-  workflowPaths
+  workflowPaths,
+  options = {}
 ) {
   if (!bmadRoot || !(await fs.pathExists(bmadRoot))) {
     throw new Error(`BMAD root directory does not exist: ${bmadRoot}`);
@@ -23,6 +25,7 @@ export async function findAgentsAndWorkflows(
     throw new Error('agentPaths and workflowPaths must be arrays');
   }
 
+  const { moduleExtractionPatterns } = options;
   const agents = [];
   const workflows = [];
 
@@ -43,7 +46,7 @@ export async function findAgentsAndWorkflows(
           }
 
           const relativePath = path.relative(bmadRoot, filePath);
-          const module = extractModule(relativePath);
+          const module = extractModule(relativePath, moduleExtractionPatterns);
           const name = path.basename(filePath, '.agent.yaml');
 
           if (!name || name.trim() === '') {
@@ -120,7 +123,10 @@ export async function findAgentsAndWorkflows(
             }
 
             const relativePath = path.relative(bmadRoot, absolutePath);
-            const module = extractModule(relativePath);
+            const module = extractModule(
+              relativePath,
+              moduleExtractionPatterns
+            );
 
             const isMarkdown = absolutePath.endsWith('.md');
             const isXml = absolutePath.endsWith('.xml');
@@ -241,12 +247,22 @@ export async function findAgentsAndWorkflows(
   return { agents, workflows };
 }
 
-function extractModule(relativePath) {
-  // Support legacy structure: src/modules/bmm/agents/...
+function extractModule(relativePath, moduleExtractionPatterns) {
+  if (
+    Array.isArray(moduleExtractionPatterns) &&
+    moduleExtractionPatterns.length > 0
+  ) {
+    for (const { pattern, group } of moduleExtractionPatterns) {
+      const m = relativePath.match(new RegExp(pattern));
+      if (m && m[group] != null) return m[group];
+    }
+    return null;
+  }
+
+  // Fallback when moduleExtractionPatterns not provided (backward compatibility)
   const modulesMatch = relativePath.match(/^src\/modules\/([^/]+)\//);
   if (modulesMatch) return modulesMatch[1];
 
-  // Support new structure (and core): src/bmm/agents/... or src/core/agents/...
   const srcMatch = relativePath.match(/^src\/([^/]+)\//);
   if (srcMatch) return srcMatch[1];
 

package/src/utils/path-rewriter.js

@@ -8,7 +8,7 @@
  * @param {string} content - File content to process
  * @param {Map|null} skillMap - Map of source paths to destination skill info
  * @param {Array|null} pathPatterns - Array of {pattern, replacement, description?} from config.json pathPatterns (source of truth for all regex rewrites)
- * @param {Object} [skillMapOptions] - From config.json skillMap: { sourcePrefix, dirLookahead, replacementPrefix } for the dynamic skillMap block
+ * @param {Object} [skillMapOptions] - From config.json skillMap: { sourcePrefix, dirLookahead, replacementPrefix, outputStructure? }. outputStructure defaults to 'flat'.
  * @returns {string} Content with rewritten paths
  */
 export function rewriteBmadPaths(
@@ -20,9 +20,10 @@ export function rewriteBmadPaths(
   let result = content;
 
   const opts = skillMapOptions || {};
-  const sourcePrefix = opts.sourcePrefix ?? '\\{project-root\\}/_bmad/';
-  const dirLookahead = opts.dirLookahead ?? "(?=['\\s`]|$)";
-  const replacementPrefix = opts.replacementPrefix ?? '{skill-root}';
+  const sourcePrefix = opts.sourcePrefix;
+  const dirLookahead = opts.dirLookahead;
+  const replacementPrefix = opts.replacementPrefix;
+  const outputStructure = opts.outputStructure ?? 'flat';
 
   // === CONFIG-DRIVEN PATTERNS (Applied First) ===
   if (pathPatterns && pathPatterns.length > 0) {
@@ -38,7 +39,13 @@ export function rewriteBmadPaths(
   }
 
   // === MAP-BASED EXACT REPLACEMENTS (Priority) ===
-  if (skillMap) {
+  // Requires sourcePrefix, dirLookahead, replacementPrefix from config.skillMap
+  if (
+    skillMap &&
+    sourcePrefix != null &&
+    dirLookahead != null &&
+    replacementPrefix != null
+  ) {
     const dirMap = new Map();
 
     // 1. Rewrite Workflow Files
@@ -53,10 +60,11 @@ export function rewriteBmadPaths(
       // srcPath is now normalized by convert.js
       const escapedPath = srcPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
       const regex = new RegExp(`${sourcePrefix}${escapedPath}`, 'g');
-      result = result.replace(
-        regex,
-        `${replacementPrefix}/${module}/${name}/SKILL.md`
-      );
+      const fileReplacement =
+        outputStructure === 'flat'
+          ? `${replacementPrefix}/${module}-${name}/SKILL.md`
+          : `${replacementPrefix}/${module}/${name}/SKILL.md`;
+      result = result.replace(regex, fileReplacement);
     }
 
     // 2. Rewrite Workflow Directories
@@ -72,7 +80,11 @@ export function rewriteBmadPaths(
         `${sourcePrefix}${escapedDir}${dirLookahead}`,
         'g'
       );
-      result = result.replace(regex, `${replacementPrefix}/${module}/${name}`);
+      const dirReplacement =
+        outputStructure === 'flat'
+          ? `${replacementPrefix}/${module}-${name}`
+          : `${replacementPrefix}/${module}/${name}`;
+      result = result.replace(regex, dirReplacement);
     }
   }
 

package/src/utils/resource-migrator.js

@@ -7,22 +7,31 @@ import { rewriteBmadPaths, shouldRewritePaths } from './path-rewriter.js';
  * @param {string} bmadRoot - Root of the fetched BMAD repo
  * @param {string} outputDir - Root of the skills output directory
  * @param {Array} auxiliaryResources - Array of migration definitions from config
+ * @param {Array|null} pathPatterns - Path patterns for rewriting (pathPatterns or pathPatternsFlat)
+ * @param {string} [outputStructure] - 'flat' | 'nested'. When 'flat' and res.destFlat exists, use destFlat.
  */
 export async function migrateResources(
   bmadRoot,
   outputDir,
   auxiliaryResources = [],
-  pathPatterns = null
+  pathPatterns = null,
+  outputStructure = 'flat'
 ) {
   console.log('📦 Migrating auxiliary resources...');
 
-  // Use config-provided resources, or empty array if none
-  const migrations = auxiliaryResources.map((res) => ({
-    src: res.src,
-    dest: res.dest,
-    name: res.name,
-    isDirectory: res.isDirectory || false,
-  }));
+  // Use config-provided resources; resolve dest vs destFlat when outputStructure is 'flat'
+  const migrations = auxiliaryResources.map((res) => {
+    const dest =
+      outputStructure === 'flat' && res.destFlat != null
+        ? res.destFlat
+        : res.dest;
+    return {
+      src: res.src,
+      dest,
+      name: res.name,
+      isDirectory: res.isDirectory || false,
+    };
+  });
 
   if (migrations.length === 0) {
     console.log('  ⚠️  No auxiliary resources configured in config.json');

package/src/utils/skill-writer.js

@@ -10,6 +10,7 @@ import { rewriteBmadPaths, shouldRewritePaths } from './path-rewriter.js';
  * @param {string} skillContent - SKILL.md content
  * @param {Object} options - Additional options
  * @param {string} options.workflowDir - Workflow directory (for copying templates/checklists)
+ * @param {string} [options.outputStructure] - 'flat' | 'nested'. Default 'flat'.
  * @returns {Promise<string>} Path to written SKILL.md file
  */
 export async function writeSkill(
@@ -40,7 +41,11 @@ export async function writeSkill(
     );
   }
 
-  const skillDir = path.join(outputDir, module, sanitizedName);
+  const outputStructure = options.outputStructure ?? 'flat';
+  const skillDir =
+    outputStructure === 'flat'
+      ? path.join(outputDir, `${module}-${sanitizedName}`)
+      : path.join(outputDir, module, sanitizedName);
 
   try {
     // Create directory structure