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

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

---
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:

---
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:

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

Nested Harnesses

A directory anywhere within a harness may itself contain a HARNESS.md. This makes it a nested harness — the root of its own independent tree — and it requires the same frontmatter (name and description) as a top-level HARNESS.md. A nested HARNESS.md resets routing-file propagation for what lies beneath it: each of its own direct child directories becomes a fresh top-level directory in its own right, exactly as top-level directories do beneath the true harness root. Propagation then continues unchanged from there until the next nested HARNESS.md is encountered.

my-harness/
├── HARNESS.md
└── skills/
    ├── SKILLS.md
    └── plugin-x/
        ├── HARNESS.md          ← nested harness; resets propagation below here
        └── tools/
            ├── TOOLS.md        ← fresh top-level directory: tools/ itself
            └── query-db/
                └── SKILL.md

skills/plugin-x/tools/’s routing file is TOOLS.md, not SKILLS.md — even though plugin-x/ itself is still addressed via the SKILLS.md top-level directory it inherited from its parent (a nested HARNESS.md resets the top-level directory for a directory’s children, not for the directory itself). .leaf-detectors is unaffected by nested-harness boundaries: the nearest ancestor config still applies regardless of nesting.

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.

For harness creators

For client implementors

Specification

Specification

Overview

HARNESS.md

Frontmatter

Body

Example

Top-Level Directories

Routing Files

Routing File Format

Nested Harnesses

Termination

`.harnessleaf`

`.leaf-detectors`

Loading Model

Versioning

​Specification

​Overview

​HARNESS.md

​Frontmatter

​Body

​Example

​Top-Level Directories

​Routing Files

​Routing File Format

​Nested Harnesses

​Termination

​.harnessleaf

​.leaf-detectors

​Loading Model

​Versioning

Specification

Overview

HARNESS.md

Frontmatter

Body

Example

Top-Level Directories

Routing Files

Routing File Format

Nested Harnesses

Termination

`.harnessleaf`

`.leaf-detectors`

Loading Model

Versioning