BitBadges · trevormil · Apr 14, 2026 · Apr 13, 2026 · Apr 13, 2026 · Apr 13, 2026
diff --git a/packages/bitbadgesjs-sdk/scripts/gen-skill-docs.ts b/packages/bitbadgesjs-sdk/scripts/gen-skill-docs.ts
@@ -0,0 +1,112 @@
+#!/usr/bin/env tsx
+/**
+ * Generate docs pages from builder skill instructions.
+ *
+ * Source of truth: src/builder/resources/skillInstructions.ts
+ * Output: ../bitbadges-docs/x-tokenization/examples/skills/
+ *
+ * Ported from the old bitbadges-builder-mcp/scripts/gen-skill-docs.ts
+ * when the MCP server was folded into the SDK. The only real change is
+ * the import path — SKILL_INSTRUCTIONS now lives under the SDK's builder
+ * subpath. Output shape + docs destination are unchanged so the existing
+ * SUMMARY.md entries and any review diffs stay stable.
+ *
+ * Usage: npx tsx scripts/gen-skill-docs.ts
+ *        (optional) DOCS_OUTPUT_DIR=/path/to/override npx tsx scripts/gen-skill-docs.ts
+ */
+
+import { SKILL_INSTRUCTIONS } from '../src/builder/resources/skillInstructions.js';
+import { writeFileSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+// Resolve __dirname in a way that works both when tsx runs this file as
+// ESM (import.meta.url present) and when it transpiles to CJS (falls
+// back to __dirname if already defined). The docs output path is
+// resolved relative to this script's location so running from any cwd
+// produces the same result.
+const here =
+  typeof __dirname !== 'undefined'
+    ? __dirname
+    : dirname(fileURLToPath(import.meta.url));
+
+const DOCS_DIR =
+  process.env.DOCS_OUTPUT_DIR ||
+  join(here, '../../../../bitbadges-docs/x-tokenization/examples/skills');
+
+mkdirSync(DOCS_DIR, { recursive: true });
+
+const categoryLabels: Record<string, string> = {
+  'token-type': 'Token Types',
+  standard: 'Standards',
+  approval: 'Approval Patterns',
+  feature: 'Features',
+  advanced: 'Advanced',
+};
+
+// Group skills by category for the README
+const byCategory = new Map<string, typeof SKILL_INSTRUCTIONS>();
+for (const skill of SKILL_INSTRUCTIONS) {
+  const list = byCategory.get(skill.category) || [];
+  list.push(skill);
+  byCategory.set(skill.category, list);
+}
+
+// Generate individual skill pages
+for (const skill of SKILL_INSTRUCTIONS) {
+  const filename = `${skill.id}.md`;
+  const refs = skill.referenceCollectionIds?.length
+    ? `\n\n## Reference Collections\n\n${skill.referenceCollectionIds
+        .map((id) => `- [Collection ${id}](https://bitbadges.io/collections/${id})`)
+        .join('\n')}`
+    : '';
+
+  const content = `# ${skill.name}
+
+> ${skill.description}
+
+**Category:** ${categoryLabels[skill.category] || skill.category}
+
+## Summary
+
+${skill.summary}
+
+## Instructions
+
+${skill.instructions}${refs}
+`;
+
+  writeFileSync(join(DOCS_DIR, filename), content);
+}
+
+// Generate README index
+const categoryOrder = ['token-type', 'standard', 'approval', 'feature', 'advanced'];
+let readme = `# 🤖 Builder Skills
+
+These pages document every guided build skill available in the BitBadges Builder (shipped as part of [bitbadgesjs-sdk](https://github.com/BitBadges/bitbadgesjs)). Each skill provides step-by-step instructions for building a specific type of token or configuring a specific feature.
+
+> **Tip:** If you're using the BitBadges builder in Claude, Cursor, or another AI tool via the MCP server (\`npx bitbadgesjs-sdk-mcp\`) or the \`bitbadges-cli builder\` command surface, these instructions are loaded automatically when you select a skill. These pages are provided as a human-readable reference.
+
+`;
+
+for (const cat of categoryOrder) {
+  const skills = byCategory.get(cat);
+  if (!skills?.length) continue;
+  readme += `## ${categoryLabels[cat] || cat}\n\n`;
+  for (const skill of skills) {
+    readme += `- [${skill.name}](${skill.id}.md) — ${skill.description}\n`;
+  }
+  readme += '\n';
+}
+
+writeFileSync(join(DOCS_DIR, 'README.md'), readme);
+
+// Print SUMMARY.md lines for easy copy-paste
+console.log('\n=== Add these lines to SUMMARY.md as a top-level section ===\n');
+console.log('## 🤖 Builder Skills\n');
+console.log('* [Overview](x-tokenization/examples/skills/README.md)');
+for (const skill of SKILL_INSTRUCTIONS) {
+  console.log(`  * [${skill.name}](x-tokenization/examples/skills/${skill.id}.md)`);
+}
+
+console.log(`\n✅ Generated ${SKILL_INSTRUCTIONS.length} skill pages + README in ${DOCS_DIR}`);
diff --git a/packages/bitbadgesjs-sdk/src/builder/index.ts b/packages/bitbadgesjs-sdk/src/builder/index.ts
@@ -1,11 +1,15 @@
 #!/usr/bin/env node
 
 /**
- * BitBadges Builder MCP Server
+ * BitBadges Builder — Model Context Protocol (MCP) stdio server bin.
  *
- * Enable natural language collection creation via MCP.
+ * Entry point when users run `bitbadges-builder` or point Claude Desktop at
+ * this package as an MCP server. The actual tool/resource handlers live in
+ * `./tools/registry.ts` and `./resources/registry.ts` — this file is just
+ * the stdio transport + lifecycle wrapper. For in-process use, import the
+ * registry directly or call `bitbadges-cli builder …`.
  *
- * Example usage:
+ * Example natural-language usage (via an MCP client):
  * > "Create a 1:1 backed USDC stablecoin with 100 USDC/day spend limit"
  *
  * Supported collection types:

diff --git a/packages/bitbadgesjs-sdk/src/builder/resources/examplesDocs.ts b/packages/bitbadgesjs-sdk/src/builder/resources/examplesDocs.ts
@@ -130,31 +130,33 @@ Create a collection of 100 unique NFTs with a public mint approval.
           "cosmosCoinBackedPath": null
         },
         "aliasPathsToAdd": [],
-        "cosmosCoinWrapperPathsToAdd": []
+        "cosmosCoinWrapperPathsToAdd": [],
+        "_meta": {
+          "metadataPlaceholders": {
+            "ipfs://METADATA_COLLECTION": {
+              "name": "My NFT Collection",
+              "description": "A collection of 100 unique NFTs.",
+              "image": "ipfs://QmCollectionImage..."
+            },
+            "ipfs://METADATA_TOKEN_{id}": {
+              "name": "My NFT Collection Token",
+              "description": "A unique NFT from the My NFT Collection.",
+              "image": "ipfs://QmTokenImage..."
+            },
+            "ipfs://METADATA_APPROVAL_mint": {
+              "name": "Public Mint",
+              "description": "Allows anyone to mint one NFT for 5 BADGE.",
+              "image": ""
+            }
+          }
+        }
       }
     }
   ],
   "memo": "",
   "fee": {
     "amount": [{ "denom": "ubadge", "amount": "5000" }],
     "gas": "500000"
-  },
-  "metadataPlaceholders": {
-    "ipfs://METADATA_COLLECTION": {
-      "name": "My NFT Collection",
-      "description": "A collection of 100 unique NFTs.",
-      "image": "ipfs://QmCollectionImage..."
-    },
-    "ipfs://METADATA_TOKEN_{id}": {
-      "name": "My NFT Collection Token",
-      "description": "A unique NFT from the My NFT Collection.",
-      "image": "ipfs://QmTokenImage..."
-    },
-    "ipfs://METADATA_APPROVAL_mint": {
-      "name": "Public Mint",
-      "description": "Allows anyone to mint one NFT for 5 BADGE.",
-      "image": ""
-    }
   }
 }
 \`\`\``,
@@ -253,36 +255,38 @@ Create a fungible token with unlimited supply.
           "cosmosCoinBackedPath": null
         },
         "aliasPathsToAdd": [],
-        "cosmosCoinWrapperPathsToAdd": []
+        "cosmosCoinWrapperPathsToAdd": [],
+        "_meta": {
+          "metadataPlaceholders": {
+            "ipfs://METADATA_COLLECTION": {
+              "name": "My Token",
+              "description": "A fungible token with unlimited supply.",
+              "image": "ipfs://QmTokenImage..."
+            },
+            "ipfs://METADATA_TOKEN": {
+              "name": "MY",
+              "description": "The MY token unit.",
+              "image": "ipfs://QmTokenImage..."
+            },
+            "ipfs://METADATA_APPROVAL_mint": {
+              "name": "Public Mint",
+              "description": "Allows anyone to mint tokens freely.",
+              "image": ""
+            },
+            "ipfs://METADATA_APPROVAL_transfer": {
+              "name": "Free Transfer",
+              "description": "Allows free transfer between users.",
+              "image": ""
+            }
+          }
+        }
       }
     }
   ],
   "memo": "",
   "fee": {
     "amount": [{ "denom": "ubadge", "amount": "5000" }],
     "gas": "500000"
-  },
-  "metadataPlaceholders": {
-    "ipfs://METADATA_COLLECTION": {
-      "name": "My Token",
-      "description": "A fungible token with unlimited supply.",
-      "image": "ipfs://QmTokenImage..."
-    },
-    "ipfs://METADATA_TOKEN": {
-      "name": "MY",
-      "description": "The MY token unit.",
-      "image": "ipfs://QmTokenImage..."
-    },
-    "ipfs://METADATA_APPROVAL_mint": {
-      "name": "Public Mint",
-      "description": "Allows anyone to mint tokens freely.",
-      "image": ""
-    },
-    "ipfs://METADATA_APPROVAL_transfer": {
-      "name": "Free Transfer",
-      "description": "Allows free transfer between users.",
-      "image": ""
-    }
   }
 }
 \`\`\``,

diff --git a/packages/bitbadgesjs-sdk/src/builder/resources/frontendDocs.ts b/packages/bitbadgesjs-sdk/src/builder/resources/frontendDocs.ts
@@ -28,7 +28,7 @@ const FRONTEND_DOCS_CONTENT = {
 
 ### Address Handling
 - Always validate addresses before use (0x or bb1 format)
-- Use \`convert_address\` MCP tool or SDK's \`ethToCosmos\`/\`cosmosToEth\` for format conversion
+- Use the \`convert_address\` builder tool or SDK's \`ethToCosmos\`/\`cosmosToEth\` for format conversion
 - Display resolved names when available
 
 ### Amount Display
@@ -37,7 +37,7 @@ const FRONTEND_DOCS_CONTENT = {
 - Show both the human-readable amount and denomination
 
 ### Transaction Flow
-- Build transaction JSON (via MCP tools or manually)
+- Build transaction JSON (via builder tools or manually)
 - Present to user for review before signing
 - User signs with their wallet (MetaMask for EVM, Keplr for Cosmos)
 - Broadcast the signed transaction
@@ -46,7 +46,7 @@ const FRONTEND_DOCS_CONTENT = {
   collectionPatterns: `## Working with Collections
 
 ### Fetching Collection Data
-Use the BitBadges API (via SDK or MCP \`query_collection\` tool):
+Use the BitBadges API (via SDK or the builder's \`query_collection\` tool):
 \`\`\`typescript
 import { BitBadgesAPI } from 'bitbadgesjs-sdk';
 
@@ -79,7 +79,7 @@ const protocolData = JSON.parse(collection.customData || '{}');
   transactionPatterns: `## Transaction Patterns
 
 ### Building and Submitting
-1. Build transaction JSON using MCP tools or construct manually
+1. Build transaction JSON using builder tools or construct manually
 2. Validate with \`validate_transaction\` tool
 3. Present to user for review
 4. User signs with their wallet