@clfhhc/bmad-methods-skills 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# BMAD-Methods-Skills
+
+Automatically convert BMAD-METHOD agents and workflows to Claude Skills format.
+
+## Distribution (New Projects)
+
+To install the BMAD bootstrap skill into a new project, you can use `npx`:
+
+```bash
+npx @clfhhc/bmad-methods-skills init
+```
+
+This will:
+1. Detect your AI tool (.agent, .cursor, or .claude)
+2. Install the `bootstrap-bmad-skills` and `enhance-bmad-skills` into your project
+3. Enable the `BS` command to fetch and install all other BMAD skills via `npx`
+
+## Documentation
+
+For full documentation on development, manual usage, and technical details, please see:
+
+- **[Getting Started](docs/getting-started.md)**: Installation, Usage, and Configuration
+- **[Technical Reference](docs/technical-reference.md)**: Output structure and conversion details
+- **[Development](docs/development.md)**: Project structure, contributing, and troubleshooting
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Credits
+
+- **BMAD-METHOD**: Created by [BMAD Code Organization](https://github.com/bmad-code-org/BMAD-METHOD)
+- **Claude Skills**: Format by [Anthropic](https://github.com/anthropics/skills)
+
+## Contributing
+
+Contributions welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Test thoroughly
+5. Submit a pull request
+
+## Related Projects
+
+- [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) - Original BMAD methodology
+- [Claude Skills](https://github.com/anthropics/skills) - Claude Skills specification and examples

package/bin/bmad-skills.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+
+import fs from 'fs-extra';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import readline from 'node:readline';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const pkgRoot = path.resolve(__dirname, '../');
+
+async function run() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (command === 'init') {
+    await init(args);
+  } else if (command === 'install') {
+    await install(args);
+  } else if (command === '--help' || command === '-h' || args.includes('--help') || args.includes('-h')) {
+    printHelp();
+  } else {
+    // Proxy to convert.js logic
+    await import('../convert.js');
+  }
+}
+
+
+
+/**
+ * Install specific skills from a source directory to the project's skill directory
+ */
+async function install(args) {
+  const sourceArg = args.find(a => a.startsWith('--from='))?.split('=')[1];
+  const force = args.includes('--force');
+
+  if (!sourceArg) {
+    console.error('❌ Missing required argument: --from=<path>');
+    return;
+  }
+
+  const sourcePath = path.resolve(process.cwd(), sourceArg);
+  if (!(await fs.pathExists(sourcePath))) {
+    console.error(`❌ Source path does not exist: ${sourcePath}`);
+    return;
+  }
+
+  // Detect tool
+  const toolInfo = await detectTool(args);
+  if (!toolInfo) return;
+
+  console.log(`📦 Installation Target: ${toolInfo.name} (${toolInfo.path})`);
+  console.log(`📂 Source: ${sourcePath}`);
+
+  // Get skills from source
+  const skills = await fs.readdir(sourcePath);
+  const validSkills = [];
+  
+  for (const skill of skills) {
+    if ((await fs.stat(path.join(sourcePath, skill))).isDirectory()) {
+      validSkills.push(skill);
+    }
+  }
+
+  if (validSkills.length === 0) {
+    console.warn('⚠️  No skill directories found in source.');
+    return;
+  }
+
+  console.log(`\nFound ${validSkills.length} skills to install.`);
+  
+  // Install
+  for (const skillName of validSkills) {
+    await installSkill(
+      skillName, 
+      path.join(sourcePath, skillName), 
+      path.join(process.cwd(), toolInfo.path, skillName),
+      force
+    );
+  }
+
+  console.log(`\n✅ Installation complete.`);
+}
+
+async function init(args) {
+  console.log('🚀 BMAD Skills Installer\n');
+
+  const toolInfo = await detectTool(args);
+  if (!toolInfo) return;
+
+  console.log(`📦 Installing Bootstrap Skills for ${toolInfo.name}...`);
+
+  // Dynamically find skills in package
+  const skillsDir = path.join(pkgRoot, 'skills');
+  if (!(await fs.pathExists(skillsDir))) {
+     console.error('❌ Critical Error: Package skills directory not found.');
+     return;
+  }
+
+  const skills = await fs.readdir(skillsDir);
+  const skillsToInstall = [];
+  
+  for (const skill of skills) {
+    // Only install directories as skills
+    if ((await fs.stat(path.join(skillsDir, skill))).isDirectory()) {
+        skillsToInstall.push(skill);
+    }
+  }
+
+  if (skillsToInstall.length === 0) {
+      console.warn('⚠️  No skills found in package to install.');
+      return;
+  }
+  
+  const force = args.includes('--force');
+
+  try {
+    for (const skillName of skillsToInstall) {
+      const sourceDir = path.join(skillsDir, skillName);
+      const targetDir = path.resolve(process.cwd(), toolInfo.path, skillName);
+      
+      await installSkill(skillName, sourceDir, targetDir, force);
+    }
+    
+    console.log(`\n✅ Successfully initialized in: ${toolInfo.path}/`);
+    console.log('\nNext steps:');
+    console.log(`1. Open your AI chat (${toolInfo.name}).`);
+    console.log('2. Type "BS" or "bootstrap-skills" to fetch and install the full BMAD method suite.');
+  } catch (error) {
+    console.error(`\n❌ Installation failed: ${error.message}`);
+  }
+}
+
+/**
+ * Helpher to copy skill with checks
+ */
+async function installSkill(name, source, target, force) {
+  if (await fs.pathExists(target)) {
+    if (!force) {
+      console.warn(`  ⚠ Skill '${name}' already exists. Skipping.`);
+    console.warn('    (Use --force to overwrite)');
+      return;
+    }
+    console.log(`  ↻ Updating ${name}...`);
+  } else {
+    console.log(`  + Installing ${name}...`);
+  }
+  
+  await fs.ensureDir(path.dirname(target));
+  await fs.copy(source, target, { overwrite: true });
+}
+
+/**
+ * Helper to detect AI tool
+ */
+async function detectTool(args) {
+  const toolArg = args.find(a => a.startsWith('--tool='))?.split('=')[1];
+  const force = args.includes('--force');
+
+  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);
+  
+  if (toolArg) {
+    selectedTool = tools.find(t => t.name.toLowerCase().includes(toolArg.toLowerCase()));
+  }
+
+  if (!selectedTool) {
+    if (force) {
+       // Default to antigravity if forced and not found
+       return tools[0];
+    }
+    
+    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;
+  }
+
+  return selectedTool;
+}
+
+function printHelp() {
+  console.log(`
+Usage: npx @clfhhc/bmad-methods-skills [command] [options]
+
+Commands:
+  init             Install bootstrap skills into the current project
+  install          Install skills from a local directory
+  [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
+  --from=<path>    (install only) Source directory containing skills
+
+Options (for conversion):
+  --repo <url>          Override BMAD repository URL
+  --branch <name>       Override BMAD branch
+  --output-dir <path>   Custom output directory
+  --identity-limit <n>  Character limit for identity
+  --[no-]examples       Enable/disable examples
+  --[no-]best-practices Enable/disable best practices
+  ... (see convert.js --help for full list)
+
+  -h, --help       Show this help
+  `);
+}
+
+run().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/config.json

@@ -0,0 +1,25 @@
+{
+  "bmadRepo": "https://github.com/bmad-code-org/BMAD-METHOD.git",
+  "bmadBranch": "main",
+  "outputDir": "./skills",
+  "tempDir": "./.temp/bmad-method",
+  "modules": ["bmm", "bmb", "cis", "core"],
+  "agentPaths": [
+    "src/core/agents",
+    "src/modules/*/agents"
+  ],
+  "workflowPaths": [
+    "src/core/workflows",
+    "src/modules/*/workflows"
+  ],
+  "enhancements": {
+    "optional": {
+      "addExamples": true,
+      "addBestPractices": true,
+      "addTroubleshooting": false,
+      "addRelatedSkills": true,
+      "generateMetaDocs": false
+    },
+    "identityCharLimit": null
+  }
+}

package/convert.js

@@ -0,0 +1,381 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fetchBmadRepo } from './src/utils/bmad-fetcher.js';
+import { findAgentsAndWorkflows } from './src/utils/file-finder.js';
+import { convertAgentToSkill } from './src/converters/agent-converter.js';
+import { convertWorkflowToSkill } from './src/converters/workflow-converter.js';
+import { writeSkill } from './src/utils/skill-writer.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Parse command line arguments
+ */
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const options = {
+    outputDir: null,
+    repoUrl: null,
+    branch: null,
+    identityCharLimit: null,
+    addExamples: null,
+    addBestPractices: null,
+    addTroubleshooting: null,
+    addRelatedSkills: null,
+    generateMetaDocs: null,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    
+    if (arg === '--output-dir' && i + 1 < args.length) {
+      options.outputDir = args[++i];
+    } else if (arg === '--repo' && i + 1 < args.length) {
+      options.repoUrl = args[++i];
+    } else if (arg === '--branch' && i + 1 < args.length) {
+      options.branch = args[++i];
+    } else if (arg === '--identity-limit' && i + 1 < args.length) {
+      const limit = Number.parseInt(args[++i], 10);
+      options.identityCharLimit = Number.isNaN(limit) ? null : limit;
+    } else if (arg === '--no-examples') {
+      options.addExamples = false;
+    } else if (arg === '--examples') {
+      options.addExamples = true;
+    } else if (arg === '--no-best-practices') {
+      options.addBestPractices = false;
+    } else if (arg === '--best-practices') {
+      options.addBestPractices = true;
+    } else if (arg === '--no-troubleshooting') {
+      options.addTroubleshooting = false;
+    } else if (arg === '--troubleshooting') {
+      options.addTroubleshooting = true;
+    } else if (arg === '--no-related-skills') {
+      options.addRelatedSkills = false;
+    } else if (arg === '--related-skills') {
+      options.addRelatedSkills = true;
+    } else if (arg === '--no-meta-docs') {
+      options.generateMetaDocs = false;
+    } else if (arg === '--meta-docs') {
+      options.generateMetaDocs = true;
+    } else if (arg === '--help' || arg === '-h') {
+      printHelp();
+      process.exit(0);
+    }
+  }
+
+  return options;
+}
+
+/**
+ * Print help message
+ */
+function printHelp() {
+  console.log(`
+BMAD to Skills Converter
+
+Usage: pnpm convert [options]
+
+Options:
+  --output-dir <path>        Custom output directory (default: ./skills)
+                            Use a non-version-controlled folder for custom configs
+  
+  --repo <url>              Override BMAD repository URL
+  --branch <name>           Override BMAD branch (default: main)
+  
+  --identity-limit <num>    Character limit for identity in description
+                            (default: no limit, use --identity-limit 200 to enable old behavior)
+  
+  Optional Enhancements (override config.json defaults):
+    --examples / --no-examples
+    --best-practices / --no-best-practices
+    --troubleshooting / --no-troubleshooting
+    --related-skills / --no-related-skills
+    --meta-docs / --no-meta-docs
+  
+  -h, --help                Show this help message
+
+Examples:
+  # Use default config (outputs to ./skills, version controlled)
+  pnpm convert
+  
+  # Output to custom directory with different settings
+  pnpm convert --output-dir ./custom-skills --identity-limit 200 --no-examples
+  
+  # Enable troubleshooting for this run
+  pnpm convert --troubleshooting
+`);
+}
+
+// Parse CLI arguments
+const cliOptions = parseArgs();
+
+// Load configuration
+const configPath = path.join(__dirname, 'config.json');
+let config;
+try {
+  if (!(await fs.pathExists(configPath))) {
+    throw new Error(`Configuration file not found: ${configPath}`);
+  }
+  const configContent = await fs.readFile(configPath, 'utf-8');
+  config = JSON.parse(configContent);
+
+  // Validate required config fields
+  const requiredFields = ['bmadRepo', 'bmadBranch', 'outputDir', 'tempDir'];
+  for (const field of requiredFields) {
+    if (!config[field]) {
+      throw new Error(`Missing required configuration field: ${field}`);
+    }
+  }
+
+  // Merge CLI options with config
+  if (cliOptions.outputDir) {
+    config.outputDir = cliOptions.outputDir;
+  }
+  if (cliOptions.repoUrl) {
+    config.bmadRepo = cliOptions.repoUrl;
+    console.log(`ℹ️  Overriding BMAD Repo: ${config.bmadRepo}`);
+  }
+  if (cliOptions.branch) {
+    config.bmadBranch = cliOptions.branch;
+    console.log(`ℹ️  Overriding BMAD Branch: ${config.bmadBranch}`);
+  }
+
+  // Initialize enhancements config if not present
+  if (!config.enhancements) {
+    config.enhancements = {};
+  }
+  if (!config.enhancements.optional) {
+    config.enhancements.optional = {
+      addExamples: true,
+      addBestPractices: true,
+      addTroubleshooting: false,
+      addRelatedSkills: true,
+      generateMetaDocs: false,
+    };
+  }
+
+  // Override with CLI options
+  if (cliOptions.identityCharLimit !== null) {
+    config.enhancements.identityCharLimit = cliOptions.identityCharLimit;
+  }
+  if (cliOptions.addExamples !== null) {
+    config.enhancements.optional.addExamples = cliOptions.addExamples;
+  }
+  if (cliOptions.addBestPractices !== null) {
+    config.enhancements.optional.addBestPractices = cliOptions.addBestPractices;
+  }
+  if (cliOptions.addTroubleshooting !== null) {
+    config.enhancements.optional.addTroubleshooting = cliOptions.addTroubleshooting;
+  }
+  if (cliOptions.addRelatedSkills !== null) {
+    config.enhancements.optional.addRelatedSkills = cliOptions.addRelatedSkills;
+  }
+  if (cliOptions.generateMetaDocs !== null) {
+    config.enhancements.optional.generateMetaDocs = cliOptions.generateMetaDocs;
+  }
+} catch (error) {
+  console.error(`❌ Failed to load configuration: ${error.message}`);
+  process.exit(1);
+}
+
+// Statistics
+const stats = {
+  agents: { total: 0, converted: 0, errors: 0 },
+  workflows: { total: 0, converted: 0, errors: 0 },
+  errors: [],
+};
+
+/**
+ * Main conversion function
+ */
+async function main() {
+  console.log('🚀 BMAD to Skills Converter\n');
+
+  try {
+    // Step 1: Fetch BMAD repository
+    console.log('📥 Fetching BMAD-METHOD repository...');
+    const bmadRoot = await fetchBmadRepo(
+      config.bmadRepo,
+      config.bmadBranch,
+      path.resolve(process.cwd(), config.tempDir),
+    );
+    console.log(`✓ Repository ready at: ${bmadRoot}\n`);
+
+    // Step 2: Discover agents and workflows
+    console.log('🔍 Discovering agents and workflows...');
+    const { agents, workflows } = await findAgentsAndWorkflows(
+      bmadRoot,
+      config.agentPaths,
+      config.workflowPaths,
+    );
+
+    stats.agents.total = agents.length;
+    stats.workflows.total = workflows.length;
+
+    console.log(
+      `✓ Found ${agents.length} agents and ${workflows.length} workflows\n`,
+    );
+
+    // Step 3: Prepare output directory
+    const outputDir = path.resolve(process.cwd(), config.outputDir);
+    await fs.ensureDir(outputDir);
+    console.log(`📁 Output directory: ${outputDir}\n`);
+
+    // Step 4: Convert agents
+    if (agents.length > 0) {
+      console.log('🤖 Converting agents...');
+      const agentOptions = {
+        identityCharLimit: config.enhancements.identityCharLimit ?? null,
+        allAgents: agents,
+        allWorkflows: workflows,
+      };
+      for (const agent of agents) {
+        try {
+          const skillContent = await convertAgentToSkill(agent.path, {
+            ...agentOptions,
+            currentModule: agent.module,
+          });
+          await writeSkill(
+            outputDir,
+            agent.module,
+            agent.name,
+            skillContent,
+          );
+          stats.agents.converted++;
+          console.log(`  ✓ ${agent.module}/${agent.name}`);
+        } catch (error) {
+          stats.agents.errors++;
+          stats.errors.push({
+            type: 'agent',
+            path: agent.path,
+            error: error.message,
+          });
+          console.error(
+            `  ✗ ${agent.module}/${agent.name}: ${error.message}`,
+          );
+        }
+      }
+      console.log();
+    }
+
+    // Step 5: Convert workflows
+    if (workflows.length > 0) {
+      console.log('⚙️  Converting workflows...');
+      const workflowOptions = {};
+      for (const workflow of workflows) {
+        try {
+          const skillContent = await convertWorkflowToSkill(
+            workflow.path,
+            workflow.instructionsPath,
+            workflow.workflowDir,
+            workflow.instructionsType,
+            {
+              ...workflowOptions,
+              isMarkdown: workflow.isMarkdown || false,
+            },
+          );
+          await writeSkill(
+            outputDir,
+            workflow.module,
+            workflow.name,
+            skillContent,
+            { workflowDir: workflow.workflowDir },
+          );
+          stats.workflows.converted++;
+          console.log(`  ✓ ${workflow.module}/${workflow.name}`);
+        } catch (error) {
+          stats.workflows.errors++;
+          stats.errors.push({
+            type: 'workflow',
+            path: workflow.path,
+            error: error.message,
+          });
+          console.error(
+            `  ✗ ${workflow.module}/${workflow.name}: ${error.message}`,
+          );
+        }
+      }
+      console.log();
+    }
+
+    // Step 6: Generate summary
+    await printSummary();
+  } catch (error) {
+    console.error(`\n❌ Fatal error: ${error.message}`);
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+/**
+ * Prints conversion summary
+ */
+async function printSummary() {
+  console.log('📊 Conversion Summary\n');
+  console.log('Agents:');
+  console.log(`  Total: ${stats.agents.total}`);
+  console.log(`  Converted: ${stats.agents.converted}`);
+  console.log(`  Errors: ${stats.agents.errors}`);
+  console.log();
+  console.log('Workflows:');
+  console.log(`  Total: ${stats.workflows.total}`);
+  console.log(`  Converted: ${stats.workflows.converted}`);
+  console.log(`  Errors: ${stats.workflows.errors}`);
+  console.log();
+
+  const totalConverted =
+    stats.agents.converted + stats.workflows.converted;
+  const totalErrors = stats.agents.errors + stats.workflows.errors;
+
+  if (totalErrors > 0) {
+    console.log('⚠️  Errors encountered:');
+    for (const err of stats.errors) {
+      console.log(`  - ${err.type}: ${err.path}`);
+      console.log(`    ${err.error}`);
+    }
+    console.log();
+  }
+
+  console.log(`✅ Successfully converted ${totalConverted} skills`);
+  console.log(
+    `📁 Output directory: ${path.resolve(process.cwd(), config.outputDir)}`,
+  );
+  
+  // Show configuration info
+  if (config.outputDir !== './skills') {
+    console.log('\n💡 Note: Output directory is not the default (./skills)');
+    console.log('   This directory is not version controlled.');
+    console.log('   To use default settings, run without --output-dir flag.');
+  }
+  
+  if (config.enhancements.identityCharLimit !== null) {
+    console.log(`\n💡 Note: Identity character limit is set to ${config.enhancements.identityCharLimit}`);
+    console.log('   Default behavior (no limit) is recommended for better content.');
+  }
+
+  // Print per-module breakdown
+  if (totalConverted > 0) {
+    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);
+      for (const module of modules) {
+        const modulePath = path.join(outputDir, module);
+        if ((await fs.stat(modulePath)).isDirectory()) {
+          const skills = await fs.readdir(modulePath);
+          console.log(`  ${module}: ${skills.length} skills`);
+        }
+      }
+    }
+  }
+}
+
+// Run the conversion
+main().catch((error) => {
+  console.error('Unhandled error:', error);
+  process.exit(1);
+});