An Agent Expert is a generic agent plus a self-maintained mental model of one domain — built from three files that close the Act → Learn → Reuse loop so specialization compounds instead of resetting.

Guide

How to Build Agent Experts

The shape of the idea

Three steps. Exactly three. Skip one and the gains leak.

Every run of an Agent Expert moves through this cycle.

01

Act

Read expertise, make the change

plan_build

→

02

Learn

Validate claims against the diff

self-improve

→

03

Reuse

Next task starts warm, not cold

question

Act without Learn is amnesia — the model goes stale.

Learn without Reuse is a journal nobody reads.

All three, or the loop is open.

If any leg is missing, you've built a generic agent with extra steps — not an expert.

What you actually build

Three artifacts. One per step of the loop.

expertise.yaml

the model

The mental model

Dense YAML: overview, core files + line numbers, patterns, data structures, operations, error handling, known issues.

≤ 1000 lines · cited

question.md

reuse

The read-only command

Loads expertise, validates key claims against the codebase, answers — never writes code. The fast-path orient.

no mutation

self-improve.md

learn

The maintenance command

Optionally reads git diff, revalidates every claim against real code, fixes stale entries, enforces the line cap, parses the YAML.

runs after changes

plan_build_improve.md

The full cycle in one invocation — chains plan-with-expertise → build-against-plan → self-improve-on-diff. Use when you want the agent to close its own loop.

Skip self-improve.md and the expertise rots. The first stale claim collapses the whole file's credibility.

The reading path

The nodes this guide teaches, in the order they click.

01

Mental ModelPrimitive

The expertise.yaml is a rough, validated approximation — not a source of truth. Code is truth; the model is how the agent orients fast. It drifts, it gets corrected, it never replaces reading code.

02

Specialization CompoundsPrinciple

The reason Agent Experts are worth the overhead. Agents that carry their own model across sessions outperform stateless generalists, and the gap grows with codebase complexity.

03

Closed Loop Systems WinPrinciple

Act→Learn→Reuse is a closed loop. Drop a step and the loop opens — gains don't accumulate, they leak.

04

12 Leverage PointsPattern

The mental model is one of the eight through-agent leverage points (Documentation column) — it persists across runs, unlike in-agent context which resets every conversation.

05

Avoid Context PollutionPrinciple

Cap the model. 1000 lines is a practical ceiling. An overloaded mental model is worse than none — it fills the context window with noise.

06

Reduce and DelegatePrinciple

The model enables Reduce: instead of searching the whole codebase, the agent narrows to the files the expertise names. Seconds instead of minutes.

07

Context PrimingPattern

Loading expertise before acting is Context Priming — surgical injection at session start, scoped to the task.

08

Context BundlePrimitive

Distinct neighbor. A bundle is a replay log of what happened. The mental model is a forward declaration of what matters. Historical vs prescriptive.

Read in order — each node earns the next. Start with Mental Model; the rest sits on top of it.

Where experts pay off

High-risk, high-complexity, or where generics keep breaking things.

Data Types / ModelsStart here

Bounded scope, highest leverage. Keeps types synced across every service that touches them.

LEVERAGE

Billing

Webhooks, billing events, payment flows — one wrong change is expensive.

REVENUE

Database

Schema decisions cascade across the whole stack — the foundational building block.

CASCADE

WebSocket / Real-time

Event flows between hooks, services, frontend state — generic agents won't trace them correctly.

COMPLEX

DevOps

Deploy pipelines, infra, environments — high blast radius on any error.

BLAST

Integrations

Third-party systems have undocumented edge cases no generic agent finds on first read.

EDGES

ML / Data Science

Datasets, configs, sandboxes — one wrong parameter breaks everything silently.

SILENT

API layer

Keeps frontend and backend contract in sync across a moving target.

SYNC

The higher the cost of a wrong change, the more an expert pays off. Start with Data Types — bounded scope, fast to prove value.

The build/skip test

Not every domain deserves an expert.

build when

An expert will compound

• Domain is high-risk — wrong changes are costly to undo
• Domain is high-complexity — generics keep missing edges
• Generics repeatedly make the same class of mistake here
• Domain evolves — static docs would go stale; self-improve justifies itself

skip when

An expert is overhead

• Domain doesn't change — a one-time doc beats the expertise.yaml
• Problem is simple — generic agents already solve it reliably
• You don't have your own mental model yet — you can't evaluate the agent

If you can't judge whether the expert is performing well, don't build it yet — build your own understanding first.

Seeding the first expertise.yaml

The first file is the hardest. Two honest paths.

Path A · agent-led

Let the agent seed it

1.Create a blank expertise.yaml in the expert's directory.

2.Run self-improve — the agent reads the codebase and builds the structure from scratch.

3.Rerun until it stops finding new things.

Use when you want to discover the domain's real shape from the code, not from your assumptions.

Path B · human-led

Seed the shape yourself

1.Write the high-level shape — section headings, key files you know matter.

2.Run self-improve — the agent fills in details, line numbers, anchors.

3.Rerun as coverage grows.

Use when you know exactly what the mental model should prioritize — ship a priority, let the agent fill the facts.

Either way — don't be too prescriptive about structure. Let the agent decide what's important within the domain. It's their mental model, not yours.

The discipline

A generic agent starts from zero. An expert starts from last time.

Three files close the loop — expertise, question, self-improve. Act produces the change, Learn keeps the model honest, Reuse makes the next run faster. Close all three legs or the loop stays open and specialization never compounds.