Skip to main content

​
Organizing Large Harnesses

As a harness grows, listing every skill and reference directly in HARNESS.md becomes unwieldy. Subdirectories let you group related skills and references together, keeping HARNESS.md short while still giving the agent a clear map of what’s available.

​
Subdirectory Structure

Organize skills/ and references/ into named subdirectories by theme: 
my-harness/
├── HARNESS.md
├── skills/
│   ├── data-access/
│   │   ├── SKILLS.md
│   │   ├── query-database/
│   │   │   ├── SKILL.md
│   │   │   └── scripts/
│   │   └── read-spreadsheet/
│   │       ├── SKILL.md
│   │       └── scripts/
│   └── reporting/
│       ├── SKILLS.md
│       ├── generate-chart/
│       │   ├── SKILL.md
│       │   └── scripts/
│       └── write-summary/
│           ├── SKILL.md
│           └── scripts/
└── references/
    ├── data-sources/
    │   ├── REFERENCES.md
    │   ├── schema-overview.md
    │   ├── table-relationships.md
    │   ├── field-definitions.md
    │   └── known-data-quirks.md
    └── report-standards/
        ├── REFERENCES.md
        ├── formatting-guide.md
        ├── chart-types.md
        ├── color-palette.md
        └── stakeholder-glossary.md

​
SKILLS.md and REFERENCES.md

Adding a summary file to each subdirectory is optional but strongly encouraged. The primary purpose of these files is routing: an agent reading a summary should be able to decide quickly whether the group is relevant to the current task, without opening individual files. SKILLS.md is valuable when a group is large or varied enough that the individual skill descriptions alone don’t paint a clear picture. REFERENCES.md is especially valuable because references vary widely in file type and may not carry a machine-readable description field — without a summary, the agent has little to go on besides filenames. The body is free-form markdown. A brief narrative works well, optionally followed by a list for larger groups: skills/data-access/SKILLS.md 
---
description: Skills for retrieving data from databases and files.
---

Use this group when the task requires reading from the product database or
from uploaded spreadsheets.

- `query-database` — run a read-only SQL query against the product database
- `read-spreadsheet` — read rows and columns from a CSV or Excel file
references/data-sources/REFERENCES.md 
---
description: Reference material about the structure and contents of available data sources.
---

Consult this group before writing any queries or interpreting query results.
It covers the schema, table relationships, field definitions, and known data
quality issues.

- `schema-overview.md` — high-level diagram and description of the database schema
- `table-relationships.md` — foreign key relationships between tables
- `field-definitions.md` — detailed field-level documentation
- `known-data-quirks.md` — known data quality issues and workarounds
With this in place, HARNESS.md stays short: 
**Skills**
- `skills/data-access/` — skills for retrieving data (see `SKILLS.md`)
- `skills/reporting/` — skills for presenting findings (see `SKILLS.md`)

**References**
- `references/data-sources/` — data structure and quality notes (see `REFERENCES.md`)
- `references/report-standards/` — formatting and chart conventions (see `REFERENCES.md`)

​
Nesting

This structure can be nested arbitrarily. Each level of subdirectory gets its own SKILLS.md or REFERENCES.md, allowing the agent to incrementally traverse the hierarchy rather than loading everything at once. 
my-harness/
├── HARNESS.md
├── skills/
│   └── data-access/
│       ├── SKILLS.md
│       ├── databases/
│       │   ├── SKILLS.md
│       │   └── query-postgres/
│       │       └── SKILL.md
│       └── files/
│           ├── SKILLS.md
│           └── read-csv/
│               └── SKILL.md
└── references/
    └── data-sources/
        ├── REFERENCES.md
        ├── relational/
        │   ├── REFERENCES.md
        │   └── schema-overview.md
        └── warehouse/
            ├── REFERENCES.md
            └── dataset-catalog.md
At each level, the agent reads only the summary file to understand what’s available, then drills into subdirectories or individual files only when the task requires it. This is the same progressive disclosure model that governs the harness as a whole.

​
Example

The data-analyst-assistant example demonstrates this pattern with three reference subdirectories and two skill subdirectories.