--- title: "Agent Harnesses: A Standard for a Word Nobody Agrees On" pubDatetime: 2026-06-27T00:00:00.000Z description: "Daniel Warfield published an open spec for agent harnesses this month: HARNESS.md, all-caps routing files, and leaf detectors. The format is sensible. The name is a fight it may not win, because most of the industry already uses 'harness' to mean the thing running the agent." tags: [ai-agents, standards, claude-code, agent-skills, context-engineering, 2026, 2026-q2, 2026-06] --- > [!tldr] TL;DR > Daniel Warfield published the [Agent Harnesses standard](https://agentharnesses.io/home) on 16 June 2026: a directory format with a required `HARNESS.md`, all-caps routing files (`TOOLS.md`, `DATA.md`) for progressive disclosure, and `.harnessleaf` / `.leaf-detectors` to stop an agent recursing into skill internals. The format is genuinely useful if you are building a role-shaped agent out of many Agent Skills, and `pip install agentharnesses-cli` gets you a scaffold in one command. The problem is the word. Across Hacker News, arXiv, and vendor docs, "harness" overwhelmingly means the program that runs the agent, so this spec is claiming vocabulary that is already occupied. Try the format, expect the name to stay contested. A commenter on Hacker News summed up the state of the term in May, under a post arguing that [the agent harness belongs outside the sandbox](https://news.ycombinator.com/item?id=47990675): > [!quote] blcknight, Hacker News, 2 May 2026 > "I am not sure anyone knows what a harness is at this point. I've heard 17 different definitions of it at this point. It's almost like a buzzword in search of a problem." Into that mess walks [Daniel Warfield](https://iaee.substack.com/), who has spent the past few weeks building an open standard called [Agent Harnesses](https://agentharnesses.io/home). Before he can specify a harness he has to say what one is, and that turns out to be the hard part. ## Two definitions, both from reputable sources LangChain's engineering blog puts it as an equation: [agent = model + harness](https://www.langchain.com/blog/how-to-build-a-custom-agent-harness). The harness is the loop, the tool dispatch, the state management. It's the code that turns a text-in-text-out model into something that does things. Anthropic's engineering team uses the word for a layer above that. Their [post on effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) describes an initializer agent plus a coding agent that makes incremental progress each session and leaves artifacts for the next one, all built on the Claude Agent SDK. There, the harness is the structure you wrap around an already-existing agent to point it at one job. Same three syllables, opposite direction. Under LangChain's definition the harness makes the agent; under Anthropic's the agent comes first and the harness aims it. Warfield takes the second, and his reasoning is sound: "agent" already has a definition, and spending a second word on it is wasteful. He lands on: > A harness is information and tools that allow a general purpose agentic system to do specific, complex tasks in a repeatable and maintainable manner. In practice, that means a directory. ## The format A harness is a folder with a `HARNESS.md` at the root and whatever top-level subdirectories the domain calls for. `HARNESS.md` carries `name` and `description` frontmatter plus a deliberately short body, and it gets loaded in full on every activation. The [spec](https://agentharnesses.io/specification) is blunt about why brevity matters: every token in that body competes with task context. Below the root, each top-level directory gets a **routing file** named after it in all caps. `tools/` gets `TOOLS.md`, `data/` gets `DATA.md`, and the name propagates all the way down the subtree, so `tools/database/` also has a `TOOLS.md` rather than a `DATABASE.md`. ``` my-harness/ ├── HARNESS.md ├── .leaf-detectors ├── tools/ │ ├── TOOLS.md │ ├── database/ │ │ ├── TOOLS.md │ │ └── query-database/ │ └── files/ │ └── TOOLS.md └── data/ ├── DATA.md └── schemas/ └── DATA.md ``` A routing file answers exactly one question: should I look in here? The agent reads a branch summary instead of opening every file in it. The termination mechanism is the part I like most. A `.harnessleaf` file marks a directory as a stopping point, and a root-level `.leaf-detectors` file declares patterns that do it automatically, in a one-line-per-rule format: ``` skill=SKILL.md ``` That line means any directory containing a `SKILL.md` is a skill leaf: load and execute it, don't wander into its `scripts/` and `assets/`. There are no built-in patterns, so a harness that bundles [Agent Skills](https://github.com/agentskills/agentskills) has to say so explicitly. Given how much of context engineering is preventing agents from reading things they shouldn't, having a declared boundary beats hoping the model exercises restraint. Getting started is one command. `pip install agentharnesses-cli`, then `ahar init`, which scaffolds `HARNESS.md`, `skills/`, `references/`, and a `.claude/settings.json` that registers the harness as a Claude Code plugin. The default preset also clones a [metaskill](https://github.com/agentharnesses/metaskill) that teaches Claude to explore the harness progressively. Then you tell Claude to load the harness. `ahar validate` and `ahar prompt` handle checking structure and rendering the whole thing as prompt XML. ## The naming problem is real Look at how the word gets used by everyone else. On Hacker News this year: [Zot](https://news.ycombinator.com/item?id=48319524), a coding agent harness. [pu.sh](https://news.ycombinator.com/item?id=47968112), a coding-agent harness in 400 lines of shell. [peerd](https://news.ycombinator.com/item?id=48646165), an agent harness that runs in the browser. Every one of them means the runtime. The [May arXiv paper](https://arxiv.org/abs/2605.15184) asking whether grep is all you need for agentic search is the clearest case. It compares "a custom agent harness (Chronos)" against "provider-native CLI harnesses (Claude Code, Codex, and Gemini CLI)". That's LangChain's definition, in a peer-reviewable venue, treating Claude Code itself as the harness. Its finding is worth sitting with anyway: grep generally beat vector retrieval, and accuracy depended heavily on which harness and tool-calling style was used even when the underlying data was identical. Structure around the model matters. The industry just hasn't settled on what to call it. Meanwhile, when a founder posted about [building agents without harness engineering](https://news.ycombinator.com/item?id=48493447) on 11 June, his own list of what harness engineering covers was "the agent loop, session management, tools, memory, skills, automations, sandboxed deployment, and self-learning." Infrastructure, all of it. A commenter's reply was fair: "effectively they're deferring harness engineering onto another developer?" So Warfield is proposing a spec for the minority reading of a word that a majority uses differently. Agent Skills had it easier, because "skill" was mostly unclaimed when Anthropic shipped the format. ## Worth using anyway Strip the word off and what's left is a small, clear convention for organising the markdown that an agent role needs, with an explicit answer to the question of when to stop reading. The [repo](https://github.com/agentharnesses/agentharnesses) went up on 15 June and Warfield says the concrete isn't dry, which is the right time to argue with it. Two things I'd push on: the routing-file naming rule (deriving the name from the top-level directory rather than the local one is clever, and it will confuse every human who opens the tree), and versioning, currently just a recommendation to use git and pin skills by directory. One caution. A harness is a pile of instructions your agent loads and follows without review, which is the same trust model that makes [prompt injection through ordinary-looking repo content](/posts/ai-agent-security-lethal-trifecta) work. A portable, shareable harness format is a portable, shareable instruction-injection format. Read harnesses you didn't write before you `ahar init` next to them. --- *Sources: [Agent Harnesses standard](https://agentharnesses.io/home) · [Specification](https://agentharnesses.io/specification) · [CLI docs](https://agentharnesses.io/cli) · [Agent Harnesses — Intuitively and Exhaustively Explained (Daniel Warfield, 16 June 2026)](https://iaee.substack.com/p/agent-harnesses-intuitively-and-exhaustively) · [Agent Harnesses with Claude](https://iaee.substack.com/p/agent-harnesses-with-claude-intuitively) · [How to build a custom agent harness (LangChain)](https://www.langchain.com/blog/how-to-build-a-custom-agent-harness) · [Effective harnesses for long-running agents (Anthropic)](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) · [Is grep all you need? (arXiv 2605.15184)](https://arxiv.org/abs/2605.15184) · [HN: The agent harness belongs outside the sandbox](https://news.ycombinator.com/item?id=47990675) · [HN: Building agents without harness engineering](https://news.ycombinator.com/item?id=48493447) · [agentharnesses/agentharnesses on GitHub](https://github.com/agentharnesses/agentharnesses)*