agent-harness-review

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: Claude Code 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.
• How the client behaves: read its current docs for what a setting covers and what disabling something removes. In Claude Code, skillOverrides does 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.