// Use when generating project structure for new bundle-plugins, adding or removing platform support (Claude Code, Cursor, Codex, OpenCode, Gemini CLI, OpenClaw), updating platform manifests, or migrating hooks and configuration between platforms
Use when reviewing a bundle-plugin for structural issues, version drift, skill quality, workflow integration, or security risks — before releasing, after changes, or after adding skills. Auto-detects scope (full project vs skill vs workflow)
Use when writing, completing, improving, or adapting SKILL.md and agents/*.md in a bundle-plugin — integrating external skills, filling scaffolded stubs, or rewriting for better triggering and token efficiency
Use when optimizing a bundle-plugin or single skill — improving descriptions, reducing tokens, fixing audit findings, restructuring workflows, adding skills to fill gaps, or iterating on user feedback
Use when planning new bundle-plugins, splitting complex skills, combining skills into bundles, or exploring a vague idea about packaging skills
Use when releasing a bundle-plugin, bumping versions, fixing version drift across manifests, setting up version sync infrastructure, updating CHANGELOG, publishing to marketplaces, or checking release readiness
Use when testing a bundle-plugin locally before release — generating dev-marketplace environments, verifying component discovery, running hook smoke tests, and validating cross-platform readiness
| name | scaffolding |
| description | Use when generating project structure for new bundle-plugins, adding or removing platform support (Claude Code, Cursor, Codex, OpenCode, Gemini CLI, OpenClaw), updating platform manifests, or migrating hooks and configuration between platforms |
| allowed-tools | Bash(bundles-forge bump-version *) |
Generate new bundle-plugin projects and manage platform support across their lifecycle. Handles initial project generation (greenfield) and ongoing platform adaptation (add, fix, migrate, remove).
Core principle: Generate only what's needed. Every platform, every file has a reason to exist. This skill generates structure only — it does not run its own scripts. Validation is delegated to bundles-forge:auditing; version checks to bundles-forge bump-version.
Skill type: Hybrid — follow the generation/adaptation process rigidly, but mode selection and component choices are flexible based on user context.
Announce at start: "I'm using the scaffolding skill to [generate your project / add support / remove support / add / remove ]."
Determine the operation based on context:
bundles-forge:blueprinting) → New Project flowFor new projects, first select a mode:
Lean plugin for marketplace distribution:
| File | Purpose |
|---|---|
.claude-plugin/plugin.json | Plugin identity and metadata |
skills/<skill-name>/SKILL.md | One directory per skill |
README.md | Installation instructions and skill catalog |
LICENSE | Default MIT unless specified |
No hooks, no bootstrap, no version infrastructure. Add these later by re-running scaffolding in platform adaptation mode.
Generated for all intelligent-mode projects regardless of platform selection:
| File | Purpose |
|---|---|
package.json | Project identity and version |
README.md | Installation per platform, skill catalog |
LICENSE | Default MIT unless specified |
.gitignore | node_modules, .worktrees, OS files |
.version-bump.json | Version sync manifest |
skills/<skill-name>/SKILL.md | One directory per skill |
| Platform | Files |
|---|---|
| Claude Code | .claude-plugin/plugin.json, hooks/hooks.json, hooks/run-hook.cmd, hooks/session-start |
| Cursor | .cursor-plugin/plugin.json, hooks/hooks-cursor.json, hooks/session-start |
| Codex | .codex/INSTALL.md, AGENTS.md |
| OpenCode | .opencode/plugins/<name>.js, .opencode/INSTALL.md |
| Gemini CLI | gemini-extension.json, GEMINI.md |
For platform-specific wiring details, read references/platform-adapters.md.
| File | Purpose |
|---|---|
skills/using-<project>/SKILL.md | Meta-skill: instruction priority, skill routing table |
skills/using-<project>/references/ | Per-platform tool mappings |
| Component | Files | When to Include |
|---|---|---|
| Executables | bin/<tool-name> | Skills reference CLI tools (see references/external-integration.md decision tree) |
| MCP servers | .mcp.json | Skills need external service integration (see references/external-integration.md decision tree) |
| LSP servers | .lsp.json | Skills involve language-specific code intelligence (see references/external-integration.md LSP section) |
| Output styles | output-styles/<style>.md | Custom output formatting (see references/external-integration.md Output Styles section) |
| Default settings | settings.json | Default agent activation (see references/external-integration.md Default Settings section) |
| User configuration | userConfig in plugin.json | Skills need user-provided API keys, endpoints, or tokens — Claude Code only (see references/external-integration.md userConfig section) |
| Marketplace entry | .claude-plugin/marketplace.json | Plugin targets marketplace distribution — declares plugin metadata for the marketplace index |
Minimal mode:
assets/platforms/claude-code/plugin.json templategit init + initial commit; validate manifest JSONIntelligent mode:
Phase 1 — Load context:
references/scaffold-templates.mdassets/ (infrastructure, docs, bootstrap)assets/platforms/<platform>/references/project-anatomy.mdPhase 2 — Generate:
5. Replace placeholders — substitute <project-name>, <author-name>, etc.
6. Generate per-platform — only create files for target platforms
7. Generate skill stubs — one directory per skill
8. Generate bootstrap — if requested, create meta-skill with routing table
10. Generate optional components — only what the design specifies. For MCP servers, use assets/mcp-json.md template and consult references/external-integration.md for transport selection and platform differences. When userConfig is specified, add the userConfig field to plugin.json with appropriate sensitive flags. When marketplace distribution is specified, generate .claude-plugin/marketplace.json with plugin metadata. When CI validation is specified, generate .github/workflows/validate-plugin.yml from template
Phase 3 — Finalize:
11. git init + initial commit; run bundles-forge bump-version --check
references/platform-adapters.md)references/platform-adapters.md for wiring detailsassets/platforms/<platform>/, replace <project-name> placeholders.version-bump.jsonsession-start (Bash) handles its JSON format via run-hook.cmd. For custom hooks beyond SessionStart, read references/hooks-configuration.mdbundles-forge bump-version --check, test hooks.version-bump.json — remove entries for deleted manifestssession-start if branches removedbundles-forge bump-version --check; run inspector validationAdd MCP servers, CLI executables, LSP servers, userConfig, output styles, or default settings to an existing project:
references/external-integration.md decision tree to choose the right integration level.mcp.json, .lsp.json, output-styles/, settings.json, or userConfig in plugin.json)plugin.json for platforms that require explicit paths (Cursor). For Claude Code, convention-based discovery handles most components automaticallyallowed-tools frontmatter for new CLI/MCP tools, add ${user_config.KEY} references where skills need user-provided valuesRemove MCP servers, CLI executables, or LSP servers from an existing project. Read references/external-integration.md "Optional Component Removal" section for step-by-step instructions covering:
.mcp.json, plugin.json mcpServers, skill references, README)bin/, allowed-tools, skill body).lsp.json, README)Step 1 — Deterministic checks (script): Run bundles-forge audit-skill <target-dir> to verify structure, manifests, version sync, and frontmatter. Review any critical or warning findings before proceeding.
Step 2 — Semantic inspection (agent): Dispatch the inspector agent (agents/inspector.md) for semantic validation that scripts cannot cover (template quality, hook logic coherence, design alignment). The inspector adjusts scope based on context:
If subagent dispatch is unavailable: Ask — "Subagents are not available. Run validation inline?" If confirmed, read agents/inspector.md and follow its instructions within this conversation, then report PASS/FAIL.
| Mistake | Fix |
|---|---|
| Generating all platforms regardless of design | Only create files for selected platforms |
Forgetting .version-bump.json entries | Every version-bearing manifest needs an entry |
| Hardcoding author in templates | Pull from git config or ask |
Missing session-start or run-hook.cmd in hook config | Claude Code uses run-hook.cmd session-start; Cursor runs ./hooks/session-start directly; both require bash |
| Bootstrap skill > 200 lines | Keep lean — extract to references/ |
| Wrong hook format (PascalCase vs camelCase) | Claude Code: SessionStart, Cursor: sessionStart |
| Copying template without customizing | Replace every <project-name> placeholder |
| Using intelligent mode infrastructure for minimal | Minimal mode avoids over-engineering |
| Using MCP when CLI suffices | Consult references/external-integration.md decision tree — prefer CLI for stateless, single-shot tools |
Using ../ paths to reference files outside the plugin | After marketplace install, plugins are cached — ../ paths break. Keep all files within the plugin root |
Writing persistent data to ${CLAUDE_PLUGIN_ROOT} | PLUGIN_ROOT changes on each update. Use ${CLAUDE_PLUGIN_DATA} for caches, installed dependencies, and generated state |
design-document (optional) — from bundles-forge:blueprinting with project mode, name, platforms, skill inventory, bootstrap strategy, and componentsproject-directory (optional) — existing bundle-plugin project root for platform adaptationtarget-platform (optional) — platform to add or removescaffold-output — generated project structure or adapted platform files. Consumed by the orchestrating skill (blueprinting or optimizing) for subsequent phasesinspector-report (optional) — validation report in .bundles-forge/blueprints/Called by:
Pairs with: