Agent Experts

Agentic Handbook

Central thesis: A generic agent executes and forgets; an agent expert executes and learns — a self-improving template meta prompt that acts, learns, and reuses a durable mental model with no human in the loop.

Overview

The one massive problem with agents that persists no matter how good your context engineering gets: your agents forget, and so they do not learn. Traditional software improves as it is used — storing analytics, usage data, and patterns. Agents of today do not. Existing fixes each have flaws: memory files are global forced context that always loads and must be manually updated; prime prompts, sub-agents, and skills all require manual updates to steer them.

The alternative is to teach your agents to act, learn, and reuse their expertise at runtime. A true expert never stops learning — it constantly updates a mental model, a data structure that evolves over time. With each useful action, experts accumulate information, examples, and expertise around one specific domain. You are not trying to solve every problem, only the one that matters most to you, your business, and your customers.

Formally, an agent expert is a concrete form of a self-improving template meta prompt. Meta prompts build other prompts; template meta prompts build them with a specific purpose and structure; self-improving prompts update themselves or a related file with new information used in the next execution. Combine all three and you get an agent that teaches itself.

This lesson builds up from meta-agentics (the atoms), through a database expert and a WebSocket expert operating a codebase, to a product-focused expert that shapes adaptive, per-user UI/UX. It closes with the seeding problem, the trade-offs, and clear rules for when — and when not — to build an expert.

Key concepts

Agent expert = self-improving template meta prompt

One executes and forgets; the other executes and learns. That difference is the whole lesson. The expert must learn on its own — you teach it to learn once (by templating your engineering into a self-improve prompt), and after that it accumulates and manages its own expertise. Real experts do not relearn their craft every task; they update their mental model as they go.

The act / learn / reuse loop

Every agent expert boils down to three steps:

• Act — the agent takes a useful action (e.g., building code changes against the domain).
• Learn — the agent stores new information; the expertise file is updated via the self-improve prompt.
• Reuse — the agent reads its mental model directly on the next execution (e.g., a question or plan prompt), skipping search entirely.

A database expert that only reuses and learns (no code changes) is a partial expert — it has reuse and learn but no act step. The WebSocket expert completes the loop: plan (reuse) → build (act) → self-improve (learn).

The expertise file is a mental model, NOT a source of truth

This is the most misunderstood point. The expertise file (YAML, or any format) is your agent's working memory — exactly like the mental model you carry of a codebase. It is a rough approximation, not documentation and not a duplicate source of truth. The true source of truth is always the code — not comments, not plans, not the expertise file. On every run the agent reads the expertise file and then validates its assumptions against the codebase before acting. Because it already knows where things live, there is no searching — just validation. This is the differentiated factor: the agent shows up with a working understanding, just like a senior engineer refreshing their memory before touching a feature.

Meta-agentics (meta prompts, meta agents, meta skills)

The building blocks of your entire agentic layer, not just experts. A meta prompt builds a new prompt (e.g., a question-with-mermaid variant). A meta agent builds a new agent (e.g., a planner agent that reads and fires the plan prompt as a sub-agent). A meta skill builds a new skill (e.g., a start-orchestrator skill). These raise your output as an agentic engineer — but note: meta-agentics act, they do not learn on their own, so they are not experts. Every codebase should have a stack of meta-agentics ready to spin up the next thing.

Seeding

Seeding is that first version of the expertise data structure. Stay relatively hands-off: ideally run the self-improve prompt against a blank file and let the agent define the structure, then tweak the self-improve prompt and re-run. Re-run self-improve until the agent stops finding new things — with a smart enough model, a locked-in mental model stops looking for improvements. Do not be too specific; do not be too high-level. It is exactly like onboarding at a new job — someone gives you the rough rundown of the codebase, tools, and processes.

Product experts vs. per-user experts

Codebase experts operate specific high-risk or complex areas of your code (billing, database, DevOps, integrations, ML/data science, API, data types). Product experts apply the same pattern inside your UI/UX — a mental model per user. When a user takes a useful action (viewing a product, adding to cart), the agent learns it into that user's expertise file and reuses it to regenerate a personalized, generative-UI experience. This is personalization to the max, one data structure per user.

Meta-agentics is how you build the system that builds the system

If you dislike a change the expert made, do not edit the expertise file directly. Update the self-improve prompt that maintains it. Teach your agents how to maintain their own mental model. This is the core message: build the system that builds the system, not the application layer.

