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

# Organizing Large Harnesses

> How to use top-level directories and routing files to manage harnesses with many skills and documents.

# Organizing Large Harnesses

As a harness grows, listing every skill and document directly in `HARNESS.md` becomes unwieldy. Top-level subdirectories let you group related content together, keeping `HARNESS.md` short while still giving the agent a clear map of what's available.

## Top-Level Directories

Choose top-level directory names that reflect your domain. There are no required names — structure the harness around how the agent actually thinks about its work:

```
data-analyst-harness/
├── HARNESS.md
├── tools/
├── data/
└── outputs/
```

```
marketing-assistant-harness/
├── HARNESS.md
├── skills/
├── brand/
└── campaigns/
```

Each top-level directory establishes a **routing file** — a markdown file named after the directory in all-caps that summarizes and navigates its contents.

## Routing Files

The routing file name is derived from the top-level directory name and propagates throughout the entire subtree. Every subdirectory within `tools/` uses `TOOLS.md`; every subdirectory within `data/` uses `DATA.md`:

```
data-analyst-harness/
├── HARNESS.md
├── .leaf-detectors           ← declares skill=SKILL.md
├── tools/
│   ├── TOOLS.md              ← describes the tools/ branch
│   ├── database/
│   │   ├── TOOLS.md          ← describes this subgroup
│   │   ├── query-database/
│   │   │   └── SKILL.md
│   │   └── write-database/
│   │       └── SKILL.md
│   └── files/
│       ├── TOOLS.md
│       └── read-spreadsheet/
│           └── SKILL.md
└── data/
    ├── DATA.md               ← describes the data/ branch
    ├── schemas/
    │   ├── DATA.md
    │   └── table-definitions.md
    └── quirks/
        ├── DATA.md
        └── known-issues.md
```

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

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

- `database/` — SQL tools for relational databases
- `files/` — readers for spreadsheets and CSVs
```

The primary purpose of a routing file is to answer "should I look here?" — a brief narrative, a list of subdirectory descriptions, or both. It is not a directory listing; it is a routing decision support document. Because it is free-form markdown, it can express nuance: cross-references to other directories, ordering hints, exceptions, or anything else that helps the agent decide quickly without reading every file.

## Routing in HARNESS.md

With routing files in place, `HARNESS.md` points to the top-level directories rather than listing every item individually:

```markdown theme={null}
---
name: Data Analyst Assistant
description: Answers data questions by querying databases, reading files, and generating reports.
---

You are a data analyst assistant.

- `tools/` — capabilities for data retrieval and computation (see TOOLS.md)
- `data/` — schemas, quirks, and context about available data sources (see DATA.md)
- `outputs/` — skills for generating charts, tables, and written reports (see OUTPUTS.md)
```

## Termination

By default an agent may explore any subdirectory. Two mechanisms stop traversal at the right boundary:

* **`.harnessleaf`** — place this file in any directory to mark it as an explicit leaf the agent should not recurse into
* **`.leaf-detectors`** — a file at the harness root that declares keyword patterns; any directory containing the named file is treated as a leaf of the declared type (e.g. `skill=SKILL.md`)

This prevents the agent from wandering into skill internals (`scripts/`, internal `references/`) or large document stores that are meant to be accessed through a dedicated traversal skill.

## Nesting

Subdirectories may be nested arbitrarily. Each level gets its own routing file, allowing the agent to incrementally drill down rather than loading everything at once:

```
tools/
├── TOOLS.md
├── database/
│   ├── TOOLS.md
│   ├── relational/
│   │   ├── TOOLS.md
│   │   └── query-postgres/
│   │       └── SKILL.md
│   └── warehouse/
│       ├── TOOLS.md
│       └── query-bigquery/
│           └── SKILL.md
└── files/
    ├── TOOLS.md
    └── read-csv/
        └── SKILL.md
```

Skill directories in this tree (`query-postgres/`, `query-bigquery/`, `read-csv/`) are treated as leaves because the harness root contains a `.leaf-detectors` file declaring `skill=SKILL.md`. Without that entry, those directories would be traversed as ordinary grouping directories.

At each level the agent reads only the routing file to understand what's available, then drills in only when a task requires it — the same **progressive disclosure** model that governs the harness as a whole.