Senior engineering habits for coding agents.
Small skills for Claude Code and Codex that turn an idea into a reviewed, tested pull request.
Quick start · Our take · The workflow · Verification · Example
As models get smarter, skills get simpler.
Agents already know how to write code. What they lack is the judgment that experienced engineers bring to a team: write down what you are building before you build it, prove it works, and get someone else to check it. Blueprint encodes those habits, drawn from years of engineering experience and working with some of the best engineers in the world.
So each skill is short. It gives the agent three things and trusts it with the rest:
| A template | The shape of a good PRD, spec, or pull request. A template beats a page of instructions. |
| A standard of proof | Every check passes, every acceptance criterion has a test, and the tests fail when the code is reverted. |
| A second pair of eyes | A fresh reviewer, ideally a different model, checks the work against the spec before a human sees it. |
The same skills work in Claude Code and Codex.
1. Install
npx skills add owainlewis/blueprint2. Describe the product. Ask your agent:
Use /requirements for a CRM that helps a small consulting firm track leads and follow-ups.
You get REQUIREMENTS.md: the PRD, written as user stories with checkable outcomes.
3. Spec one feature.
Use /spec for capturing a new lead.
You get docs/capture-lead/spec.md: the user stories for that feature, a diagram, and the technical design an agent can build from.
4. Ship it.
Use /task-to-pr for docs/capture-lead/spec.md.
The agent builds it, runs every check until green, gets an independent review, waits for CI, fixes what comes back, and leaves a pull request ready for you.
See the full result in the consulting CRM example.
Blueprint follows how good engineers already work. Each skill belongs to one stage.
flowchart LR
D["Design<br/>/requirements /architecture /spec"] --> P["Plan<br/>/plan"]
P --> B["Build<br/>/task-to-pr"]
B --> T["Test<br/>does it work?"]
T -->|fails| B
T --> R["Review<br/>is it right?"]
R -->|findings| B
R --> M(["Merge"])
subgraph V [Verify]
T
R
end
Skip any stage the work does not need. A small, clear fix can go straight to Build.
Verify has two parts, in order. Test asks does it work?: machines run format, lint, typecheck, tests, and browser checks. Review asks is it right?: another model, then you, check that it matches the spec, is safe, and can be maintained. Review starts only once tests pass. The verification guide shows how to set up both in any repository.
| Skill | Use it when | You get |
|---|---|---|
/requirements |
Starting a product or changing what it does | REQUIREMENTS.md, a PRD of user stories |
/architecture |
Designing the system or changing its shape | ARCHITECTURE.md with a data flow diagram |
/spec |
A feature has decisions to settle first | User stories, a diagram, technical design, acceptance checks |
/architecture-review |
A design choice is costly to get wrong | Findings and a verdict before any code |
/html-doc |
You want to share a design as a web page | A checked, static HTML view |
| Skill | Use it when | You get |
|---|---|---|
/plan |
A spec is too big for one pull request | Small tasks, each a working slice |
| Skill | Use it when | You get |
|---|---|---|
/task-to-pr |
A spec or task is ready to build | A tested, reviewed pull request, left open unless you say "and merge it" |
/codex-issue-coordinator |
You have a batch of GitHub issues for Codex | One worker and one checked PR per issue |
/improve |
Code works but is hard to follow | Simpler code with the same behavior |
| Skill | Use it when | You get |
|---|---|---|
/test |
You need to know it works | Every check green, and pass or fail for each criterion |
/review |
You need to know it is right | Spec fit, correctness findings, and a verdict from a fresh reviewer |
/task-to-pr runs Test and Review for you, then waits for CI.
Blueprint runs only when you ask for it. "Fix this bug" gets your agent's normal behavior; "use /task-to-pr to fix this bug" gets the full workflow. Once you pick a workflow, it loads the skills it needs on its own.
Claude Code honors this through disable-model-invocation: true, and Codex
through agents/openai.yaml. Agents only merge when you ask them to, or when you
invoke /codex-issue-coordinator by name.
- Verification: set up testing and review for any repository.
- Choosing a skill: where each skill starts and stops.
- Workflows: small fixes, larger features, existing systems, and issue batches.
- Consulting CRM example: requirements, architecture, a spec, and a plan.
- Migration: upgrading from an older Blueprint.
- Changelog
Blueprint stays small on purpose. It is not an issue tracker, an agent runtime, or a release system. Read CONTRIBUTING.md before opening a pull request, and report security problems through SECURITY.md.
Released under the MIT License.