// Use when planning new bundle-plugins, splitting complex skills, combining skills into bundles, or exploring a vague idea about packaging skills
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 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 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 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 | blueprinting |
| description | Use when planning new bundle-plugins, splitting complex skills, combining skills into bundles, or exploring a vague idea about packaging skills |
Turn a vague idea ("I want to package my skills") into a concrete project blueprint through needs exploration, architecture design, and structured review — then orchestrate the full creation pipeline: scaffolding, content authoring, workflow wiring, and initial quality check.
Core principle: Understand what you're building — and why — before generating anything. Five minutes of needs exploration saves hours of rework.
Skill type: Hybrid pattern — follow the three-phase process rigidly, but question selection, depth, and approach recommendations adapt to user context.
Announce at start: "I'm using the blueprinting skill to plan your bundle-plugin."
Do NOT invoke bundles-forge:scaffolding or any subsequent orchestration phase until the user has approved the design document. Every project — regardless of perceived simplicity — must pass through needs exploration → architecture design → design document review. Quick mode may shorten the process (needs exploration asks only 2 core questions), but it cannot skip it.| Agent Reasoning | Reality |
|---|---|
| "The user's requirements are already clear" | Seemingly clear requirements often miss platform, workflow, and visibility architecture decisions |
| "This is just packaging a few existing skills" | Even simple packaging requires compatibility verification, cross-reference validation, and workflow chain mapping |
| "Moving fast through the process is more efficient" | Five minutes of exploration saves hours of rework from missing architecture decisions |
This skill handles three scenarios. All three feed into the same three-phase interview — only the initial context differs.
references/decomposition-analysis.md, then enters the interview with richer context. Splitting produces a new project. To refactor skills within an existing project, use bundles-forge:optimizing (Skill & Workflow Restructuring target).references/composition-analysis.md, then enters the interview with richer contextIf the user has an existing skill they want to break apart, start with Scenario B. If the user has multiple existing skills they want to combine into a new unified project, start with Scenario C. Otherwise, start with Scenario A.
Adding skills to an existing project? That's optimization, not blueprinting. Use
bundles-forge:optimizing(Skill & Workflow Restructuring target).
Read references/dialogue-strategies.md for the full interview protocol. Core principles: ask 1-2 questions at a time, reject vague answers, propose approaches with trade-offs, challenge over-scoping, surface contradictions immediately, and confirm understanding after each phase.
Before asking any questions, gather available context:
references/decomposition-analysis.md to map responsibilities, identify split points, and propose a decompositionreferences/composition-analysis.md to check compatibility, detect conflicts, and design orchestrationUnderstand what the user wants to build and why, before making any architecture decisions. Ask these one at a time, adapting based on answers.
Ask: "What problem does this skill bundle solve? How are people solving it today?"
Understand the gap between the current state and what the user envisions. This is the foundation for all subsequent decisions.
Ask: "Who will use this skill bundle? What's their background — what type of developers, what workflows, what platforms?"
The answer shapes platform selection, skill complexity, and documentation style.
Ask: "What capabilities must this skill bundle provide? If you had to remove one, which one would make it pointless?"
This identifies the non-negotiable skills vs nice-to-haves. The agent should actively propose a skill decomposition based on the answer — present 2-3 decomposition approaches with trade-offs when the boundaries aren't obvious.
Ask: "Walk me through how someone would use this — from installing the plugin to completing their task."
This reveals workflow dependencies, entry points, and the natural sequence of operations.
Ask: "Are there similar skill bundles or tools out there? What's different about yours?"
Skip this if the user has already addressed it or if the domain is clearly novel.
After collecting needs exploration answers, restate the understanding and verify completeness:
"Let me confirm what I understand: You're building [one-sentence summary] for [target users] to solve [problem]. The core capabilities are [list]. The usage flow is [summary]. Does this match your intent?"
Must verify before proceeding:
Wait for user confirmation before proceeding to Phase 2. If the user corrects anything, update the understanding and re-confirm.
With a clear understanding of what and why, now decide how to build it. The agent should actively recommend answers based on Phase 1 context, rather than asking open-ended questions.
Before making architecture recommendations: Explicitly list key assumptions derived from Phase 1 and wait for user confirmation. Template:
"Based on our needs exploration, I'm operating on these assumptions:
- [Complexity assumption — e.g., 'This is a straightforward packaging project']
- [Platform assumption — e.g., 'Primary platform is Claude Code based on your workflow']
- [Independence assumption — e.g., 'Skills appear independent with no workflow chain']
If any of these are wrong, correct me now — they will shape all architecture decisions."
Based on Phase 1 answers, recommend quick or adaptive mode:
Quick mode (quick packaging):
Adaptive mode (adaptive deep interview):
Present the recommendation with reasoning: "Based on what you've described — [reasoning] — I recommend [quick/adaptive] mode. [Quick explanation of what this means]."
Quick mode skips most Phase 1/2 questions and defaults to Claude Code only with independent skills. See references/dialogue-strategies.md for the full behavior summary table.
Kebab-case identifier (e.g., my-dev-tools). This becomes the directory name, package name, and plugin ID across all platforms.
Validation: lowercase letters, numbers, hyphens only. No underscores, no spaces.
Which platforms should the project support? See references/platform-reference.md for the full platform table and selection strategies.
Based on the target users identified in Phase 1, recommend a platform combination with reasoning. Start with what the user actually uses — others can be added later via bundles-forge:scaffolding.
Based on the core capabilities and usage flow from Phase 1, propose a skill decomposition rather than asking the user to list skills:
"Based on the capabilities you described, I recommend splitting into these skills: [proposed list with one-sentence purpose each]. Here's why this decomposition makes sense: [reasoning]."
When the decomposition isn't obvious, present 2-3 approaches:
For each skill, determine:
If the user isn't sure yet, scaffold with a single placeholder skill and the bootstrap.
Questions 4a (Skill Visibility), 5 (Workflow Chain), 6 (Bootstrap Strategy), and 7 (Advanced Components) apply only in adaptive mode. Quick mode skips them. See references/adaptive-mode-questions.md for the full question set.
Restate the architecture decisions and verify completeness before generating the design document.
Must satisfy (missing any one blocks document generation):
Should satisfy (mark unmet items as [TBD] in the design document):
Wait for user confirmation before proceeding to Phase 3.
After the interview, compile a design summary using the template in references/design-document-template.md. This template includes both needs context (project overview, target users, use cases, success criteria) and technical architecture (mode, platforms, skills, workflow, components). Conditional fields: fill Third-Party Sources only when Scenario C involves external skills; fill Notes for special constraints not captured elsewhere. Leave unused conditional fields out of the document.
Before presenting to the user, review the document:
Fix issues inline. Then present the document to the user.
Present the design document and ask the user to review:
"Here's the design document. Please review and let me know if anything needs adjustment before I proceed with the creation pipeline."
If the user requests changes, update the document and re-run the self-review. Only proceed to the Orchestration Pipeline when the user explicitly approves.
The user may request going back to a specific phase to re-discuss decisions — support this without restarting from scratch.
After the user approves the design, orchestrate the full project creation pipeline. Execute each phase in order — do not skip or reorder phases.
"Design approved. Invoking scaffolding to generate the project structure."
Invoke bundles-forge:scaffolding with the approved design. Wait for scaffolding to complete (including its inspector self-check) before proceeding.
→ verify: inspector self-check passes with 0 critical findings → on fail: fix structural issues inline, re-run inspector before proceeding
"Structure generated. Invoking authoring to write skill and agent content."
Invoke bundles-forge:authoring with the full skill inventory from the design document. Pass the complete design document (including project overview, target users, and use cases) so authoring can write more targeted descriptions and overviews. Authoring handles:
agents/*.md) if the design specifies subagentsPass the complete list in one invocation — authoring processes them in sequence.
→ verify: every skill in the design has a SKILL.md with valid frontmatter (name, description) → on fail: re-invoke authoring for missing or invalid skills
"Content authored. Designing workflow integration."
This step runs within blueprinting — workflow wiring requires the full project context from the interview.
## Integration section:
**Calls:** and **Called by:** declarations must be symmetric (A calls B ⟹ B is called by A)## Outputs must match downstream ## InputsDispatched by: to the agent file→ verify: all Calls/Called-by pairs are symmetric; bootstrap routes match skill inventory → on fail: fix asymmetric links or missing routes before proceeding
"Workflow wired. Running initial audit."
Invoke bundles-forge:auditing on the project root for a baseline quality check.
→ verify: 0 critical audit findings → on warn: present to user, proceed if user approves → on critical: must address before project is considered ready
| Mistake | Fix |
|---|---|
| Skipping needs exploration, jumping to architecture design (see HARD-GATE above) | Understand "what and for whom" before deciding "how to build" |
| Proposing approaches without trade-off analysis | Each approach needs pros, cons, best-fit scenario, and an explicit recommendation — not just a list of options |
| Forgetting workflow chain mapping | Chains determine bootstrap skill content — an unmapped chain produces a bootstrap that routes incorrectly |
| Dumping skills into one folder without analyzing compatibility | Audit each skill first — naming conflicts and overlapping responsibilities cause confusion |
| Copying third-party skills without security audit | Always invoke bundles-forge:auditing on imported content |
| Treating all third-party skills as repackage-only | Ask integration intent — workflow integration requires adaptation |
| Forgetting skill visibility classification | Entry-point vs internal determines description style |
| Using blueprinting to add skills to an existing project | Blueprinting creates new projects; use bundles-forge:optimizing (Skill & Workflow Restructuring target) for existing ones |
user-requirements (required) — conversational input gathered through the structured interview processexisting-skill (optional) — path to existing SKILL.md for Scenario B (decomposition)candidate-skills (optional) — list of existing skills for Scenario C (composition)design-document — structured design summary containing project overview, target users, use cases, success criteria, project name, platforms, skill inventory, workflow chain, bootstrap strategy, and advanced components. Contains skill-inventory (consumed by bundles-forge:authoring) and workflow-chain (consumed during the Wire Workflow step). Consumed by bundles-forge:scaffolding and bundles-forge:authoringCalls:
design-document → design-document (direct match)design-document → skill-inventory (indirect — skill inventory extracted from design document)design-document → project-directory (indirect — auditing targets the scaffolded project, not the design document)Pairs with: