blueprint

Overview of blueprint skill

What blueprint does

The blueprint skill turns a one-line goal into a step-by-step construction plan for complex engineering work. It is designed for multi-session, multi-PR tasks where a fresh agent needs enough context to continue without guessing. If you need a blueprint for Project Setup, a migration roadmap, or a refactor plan with dependencies, this skill is a strong fit.

Who should install it

Install blueprint if you regularly hand off work between sessions, coordinate parallel sub-tasks, or need a plan that survives context loss. It is especially useful for agents working inside an existing repo, where the real challenge is sequencing work safely rather than generating ideas.

What makes it different

Unlike a generic prompt, blueprint bakes in trigger rules, dependency ordering, parallel-step detection, an adversarial review gate, and a plan mutation protocol. That matters when the main risk is not writing code, but choosing the wrong order, under-scoping a step, or missing a rollback path.

How to Use blueprint skill

Install and trigger it correctly

Install the blueprint skill with the directory’s normal skill installer, then invoke it only when the task is genuinely multi-stage. The repository’s own trigger rule is narrow on purpose: use it for a plan, blueprint, or roadmap when the work likely needs multiple sessions or multiple PRs; do not use it for a small change you can finish in one pass.

Give it the right source input

Blueprint works best when your input names the objective, target repo, constraints, and definition of done. A weak prompt is “plan the refactor.” A stronger prompt is: “Create a blueprint for Project Setup: move config loading into a shared module, keep backward compatibility for two releases, and separate UI changes from backend migration.” The more concrete the scope, the better the dependency graph and step sizing.

Read these files first

Start with SKILL.md, then inspect any repo docs that describe workflow, conventions, or existing plans. In this repository, the skill body is self-contained, so the key thing to extract is the pipeline: research, design, review, and mutation rules. If the target codebase has memory files, architecture docs, or prior migration notes, those will materially improve the blueprint output.

Workflow that produces better output

Use blueprint in three passes: first generate the plan, then check whether the steps can really stand alone, then revise for missing dependencies or unsafe parallelism. Pay attention to steps that require the same files, shared state, or release sequence; those are the cases where a plan that looks neat can fail in execution. The best blueprint usage is not “more detail,” but “correct sequencing with enough context to execute cold.”

blueprint skill FAQ

Is blueprint only for large projects?

Yes, mostly. The skill is built for work that is too large for a single PR or would be risky if attempted without a plan. If the task is small, straightforward, or can be completed in a few tool calls, a normal prompt is usually faster.

How is blueprint different from an ordinary prompt?

An ordinary prompt can ask for a plan, but blueprint adds structure: step dependencies, parallel detection, rollback thinking, and a review layer that tries to catch weak assumptions. That makes it more reliable when you need a blueprint for Project Setup or another task where order and handoff quality matter.

Is blueprint good for beginners?

Yes, if the goal is learning how to break a project into manageable phases. It is less useful if you are still deciding what the task actually is, because the skill assumes there is a real engineering objective with constraints and a path to completion.

When should I not use blueprint?

Do not use blueprint when the job is small enough to finish directly, when the user explicitly says “just do it,” or when the task has no meaningful dependency structure. In those cases, the planning overhead can slow you down without improving the result.

How to Improve blueprint skill

Be explicit about boundaries

The best blueprint outputs come from clear scope limits: what must change, what must stay stable, what is out of scope, and what counts as success. If you want a blueprint for Project Setup, say whether you are changing repo bootstrapping, environment config, CI setup, or all three. Ambiguous scope is the fastest way to get a plan that is either too big or too shallow.

Provide dependency clues up front

Blueprint is strongest when it knows which pieces block others. Mention migrations, shared modules, feature flags, API contracts, release order, and anything that must land before another step can start. This helps the skill produce a useful dependency graph instead of a list of disconnected tasks.

Ask for execution-ready steps

If you want better blueprint skill output, ask for steps that a fresh agent can execute cold. That means each step should have enough context, expected outcome, and risk notes to avoid rereading the whole repo. This is especially important for multi-agent work, where a vague step title causes rework.

Iterate on the first plan

Treat the first blueprint as a draft, then tighten it after checking for missing constraints, parallel work that conflicts, or steps that are too large for one PR. If the plan is too broad, split it; if it is too detailed, collapse repeated setup work. The goal is not a prettier outline, but a blueprint that lowers execution risk.