Towards Self-Repairing and Repeatable AI Systems

Recent Progress in the Agent Harnesses Standard

“Roles” by Daniel Warfield using Midjourney. All images by the author unless otherwise specified. Brought to you by the subscribers of Intuitively and Exhaustively Explained.

I’ve been working on the Agent Harnesses Standard for a few months, and have been using it to automate key tasks within my workflow. I’d like to share how I use it, the tools I’ve built around it, their features, and the practical impact of approaching agentic role definitions in a standardized way.

---

---

The Goal of The Agent Harnesses Standard

Fundamentally, the idea is to standardize how information is organized throughout a folder hierarchy to make information easily discoverable by AI systems like Claude. As the project matures, that goal is beginning to crystalize into a set of subgoals:

• People work with agents to satisfy several tasks throughout the day. Often, agents get confused when they need to reconcile with multiple roles simultaneously. One goal of the agent harnesses standard is to make the creation, maintenance, and isolation of these roles easier and more intuitive.

• When an agent is designed to handle a complex role with multiple responsibilities, the context and tools necessary to fulfill that role can become numerous. This can lead to confusion as critical tools being misused. Another goal of the agent harnesses standard is to allow for greater organization of context and tools.

• Regardless of the organisational patterns of information, it’s useless if an agent can’t find that information efficiently. Another goal of the agent harnesses standard is to structure the context and information necessary to satisfy a role in a way that can be effectively, efficiently, and inexpensively understood by AI systems.

• Agentic systems can quickly deviate from human understanding if left to update themselves. A goal of the agent harnesses standard is to encourage AI systems to follow a structure that a human can readily understand, edit, adjust, and converse with an agent about, preserving human comprehension.

I don’t think any of these are solved problems, but the Agent Harnesses Standard has been a useful construct in allowing me to iterate on these problems and wrangle them significantly more easily. I’d like to briefly describe the standard, then describe some of the tools I’ve built to accelerate workflows around it.

The Standard in a Nutshell

The Agent Harnesses Standard is, in its essence, an extension of the skills standard.

If you’re familiar with the skills standard, it boils down to having a single markdown file, called SKILL.md, which describes context and tools the agent can use to do stuff. You might have a directory called send-email that contains a SKILL.md file describing the skill, and some code the agent can execute to send the email.

send-email/
├── SKILL.md
└── scripts/
     └── send_email.py

The actual SKILL.md file has information about all of the scripts and references in the send-email directory, allowing an agent to read a markdown file to get a gist of how to use the resources within the skill, rather than needing to read all the files and understand the code for itself. This saves time, and makes execution of the skill more consistent. If you want to know more about the specifics, I have a whole article on the subject.

Agent Skills — Intuitively and Exhaustively Explained

This standard is simple, but it’s great. It’s great because it allows for a few key things:

• Efficient abstraction of large batches of information, allowing an AI model to quickly understand sophisticated functionality.

• A single entry point. You know the agent will look at SKILL.md before doing other stuff with the skill, so you can introduce critical prompting information just in time, rather than trying to get the agent to understand everything about a whole project in a system prompt.

• A shared standard. Skills aren’t model or provider specific, a skill defined for one agent will likely work for another, as the skill standard is ubiquitously adopted.

However, skills aren’t perfect.

Claude, for instance, organizes skills into a flat directory structure. This is fine if you only have a handful of skills, but if you have many skills, or if skills are meant to exist in some type of sequential workflow, it can be cumbersome to try to get the model to consistently execute on high-level tasks consistently. You might have skills for send-email, look-up-user-preferences , and view-purchasing-history, but if you want the model to execute those skills in a particular way, like looking up the user and viewing their purchasing history before sending an email, there’s no standard way of defining that intention. The Agent Harnesses Standard attempts to solve that problem via a hierarchical organizational structure.

The Agent Harnesses Standard allows you to specify skills within a hierarchical structure, and to create key routing documents to describe to an agent how information should be used. For instance, we could have the following structure

email-client/
├── EMAIL-CLIENT.md
├── send-email/
├── look-up-user-preferences/
└── view-purchasing-history/

Where send-email, look-up-user-preferences, and view-purchasing-history are all skill folders with their own SKILL.md file. The EMAIL-CLIENT.md file is from the Agent Harnesses Standard, and it’s called a “routing file”. It serves as an entry point, allowing the agent to understand how these skills should be used within the context of emailing a client.

These organizations can take on high-order structures. Say you also need to call or send physical mail to a customer. Those could be their own directory each with routing files allowing the AI system to quickly understand how and when these high level functionalities, and their respective skills, should be used.

