Skip to content

Agent architecture

The big picture: Blueprint splits AI work two ways. Skills are workflows started with /name (some only by you); agents are specialists Claude starts when a change needs them. And each job goes to the cheapest model that can do it well — Opus for judgment, Sonnet for checklists.

Why it matters: The right split keeps quality high where it counts and cost low everywhere else. Most of the bill in agent-heavy work is re-reading context, not writing code, so how many agents run — and on which model — decides what a feature costs.

How it works:

  • Opus agents (architecture, security, permissions, design, the completeness audit) make the judgment calls. They hand mechanical scanning to a few parallel Sonnet sub-agents, then synthesize.
  • Sonnet agents (regressions, performance, UX, tests, changelog) follow a checklist.
  • Delegation stops at one level. A sub-agent starts no more agents beyond the fan-out ceiling’s exceptions — see Fan-out ceiling.
  • Every agent’s tools: line limits what it can do. A reviewer with only Read, Grep, Glob can’t edit anything.

The full roster is on the Agents and Skills pages. This page is how they’re built, and how to add your own.

Use opus when the agent needs to… Use sonnet when the agent needs to…
Synthesize findings across multiple files Scan for patterns in code
Make judgment calls or trade-off decisions Follow a checklist or ruleset
Reason about attack scenarios or edge cases Generate code from templates
Inhabit a persona or produce empathetic analysis Execute mechanical transformations

The template uses two extension points:

  • Skills (.claude/skills/<name>/SKILL.md) — user-invocable workflows triggered by /name. Used for multi-step operations like opening MRs, running releases, or importing specs. Skills with disable-model-invocation: true can only be triggered by the user (not auto-invoked by Claude) — use this for actions with external side effects.
  • Agents (.claude/agents/<name>.md) — proactively invoked by Claude when their trigger conditions are met. Used for review, analysis, and generation tasks that should run automatically as part of the development workflow.
Feature Skills Agents
Invocation You type /name; Claude may also start one unless it’s marked ⛔ Claude invokes proactively, or you ask by name
Side effects Can have external effects (GitLab, git push) Typically read/analyze/generate
disable-model-invocation Supported N/A (agents are always model-invokable)
Frontmatter Full schema (model, effort, argument-hint, etc.) Limited (name, model, description, tools)
Supporting files Can include templates/scripts in the skill directory Single file only

Skills marked ⛔ on the Skills page have disable-model-invocation: true.

Create a file in .claude/agents/:

---
name: my-agent
model: opus # or sonnet — see model selection above
description: When to use this agent (be specific so Claude invokes it proactively).
tools: Read, Grep, Glob, Bash, Agent
---
# My Agent
[instructions — include sub-agent delegation if the agent does Phase 1 scanning]

If the agent delegates scanning work to sub-agents, include Agent in the tools list and structure the instructions with parallel sub-agent launches. Cap the launch at a handful (2–3 is typical; /wave’s own wave default is 5) and never give the sonnet sub-agent Agent in its tools — one level of delegation is the pattern, not a precedent for the sub-agent to delegate again. See Fan-out ceiling below for the project-wide default this pattern has to fit inside.

### Step 1 — Gather context (parallel sub-agents)
Launch **2 sub-agents in parallel** (both with `model: "sonnet"`). Wait for both.
**Sub-agent 1 — [scanning task]:**
> [instructions]
**Sub-agent 2 — [scanning task]:**
> [instructions]
### Step 2 — Synthesize (you do this — do NOT delegate)
[synthesis instructions using sub-agent results]

.claude/settings.json’s deny list guards what agent work does — force-push, auto-merge, reading secrets. It has no per-task wave-size lever (nesting depth and concurrent-subagent count are bounded by the CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH and CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS env keys; see the subagents reference, checked: 2026-10-15), and runaway fan-out (agents spawning agents spawning agents on a task that didn’t need it) is its own failure mode: upstream, a wave of delegated agents ran ~122M tokens per merged MR, 95.9% of it cache reads rather than generation, and spend was concentrated — the top 10 of 169 subagents were 44% of the total, one subagent alone at 166M against a 6M median.

