> ## Documentation Index
> Fetch the complete documentation index at: https://agentharnesses.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Specification

> The complete Agent Harnesses format specification.

# Specification

## Overview

A harness is a directory that gives an AI agent everything it needs to fulfill a role. It contains a required `HARNESS.md` file, an optional `.leaf-detectors` configuration file, and any number of top-level subdirectories the domain requires:

```
my-harness/
├── HARNESS.md
├── .leaf-detectors         # e.g. skill=SKILL.md
├── tools/
│   └── query-db/
│       └── SKILL.md
├── brand/
│   └── style-guide.md
└── data/
    └── schema.md
```

The subdirectory names are chosen by the harness author to reflect the agent's domain. There are no required directory names beyond `HARNESS.md` itself.

***

## HARNESS.md

`HARNESS.md` is the required entry point for every harness. It uses YAML frontmatter followed by a markdown body.

### Frontmatter

```yaml theme={null}
---
name: <name>
description: <one-line description>
---
```

| Field         | Required | Description                                                      |
| ------------- | -------- | ---------------------------------------------------------------- |
| `name`        | Yes      | Short human-readable name for the harness                        |
| `description` | Yes      | One sentence describing what this harness enables an agent to do |

### Body

The body is free-form markdown. Its primary purpose is **routing**: an agent reading `HARNESS.md` should be able to decide which subdirectories to explore for a given task without opening anything else first.

The body should be **as brief as possible**. It is loaded into the agent's context window on every activation — every token competes with task context. Avoid prose that restates the frontmatter description or explains concepts the agent already knows.

A well-structured body typically includes:

* A one-paragraph summary of the agent's role
* A bulleted index of top-level directories with one-line descriptions
* References to routing files within those directories for larger harnesses

**Avoid over-indexing.** The more routing information the body contains, the more the agent must read before acting. Start with a minimal body and add detail only where routing demonstrably fails — not preemptively.

### Example

```markdown theme={null}
---
name: Marketing Assistant
description: Helps create and review marketing content across blog, social, and visual channels.
---

You are a marketing assistant. Produce content that is on-brand, consistent,
and appropriate for each channel.

- `tools/` — capabilities for content creation and research (see TOOLS.md)
- `brand/` — tone, typography, and visual guidelines (see BRAND.md)
- `campaigns/` — active campaign briefs and goals (see CAMPAIGNS.md)
```

***

## Top-Level Directories

The harness root may contain any number of top-level subdirectories. Each one organizes content relevant to the agent's domain — capabilities, reference material, data, outputs, environment details, or anything else the harness author needs.

### Routing Files

Each top-level directory establishes a **routing file** — a named markdown file used to summarize and navigate the contents of that directory and its descendants. The routing file is named after the top-level directory in all-caps with a `.md` extension:

| Top-level directory | Routing file    |
| ------------------- | --------------- |
| `skills/`           | `SKILLS.md`     |
| `references/`       | `REFERENCES.md` |
| `tools/`            | `TOOLS.md`      |
| `data/`             | `DATA.md`       |
| `outputs/`          | `OUTPUTS.md`    |

The routing file name is derived from the **top-level** directory and propagates throughout the entire subtree. Every grouping subdirectory within `tools/` uses `TOOLS.md` — not a name derived from the subdirectory itself:

```
tools/
├── TOOLS.md
├── database/
│   ├── TOOLS.md
│   └── query-database/
│       └── instructions.md
└── files/
    ├── TOOLS.md
    └── read-spreadsheet/
        └── instructions.md
```

### Routing File Format

Routing files use the same frontmatter-plus-body format as `HARNESS.md`:

```markdown theme={null}
---
description: <one-line summary of the contents of this directory>
---

<body>
```

The `description` field characterizes the directory as a whole. The body is free-form markdown written to answer "should I look here?" — a brief narrative, a list of subdirectory descriptions, or both:

```markdown theme={null}
---
description: Tools for querying databases and reading structured files.
---

Use this group when the task involves retrieving or manipulating data from
any external source. Subdirectories are organized by source type.

- `database/` — SQL query tools for relational databases
- `files/` — readers for spreadsheets, CSVs, and JSON
- `compute/` — Python and SQL execution environments
```

Routing files are optional at any level — for small directories, filenames and `description` frontmatter fields in individual files are often sufficient. For larger or more varied groups, a well-written routing file is the difference between efficient discovery and exhaustive scanning.

Subdirectories may be nested arbitrarily, with each grouping level getting its own routing file.

***

## Termination

By default an agent traversing a harness may explore any subdirectory. Two mechanisms mark a directory as a **leaf** — a terminal point beyond which the harness routing logic does not recurse:

### `.harnessleaf`

A file named `.harnessleaf` placed in a directory signals an explicit termination boundary. The agent treats the directory as a unit to be read or invoked rather than a branch to explore further.

### `.leaf-detectors`

`.leaf-detectors` is an optional file at the harness root that defines **keyword patterns** — rules that automatically mark a directory as a leaf when it contains a specific file. It uses a simple line-based format:

```
# Lines beginning with # are comments.
# Format: leaf_type=relative_path
# A directory containing the specified path is treated as a leaf of that type.
skill=SKILL.md
```

Each line declares that any directory containing the named file is a leaf of the given type. There are no built-in patterns — all detection is explicit. A harness that contains Agent Skills should declare `skill=SKILL.md`; without that entry, directories containing `SKILL.md` are traversed rather than treated as skill leaves.

Leaf type names are meaningful: clients and tools use them to decide how to handle the leaf. A `skill` leaf is loaded and executed as an Agent Skill. Other types are treated as opaque boundaries — traversal stops, and the agent is expected to access the directory through a dedicated skill or tool.

Termination gives the harness a well-defined boundary. It prevents the routing layer from recursing into skill internals (`scripts/`, internal `references/`, `assets/`) and into large content stores that are meant to be accessed through a purpose-built traversal skill.

***

## Loading Model

Harnesses use **progressive disclosure** — agents load only what each task requires.

| Phase          | Trigger                  | Interaction with the harness                                                   |
| -------------- | ------------------------ | ------------------------------------------------------------------------------ |
| **Load**       | Session start            | Full `HARNESS.md` body is injected into context, establishing the agent's role |
| **Discovery**  | Task received            | Agent reads routing files to find relevant subdirectories                      |
| **Activation** | Routing aligns with task | Agent reads the full content of a relevant skill, directory, or file           |
| **Execution**  | Action required          | Agent runs a script bundled within a skill                                     |

`HARNESS.md` is the agent's map of the harness. From there the agent navigates progressively — reading routing files to decide which branch is relevant, then loading individual files only when a task requires them. This model allows a harness to contain dozens of capabilities and reference documents without consuming the full context window on every interaction.

***

## Versioning

Harnesses do not define a required versioning scheme. It is recommended to version harnesses using standard version control (git) and to pin skill dependencies by directory rather than by registry reference.