When NOT to use an agent expert

• The problem does not evolve or change over time — deploy a generic, forgetful agent instead.
• You do not need a maintained mental model to solve it well — build a one-off prompt, agent, or skill.
• Simpler or brand-new codebases the model has effectively already seen — no unique value to model yet.
• You yourself do not have a mental model of the domain — if you cannot judge whether the expert is performing, you will build one that makes problems worse, not better.

How to apply it

1. Pick a high-value, high-risk, or high-complexity domain — billing, security, database, integrations, data types across microservices. The higher the risk and complexity, the more valuable the expert.
2. Write the self-improve (template meta) prompt first. Its workflow: get git diff → read current expertise → validate against the codebase → identify discrepancies → update expertise → self-validate (line limit + valid data structure).
3. Seed by running self-improve against a blank file. Let the agent define the structure. Re-run until it stops finding new things.
4. Add a reuse prompt (e.g., a question prompt) that reads the expertise file and then validates against code before reporting.
5. Add an act path (e.g., plan → build) so real, useful changes flow through the expert, then trigger self-improve to learn from the git diff.
6. Keep the file bounded. Enforce a max-line limit in the prompt (staying under ~1000 lines is realistic in YAML). The agent must enforce this on itself.
7. Let the agent own the structure. Lean toward autonomy — it is the agent's mental model, not yours. Only get prescriptive where error rates are high ("make sure this is part of your mental model").
8. Scale confidence with compute. For critical answers, spin up three, five, or more experts on the same question (even mixing models like Opus) and synthesize — non-deterministic runs surface things a single agent misses.
9. Once you have several experts, add process. Routers, reminders, or a team practice of checking the experts before starting work. Make "look at the expert first" a habit.

Commands & conventions

Command / prompt	Role in the loop
/question <domain>-question	Reuse — reads the expertise file, validates vs. code, then reports.
/plan	Reuse — generates a plan from the validated mental model.
/build	Act — implements against the plan; produces a git diff.
/self-improve <domain>	Learn — syncs the expertise file to the real codebase from the diff.
Meta prompt / meta agent / meta skill	Builds new prompts / agents / skills (act only — not experts).
/self-improve --<flags>	Optional flags (e.g., check git diff) guide what the sync focuses on.

Conventions:

• Directory: experts live under .claude/commands/experts/<domain>/ — typically two prompts (a question/reuse prompt and a self-improve/learn prompt) plus one expertise file.
• Expertise format: YAML is the default (compact, agent-friendly); TOML, JSON, CSV also work. At scale, store as JSONB blobs in the database (per-user for product experts).
• Consistency of prompt structure builds trust — all prompts follow the same agentic format from Agentic Handbook lesson one; only the details change.
• Closed-loop validation inside self-improve: enforce the line limit and validate the data structure; if invalid, redo.
• Key self-improve line: "Prioritize actionable, high-value expertise over verbose documentation." And: after a search, there may be nothing to do — that is perfectly acceptable (stop agents from always acting).
• Everything reduces to the core four: context, model, prompt, tools. Skill, sub-agent, or MCP server — pick whatever ergonomics you like; it is all an abstraction over the same atoms.
• Once a pattern repeats three times, automate it — hence a meta expert prompt that generates new experts.

Key takeaways

• The one problem context engineering cannot fix is that agents forget — agent experts solve it by learning at runtime.
• An agent expert is a self-improving template meta prompt executing the act → learn → reuse loop.
• The expertise file is a mental model, not a source of truth; the code is always the source of truth, and the agent validates against it every run.
• Teach the agent to maintain its own expertise — never hand-edit the expertise file; update the self-improve prompt instead.
• Seed hands-off and re-run self-improve until the mental model locks in.
• Scale confidence by throwing multiple experts at critical questions and synthesizing results.
• Build experts for high-risk, high-complexity, evolving domains; skip them for static, simple, or generic problems, or when you lack a mental model yourself.
• As a successful product grows in complexity and specialty, agent experts become more valuable, not less.

Notable quotes

"One executes and forgets, the other executes and learns."

"This is not a source of truth. This is your agent's mental model."

"You don't need to tell an expert to learn. It's in their DNA."

"Do you want a generalist working on your codebase that forgets every time they work? Or do you want an expert that remembers and learns from the work done?"