Introduction
Publishing skills, combining context files into a preamble, generating titles from early user messages, and adopting roles for varied workflows are all on the laundry list of concerns that cut across harnesses; without solutions, making regular use of multiple harnesses is less than seamless, and adapting workflows to changes on the frontier takes extra effort. Serving as a single entry point to all harnesses, a metaharness can make your agents' core configuration portable so that you can always choose the best model for the job.
What follows is a sketch of how my metaharness, agent, works in my software factory
sweatshop;
the ideas are simple enough and my implementation casual enough that I am sharing this
merely as a page from my grimoire, not as software ready to eat—though perhaps
your agent can help you extract some nutriment from the 1,700-line reference
implementation.
One Wrapper to Rule Them All
Instead of calling codex, claude, or pi directly, I call agent. It consults the
environment for a variety of values, e.g.:
- AGENT_BIN=codex
- AGENT_CODEX_MODEL=gpt-6-astra
- AGENT_EFFORT=xhigh
- AGENT_CODEX_FLAGS=--dangerously-bypass-approvals-and-sandbox
If I want to run claude for a one-off while my environment defaults to codex, I run
agent claude. If I need a harness-specific subcommand or flag, agent will pass it
through: agent claude --resume.
agent's core responsibility is preamble composition; skills and roles are implemented via
the preamble, so let's start there.
The Preamble
By preamble, I mean AGENTS.md or CLAUDE.md and other files that get concatenated and
prepended to each session. Upon invocation, agent traverses the list of directories in
its environment's AGENT_PREAMBLE_PATH, concatenating ./AGENTS.md and
./AGENTS.md.d/*.md files found in each directory. By default, it will skip filenames
that start with role-, which can, of course, be included by invoking agent --role <role>. agent then passes the preamble to the concrete harness with whichever flag is
appropriate.
This is the meat of my metaharness; skills and roles are just files that get included.
From Skills to man
Skills are little more than a list of names and short descriptions included in the preamble, behind each of which lies a prompt waiting to be read. Yes, harness-native skills come bristling with extra features (execution isolation! parameter substitution! scripts!), but none of them earn their keep when I weigh them against the portability, simplicity, and flexibility of the Linux manual.
Skills management was in fact the first thing that motivated agent. I was looking to:
- forget about skill format compatibility and availability across harnesses
- install skills directly from repositories or built packages
- have easy access to skills as a human reader
- publish skills and documentation automatically as part of everyday development
The Linux manual is very nearly purpose-built for this problem. Not only can you install
man pages from just about anywhere (MANPATH, of course, is malleable), but you can
also add and name new sections of the manual, and generate a table of contents for any
section with apropos -s <section> ., which serves as a perfect skills preamble.
Since this is not a post about NixOS, I will omit the implementation details, but roughly:
- my agents or I write a skill or reference page in Markdown
- Markdown gets converted to roff via Lowdown
- roff files get installed somewhere on MANPATH
- mandbgets nudged to rebuild its index
- aproposgenerates the tables of contents for- lab-guideand- lab-referencesections
- TOCs get written to a file that is read into the preamble
(/etc/agent/AGENTS.md.d/man-pages.md), along with a note explaining that we're eschewing skills in favor of these man pages
This approach lends itself to solving a second-order problem in skills management, which
is just-in-time discovery, for situations where you have too many skills or reference
pages to load into the preamble: if you write a high-level table of contents into a
section called something like lab-toc with names and descriptions of each sub-section
(e.g., hardware, networking, os-config, application development, etc.), then
agents can use apropos to either search or list all pages in sub-sections as they
encounter related tasks.
Transcripts, Resume, & Usage
There are sundry other items one might want in a metaharness, surely more than I've
mentioned. agent transcripts standardizes access to harness transcripts for a few minor
conveniences, primarily providing an fzf-searchable agent resume command, and tailing
session transcripts to catch early user messages that can be used to auto-title the
windows or tmux sessions in which they live. agent usage prints a summary of usage
limits per provider and their expiration formatted for a status line.
Beyond the Metaharness
agent makes changing harnesses and providers easy enough that I frequently use multiple
within a single workflow. E.g., my kanban system uses astra for authoring and fable
for review. If I hit usage limits on one harness, I edit an environment variable, reload a tmux pane, and am back in action
within a few keystrokes.
While the metaharness is indispensable, lab throughput is more a function of tmux-managed workspaces, workspace filesystem isolation, a speculative merge queue that enables multiple releases to test in parallel, Makefile conventions that keep development and deployment loops hands-free, and a kanban experiment that is moving me away from pair programming and towards product management. It's far from perfect and a work in progress; the underlying mania sometimes has overtones of hamster-on-wheel, but this year has been the most fun I've had building since I learned ActionScript as a teenager.
P.S. Semantic Search
apropos's regex matches only against page titles and short descriptions. I wanted
semantic search over full page contents, so I implemented vapropos, a small wrapper on
a lab-local embedding generation service for searching man pages with vectors. Even
though they have the full table of contents loaded into their preamble, I still see my
agents using it to find the most relevant pages.
If this sounds like the kind of work your team or organization needs, feel free to reach out. I'm currently helping banks modernize their software and infrastructure as a consultant with PwC, and also offer pro bono advisory conversation to good causes.