The project’s own CLAUDE.md documents the default this pattern has to respect (see Subagent fan-out ceiling in its Agent workflow section, and the cost rules section of .claude/skills/wave/SKILL.md): cap concurrent delegated agents at 5 per task unless the user asks for more, never let a delegated agent re-delegate beyond the one Phase-1 level shown above (or a /wave --harness implementer’s pre-MR gate batch; a pinned wave-worker spawns nothing, and the orchestrator runs its gates), default read-only gates to the cheaper model, and state an explicit reason when a task needs to exceed the default.

This is enforced by two things, not one: the tools: restriction on each agent definition (a real, load-bearing cap — an agent with no Agent in its tools: cannot spawn sub-agents at all), and review discipline for everything tools: can’t reach — verifying what a delegated agent actually committed rather than trusting its summary. A settings.json hook was considered for the harder cap (blocking a spawn outright, or counting fan-out across a wave) and rejected: the lifecycle events for a subagent spawn (SubagentStart/SubagentStop) can’t refuse a spawn (SubagentStart has no decision control; SubagentStop can only keep a subagent from stopping), and a PreToolUse hook would have to match the spawn tool by name, which has changed across Claude Code versions (Task vs. Agent; see the hooks reference, checked: 2026-10-15).

Create a directory in .claude/skills/:

---
name: my-skill
description: What this does and when to use it.
disable-model-invocation: true # only if it has external side effects
argument-hint: "[arg description]"
---
# My Skill
[instructions — same format as agents, with $ARGUMENTS for user input]

The workflow is mandatory rather than suggested because its rules are in the repository: the Fast paths by change class table and the Pre-MR gate batch in CLAUDE.md, plus the Gate reference table and cross-cutting rules in .claude/operating-rules.md (imported by CLAUDE.md). They load whenever Claude Code opens the project, and only then, so they do not leak into your other repositories.

The Gate reference table says when each gate applies and when it doesn’t, so backend-only changes skip the UX agents and bug fixes skip the design phases. It records only what each agent’s own description: does not already say, because the harness injects those descriptions anyway.

global-claude-md.example remains as an optional template for personal preferences that apply across projects. Nothing in it is needed for the harness to run. See Start a project, step 7.

For monorepos with distinct frontend/backend/worker packages, give agents stack-specific context in one of two ways:

my-project/
├── AGENTS.md # Project contract any coding agent reads
├── CLAUDE.md # Claude Code workflow; imports AGENTS.md
├── worker/CLAUDE.md # nested: loads when files under worker/ are read
└── .claude/rules/
├── frontend.md # paths: ["frontend/**"] React patterns, design tokens
└── backend.md # paths: ["backend/**"] Django patterns, API rules

A nested CLAUDE.md loads when Claude reads a file in its directory. A .claude/rules/*.md file with paths: globs loads when Claude works with a matching file, and can match a file class rather than one directory. Both keep package rules out of the always-loaded root file. Use /import-design to generate .claude/rules/frontend.md from a design guide.

The permission deny list is not a security boundary; the sandbox is the layer that limits what an allowed Bash command can touch. The template ships an opt-in profile, .claude/settings.sandbox.example.jsonc, that restricts filesystem writes and network hosts; make doctor reports whether it is active. It is off by default.

There is no per-agent sandbox: subagents share the parent session’s sandbox, and it covers Bash only (see Sandboxing, checked: 2026-10-17). Gates limited to Read, Grep and Glob are unaffected. Every agent with the Bash tool is constrained: the read-only gates completeness-check, schema-check, generated-artifact-check, regression-check, security-review and architect, plus dependency, docs, test-scaffold, threat-model, ux-design and voc.