Specification

Overview

A harness is a directory that gives an AI agent everything it needs to fulfill a role. It consists of three components:

Component	Required	Purpose
`HARNESS.md`	Yes	Identity, description, and structural overview
`skills/`	No	Atomic capabilities following the Agent Skills standard
`references/`	No	Cross-cutting documentation that applies across skills

my-harness/
├── HARNESS.md
├── skills/
│   └── my-skill/
│       └── SKILL.md
└── references/
    └── style-guide.md

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. It must give the agent enough information to:

Understand the scope and purpose of the harness
Know which skills exist and when to use each one
Know which references exist and when to consult them

The body should be as brief as possible while remaining complete. It is loaded into the agent’s context window on activation and competes with other 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 skills with one-line descriptions
A bulleted index of references with one-line descriptions

Example

---
name: Marketing Assistant
description: Helps create and review marketing content across blog, social, and visual channels.
---

You are a marketing assistant. Use the skills and references below to produce
content that is on-brand, consistent, and appropriate for each channel.

**Skills**
- `create-blog-post` — draft and edit long-form blog articles
- `generate-images` — produce image prompts and review generated visuals
- `scan-social` — search and summarize recent social media activity

**References**
- `style-guide.md` — typography, tone, and formatting rules for all content
- `brand-priorities.md` — current campaign priorities and brand voice guidelines

Skills Directory

The skills/ directory contains one subdirectory per skill. Each skill follows the Agent Skills standard exactly:

skills/
└── my-skill/
    ├── SKILL.md          # Required: metadata + instructions
    ├── scripts/          # Optional: executable code
    ├── references/       # Optional: skill-specific documentation
    └── assets/           # Optional: templates, resources

Skills in a harness may be organized into subdirectories when the number of skills is large enough that a flat list becomes difficult to navigate. Each grouping subdirectory may include a SKILLS.md file that summarizes its contents — this is optional but strongly encouraged:

skills/
├── content-creation/
│   ├── SKILLS.md         # Optional but recommended: index of skills within
│   ├── create-blog-post/
│   └── generate-images/
└── research/
    ├── SKILLS.md
    └── scan-social/

SKILLS.md

The primary purpose of SKILLS.md is to support routing: an agent reading it should be able to decide quickly whether any skill in this group is relevant to the current task, without opening individual skill files. For small groups this file may be unnecessary — the skill description fields alone are often sufficient. For larger or more varied groups, a well-written SKILLS.md is the difference between efficient discovery and loading every skill to find the right one. SKILLS.md uses the same frontmatter-plus-body format as HARNESS.md. The description field gives a one-line characterization of the group as a whole. The body is free-form markdown — a brief narrative, a list, or a combination — written to answer “should I look here?” rather than to enumerate contents exhaustively:

---
description: Skills for creating written and visual content.
---

These skills cover the full content production pipeline, from drafting long-form
articles to generating and reviewing images. Use this group when the task involves
producing any kind of publishable asset.

- `create-blog-post` — draft and edit long-form blog articles
- `generate-images` — produce image prompts and review generated visuals

With SKILLS.md in place, HARNESS.md can reference the group summary rather than listing every skill individually, keeping the entry point short as the harness grows. Grouping subdirectories may be nested arbitrarily; each level gets its own SKILLS.md.

References Directory

The references/ directory contains markdown documents that provide cross-skill context — information that is relevant to more than one skill or that describes the agent’s environment at a higher level of abstraction than any individual skill. Typical reference content:

Brand guidelines and style guides
Organizational priorities or constraints
Infrastructure overviews and environment details
Personas, audiences, or stakeholder maps

Reference File Format

Reference files may be any file type. Markdown is the recommended format — it is human-readable, broadly supported, and allows a description frontmatter field that agents can use to evaluate relevance during the Discovery phase without reading the full file:

---
description: <one-line summary of what this document covers>
---

<body>

Organization

Like the skills directory, references may be organized into subdirectories. Each grouping subdirectory may include a REFERENCES.md file that summarizes its contents — this is optional but strongly encouraged:

references/
├── brand/
│   ├── REFERENCES.md     # Optional but recommended: index of references within
│   ├── style-guide.md
│   └── voice-guidelines.md
└── infrastructure/
    ├── REFERENCES.md
    ├── database-overview.md
    └── api-inventory.md

REFERENCES.md

The primary purpose of REFERENCES.md is to support routing: an agent reading it should be able to decide quickly whether any document in this group is relevant to the current task. This is particularly important for references because they vary widely in file type and may not carry a machine-readable description field — without a summary file, the agent has little to go on besides filenames. REFERENCES.md follows the same frontmatter-plus-body format as individual reference files. The description field characterizes the group as a whole. The body is free-form markdown written to answer “should I look here?”:

---
description: Brand guidelines governing tone, typography, and visual style.
---

These documents define how all published content should look and sound. Consult
this group whenever the task involves producing or reviewing content that will
be seen externally.

- `style-guide.md` — typography, tone, and formatting rules for all content
- `voice-guidelines.md` — brand voice principles and examples

HARNESS.md can then point to the group summary instead of each file individually. Grouping subdirectories may be nested arbitrarily; each level gets its own REFERENCES.md.

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 and constraints
Discovery	Task received	Agent reads `SKILLS.md` / `REFERENCES.md` group summaries to find relevant capabilities
Activation	Description aligns with task	Agent reads the full content of a relevant skill or reference
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 group summaries to understand what is available, then loading individual skills and references only when a task requires them. This model allows a harness to contain dozens of skills and references 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.

​Specification

​Overview

​HARNESS.md

​Frontmatter

​Body

​Example

​Skills Directory

​SKILLS.md

​References Directory

​Reference File Format

​Organization

​REFERENCES.md

​Loading Model

​Versioning