{"id":"42f110b2-73a8-4200-91eb-5a30ef9a411d","shortId":"NMByE8","kind":"skill","title":"scaffolding","tagline":"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","description":"# Scaffolding Bundle-Plugins\n\n## Overview\n\nGenerate new bundle-plugin projects and manage platform support across their lifecycle. Handles initial project generation (greenfield) and ongoing platform adaptation (add, fix, migrate, remove).\n\n**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`.\n\n**Skill type:** Hybrid — follow the generation/adaptation process rigidly, but mode selection and component choices are flexible based on user context.\n\n**Announce at start:** \"I'm using the scaffolding skill to [generate your project / add <platform> support / remove <platform> support / add <component> / remove <component>].\"\n\n## Entry Detection\n\nDetermine the operation based on context:\n\n1. **Design document provided** (from `bundles-forge:blueprinting`) → **New Project** flow\n2. **User request + no existing project** → **New Project** flow\n3. **User request + existing project** → **Platform Adaptation** flow (add / fix / migrate / remove)\n\n## New Project: Scaffold Layers\n\nFor new projects, first select a mode:\n- **Design document** specifies the mode (minimal or intelligent)\n- **Direct invocation** — choose between:\n  - **intelligent** — recommend architecture based on user description, avoid unnecessary components\n  - **custom** — present the full architecture option set, ask the user about each component\n\n### Minimal Mode (quick packaging)\n\nLean plugin for marketplace distribution:\n\n| File | Purpose |\n|------|---------|\n| `.claude-plugin/plugin.json` | Plugin identity and metadata |\n| `skills/<skill-name>/SKILL.md` | One directory per skill |\n| `README.md` | Installation instructions and skill catalog |\n| `LICENSE` | Default MIT unless specified |\n\nNo hooks, no bootstrap, no version infrastructure. Add these later by re-running scaffolding in platform adaptation mode.\n\n### Intelligent Mode\n\n#### Core\n\nGenerated for all intelligent-mode projects regardless of platform selection:\n\n| File | Purpose |\n|------|---------|\n| `package.json` | Project identity and version |\n| `README.md` | Installation per platform, skill catalog |\n| `LICENSE` | Default MIT unless specified |\n| `.gitignore` | node_modules, .worktrees, OS files |\n| `.version-bump.json` | Version sync manifest |\n| `skills/<skill-name>/SKILL.md` | One directory per skill |\n\n#### Platform Adapters (selected platforms only)\n\n| Platform | Files |\n|----------|-------|\n| Claude Code | `.claude-plugin/plugin.json`, `hooks/hooks.json`, `hooks/run-hook.cmd`, `hooks/session-start` |\n| Cursor | `.cursor-plugin/plugin.json`, `hooks/hooks-cursor.json`, `hooks/session-start` |\n| Codex | `.codex/INSTALL.md`, `AGENTS.md` |\n| OpenCode | `.opencode/plugins/<name>.js`, `.opencode/INSTALL.md` |\n| Gemini CLI | `gemini-extension.json`, `GEMINI.md` |\n\nFor platform-specific wiring details, read `references/platform-adapters.md`.\n\n#### Bootstrap (if requested)\n\n| File | Purpose |\n|------|---------|\n| `skills/using-<project>/SKILL.md` | Meta-skill: instruction priority, skill routing table |\n| `skills/using-<project>/references/` | Per-platform tool mappings |\n\n#### Optional Components (only if specified)\n\n| Component | Files | When to Include |\n|-----------|-------|-----------------|\n| Executables | `bin/<tool-name>` | Skills reference CLI tools (see `references/external-integration.md` decision tree) |\n| MCP servers | `.mcp.json` | Skills need external service integration (see `references/external-integration.md` decision tree) |\n| LSP servers | `.lsp.json` | Skills involve language-specific code intelligence (see `references/external-integration.md` LSP section) |\n| Output styles | `output-styles/<style>.md` | Custom output formatting (see `references/external-integration.md` Output Styles section) |\n| Default settings | `settings.json` | Default agent activation (see `references/external-integration.md` Default Settings section) |\n| 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) |\n| Marketplace entry | `.claude-plugin/marketplace.json` | Plugin targets marketplace distribution — declares plugin metadata for the marketplace index |\n\n## New Project: Generation Process\n\n**Minimal mode:**\n1. Create plugin manifest from `assets/platforms/claude-code/plugin.json` template\n2. Generate skill directories — one per skill\n3. Generate README + LICENSE\n4. `git init` + initial commit; validate manifest JSON\n\n**Intelligent mode:**\n\n*Phase 1 — Load context:*\n1. **Read template index** — load `references/scaffold-templates.md`\n2. **Read templates** — load from `assets/` (infrastructure, docs, bootstrap)\n3. **Read platform templates** — load from `assets/platforms/<platform>/`\n4. **Read anatomy** — load `references/project-anatomy.md`\n\n*Phase 2 — Generate:*\n5. **Replace placeholders** — substitute `<project-name>`, `<author-name>`, etc.\n6. **Generate per-platform** — only create files for target platforms\n7. **Generate skill stubs** — one directory per skill\n8. **Generate bootstrap** — if requested, create meta-skill with routing table\n10. **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\n\n*Phase 3 — Finalize:*\n11. `git init` + initial commit; run `bundles-forge bump-version --check`\n\n## Platform Adaptation: Existing Projects\n\n### Adding a Platform\n\n1. **Detect current platforms** — scan for existing manifests (see detection table in `references/platform-adapters.md`)\n2. **Identify target** — read `references/platform-adapters.md` for wiring details\n3. **Generate adapter files** — from `assets/platforms/<platform>/`, replace `<project-name>` placeholders\n4. **Update version sync** — add version-bearing manifests to `.version-bump.json`\n5. **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`\n6. **Update documentation** — add install section to README; create platform-specific docs if needed\n7. **Verify** — validate manifests, `bundles-forge bump-version --check`, test hooks\n\n### Removing a Platform\n\n1. **Delete manifest files** — remove the platform's manifest directory or file\n2. **Update `.version-bump.json`** — remove entries for deleted manifests\n3. **Clean hooks** — delete platform-specific hook files; simplify `session-start` if branches removed\n4. **Update documentation** — remove install section from README and platform-specific docs\n5. **Verify** — `bundles-forge bump-version --check`; run inspector validation\n\n### Adding Optional Components\n\nAdd MCP servers, CLI executables, LSP servers, userConfig, output styles, or default settings to an existing project:\n\n1. **Determine component type** — read `references/external-integration.md` decision tree to choose the right integration level\n2. **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`)\n3. **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\n4. **Update skill references** — add `allowed-tools` frontmatter for new CLI/MCP tools, add `${user_config.KEY}` references where skills need user-provided values\n5. **Update README** — add setup instructions for the new component (especially MCP server config for non-Claude Code platforms, LSP binary installation)\n6. **Verify** — run inspector validation to confirm structural integrity\n\n### Removing Optional Components\n\nRemove 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:\n\n- Removing MCP servers (`.mcp.json`, `plugin.json mcpServers`, skill references, README)\n- Removing CLI executables (`bin/`, `allowed-tools`, skill body)\n- Removing LSP servers (`.lsp.json`, README)\n- Downgrading MCP to CLI (replace MCP with lighter CLI alternative)\n\n## Post-Action Validation\n\n**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.\n\n**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:\n- **New project** → full inspection (template quality, optional components, hook semantics, design coherence)\n- **Platform adaptation** → focused inspection (hook semantics and template quality for affected platforms)\n\n**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.\n\n## Common Mistakes\n\n| Mistake | Fix |\n|---------|-----|\n| Generating all platforms regardless of design | Only create files for selected platforms |\n| Forgetting `.version-bump.json` entries | Every version-bearing manifest needs an entry |\n| Hardcoding author in templates | Pull from git config or ask |\n| 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 |\n| Bootstrap skill > 200 lines | Keep lean — extract to `references/` |\n| Wrong hook format (PascalCase vs camelCase) | Claude Code: `SessionStart`, Cursor: `sessionStart` |\n| Copying template without customizing | Replace every `<project-name>` placeholder |\n| Using intelligent mode infrastructure for minimal | Minimal mode avoids over-engineering |\n| Using MCP when CLI suffices | Consult `references/external-integration.md` decision tree — prefer CLI for stateless, single-shot tools |\n| Using `../` paths to reference files outside the plugin | After marketplace install, plugins are cached — `../` paths break. Keep all files within the plugin root |\n| Writing persistent data to `${CLAUDE_PLUGIN_ROOT}` | `PLUGIN_ROOT` changes on each update. Use `${CLAUDE_PLUGIN_DATA}` for caches, installed dependencies, and generated state |\n\n## Inputs\n\n- `design-document` (optional) — from `bundles-forge:blueprinting` with project mode, name, platforms, skill inventory, bootstrap strategy, and components\n- `project-directory` (optional) — existing bundle-plugin project root for platform adaptation\n- `target-platform` (optional) — platform to add or remove\n\n## Outputs\n\n- `scaffold-output` — generated project structure or adapted platform files. Consumed by the orchestrating skill (blueprinting or optimizing) for subsequent phases\n- `inspector-report` (optional) — validation report in `.bundles-forge/blueprints/`\n\n## Integration\n\n**Called by:**\n- **bundles-forge:blueprinting** — Phase 1 of the new-project pipeline\n- **bundles-forge:optimizing** — Platform Coverage routing for adding new platforms\n- User directly — for platform adaptation or ad-hoc project generation\n\n**Pairs with:**\n- **bundles-forge:releasing** — version infrastructure and sync","tags":["scaffolding","bundles","forge","odradekai","agent-skills","bundle-plugin","claude-code","claude-plugin","claude-skills","cursor-plugin"],"capabilities":["skill","source-odradekai","skill-scaffolding","topic-agent-skills","topic-bundle-plugin","topic-claude-code","topic-claude-plugin","topic-claude-skills","topic-cursor-plugin"],"categories":["bundles-forge"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/OdradekAI/bundles-forge/scaffolding","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add OdradekAI/bundles-forge","source_repo":"https://github.com/OdradekAI/bundles-forge","install_from":"skills.sh"}},"qualityScore":"0.554","qualityRationale":"deterministic score 0.55 from registry signals: · indexed on github topic:agent-skills · 208 github stars · SKILL.md body (11,984 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-02T12:54:05.944Z","embedding":null,"createdAt":"2026-04-18T22:12:14.152Z","updatedAt":"2026-05-02T12:54:05.944Z","lastSeenAt":"2026-05-02T12:54:05.944Z","tsv":"'/plugin.json':251,352,360 '/references':398 '/skill.md':257,335,388 '1':158 '2':170 '3':179 'across':50 'ad':12 'adapt':61,185,290,341 'add':62,144,148,187,280 'agents.md':365 'announc':131 'architectur':216,228 'ask':231 'audit':101 'avoid':221 'base':127,155,217 'bin':415 'blueprint':166 'bootstrap':276,382 'bump':109 'bump-vers':108 'bundl':10,37,43,99,106,164 'bundle-plugin':9,36,42 'bundles-forg':98,105,163 'catalog':267,318 'check':103 'choic':124 'choos':212 'claud':17,249,347,350 'claude-plugin':248,349 'cli':23,371,418 'code':18,348,444 'codex':20,363 'codex/install.md':364 'compon':123,223,236,405,409 'configur':32 'context':130,157 'core':66,294 'cursor':19,356,358 'cursor-plugin':357 'custom':224 'decis':422,434 'default':269,320 'deleg':96 'descript':220 'design':159,202 'detail':379 'detect':151 'determin':152 'direct':210 'directori':259,337 'distribut':245 'document':160,203 'entri':150 'everi':73,75 'execut':414 'exist':81,174,182 'extern':429 'file':76,246,306,329,346,385,410 'first':198 'fix':63,188 'flexibl':126 'flow':169,178,186 'follow':114 'forg':100,107,165 'full':227 'gemini':22,370 'gemini-extension.json':372 'gemini.md':373 'generat':4,40,56,68,84,141,295 'generation/adaptation':116 'gitignor':324 'greenfield':57 'handl':53 'hook':30,274 'hooks/hooks-cursor.json':361 'hooks/hooks.json':353 'hooks/run-hook.cmd':354 'hooks/session-start':355,362 'hybrid':113 'ident':253,310 'includ':413 'infrastructur':279 'initi':54 'instal':263,314 'instruct':264,392 'integr':431 'intellig':209,214,292,299,445 'intelligent-mod':298 'invoc':211 'involv':440 'js':368 'languag':442 'language-specif':441 'later':282 'layer':194 'lean':241 'licens':268,319 'lifecycl':52 'lsp':436,448 'lsp.json':438 'm':135 'manag':47 'manifest':27,333 'map':403 'marketplac':244 'mcp':424 'mcp.json':426 'meta':390 'meta-skil':389 'metadata':255 'migrat':29,64,189 'minim':207,237 'mit':270,321 'mode':120,201,206,238,291,293,300 'modul':326 'need':72,428 'new':8,41,167,176,191,196 'node':325 'one':258,336 'ongo':59 'openclaw':24 'opencod':21,366 'opencode/install.md':369 'opencode/plugins':367 'oper':154 'option':229,404 'os':328 'output':450,453 'output-styl':452 'overview':39 'packag':240 'package.json':308 'per':260,315,338,400 'per-platform':399 'platform':15,26,34,48,60,74,184,289,304,316,340,343,345,376,401 'platform-specif':375 'plugin':11,38,44,242,250,252,351,359 'present':225 'principl':67 'prioriti':393 'process':117 'project':5,45,55,143,168,175,177,183,192,197,301,309 'provid':161 'purpos':247,307,386 'quick':239 're':285 're-run':284 'read':380 'readme.md':262,313 'reason':79 'recommend':215 'refer':417 'references/external-integration.md':421,433,447 'references/platform-adapters.md':381 'regardless':302 'remov':14,65,146,149,190 'request':172,181,384 'rigid':118 'rout':395 'run':90,286 'scaffold':1,35,138,193,287 'script':93 'section':449 'see':420,432,446 'select':121,199,305,342 'server':425,437 'servic':430 'set':230 'skill':83,111,139,256,261,266,317,334,339,391,394,416,427,439 'skill-scaffolding' 'skills/using-':387,397 'source-odradekai' 'specif':377,443 'specifi':204,272,323,408 'start':133 'structur':6,85 'style':451,454 'support':16,49,145,147 'sync':332 'tabl':396 'tool':402,419 'topic-agent-skills' 'topic-bundle-plugin' 'topic-claude-code' 'topic-claude-plugin' 'topic-claude-skills' 'topic-cursor-plugin' 'tree':423,435 'type':112 'unless':271,322 'unnecessari':222 'updat':25 'use':2,136 'user':129,171,180,219,233 'valid':94 'version':102,110,278,312,331 'version-bump.json':330 'wire':378 'worktre':327","prices":[{"id":"bb9aa03a-99e6-4891-8694-9b8bb304f27d","listingId":"42f110b2-73a8-4200-91eb-5a30ef9a411d","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"OdradekAI","category":"bundles-forge","install_from":"skills.sh"},"createdAt":"2026-04-18T22:12:14.152Z"}],"sources":[{"listingId":"42f110b2-73a8-4200-91eb-5a30ef9a411d","source":"github","sourceId":"OdradekAI/bundles-forge/scaffolding","sourceUrl":"https://github.com/OdradekAI/bundles-forge/tree/main/skills/scaffolding","isPrimary":false,"firstSeenAt":"2026-04-18T22:12:14.152Z","lastSeenAt":"2026-05-02T12:54:05.944Z"}],"details":{"listingId":"42f110b2-73a8-4200-91eb-5a30ef9a411d","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"OdradekAI","slug":"scaffolding","github":{"repo":"OdradekAI/bundles-forge","stars":208,"topics":["agent-skills","bundle-plugin","claude-code","claude-plugin","claude-skills","cursor-plugin"],"license":"apache-2.0","html_url":"https://github.com/OdradekAI/bundles-forge","pushed_at":"2026-04-27T02:13:58Z","description":"An agentic skills framework & bundle-plugin engineering toolkit that works.","skill_md_sha":"60cff970ad56467d5385e9684a84071350485e20","skill_md_path":"skills/scaffolding/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/OdradekAI/bundles-forge/tree/main/skills/scaffolding"},"layout":"multi","source":"github","category":"bundles-forge","frontmatter":{"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"},"skills_sh_url":"https://skills.sh/OdradekAI/bundles-forge/scaffolding"},"updatedAt":"2026-05-02T12:54:05.944Z"}}