Scaffolding Bundle-Plugins
Overview
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 ]."
Entry Detection
Determine the operation based on context:
- Design document provided (from
bundles-forge:blueprinting) → New Project flow
- User request + no existing project → New Project flow
- User request + existing project → Platform Adaptation flow (add / fix / migrate / remove)
New Project: Scaffold Layers
For new projects, first select a mode:
- Design document specifies the mode (minimal or intelligent)
- Direct invocation — choose between:
- intelligent — recommend architecture based on user description, avoid unnecessary components
- custom — present the full architecture option set, ask the user about each component
Minimal Mode (quick packaging)
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.
Intelligent Mode
Core
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 Adapters (selected platforms only)
| 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.
Bootstrap (if requested)
| File |
Purpose |
skills/using-<project>/SKILL.md |
Meta-skill: instruction priority, skill routing table |
skills/using-<project>/references/ |
Per-platform tool mappings |
Optional Components (only if specified)
| 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 |
New Project: Generation Process
Minimal mode:
- Create plugin manifest from
assets/platforms/claude-code/plugin.json template
- Generate skill directories — one per skill
- Generate README + LICENSE
git init + initial commit; validate manifest JSON
Intelligent mode:
Phase 1 — Load context:
- Read template index — load
references/scaffold-templates.md
- Read templates — load from
assets/ (infrastructure, docs, bootstrap)
- Read platform templates — load from
assets/platforms/<platform>/
- Read anatomy — load
references/project-anatomy.md
Phase 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
Platform Adaptation: Existing Projects
Adding a Platform
- Detect current platforms — scan for existing manifests (see detection table in
references/platform-adapters.md)
- Identify target — read
references/platform-adapters.md for wiring details
- Generate adapter files — from
assets/platforms/<platform>/, replace <project-name> placeholders
- Update version sync — add version-bearing manifests to
.version-bump.json
- Update hooks — if platform uses session hooks, ensure
session-start (Bash) handles its JSON format via run-hook.cmd. For custom hooks beyond SessionStart, read references/hooks-configuration.md
- Update documentation — add install section to README; create platform-specific docs if needed
- Verify — validate manifests,
bundles-forge bump-version --check, test hooks
Removing a Platform
- Delete manifest files — remove the platform's manifest directory or file
- Update
.version-bump.json — remove entries for deleted manifests
- Clean hooks — delete platform-specific hook files; simplify
session-start if branches removed
- Update documentation — remove install section from README and platform-specific docs
- Verify —
bundles-forge bump-version --check; run inspector validation
Adding Optional Components
Add MCP servers, CLI executables, LSP servers, userConfig, output styles, or default settings to an existing project:
- Determine component type — read
references/external-integration.md decision tree to choose the right integration level
- Generate component files — create the corresponding file(s) at their default location (
.mcp.json, .lsp.json, output-styles/, settings.json, or userConfig in plugin.json)
- Update plugin manifests — add component declarations to
plugin.json for platforms that require explicit paths (Cursor). For Claude Code, convention-based discovery handles most components automatically
- Update skill references — add
allowed-tools frontmatter for new CLI/MCP tools, add ${user_config.KEY} references where skills need user-provided values
- Update README — add setup instructions for the new component (especially MCP server config for non-Claude Code platforms, LSP binary installation)
- Verify — run inspector validation to confirm structural integrity
Removing Optional Components
Remove 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:
- Removing MCP servers (
.mcp.json, plugin.json mcpServers, skill references, README)
- Removing CLI executables (
bin/, allowed-tools, skill body)
- Removing LSP servers (
.lsp.json, README)
- Downgrading MCP to CLI (replace MCP with lighter CLI alternative)
Post-Action Validation
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:
- New project → full inspection (template quality, optional components, hook semantics, design coherence)
- Platform adaptation → focused inspection (hook semantics and template quality for affected platforms)
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.
Common Mistakes
| 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 |
Inputs
design-document (optional) — from bundles-forge:blueprinting with project mode, name, platforms, skill inventory, bootstrap strategy, and components
project-directory (optional) — existing bundle-plugin project root for platform adaptation
target-platform (optional) — platform to add or remove
Outputs
scaffold-output — generated project structure or adapted platform files. Consumed by the orchestrating skill (blueprinting or optimizing) for subsequent phases
inspector-report (optional) — validation report in .bundles-forge/blueprints/
Integration
Called by:
- bundles-forge:blueprinting — Phase 1 of the new-project pipeline
- bundles-forge:optimizing — Platform Coverage routing for adding new platforms
- User directly — for platform adaptation or ad-hoc project generation
Pairs with:
- bundles-forge:releasing — version infrastructure and sync
1---
2name: scaffolding
3description: "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"
4allowed-tools: Bash(bundles-forge bump-version *)
5metadata:
6 source: https://skillmd.com/skills/odradekai/scaffolding
7---
8
9# Scaffolding Bundle-Plugins
10
11## Overview
12
13Generate new bundle-plugin projects and manage platform support across their lifecycle. Handles initial project generation (greenfield) and ongoing platform adaptation (add, fix, migrate, remove).
14
15**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`.
16
17**Skill type:** Hybrid — follow the generation/adaptation process rigidly, but mode selection and component choices are flexible based on user context.
18
19**Announce at start:** "I'm using the scaffolding skill to [generate your project / add <platform> support / remove <platform> support / add <component> / remove <component>]."
20
21## Entry Detection
22
23Determine the operation based on context:
24
251. **Design document provided** (from `bundles-forge:blueprinting`) → **New Project** flow
262. **User request + no existing project** → **New Project** flow
273. **User request + existing project** → **Platform Adaptation** flow (add / fix / migrate / remove)
28
29## New Project: Scaffold Layers
30
31For new projects, first select a mode:
32- **Design document** specifies the mode (minimal or intelligent)
33- **Direct invocation** — choose between:
34 - **intelligent** — recommend architecture based on user description, avoid unnecessary components
35 - **custom** — present the full architecture option set, ask the user about each component
36
37### Minimal Mode (quick packaging)
38
39Lean plugin for marketplace distribution:
40
41| File | Purpose |
42|------|---------|
43| `.claude-plugin/plugin.json` | Plugin identity and metadata |
44| `skills/<skill-name>/SKILL.md` | One directory per skill |
45| `README.md` | Installation instructions and skill catalog |
46| `LICENSE` | Default MIT unless specified |
47
48No hooks, no bootstrap, no version infrastructure. Add these later by re-running scaffolding in platform adaptation mode.
49
50### Intelligent Mode
51
52#### Core
53
54Generated for all intelligent-mode projects regardless of platform selection:
55
56| File | Purpose |
57|------|---------|
58| `package.json` | Project identity and version |
59| `README.md` | Installation per platform, skill catalog |
60| `LICENSE` | Default MIT unless specified |
61| `.gitignore` | node_modules, .worktrees, OS files |
62| `.version-bump.json` | Version sync manifest |
63| `skills/<skill-name>/SKILL.md` | One directory per skill |
64
65#### Platform Adapters (selected platforms only)
66
67| Platform | Files |
68|----------|-------|
69| Claude Code | `.claude-plugin/plugin.json`, `hooks/hooks.json`, `hooks/run-hook.cmd`, `hooks/session-start` |
70| Cursor | `.cursor-plugin/plugin.json`, `hooks/hooks-cursor.json`, `hooks/session-start` |
71| Codex | `.codex/INSTALL.md`, `AGENTS.md` |
72| OpenCode | `.opencode/plugins/<name>.js`, `.opencode/INSTALL.md` |
73| Gemini CLI | `gemini-extension.json`, `GEMINI.md` |
74
75For platform-specific wiring details, read `references/platform-adapters.md`.
76
77#### Bootstrap (if requested)
78
79| File | Purpose |
80|------|---------|
81| `skills/using-<project>/SKILL.md` | Meta-skill: instruction priority, skill routing table |
82| `skills/using-<project>/references/` | Per-platform tool mappings |
83
84#### Optional Components (only if specified)
85
86| Component | Files | When to Include |
87|-----------|-------|-----------------|
88| Executables | `bin/<tool-name>` | Skills reference CLI tools (see `references/external-integration.md` decision tree) |
89| MCP servers | `.mcp.json` | Skills need external service integration (see `references/external-integration.md` decision tree) |
90| LSP servers | `.lsp.json` | Skills involve language-specific code intelligence (see `references/external-integration.md` LSP section) |
91| Output styles | `output-styles/<style>.md` | Custom output formatting (see `references/external-integration.md` Output Styles section) |
92| Default settings | `settings.json` | Default agent activation (see `references/external-integration.md` Default Settings section) |
93| 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) |
94| Marketplace entry | `.claude-plugin/marketplace.json` | Plugin targets marketplace distribution — declares plugin metadata for the marketplace index |
95
96## New Project: Generation Process
97
98**Minimal mode:**
991. Create plugin manifest from `assets/platforms/claude-code/plugin.json` template
1002. Generate skill directories — one per skill
1013. Generate README + LICENSE
1024. `git init` + initial commit; validate manifest JSON
103
104**Intelligent mode:**
105
106*Phase 1 — Load context:*
1071. **Read template index** — load `references/scaffold-templates.md`
1082. **Read templates** — load from `assets/` (infrastructure, docs, bootstrap)
1093. **Read platform templates** — load from `assets/platforms/<platform>/`
1104. **Read anatomy** — load `references/project-anatomy.md`
111
112*Phase 2 — Generate:*
1135. **Replace placeholders** — substitute `<project-name>`, `<author-name>`, etc.
1146. **Generate per-platform** — only create files for target platforms
1157. **Generate skill stubs** — one directory per skill
1168. **Generate bootstrap** — if requested, create meta-skill with routing table
11710. **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
118
119*Phase 3 — Finalize:*
12011. `git init` + initial commit; run `bundles-forge bump-version --check`
121
122## Platform Adaptation: Existing Projects
123
124### Adding a Platform
125
1261. **Detect current platforms** — scan for existing manifests (see detection table in `references/platform-adapters.md`)
1272. **Identify target** — read `references/platform-adapters.md` for wiring details
1283. **Generate adapter files** — from `assets/platforms/<platform>/`, replace `<project-name>` placeholders
1294. **Update version sync** — add version-bearing manifests to `.version-bump.json`
1305. **Update hooks** — if platform uses session hooks, ensure `session-start` (Bash) handles its JSON format via `run-hook.cmd`. For custom hooks beyond SessionStart, read `references/hooks-configuration.md`
1316. **Update documentation** — add install section to README; create platform-specific docs if needed
1327. **Verify** — validate manifests, `bundles-forge bump-version --check`, test hooks
133
134### Removing a Platform
135
1361. **Delete manifest files** — remove the platform's manifest directory or file
1372. **Update `.version-bump.json`** — remove entries for deleted manifests
1383. **Clean hooks** — delete platform-specific hook files; simplify `session-start` if branches removed
1394. **Update documentation** — remove install section from README and platform-specific docs
1405. **Verify** — `bundles-forge bump-version --check`; run inspector validation
141
142### Adding Optional Components
143
144Add MCP servers, CLI executables, LSP servers, userConfig, output styles, or default settings to an existing project:
145
1461. **Determine component type** — read `references/external-integration.md` decision tree to choose the right integration level
1472. **Generate component files** — create the corresponding file(s) at their default location (`.mcp.json`, `.lsp.json`, `output-styles/`, `settings.json`, or `userConfig` in `plugin.json`)
1483. **Update plugin manifests** — add component declarations to `plugin.json` for platforms that require explicit paths (Cursor). For Claude Code, convention-based discovery handles most components automatically
1494. **Update skill references** — add `allowed-tools` frontmatter for new CLI/MCP tools, add `${user_config.KEY}` references where skills need user-provided values
1505. **Update README** — add setup instructions for the new component (especially MCP server config for non-Claude Code platforms, LSP binary installation)
1516. **Verify** — run inspector validation to confirm structural integrity
152
153### Removing Optional Components
154
155Remove 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:
156
157- Removing MCP servers (`.mcp.json`, `plugin.json mcpServers`, skill references, README)
158- Removing CLI executables (`bin/`, `allowed-tools`, skill body)
159- Removing LSP servers (`.lsp.json`, README)
160- Downgrading MCP to CLI (replace MCP with lighter CLI alternative)
161
162## Post-Action Validation
163
164**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.
165
166**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:
167- **New project** → full inspection (template quality, optional components, hook semantics, design coherence)
168- **Platform adaptation** → focused inspection (hook semantics and template quality for affected platforms)
169
170**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.
171
172## Common Mistakes
173
174| Mistake | Fix |
175|---------|-----|
176| Generating all platforms regardless of design | Only create files for selected platforms |
177| Forgetting `.version-bump.json` entries | Every version-bearing manifest needs an entry |
178| Hardcoding author in templates | Pull from git config or ask |
179| 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 |
180| Bootstrap skill > 200 lines | Keep lean — extract to `references/` |
181| Wrong hook format (PascalCase vs camelCase) | Claude Code: `SessionStart`, Cursor: `sessionStart` |
182| Copying template without customizing | Replace every `<project-name>` placeholder |
183| Using intelligent mode infrastructure for minimal | Minimal mode avoids over-engineering |
184| Using MCP when CLI suffices | Consult `references/external-integration.md` decision tree — prefer CLI for stateless, single-shot tools |
185| Using `../` paths to reference files outside the plugin | After marketplace install, plugins are cached — `../` paths break. Keep all files within the plugin root |
186| Writing persistent data to `${CLAUDE_PLUGIN_ROOT}` | `PLUGIN_ROOT` changes on each update. Use `${CLAUDE_PLUGIN_DATA}` for caches, installed dependencies, and generated state |
187
188## Inputs
189
190- `design-document` (optional) — from `bundles-forge:blueprinting` with project mode, name, platforms, skill inventory, bootstrap strategy, and components
191- `project-directory` (optional) — existing bundle-plugin project root for platform adaptation
192- `target-platform` (optional) — platform to add or remove
193
194## Outputs
195
196- `scaffold-output` — generated project structure or adapted platform files. Consumed by the orchestrating skill (blueprinting or optimizing) for subsequent phases
197- `inspector-report` (optional) — validation report in `.bundles-forge/blueprints/`
198
199## Integration
200
201**Called by:**
202- **bundles-forge:blueprinting** — Phase 1 of the new-project pipeline
203- **bundles-forge:optimizing** — Platform Coverage routing for adding new platforms
204- User directly — for platform adaptation or ad-hoc project generation
205
206**Pairs with:**
207- **bundles-forge:releasing** — version infrastructure and sync