Guide · Agent skill
How to use the Blueprint Build Planner agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
Blueprint is an agent skill that turns a one-line goal for a large, multi-session engineering project into a step-by-step build plan saved as a markdown file. It is for engineers who plan large features, migrations or refactors spanning several pull requests, and for anyone who loses context between sessions. After this guide you will know what the skill does, how to install it, how to ask for a plan, and when to skip it.
Blueprint Build Planneraffaan-m/ECC · MIT Download the skill Quick start
- 1Confirm the skill is present. From an ECC checkout, run the test command to confirm skills/blueprint/SKILL.md exists. Otherwise, download the ZIP from the page.
- 2Install the skill. Unzip it into ~/.claude/skills/ for personal use, into a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Check git and gh. Make sure git is available and GitHub CLI is authenticated so the full branch, PR and CI workflow can run.
- 4Ask for a plan. Describe a large goal that spans several PRs or sessions, using words like plan, blueprint or roadmap.
- 5Review the plan file. Open the markdown file the skill saved in plans/ and check dependencies, steps and verification commands.
- 6Run the steps. Hand each step to an agent or subagent. Each step's context brief is written to work without earlier steps.
What the Blueprint skill makes the agent do
When you ask for a plan for a large, multi-PR or multi-session project, the agent breaks the goal into roughly 3 to 12 PR-sized steps. Each step has dependencies, notes on what can run in parallel, a rollback strategy and verification commands.
Each step also includes a self-contained context brief, so a fresh agent can run that step without reading the earlier ones. The plan is written as a markdown file in a plans/ folder, reviewed adversarially by a stronger model subagent against a checklist and an anti-pattern catalog, and then saved.
- Pipeline: research, design, draft, review, register
- Output: a markdown file in plans/, for example plans/myapp-migrate-database-to-postgresql.md
- Each step includes a context brief, task list, verification commands and exit criteria
Install the Blueprint skill
If you use the ECC repository, the skill ships with ECC and you do not need a separate install. To check that it is present from an ECC checkout, run the test command below.
You can also install the skill by downloading the ZIP from the page, then unzipping it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder for one project. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal: unzip into ~/.claude/skills/
- Single project: unzip into the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
test -f skills/blueprint/SKILL.mdCheck your requirements before you start
The full branch, pull request and CI workflow needs git and GitHub CLI (gh), with gh authenticated. The skill runs a preflight check on git, gh authentication, the remote and the default branch before it plans.
Without git and GitHub CLI, the skill switches to a reduced direct mode instead of the full branch/PR/CI workflow. The skill also expects skills/blueprint/SKILL.md to be present, which is the case when it is part of the ECC repository.
- git
- GitHub CLI (gh), authenticated, for the full workflow
- The ECC repository, with skills/blueprint/SKILL.md present
Trigger the skill with a natural request
The skill is meant for complex multi-PR tasks. Ask for a plan, blueprint or roadmap, or describe work that will need several sessions. You can also invoke it directly with a slash command and a project name plus a goal.
Do not expect it to fire for small work. The skill says not to use it when a task fits in a single PR or fewer than three tool calls, or when the user says to just do it.
- "Plan the migration of our billing service into separate PRs across several sessions."
- "Give me a blueprint for splitting this monolith's auth code into steps other agents can run."
- "Create a roadmap for the new reporting feature, with rollback steps."
/blueprint myapp "PostgreSQLにデータベースを移行"Read an example plan
For the goal of migrating a database to PostgreSQL, the skill's example produces a plan in plans/ with five steps: add the PostgreSQL driver and connection configuration, write migration scripts for each table, update the repository layer to use the new driver, add integration tests against PostgreSQL, and remove the old database code and configuration.
Each of those steps is written so an agent can start from it alone, which is the point of the format when work spans several sessions.
- Step 1: add PostgreSQL driver and connection configuration
- Step 2: write migration scripts for each table
- Step 3: update the repository layer to use the new driver
- Step 4: add integration tests against PostgreSQL
- Step 5: remove old database code and configuration
Safety notes: scripts and network
According to the source, this skill runs no scripts and uses no network access. It works by reading your project files and git/gh state and writing a markdown plan into plans/.
Review the generated plan before you act on it, since the verification commands and rollback steps are written for your project and should be checked against your setup.
- Runs scripts: no
- Uses network: no
- Writes a markdown plan file to plans/
Tips for getting good plans
Give the goal in one clear line and name the project, so the research step can find the right structure. Mention any constraints such as deadlines, required reviewers or parts of the code that must not change.
If you work with several agents, say so. The skill can note which steps run in parallel and which must run in order.
- State the goal in one line, with the project name
- Say whether several agents or sessions will run the plan
- Point to existing plans or notes so the research step can read them
What people use it for
- Splitting a large feature into PR-sized steps with dependencies
- Planning a database migration across several sessions
- Coordinating subagents that work on different steps in parallel
- Writing a rollback-aware refactor plan for a team
- Resuming a long project in a new session from a self-contained step
Frequently asked questions
How do I install the blueprint agent skill?
Download the ZIP from the page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills. If you use the ECC repository, the skill is already included.
What do I need to run the blueprint skill?
The full branch, pull request and CI workflow needs git and GitHub CLI (gh), authenticated. The skill also expects skills/blueprint/SKILL.md to be present, which is true when it is part of the ECC repository. Without git and gh it runs in a reduced direct mode.
Is the blueprint skill free?
The source lists the licence as MIT. It does not mention pricing, so check the page for current terms before relying on it.
Does blueprint run scripts or use the network?
According to the source, it runs no scripts and uses no network. It reads project files and git/gh state and writes a markdown plan into plans/.
Why does blueprint not trigger for my small change?
The skill is designed for work that spans several PRs or sessions. It says not to use planning for a single PR, tasks under three tool calls, or when you ask it to just do the task.
How does blueprint compare with just asking an agent to plan?
Blueprint adds a fixed structure: 3 to 12 PR-sized steps, dependency and parallel notes, rollback strategy, self-contained context briefs, and an adversarial review by a stronger model subagent. A plain request does not guarantee those parts.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Blueprint suits engineers and teams planning large features, migrations or refactors across several PRs, especially when several agents or sessions must pick up work without earlier context. It is not worth it for small changes or for anyone who just wants the task finished now. Projects without git and GitHub CLI get a reduced mode, so the full workflow needs those tools.
Download the skill