Adapter metadata reference#
An adapter keeps two kinds of declaration apart. .hermit/adapter.yaml is the template’s metadata: it names the
template the adapter comes from, states which files a learner may change, and declares the template’s own checker
and learner tools. exports.yaml, at the adapter root, declares what the adapter exports to an acting agent. The
rules below are the ones hermit.adapter.manifest and hermit.adapter.loader enforce; metadata or exports that
break one do not load, and a candidate whose exports.yaml does not parse fails the specification check.
my_adapter/
.hermit/
adapter.yaml template identity, structure, check, evolver_tools
check.py the template's checker, when it has one
EVOLVER.md the learner's guide; not exported
CARD.md the adapter card, written by the Trainer and `hermit eval`
exports.yaml what the acting agent receives
ADAPTER.md the acting agent's context
... skills, roles, tool code, other content
.hermit/adapter.yaml has four sections and no others:
Section |
Who writes it |
Who reads it |
|---|---|---|
the template author |
everyone: identity and compatibility |
|
the template author |
the Trainer’s specification check; the learner, through |
|
the template author |
the specification check |
|
the template author |
the Evolver’s tool endpoint |
A fifth, serve, is proposed and not yet read by anything; its stdio command,
hermit serve DIR, exists and is what convert writes into a plugin. Paths in the metadata are relative to the
adapter root, so a checker inside .hermit/ is declared as .hermit/check.py:check.
An acting integration reads exports.yaml and the template identity; flatten() returns the exports with
context, id, name and version filled in.
What a learner may change#
By default a learner may change everything in an adapter except .git/ and .hermit/. Every other limit is added
by the template, through structure and its check, or by the Evolver itself. In MWM, for example,
the Evolver protects interface.py and mwm_core/, and the template’s check keeps the wm tool in exports.yaml.
.hermit/ is the same in every adapter of a tree: each carries it byte-for-byte as the tree’s root (the template)
does. The one exception is .hermit/CARD.md, which only the Trainer and hermit eval write; the check compares it
with the parent version instead. Check 1 of the specification check reports any
change, deletion or addition under .hermit/, and repair restores the file from the root (the card from the
parent). Because structure and check are always read from the template root, an adapter cannot loosen its own
limits.
Customizing an adapter#
Most people never write the metadata from scratch: they take a template and change one thing. A run names a
template either by its built-in id (template: prompt-only@1.0) or by a directory holding a
.hermit/adapter.yaml (template: ./my_template), so the way to customize is to copy a template directory, edit
it, and point the run at the copy. The built-in templates are under hermit/adapter/templates/; finished
adapters with their cards are under examples/. What you want to change decides which part you touch:
You want to |
Change |
Where |
|---|---|---|
Different starting instructions, skills or roles |
the learnable files themselves: |
no metadata change; the learner starts from your text |
A new tool for the acting agent |
add its Python to the directory and declare it |
|
Context chosen per task (a retrieval, a lookup) |
a tool declaration the harness calls, not the agent |
|
Let the learner edit more, or less |
the list of learnable paths and their limits (size, file count, frontmatter) |
|
Keep a file exactly as shipped |
list it under |
|
Keep the exports as shipped |
list |
|
Reject candidates by a rule of your own (a lint, a test, a forbidden word) |
a checker function run after the built-in checks |
|
Give the learner a helper during training (a renderer, a validator) that the agent never sees |
a tool declaration under |
|
Change how a learner should edit, not what it may edit |
|
no metadata change |
Two rules hold throughout. When structure lists learnable paths, every file outside .hermit/ must be learnable
or fixed, so adding a file means listing it. And .hermit/ is the template’s: edit it in the template root before
training starts, not in a trained adapter, where the check rejects the change. If the change is an edit to the
acting-side texts only, keep the template’s id and version; if it changes .hermit/adapter.yaml or
exports.yaml, give the copy its own template.id (or a new version) so its tree is not mistaken for the
original’s. Run hermit check --config run.yaml afterwards: it loads the template, the task and the Evolver and
reports what does not fit.
The sections below are the reference for each field.
A minimal .hermit/adapter.yaml:
template:
id: prompt-only
version: "1.0"
structure:
learnable:
- exports.yaml
- path: ADAPTER.md
format: {text: true, max_bytes: 40000}
fixed: [README.md]
The complete example from docs/_examples/file_adapter/.hermit/adapter.yaml:
template:
id: file-example
version: "1.0"
contract: "2"
structure:
learnable:
- exports.yaml
- path: ADAPTER.md
format: {text: true, max_bytes: 4000}
- path: agents/*.md
format: {text: true, max_bytes: 4000, frontmatter: [name, description]}
- path: skills/**
format: {text: true, max_bytes: 4000, max_files: 8}
fixed:
- tools.py
- README.md
template#
Identity of the template this adapter belongs to. Required.
Key |
Required |
Rule |
|---|---|---|
|
yes |
lowercase slug: |
|
yes |
nonempty string. With |
|
no |
display name; defaults to |
|
no |
the metadata contract this file follows; |
structure#
The specification: which files a learner may change, in what form, and which must stay as the template ships
them. Optional: without it, every file outside .hermit/ is learnable.
structure:
learnable:
- exports.yaml # a bare path: any content
- ADAPTER.md
- path: agents/*.md
format: {text: true, max_bytes: 4000, frontmatter: [name, description]}
- path: skills/**
format: {text: true, max_bytes: 4000, max_files: 8}
fixed:
- tools.py
- README.md
learnable: a list of entries, each a path or {path, format}. path is a glob relative to the adapter
root: * matches within one path segment, ** across segments, and a directory name covers everything below it.
A file may be changed, added or deleted only if it matches a learnable path and no fixed path.
Format key |
Meaning |
|---|---|
|
the file must decode as UTF-8 |
|
size limit per file |
|
at most N files may match this entry |
|
the file starts with YAML frontmatter carrying these keys (implies text) |
fixed: paths (files or directories) that must exist exactly as in the template root; changing, deleting or
adding a file under one fails the check. .hermit/ is always fixed and needs no entry.
When structure is present, every file outside .hermit/ must be either fixed or covered by a learnable entry;
exports.yaml is the exception, learnable unless fixed lists it. A file outside both is a check failure, and the
Trainer removes it when it repairs a candidate. See How does the specification limit
edits?.
check#
check: .hermit/check.py:check
Optional. A template’s own checker, file.py:function with the path relative to the adapter root, loaded from the
template root (not the candidate) and run after the built-in checks: check(adapter_path) -> list[dict], each
issue {path, problem}; a nonempty list rejects the candidate. It runs in a subprocess, 120 seconds, network isolated when bubblewrap is available. See
Specification check.
evolver_tools#
evolver_tools:
- name: render
description: Render the context the way the host will see it.
entrypoint: .hermit/preview.py:render
input_schema: {type: object, additionalProperties: false}
output_schema: {type: object}
Optional. Tools the learner gets during training, in the same form as a tool declaration,
with the entrypoint resolved against the template root. They join check_spec (always present), the task’s
evolver_access.tools and the run’s budget / llm on the Evolver’s tool endpoint; they are never exported to
the acting agent.
plugin-portable#
plugin-portable: false
Optional, true or false; without it, true. Whether the template’s adapters can leave hermit: false makes
hermit deploy (a host workspace) and hermit convert (a plugin) refuse them, with the reason, before writing
anything, so that an adapter that works only through hermit (training, evaluation, a Session) is never installed
without the part that needs hermit. A template whose adapters declare a context tool must set
it to false: such an adapter does not load otherwise. The reharness template does.
Exports#
exports.yaml at the adapter root: what the acting agent receives, as a top-level mapping. Optional: an adapter
without it, or with an empty one, exports its context only. It is ordinary adapter content, learnable unless the
template’s structure lists it under fixed, whether or not a learnable entry names it; check 3 of the specification
check requires it to parse, and repair restores it from the parent.
Key |
Value |
Rule |
|---|---|---|
|
|
optional and fixed: the context is always the file |
|
list of tool declarations |
names unique; each tool’s code lives inside the adapter |
|
a directory, or |
roles (subagents). A directory holds one Markdown file per role, |
|
a directory |
skill folders copied to the host as they are ( |
|
a JSON file |
lifecycle hooks in Claude Code’s hook schema, |
|
|
service integration only: a function the framework service calls on events; |
|
boolean |
service integration only: run the adapter’s tool calls concurrently instead of one at a time |
|
list of paths or globs (a directory covers its files) |
the harness’s own files: what a context tool or a tool reads and the agent never receives; a deployment neither copies nor names them. May not cover |
|
the name of one declared tool |
per-task context: the harness calls that tool once per task with |
All paths are relative to the adapter root and must stay inside it.
Only declared exports are connected to the host: an adapter without exports.yaml deploys as an instruction file
and a copy of its files under hermit/<id>/, which the instruction file names. How each export reaches Codex or Claude Code is in
Acting interface. The example’s exports.yaml:
agents: agents
skills: skills
tools:
- name: count_words
description: Count whitespace-separated words in text.
entrypoint: tools.py:count_words
input_schema:
type: object
properties:
text: {type: string}
required: [text]
additionalProperties: false
output_schema:
type: object
properties:
count: {type: integer}
required: [count]
additionalProperties: false
Tool declaration#
- name: count_words
description: Count whitespace-separated words in text.
entrypoint: tools.py:count_words
input_schema:
type: object
properties: {text: {type: string}}
required: [text]
additionalProperties: false
output_schema:
type: object
properties: {count: {type: integer}}
required: [count]
annotations: {readOnlyHint: true}
Key |
Required |
Rule |
|---|---|---|
|
yes |
|
|
yes |
nonempty; shown to the agent as the tool’s description |
|
yes |
|
|
yes |
a JSON Schema object ( |
|
yes |
a JSON Schema object; the result is validated against it |
|
no |
MCP tool annotations passed through to the host ( |
Schemas may use local $refs only; remote and dynamic references are rejected. A tool function may declare a
reserved _resources parameter to receive framework bindings (the evidence store, deployment settings) from a
pipeline that supplies them; the agent cannot pass it.
Per-task context#
# exports.yaml
tools:
- name: reflections
description: The top-k reflections of the bank for an instance's input.
entrypoint: interface.py:reflections
input_schema:
type: object
properties: {query: {type: string}, task: {type: object}}
additionalProperties: false
output_schema:
type: object
properties: {text: {type: string}}
required: [text]
context_tool: reflections
context_tool names one of the declared tools as the harness’s. The harness, not the agent, calls it once per
task, before the agent’s first model call, with query (the task’s input text) and task (its row), and appends
the text of the result below ADAPTER.md for that task. Session.context(query=..., task=...) makes the call
and keeps the whole result in session.last_context; the built-in react agent does both and records the result as
RunOutput.extra["context_tool"], and so do the built-in codex and claude-code agents, which deploy this task’s
context into the session’s AGENTS.md or CLAUDE.md. The tool is left out of Session.tools, tool_specs and the hosts’ tool
servers, and respond refuses it: the agent cannot call it. A manifest that names an undeclared tool does not load.
The specification check’s load check (check 5) calls the tool once with an empty query and an empty task, in a
run’s sandbox (strict, without network or keys, when the sandbox is on; unconfined when sandbox.enabled is false), so the tool must answer that call without an endpoint (with no query there is
nothing to retrieve) and return an object with a text string. A host workspace or plugin has no per-task context,
so an adapter that names a context tool loads only when its template declares
plugin-portable: false, and deploy and convert refuse it. The reharness template retrieves reflections this way
(ReHarness).
Internal#
# exports.yaml
internal: [reflections/, index.json, interface.py, reharness_core/]
Some files of an adapter are the harness’s, not the agent’s: the reflection bank a context tool retrieves from, the
code behind it. internal lists them. A deployment copies every other file into the workspace and names it in the
context, so that nothing reaches the agent by surprise and nothing it should have is missing; an internal file is
neither copied nor named, and reaches the agent only through what the harness renders from it (the retrieved
reflections). Tools still run from the adapter itself, so their code may be internal. The reharness template marks
its bank and its retrieval this way; a learner may not change it there (exports.yaml is fixed). An internal that
covers a file an export copies (a skill’s, a role’s, the hooks file) does not load: the host would receive it anyway.
serve (design, not implemented)#
.hermit/adapter.yaml does not accept a serve section. The implemented hermit serve DIR command starts a
per-session stdio MCP tool server, normally launched by a generated host entry. Generic standalone startup,
health checks, discovery, and relay lifecycle remain a design proposal.
Do not add the proposed fields or flags to a working configuration.
Migrating from Hermit 0.1#
In Hermit 0.1 the metadata and the exports were one file, adapter.yaml, at the adapter root; Hermit now refuses
that layout and names it. To migrate an adapter or a template, in its directory:
mkdir .hermit
git mv adapter.yaml .hermit/adapter.yaml
git mv EVOLVER.md .hermit/EVOLVER.md # each of these three only if present
git mv CARD.md .hermit/CARD.md
git mv check.py .hermit/check.py
Then edit .hermit/adapter.yaml: move the exports section into a new exports.yaml at the root (its contents
become the file’s top level), delete the origin section, and point check to .hermit/check.py. A template that
lists adapter.yaml, EVOLVER.md or check.py under fixed drops those entries: .hermit/ is always fixed. Every
adapter of a tree must carry the template’s .hermit/ byte for byte, so migrate the template and its adapters
together, and rebuild plugins made by hermit convert from the migrated adapter.
What is not in the metadata or the exports#
The content format of
ADAPTER.md. Beyondstructure’s size and text rules, the context is free text; no frontmatter or sections are required or interpreted.Dependencies. A tool’s imports must be importable where the adapter runs;
README.mdis the place to say what they are.Learner guidance.
.hermit/EVOLVER.mdtells the learner how to edit withinstructure; it is not exported.Run settings. Budgets, sandbox, data and the Evolver are in
run.yaml; see Configuration.