Agent Harnesses: A Folder Standard for Skills and References

An agent harness is a way of wrapping structure around how an AI system acts and thinks, so that one underlying model can be pointed at many different jobs. The idea builds on a few earlier pieces, so those come first: what an LLM is, what an agent is, how reasoning and tool use fit together, and what skills add. With those in place, the harness itself is a small step, and a simple folder layout is enough to describe one.

The ground floor

Language models as functions

For this purpose an LLM can be treated as a function: text goes in and text comes out. Responding to text with text is all it does, yet most of the recent wave of AI products is assembled on top of that single behavior.

What counts as an agent

Agent remains a broad word. Academic work describes several kinds that operate in fundamentally different ways. In everyday conversation, though, nearly everyone means one thing: a chat system that takes a message, does some work, and replies. That pattern is commonly called ReAct, a thin layer of code connecting a model to functionality so it can reason, act and observe. ReAct lets the model think about what it will do, pick an action that touches the environment, and then read an observation about the result. Everything below uses agent in this ReAct-like sense.

Reasoning and acting

Two ideas sit under that loop. Reasoning is usually handled with chain of thought, which means nudging a model to work through its solution before it commits to an answer. The paper that introduced it did so by putting a worked example inside the prompt, and a question that failed under ordinary prompting succeeded with the very same model once the example was added.

The technique has become so central that many models are now trained to produce a chain of thought on their own. Ordinary models tend to think a problem through before replying, and the reasoning models popularized by DeepSeek have a dedicated stage where the model works through a problem with a very long chain.

Tool use has a similar history: it has been around a while, keeps proving useful, and is turning into a standard. In its simplest form it tells the model that if it emits a particular piece of text, some code will run and the result will come back. The model then decides when to search the web, read through files, or, in the worst case, send money somewhere it should not. Complex questions often need reasoning and action combined, and comparisons of prompting strategies show that mix beating either one alone.

Skills

Practices settle out as agents, tool use and prompting mature. Suppose an agent should add rows to a database. It needs tools that let the model see and touch the database, and it needs prompts that describe the database's shape and the tools on offer.

A skill is a standard way to structure that bundle. Information and functionality get lumped into one unit, so the agent receives it as a complete package. A skill is a folder:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

Most skills are really just text files. Even so, they let an agent understand and operate complex systems, and they give agent developers a reusable, portable layer for plans and procedures.

What a harness is

A harness is best seen as an extension of skills. A skill packages a broad capability such as editing a website, administering a database or making sense of customer feedback. Serious work, like acting as an assistant to the developers of a product, can require many skills used together. A harness bundles several skills along with the reference material the agent needs to grasp its role and the environment it works in.

The Agent Harnesses format

Under this proposed standard, a harness has three parts: a markdown file that describes it, a set of skills for interacting with the environment, and a set of references that help the agent understand where it is working. The standard is an open-source project maintained in public.

my-harness/
├── HARNESS.md        # Required: metadata + instructions
├── skills/           # Optional: a set of skills
└── references/       # Optional: a set of reference documents

The top-level file, HARNESS.md, is meant to be short. It gives the agent a quick high-level picture of the problem and signposts where to find specifics inside skills and references.

The design follows progressive disclosure, a pattern recently popularized by the Agent Skills standard. It unfolds in three phases:

1. Discovery. At startup the agent loads only HARNESS.md, which lays out the harness structure. When a prompt arrives, the agent matches it against those descriptions and gradually walks through the names and descriptions of skills and references until it reaches what it needs.
2. Activation. Once relevant material has been found, the complete documentation for those skills and references is loaded and read.
3. Execution. The agent follows what the harness says and may run skills.

The HARNESS.md file

As with skills, the harness uses frontmatter, key facts placed at the top of a markdown file so the agent can scan assets efficiently.

---
name: <name of the harness>
description: <description of what the harness is for>
---

<body>

A name and a description are mandatory so the agent can tell at once what the harness is. The body is a brief explanation of the main elements, guiding the agent toward the skills and references it should use.

The skills directory

This directory holds skills that follow the Agent Skills standard, which defines one like this:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

A harness builds on that, so the skills directory looks like this:

my-harness/
├── HARNESS.md
├── skills/
|  ├── my-skill-1/
|  |  ├── SKILL.md
|  |  ├── scripts/
|  |  ├── references/
|  |  ├── assets/
|  |  └── ...
|  └── my-skill-2/
|     ├── SKILL.md
|     ├── scripts/
|     ├── references/
|     ├── assets/
|     └── ...
└── references/

The references directory

The references directory contains arbitrary documents that help the agent understand its environment, its role or other high-level context.

Skills also carry references, and the two levels differ in scope. References inside a skill explain how to use that specific skill. References at harness level should hold what several skills need in common, at a higher level of abstraction.

Take an agent built to help produce marketing content. It might have one skill for writing blog posts, one for generating images and one 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 skill can have its own references. The social-scanning skill might list the company's accounts, the image skill might say where finished images are stored, and the blog skill might describe the publishing process. The harness-level references are the natural home for things used across all three, such as style guides and brand priorities:

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.md

Any content may go in the harness-level references directory, but markdown is strongly recommended, with a short description at the top of each file so an agent can judge relevance quickly. A style guide in this example could begin like so:

---
description: a style guide for the marketing website, which covers the creation
of all visual assets and standard typography rules
---

<body>

Organizing a large harness

A harness may contain a great many skills and references. Once the sets get big enough, maintenance turns confusing and feeding information to the agent gets inefficient.

my-harness/
├── HARNESS.md
├── skills/
|  ├── skill1/
|  ├── skill2/
|  ├── skill3/
|  └── ...
└── references/
   ├── reference1
   ├── reference2
   ├── reference3
   └── ...

The answer is sub-directories. Inside both skills and references, folders can group items 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.md

For the agent to grasp this structure fully but economically, HARNESS.md should describe it. Each subdirectory also carries a descriptive file: SKILLS.md covers the skills in a subdirectory and REFERENCES.md covers its references.

This is where progressive disclosure pays off. The agent reads the top-level file to learn the overall shape, then opens specific SKILLS.md and REFERENCES.md files only when needed, which is the efficient route to relevant material.

Nesting can go as deep as the content demands, so a big collection can be organized at a high level. Every subdirectory should hold its own SKILLS.md or REFERENCES.md so the agent understands each layer as it descends:

...
└── references/
  └── data-sources/
      ├── REFERENCES.md
      ├── relational/
      │   ├── REFERENCES.md
      │   └── schema-overview.md
      └── warehouse/
          ├── REFERENCES.md
          └── dataset-catalog.md

Why the layout works

The format asks very little of an author. Everything is a text file in a folder, which means a harness can be versioned, reviewed and shared like any other project. The agent never has to load the entire collection, because each descriptive file is a small signpost that decides whether to go further. A harness for a marketing team and one for a database administrator differ only in their contents, while the discovery, activation and execution flow stays identical.

Two habits keep a harness healthy. First, write each description so it says when the material is relevant and not just what it contains, since the agent chooses what to open from that sentence alone. Second, keep harness-level references truly shared. If a document applies to a single skill, it belongs inside that skill, and promoting it upward only adds noise to every other lookup.