Skip to content

Agent Harness — Complete Cheat Sheet

Quick reference on agent harnesses: what they are, every component in one place, and how Skills / Hooks / Subagents / MCP relate. Editable diagrams (draw.io): agent-harness-anatomy.drawio (2 pages) — same folder.

Quick Definition

Agent = Model + Harness. The model is the raw LLM; the harness is everything else — every piece of code, configuration, and execution logic that turns a model into a work engine: prompts, tools, context policies, hooks, sandboxes, subagents, feedback loops, and recovery paths.

[!TIP] "If you're not the model, you're the harness." A decent model with a great harness beats a great model with a bad harness.

A raw model can't: maintain durable state, execute code, access real-time knowledge, or set up environments — all of that is harness-level. Claude Code, Cursor, Codex, Aider, Cline, Hermes: these are all harnesses.

Anatomy (diagram)

Harness Anatomy

The Agent Loop (ReAct) + Delegation

Agent Loop

The core pattern is a ReAct loop: Reason → Act (tool call / delegate) → Observe → repeat, until the goal is met.

Component Quick Reference

Component Quick definition
System prompts / context files Instructions injected at start: system prompt, CLAUDE.md, AGENTS.md, skill files, subagent prompts. The "always-on" context.
Tools Functions the model can call (filesystem, bash, browser, APIs, search). Tool descriptions matter — the model selects tools by them.
MCP (Model Context Protocol) Standard protocol to plug external tools/data servers into any harness (one integration, many agents).
Skills Folder-based packs (SKILL.md + helper scripts) of repeatable expertise ("how we ship a feature here"). Loaded on demand when the task matches; the agent chooses to invoke them. Know-how.
Hooks Deterministic scripts that fire on lifecycle events (PreToolUse, PostToolUse, Stop, Notification, SubagentStop…) with no agent discretion. E.g. block writes outside the repo, run formatter after edits, run tests on stop, redact secrets. Guarantees.
Subagents Isolated workers with a fresh context window, spawned for independent/parallel subtasks; results return to the main agent without polluting its context. Delegation.
Memory & filesystem Durable state across sessions; filesystem is the foundational primitive (workspace, context offload, git versioning, AGENTS.md memory injection, collaboration surface for agent teams).
Sandbox Safe, isolated execution environment (containers/VMs): allow-listed commands, network isolation, on-demand scale, teardown.
Orchestration The control logic: subagent spawning, handoffs, model routing, context compaction, planning tools, eval loops.
Observability Logs, traces, cost/latency metering — you can't improve what you can't see.

Skill vs Hook vs Subagent (one-liners)

Primitive One-liner
Skill Things you want the agent to know how to do — invoked, on demand.
Hook Things you want to happen no matter what — invisible, deterministic, no agent choice.
Subagent Things you want the agent to delegate — isolated context, parallel work.
MCP How the harness connects external tools/data — standard protocol.

Harness Engineering (best practices)

  1. Treat the harness as a real artifact — it's your surface area, not the model provider's.
  2. Tighten the loop on every failure: agent makes a mistake → engineer a solution so it never does again (better prompt, guardrail hook, eval, skill, or subagent boundary).
  3. Default to the filesystem for durable state and context offload — don't stuff everything in context.
  4. Run risky code in sandboxes; enforce allow-lists and network isolation.
  5. Make hooks for guarantees, skills for expertise, subagents for isolation.
  6. Measure: logs, traces, evals, cost/latency — most agent failures are "skill issues" of harness configuration, not model weights.

Sources