Foundations¶

You can use coding agents productively without understanding how they work. You cannot design a harness that way.

The gap shows up quickly. An engineer who has only used agents explains a bad run in human terms: it got confused, it forgot, it was lazy today. An engineer who understands the mechanism explains it in system terms: the instruction was 120,000 tokens back, the test output drowned it, nothing checked the claim that tests passed. The first explanation leads to retrying. The second leads to a change that stops the failure happening again — and that change is what a harness is made of.

This section is the minimum mental model I think every builder needs in late 2026: what an agent actually does in a loop, why context is the scarce resource, and what each of the primitives — instructions, skills, tools, subagents, hooks — is good for and bad at. It is deliberately tool-agnostic, with concrete examples from the tools whose behaviour is documented well enough to show precisely.

Why the primitives are worth learning once¶

A year ago, every agent had its own vocabulary and its own file formats, and learning one taught you little about the next. That has changed faster than most people noticed.

AGENTS.md and the Model Context Protocol now sit in a vendor-neutral home: the Agentic AI Foundation, launched under the Linux Foundation in December 2025 with MCP from Anthropic, AGENTS.md from OpenAI and goose from Block. Agent Skills became an open standard the same month. A July 2026 source-code study of eleven agent harnesses found SKILL.md skills in nine of them and MCP in eight, and noted that Codex had adopted Claude Code's hook vocabulary verbatim. The names still differ at the edges, and the details of loading and discovery differ more than the marketing suggests. But the ideas have converged.

That convergence is what makes a team harness possible. If the same AGENTS.md, the same skills and the same guards work across the agents your engineers prefer, the harness belongs to the team rather than to a tool. It is also why this section explains mechanisms rather than menus: the menu will change next month; the loop will not.

Where each primitive acts¶

Every primitive in this section attaches to a specific point in the same loop. Holding that picture makes most design decisions easier.

            ┌──────────────── context window ────────────────┐
            │ instructions (always)   skill descriptions     │
            │ tool definitions        conversation + results │
            └───────────────────────────┬────────────────────┘
                                        ▼
                                  model decides
                                        │ tool call
                                        ▼
                      hooks and permissions: allowed?
                         │ no: reason back       │ yes
                         ▼                       ▼
                    model adapts         tool runs (or a subagent
                                          runs its own loop)
                                                 │
                                       result appended to context

Instructions and skill descriptions are in the window from the start. Skills add their full text only when a task matches. Tools define what an action can be, and their results are what fills the window fastest. Hooks and permissions sit between the decision and the action. Subagents are a whole second loop whose only output, from the parent's point of view, is one tool result.

What this section covers¶

Read them in order if you are new to this. The first two pages are the mental model; the other five are applications of it. If you already work with agents daily, start wherever your harness hurts most — the pages stand alone.

The primitives at a glance¶

A useful rule of thumb: if it must always happen, make it a hook or a check. If it should happen when relevant, make it a skill. If the agent needs it on every task, make it an instruction — and keep it short.

The rule of thumb has a corollary that teams learn the hard way: the cost of getting it wrong is asymmetric. A rule placed in a skill when it should have been a hook fails silently, on the one task where the skill did not load. A procedure placed in the instruction file when it should have been a skill fails slowly, by making every session a little heavier and a little less focused. Neither failure announces itself, which is why the pages that follow spend so much time on how to notice them.

What good looks like¶

Failure modes and mitigations¶

Most harnesses go wrong in the same direction: towards more. More lines in the instruction file, more servers connected, more agents in the diagram. Each addition is locally reasonable and collectively expensive, and the cost is paid in attention on every step of every task.

Further reading¶

• How coding agents work by Simon Willison — The shortest good explanation of the loop.
• Effective context engineering for AI agents by Anthropic — The attention-budget view of context that this section builds on. (Vendor engineering post.)
• Harness Engineering: anatomy, architecture, and evolution of coding agents by Paul Barbaste et al. — What eleven agent harnesses actually implement, from their source code. (Preprint.)
• Linux Foundation announces the Agentic AI Foundation by the Linux Foundation — The neutral home for MCP and AGENTS.md.

Related pages¶

• Glossary — Definitions for every term used here.
• What a Harness Is — How the primitives combine into a system.
• Portability — Keeping one source of truth across several agents.