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

# Best Practices

> Recommended approaches for building maintainable, effective harnesses.

# Best Practices

## Keep skills atomic

Each skill should do one thing. Resist the temptation to build a large skill that handles many related tasks — prefer composing several small skills at the harness level instead.

**Instead of:**

```
tools/
└── content/         # drafts posts, generates images, scans social, emails stakeholders
```

**Prefer:**

```
tools/
├── create-blog-post/
├── generate-images/
├── scan-social/
└── email-stakeholders/
```

Atomic skills are easier to test, easier to reuse across harnesses, and easier to update independently.

***

## Put shared context in a dedicated top-level directory

Content that is relevant across multiple skills — style guides, environment details, organizational priorities — belongs in its own top-level directory, not inside any individual skill. This avoids duplication and keeps cross-cutting knowledge in one place.

Choose a directory name that fits your domain: `context/`, `references/`, `environment/`, `brand/` — whatever reflects what the content actually is. Add a routing file named after that directory so the agent can navigate it efficiently.

***

## Keep HARNESS.md as short as possible

`HARNESS.md` is loaded into the agent's context window on every activation. Write the minimum body that lets the agent understand the harness structure and navigate to the right content.

A good body:

* One short paragraph describing the agent's role
* A bulleted list of top-level directories with one-line descriptions
* Pointers to routing files for larger directories

A bad body:

* Repeats information already in routing files or skill documents
* Explains how skills work internally
* Contains lengthy prose that could live in a dedicated document

***

## Structure directories around the agent's domain, not the spec

The spec constrains almost nothing about top-level directory names. Choose names and structure based on how the agent thinks about its work — not on what feels technically correct.

A job search harness might have `leads/`, `materials/`, and `workflow/`. A technical support harness might have `playbooks/`, `environment/`, and `escalations/`. The structure should feel obvious to whoever maintains the harness.

***

## Use subdirectories for large directories

When a top-level directory grows large, group related content into named subdirectories and add a routing file at each level. This keeps the agent from having to scan a long flat list.

See [Organizing Large Harnesses](/harness-creation/organizing-large-harnesses) for the full pattern.

***

## Use termination to protect boundaries

Mark directories that shouldn't be traversed by the harness routing layer:

* Place `.harnessleaf` in directories with large document stores that have their own access skill
* Declare keyword patterns in `.leaf-detectors` to automatically mark directories as leaves based on the files they contain

Without termination, an agent may wander into skill internals or large content stores that are meant to be accessed through a dedicated tool.