Agent Harnesses — Intuitively and Exhaustively Explained
A new standard for modern AI agent development
In this article we’ll discuss “Agent Harnesses,” a new standard in AI agent development. Harnesses allow you to build a structure around how AI systems act and think, allowing you to customize those AI systems to do a variety of tasks.
We’ll explore this paradigm by first covering fundamental ideas that harnesses build off of. Once we have a foundational understanding, we’ll discuss the idea of a harness and how one can be implemented.
Who is this useful for? Anyone who wants to learn about modern AI Agent development
How advanced is this post? This article is accessible to readers of all levels
Prerequisites: All prerequisite are covered in the “Building a Fundamental Understanding” section
Contributing: This article proposes a standard for developing agent harnesses, called “Agent Harnesses.” This is an open-source and publicly maintained project. If you’re interested in contributing, check out the contributing guidelines.
Building a Fundamental Understanding
Before we discuss harnesses, let’s cover some of the fundamental ideas harnesses build off of.
Review: LLMs
I have long and in-depth articles discussing LLMs, their various types, and how they function. Feel free to explore these if you’re curious:
For the purposes of this article, you can think of an LLM as a function. You put text in, you get a response out. That’s all they do: respond to text with text. Much of the modern AI technology that’s been coming out recently is built on top of this text response functionality.
Review: Agents
An “agent” is still a broad term. From an academic perspective, there are many types of agents that function fundamentally differently. Here are a few articles where I explore several of those approaches, from newest to oldest.
When you talk to a layman, however, there’s really only one type of agent. It’s a chat AI system that takes your response, does things, then responds. I typically refer to this as a ReAct-style agent, which is essentially some lightweight code that connects an LLM to functionality, allowing the LLM to reason, act, and observe.
When I refer to “Agents” throughout this article, I am referring to ReAct, or “ReAct-esque” agents.
Review: Chain of Thought and Tool Use
To understand ReAct-style agents, it’s critical to understand how they approach “reasoning” and “action”.
Reasoning is typically performed with “chain of thought.” Basically, the idea of chain of thought is to encourage a model to think about its solution before the model outputs an answer. In the original paper that introduced chain of thought, this was done by giving the model an example of how it should answer in the prompt itself.
The example on the left failed with standard prompting, even though the model was exactly the same. From my article on agents. Source
As LLM-powered systems have evolved, this is such a core paradigm that, often, the models are trained to produce a chain of thought implicitly. Normal models have a tendency to think through problems before spitting out an answer, and now “reasoning models”, popularized by DeepSeek, have a specific step where the model thinks through a problem with a very long chain of thought.
Tool use is similar in that it’s been around for a while, has consistently proven useful, and is starting to become standardized. In its most simplistic form, tool use is essentially telling an LLM, “If you output this specific text, I’ll run some code and give you an answer”, allowing the model to decide when it should search the internet, look through your files, transfer all your money to a Nigerian prince, or whatever.
An example of a prompt, and a variety of answers from different prompting strategies. As can be seen, sometimes a combination of chain of thought and action is required to answer complex questions. From my article on agent. source
Review: Skills
As agents, tool use, and prompting have evolved over the last few years, standard practices have emerged as a natural consequence. If you want to get an agent to automate some process, maybe adding some fields to a database, you need to define tools allowing the model to see the database and interact with it. You also need to define prompts that describe to the model what the database looks like, and the tools the agent has access to.
Skills are a standardized way of structuring this information. It allows you to lump information and functionality into a single “skill” so the agent can leverage that information as a complete package.
my-skill/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
├── assets/ # Optional: templates, resources
└── ... # Any additional files or directoriesI covered skills in this article in depth:
In reality, skills are remarkably simple. Most skills are just a bunch of text files. Despite their simplicity, though, skills are incredibly powerful in allowing agents to understand and interact with complex systems, and provide a reusable and portable layer that allows developers working on agents to define robust and reusable plans and procedures.
With that, I think we’ve covered all the essential ideas. Let’s get into it.
The Fundamental Idea of a Harness
Harnesses can be best understood as an extension of skills. Skills allow you to package broad functionality, like modifying a website, database administration, and understanding customer feedback into a single “thing.” However, to do many complicated tasks, like to serve as an assistant to developers working on a product, an AI agent might need to use numerous different skills in tandem. A harness allows you to bunch together various skills, as well as the reference information necessary for the agent to understand its role and the environment it’s operating in.
The Agent Harnesses Standard
A Harness consists of three key parts: a markdown file describing the harness, a set of skills allowing the agent to interact with its environment, and a set of references an agent can use to better understand the environment it’s working in.
my-harness/
├── HARNESS.md # Required: metadata + instructions
├── skills/ # Optional: a set of skills
└── references/ # Optional: a set of reference documentsHARNESS.md describes the harness from a high level. This is designed to be a lightweight document that an agent can use to quickly understand the most fundamental high-level information of the problem it’s working on and to understand where it can find more specific information within skills and references.
This paradigm follows the “progressive disclosure” paradigm, recently popularized by the Agent Skills standard, which encourages an agent to engage in the following:
Discovery: At startup, agents load only
HARNESS.md, which describes the structure of the harness. When a prompt is provided to the agent, the agent compares the prompt to the definitions provided in the harness and incrementally explores the descriptions and names of skills and references in the harness until it finds the necessary material.Activation: When relevant material is discovered, the full documentation on the relevant skills and references are loaded and read by the agent.
Execution: The agent follows information provided in the harness and optionally executes skills.
Let’s dig through each of these components individually so we can understand their rationale.
Defining HARNESS.md
Like skills, the harness employs frontmatter to allow for more efficient exploration of the pertinent assets. Frontmatter allows developers to assign key information at the top of a markdown file, which the agent can use to readily understand
---
name: <name of the harness>
description: <description of what the harness is for>
---
<body>In HARNESS.md, a “name” and “description” are required so that the agent can easily understand what the harness is. The body is a brief markdown file designed to explain key elements of the harness to the agent, allowing it to understand which skills or references it should employ.
Defining the Skills Directory
The skills directory is a directory containing a set of skills following the Agent Skills standard, which defines a skill as the following:
my-skill/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
├── assets/ # Optional: templates, resources
└── ... # Any additional files or directoriesHarnesses extend this functionality. Thus, the skills directory might look like the following:
my-harness/
├── HARNESS.md
├── skills/
| ├── my-skill-1/
| | ├── SKILL.md
| | ├── scripts/
| | ├── references/
| | ├── assets/
| | └── ...
| └── my-skill-2/
| ├── SKILL.md
| ├── scripts/
| ├── references/
| ├── assets/
| └── ...
└── references/Defining the References Directory
The references directory is a set of arbitrary documents that can be used by the agent to better understand its environment, role, or other high-level information.
Skills also have a concept of references. Generally, information in the references directory of the harness should be at a level of abstraction higher than skills. The references within skills should discuss how the specific skill should be employed, while the references at the harness level should describe information that is necessary across numerous skills.
For instance, if you were building an agent designed to assist with the creation of marketing content, you might have a skill for creating blog posts, a skill for generating images, and a skill for scanning social media.
my-mraketing-harness/
├── HARNESS.md
├── skills/
| ├── create-blog-post/
| | ├── SKILL.md
| | └── ...
| ├── generate-images/
| | ├── SKILL.md
| | └── ...
| └── scan-social/
| ├── SKILL.md
| └── ...
└── references/Each of these skills might have references necessary for their function. scan-social might have references pertaining to the social media accounts in the company, generate-images might have references about references describing where images are saved within the company after creation, and create-blog-post might have references about the publication process.
In this context, you might choose to use the harness-level reference directory to create things like style guides and brand priorities that can be used across all of the skills.
my-mraketing-harness/
├── HARNESS.md
├── skills/
| ├── create-blog-post/
| | ├── SKILL.md
| | └── ...
| ├── generate-images/
| | ├── SKILL.md
| | └── ...
| └── scan-social/
| ├── SKILL.md
| └── ...
└── references/
├── style-guide.md
└── brand-priorities.mdThe harness standard allows arbitrary content to be added to the harness-level references directory. However, it’s highly recommended to use markdown files, and to add a high level description to each markdown file so that agents can quickly understand if a particular reference is relevant. style-guide.md, in this example, it might look like the following:
---
description: a style guide for the marketing website, which covers the creation
of all visual assets and standard typography rules
---
<body>
Structuring Large Harnesses
One of the most important aspects of a harness is that it can contain numerous skills and references. With sufficiently large sets of skills and references, maintenance can become confusing, and efficiency around injecting information into the agent can become problematic.
my-harness/
├── HARNESS.md
├── skills/
| ├── skill1/
| ├── skill2/
| ├── skill3/
| └── ...
└── references/
├── reference1
├── reference2
├── reference3
└── ...within both the skills and references directory, sub-directories can be created to organize skills and references into subsets.
my-harness/
├── HARNESS.md
├── skills/
│ ├── software-development/
│ │ ├── SKILLS.md
│ │ ├── skill1/
│ │ │ └── SKILL.md
│ │ └── skill2/
│ │ └── SKILL.md
│ ├── market-analysis/
│ │ ├── SKILLS.md
│ │ └── skill3/
│ │ └── SKILL.md
│ └── social-media/
│ ├── SKILLS.md
│ ├── skill4/
│ │ └── SKILL.md
│ └── skill5/
│ └── SKILL.md
└── references/
├── brand-assets/
│ ├── REFERENCES.md
│ ├── reference1.md
│ └── reference2.md
├── software-infrastructure/
│ ├── REFERENCES.md
│ ├── reference3.md
│ └── reference4.md
└── product-information/
├── REFERENCES.md
└── reference5.mdIn order to allow the agent to fully but succinctly understand this structure, it should be communicated to the agent via HARNESS.md. To aid in exploration, each subdirectory should have a file describing it. SKILLS.md describes the skills within a subdirectory and REFERENCES.md describes the references within a subdirectory.
This structure enables something called “progressive disclosure.” An agent can use HARNESSES.md to understand the high-level structure of the harness, then choose to explore specific SKILLS.md and REFERENCES.md files as necessary to efficiently find relevant material.
Within both Skills and References, the folder structure can be nested arbitrarily, allowing for high-level organization of many skills and references. Each of these subdirectories should contain a SKILLS.md or REFERENCES.md file, allowing the agent to understand the structure within each layer.
...
└── references/
└── data-sources/
├── REFERENCES.md
├── relational/
│ ├── REFERENCES.md
│ └── schema-overview.md
└── warehouse/
├── REFERENCES.md
└── dataset-catalog.mdFurther Reading
I’ll be releasing several articles over the coming days that explore how the “Agent Harnesses” standard can be employed to build both harnesses and clients that can efficiently expose harnesses to an agent. For now, if you’re interested in learning more, check out the official docs.
And the github repo
The agent harness standard also provides several examples of properly defined agent harnesses, which you can explore to better understand the standard.
The progressive disclosure pattern is the right approach. Most agent frameworks fail at scale because they dump everything into context upfront. The harness structure changes the economics -- instead of paying for full context on every call, the agent pulls only what's needed for the current task. That's both cheaper and safer, since smaller context reduces hallucination risk on irrelevant paths.