Skip to main content

​
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:
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:
Routing files use the same frontmatter-plus-body format as HARNESS.md:
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:

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