interactin-skills/
├── INTERACTION-SKILLS.md
├── email-client/
|   ├── INTERACTION-SKILLS.md
|   ├── send-email/
|   ├── look-up-user-preferences/
|   └── view-purchasing-history/
├── call-client/
|   ├── INTERACTION-SKILLS.md
|   ├── send-call/
|   └── look-up-number/
└── mail-client/
    ├── INTERACTION-SKILLS.md
    ├── send-mail/
    └── look-up-address/

Exactly how you organize a harness is up to you, and should be designed as a function of the project you’re working on and what you want an agent like Claude to do within that project.

You might notice that each of the skills has an INTERACTION-SKILLS.md. To make routing decisions more obvious to both agents and humans, each routing file within a subdirectory inherits the name of the top-level subdirectory. All the routing files in interactin-skills/ are INTERACTION-SKILLS.md . Here’s a more complex example from the agent harnesses docs that has two top level subdirectories.

my-harness/
├── HARNESS.md
├── tools/
│   ├── TOOLS.md
│   ├── backend/
│   │   ├── TOOLS.md        
│   │   └── create-api/
│   └── frontend/
│       ├── TOOLS.md
│       └── build-ui/
└── data/
    ├── DATA.md             
    ├── schemas/
    │   ├── DATA.md
    │   └── table-definitions.md
    └── quirks/
        ├── DATA.md
        └── known-issues.md

At the very top of the harness there’s a HARNESS.md file, which serves as the entry point to the entire harness. Like how SKILL.md is the single entry point into a skill, HARNESS.md is the single entry point into a harness, and can provide top-level routing information, allowing an agent to navigate through the harness from a particular starting point.

Since defining the structure of the agent harnesses standard, I’ve been refining tools to allow Claude to efficiently interact with an manage this structure. I want to talk about those tools, and how I work with them, next.

Tools and Workflow

One of the biggest quality of life changes I’ve made recently is a tool called ahar, which allows one to initialize repos that follow the agent harnesses standard. It’s pip installable via the following:

pip install agentharnesses-cli

This installs ahar which can be used to do all sorts of stuff. Chiefly, initialize an agent harnesses standard directory.

ahar init

Currently, this creates the following structure. This can be modified based on the nature of your project, the agent harnesses standard is agnostic to folder names, though I’ve found that having a skills/ and references/ directory along with HARNESS.md has worked well for me.

my-harness/
├── HARNESS.md                       # entry point and agent identity
├── README.md                        # human-facing description
├── .gitignore
├── .claude/settings.json            # registers the harness as a Claude Code plugin
├── skills/
│   └── SKILLS.md                    # skill index
└── references/
    └── REFERENCES.md                # reference index

If you type in claude in the configuration, it will also create the “agent harnesses metaskill”, which is a skill that claude can use to interact with the harness.

├── .claude/skills/agent-harnesses/  # metaskill for progressive harness exploration
└── skills/
    └── maintenance/
        ├── SKILLS.md
        └── modify-harness/
            └── SKILL.md

Pretty much any time I start a new repo any more I

• git initialize

• call ahar init and specify claude

• then run claude in the command line.

When claude is running, I just tell it load harness and it loads the metaskill, observes that the harness is empty, and asks if I want to do anything. I then tell it what I’m working on, and it begins building out the structure of the project for me.

Because Claude knows about the agent harnesses standard through the metaskill, it understands the intent behind the routing files, and has tools to programatically interact with them. This allows Claude to do things like:

• Create an efficient summary of the entire structure of the project in a single command line argument (using the metaskill), allowing claude to quickly understand an entire project at a glance.

• Trace references of functionality throughout the hierarchy of a project, and adjust that referencing based on user feedback, allowing for modifications that remain discoverable across sessions, improving consistency.

• Organize and structure information hierarchically, meaning I can let Claude make substantial changes, and the results tend to be both reasonable and easily understandable by me.

I’ve been rather impressed with Claud’s ability to do this. It works nicely with the standard, and I find that it can create well thought out organizational systems efficiently. This lets me spool up multiple sub-agents, update prompting information, and cache key information in these routing documents so that Claude behaves more consistently across different sessions. I think the biggest benefit is the hierarchical caching of key prompting information, which allows the system to achieves the “Self-Repairing and Repeatable” qualities referenced in the title.

Conclusion

I’ve been enjoying the Agent Harnesses Standard. Regardless of if it sees widespread adoption, it’s been a significant boost to my productivity, and I’ll continue working on it. Check it out if it interests you.