Review an agent harness
The goal is the simplest harness that does the job. Add an agent, subagent, skill, plugin or hook only where it measurably helps; removing parts and "no change" are valid outcomes. Match the review to the request: a question about one subagent needs one answer, a whole-setup audit needs the inventory below.
Gather evidence before judging
- What loads every session: instruction files, the skill list (count, near-duplicate names and descriptions), plugins (each can bring skills, hooks, MCP servers and agents), MCP servers, custom subagents and hooks that inject context.
- What is used: in Claude Code,
claude -p "/skill-doctor"(v2.1.252+; needs feature-flag fetching, which third-party providers, a Claude apps gateway and the telemetry, nonessential-traffic and feature-flag opt-outs turn off; in Git Bash prefixMSYS_NO_PATHCONV=1) lists each skill's listing cost, uses and last use, and the plugins not used lately. Transcripts (~/.claude/projects/**/*.jsonl) record skill calls ("name":"Skill"), subagent types ("subagent_type") and MCP calls (mcp__<server>__); Codex keeps sessions under~/.codex/sessions. Low use is a lead, not a verdict: a rarely needed domain skill can still be the right one.claude plugin details <plugin>lists a plugin's skills, agents, hooks and MCP servers with the tokens it adds to every session and per invocation. - How the client behaves: read its current docs for what a setting covers and what
disabling something removes. In Claude Code,
skillOverridesdoes not apply to plugin skills, and disabling a plugin also disconnects its MCP servers; a plugin's MCP server can be re-added as a user-scoped server.
What the sources found, and what to check
Start simple and design the tools (Building effective agents). Prefer a single call or a fixed workflow when the path is predictable; use an agent for open-ended work. Keep the design simple, show the agent's planning, and give the agent-computer interface the care of a prompt: clear tool descriptions with examples and boundaries between similar tools, formats the model writes easily, and arguments that make mistakes hard (absolute paths instead of relative ones).
Delegate breadth, not shared decisions (multi-agent research system, Don't build multi-agents). Agents used about 4× the tokens of chat and multi-agent systems about 15×, so the task must be worth it. Multi-agent pays off for breadth-first, parallel, read-heavy work that exceeds one context, and fits poorly where agents need the same context or depend on each other, which covers most coding. Actions carry implicit decisions: parallel writers without shared context produce conflicting results, so default to one writing thread and use subagents to answer questions. Check that delegation prompts give each subagent an objective, an output format, tools or sources, and boundaries; that the number of agents scales with the task (one agent with 3–10 tool calls for a fact, 2–4 for a comparison, more only for wide research; without such a rule the system spawned 50 subagents for simple queries); and that long results go to files with a reference back instead of being relayed through the lead.
Partition large parallel work and check the evidence (Prompting Claude Opus 5.5, Getting the most out of Opus 5.5). Opus 5.5 runs long audits and migrations with parallel subagents well when each unit is independent (one service per subagent) and the lead checks each subagent's evidence before accepting it. This reconciles with the single-writer rule: parallel writers get separate files or worktrees and no shared decisions. Long runs keep their task list in a file, state what "done" means and which stops are wanted, and give the lead a time budget or elapsed time when finishing sooner matters.
Keep the always-listed skill set small and distinct (Lost in Implicit Routing, arXiv 2610.18522).
With 1,000 irrelevant skills listed, agents loaded the relevant skill far less often
(recall 73.6% → 27.4%) and loaded nothing in 51.6% of tasks (from 9.3%). Hiding only
the irrelevant skills' descriptions largely restored loading; preselecting skills
kept 73.9% recall, and asking the agent to plan its skill use did not match that.
Turn off unused skill bundles, set rarely needed skills to name-only in Claude Code's
skillOverrides (lists the name without its description), merge near-duplicates and keep
descriptions distinct before adding trigger words to a skill that is not picked.
Skills can cost more than they help (Agent Skills Can Be Harmful, arXiv 2608.11888). Across 307 skill-induced failures (125 functional, 182 efficiency), functional failures came mostly from relevant-looking skills that led the agent to implement part of the task wrongly or leave it out. The largest efficiency costs were checks a skill made mandatory regardless of task size (67), long skill bodies (43) and heavy build pipelines (30); prompt length alone did not explain them. Check that a skill's checks and procedures scale with the change, and compare a doubtful skill against a no-skill run on the same task.
Model settings and instruction wording (prompting best practices,
which links each model's own guide). Effort is the main control and its starting level
differs by model (Opus 5.5 medium, Fable 5.2 high): read the guide for the model
the harness runs, and keep xhigh and max for work where a quality gain was measured.
Steer thinking with effort, not prompt lines: remove "think carefully" lines and, on Fable 5.2,
"answer without deliberating" lines, which it no longer follows at medium and above (on
Opus 5.5 at low, such a line can still cut thinking when time to first token matters; keep
it only where quality was measured). Name the early stops to avoid and the stops wanted, keep
confirmation for destructive actions, name the exact actions an approval rule covers, and
mark pasted text. Make the agent loop treat a text-only end of turn as a report, not
completion, and wait for running background commands and subagents before it ends the task.
Reread what a harness carries over to a newer model (Prompting Claude Fable 5.2).
Check standing instructions to delegate and which model subagents run on by default;
"treat that answer as done" lines, which belong in chat and make the model less likely
to point out its own earlier mistakes in agentic work; a token budget written into the
prompt; and cautions that have piled up in memory files, notes and messages between
agents, which make the model ask for approvals it does not need. At higher effort
(xhigh, max) Fable 5.2 was also seen starting subagents to review its own work. If it
still starts more than needed, have the subagent tool's description say, cost first, what
a subagent adds to the session, when delegating pays off and how to brief one: at high
effort a longer description focused on what a subagent costs roughly halved the number
of subagents against a shorter one, so test the change on the harness's own tasks. Where
the app keeps its own message history (not where Claude Code, claude.ai, Managed Agents or
the Agent SDK with an unchanged system prompt keep it), check that the loop is append-only:
changing system, the tools or an earlier message between requests, removing or rewording
an injected reminder included, invalidates the thinking blocks after that point, and on
Fable 5.2 the Messages API then rejects the request with a 400 error by default. Send each
assistant turn back unchanged, thinking blocks with empty text included, put new
instructions in a new message at the end, and shorten history only with context editing or
with compaction that keeps no earlier turns after the summary. A client that renders only
text blocks can look silent during long tool runs, because Fable 5.2's updates between tool
calls arrive as thinking blocks whose text is empty at the default display: "omitted".
An ownership line ("You are the owner and long-term maintainer of this codebase, and its
design is up to you.") made it consolidate duplicated code in about three quarters of runs
instead of under a tenth on small coding tasks, at about 1.7–1.8× the output tokens and
with unrequested changes (new tests and docs, sometimes changed feature behaviour). A scope
rule does not cancel it: with "No drive-by refactors, renames or cleanups" earlier in the
prompt it still consolidated in more than half of runs, so leave the line out where minimal
change is wanted.
Report
Give one table of findings, each with its evidence: measured use, the config or doc fact, and the source finding. Mark which changes were made (reversible, with backups). Say what was measured and what is inferred from a source whose setting differs from the user's.