Authoring overlays¶
Package layout¶
Keep each overlay in its own directory, and refer to its files with relative paths. Put files where a consumer looks for them, and they work with no manifest:
| Put | And a consumer |
|---|---|
programs in bin/ |
puts bin/ first on PATH |
Python modules in lib/python/ |
puts lib/python/ first on PYTHONPATH |
Node.js modules in lib/node/ |
puts lib/node/ first on NODE_PATH |
the packages they need in lib/python/requirements.txt or lib/node/package.json |
installs them before setup, at every install and sync, and reports it |
always-on rules in rules/<name>.md |
adds them to the always-on rules |
initial context as the body of OVERLAY.md, or in CONTEXT.md |
adds it to the agent's first context |
a skill in skills/<name>/SKILL.md |
offers the skill |
a skill from elsewhere, named in skills |
shows it with its source, and fetches it if you accept the overlay |
NAME=value lines in env |
sets them in order, substituting ${NAME} placeholders |
a script in env.py (or .js, .ps1, .sh, ...) |
runs it to compute environment values once the user allows it, and reports it |
a script in setup.py (or .ps1, .sh, ...) |
runs it with its phase (install on the first add, sync on every sync, remove), with the network, and reports it |
a script in hook.py (or .ps1, .sh, ...) |
runs it at a session's events once the user allows it, telling it the event, and reports it |
Other common paths are kb/, references/, workflows/, setup/, env/ and locks/; they mean
something when a field names them. A local.env is not part of an overlay: local overrides belong to
the user's or project's own configuration.
Defaults and how to turn one off¶
Each default stays on until you turn it off in [defaults], one
key each: bin, lib, env, env_scripts, setup, deps, context, skills, rules, hooks.
[defaults]
setup = false
What you declare adds to the defaults: a [[paths]] entry for man/ keeps bin/ on PATH. An
entry that names the same file or directory as a default replaces that default, so it is never
applied twice. To append lib/python/ instead of prepending it:
[[paths]]
variable = "PYTHONPATH"
path = "lib/python"
position = "append"
When you ship several env scripts or setup scripts, a consumer runs one: the first that can run, in
the order .py, .js, .mjs, .cjs, .ps1 (Windows), .bash, .sh (the other systems). Ship
env.ps1 beside env.sh to give each OS its own.
A default setup is taken to need the network. If yours does not, declare an entry naming it, so the consumer can deny it the network:
[[setup]]
interpreter = "sh"
path = "setup.sh"
network = false
Values that use other values¶
An env value can read other variables, as a shell would in "${...}", but nothing runs:
# env, read line by line: each line sees the lines before it
TOOL_HOME=${AOS_OVERLAY_ROOT}/tool
TOOL_CACHE=${TOOL_CACHE_DIR:-${TOOL_HOME}/cache}
PATH=${TOOL_HOME}/bin:${PATH}
TOOL_PROMPT='${USER}$ '
PATH=...${PATH}readsPATHas it was before the line. An overlay with abin/cannot also setPATH: there,bin/is already on it.${AOS_OVERLAY_ROOT}is your overlay's root, whatever name it was installed under;${AOS_OVERLAY_STATE}is its state directory. They are readable here, not set.- An unset name is an error. Give a default where a variable may be missing:
${NAME:-default}, or${NAME-}for empty. A refused value is better than/binwhere you meant$TOOL_HOME/bin. - Defaults (
-,:-), alternates (+,:+), the length${#NAME}, slices${NAME:1:3}, replacements${NAME//:/ }, trims${FILE%.*}and case${NAME^^}work as in bash, on globs.$NAMEwithout braces,$(...)and backticks are characters;$$is a$. - Single quotes keep a
dotenvvalue as written. Inoverlay.cfgandaosenv files a string is substituted the same way; write$${for a literal${. - Values chain in order: earlier lines and files, then
env, and every overlay before yours. The entries of one mapping (env, oneaosfile) do not see each other, so put a value you reuse in an earlier file or line. - A placeholder cannot read a variable set from a secret reference. Use the reference itself.
Name your own files and settings in text¶
Context and the skills you bundle can refer to the overlay by name instead of by a path you cannot
know. A consumer replaces ${NAME} when it serves the text, and nothing in the installed files changes:
Read `${AOS_OVERLAY_ROOT}/kb/checklist.md`. Reviews are `${depth}`; keep notes in
`${AOS_OVERLAY_STATE}`. Write `$${AOS_OVERLAY_ROOT}` for the text itself.
- When: as the context is assembled and a skill's body is served. Never when the overlay is installed, so digests, pins, sync and moves are untouched, and never when the agent reads a file itself.
- Which names:
AOS_OVERLAY_ROOT,AOS_OVERLAY_STATE,AOS_OVERLAY_NAME,AOS_OVERLAY_SCOPE,AOS_PROJECT_ROOT, and the options you declare. A name with no value, such as a state directory the overlay does not have, is left as written. - Anything else is left as written:
${HOME},$HOME,${AOS_OVERLAY_ROOT:-x}, a shell line, a price. Write$${for a literal${. A$$that is not followed by{is just itself. - Files the agent opens itself (a script, a document it reads on request) are not replaced, so
routingandruleskeep naming them as$TEAM_REVIEW_OVERLAY_ROOT/kb/review.md, which the environment resolves. - Options are settings the user gives a value for, in the consumer's own configuration:
[options.depth]
type = "string" # or "integer", "boolean"
default = "normal"
description = "How thorough a review is."
[options.service_token]
type = "string"
sensitive = true # never put in context, and has no default
A text with ${depth} reads the user's value, else the default, else is left as written. The value is
in the agent's context, so keep a secret out of an option: a sensitive one is never replaced, and a
process that needs a secret takes a secret reference.
See Templating for the rules.
Knowledge the agent asks for¶
Files under kb/, flows/, references/, rules/ and context/, and CONTEXT.md, are served to the agent by
path, with a search where the consumer has one, so a long convention need not sit in every context. Say so with
[knowledge] serve = true and leave a routing line that names the path. A .md file is expanded by default:
${AOS_OVERLAY_NAME} is replaced (write $${ for a literal one), and @part.md on its own line includes another
file of the overlay, as Claude Code's CLAUDE.md imports do, never from a code block and never from outside the
overlay. Neither is touched in code. Give a file the first line #!markdown (or #!raw) to serve it exactly as
written. To make one depend on who asks, give it a first line #!envsubst (${AOS_CALLER_ROLE}) or
#!mustache ({{caller.role}}), the real engines, with options after the name (#!envsubst undefined=lenient,
#!mustache escape=none); a server without that engine serves it as written with the context in a front
matter after the line. Only .md and .markdown files read a first line. See Knowledge.
The manifest¶
Start with the fields your consumers use:
name = "team-review"
description = "Review conventions for shared services."
requires = ["engineering"]
routing = ["- Service reviews → `$TEAM_REVIEW_OVERLAY_ROOT/kb/review.md`"]
priority = 450
That is overlay.cfg, TOML unless #!json or #!yaml is on its first line. Written by hand, the
same fields are usually better as the front matter of OVERLAY.md, with the overlay's context as its
body, so there is one file to read:
---
requires: [engineering]
routing:
- Service reviews → `$TEAM_REVIEW_OVERLAY_ROOT/kb/review.md`
priority: 450
---
Review services with their failure modes in mind.
- The front matter is YAML, or what
#!tomlor#!jsonnames as the first line inside the fence, and it closes with---or.... - The YAML is restricted: no anchors, aliases, tags, merge keys or
second documents, and
yesis a string. - A body makes
CONTEXT.mdbeside it ignored, and reported, so keep one or the other.[defaults] context = falsekeeps a body as notes for people. - An overlay with both
OVERLAY.mdandoverlay.cfgis refused.
Every reader reads TOML and restricted YAML; JSON is optional. Do not add a format version: the edition belongs to the specification. See the manifest reference for every field.
Name the skills you need¶
skills lists your bundled skills, and the ones you need without carrying a copy:
skills = [
"summarize-docs", # skills/summarize-docs/SKILL.md, in this overlay
"pdf", # no such directory: the consumer's catalogs resolve it
{ name = "review", source = "https://github.com/example/skills.git#skills/review", pin = "sha256:8280aaf5de7c4f61342f648586d534e481ae095cef223dded70f5b1db5bd84a1" },
]
- A source points at the skill's own directory, the one holding its
SKILL.md. It is a remote location with no credential in it: a manifest names no place on the consumer's machine. - Pin what you reviewed: a skill with no pin is reported
unpinned, each time. - A validator flags a bare name with no directory, so a typo shows before anyone looks it up. A consumer that cannot find one reports it missing, and never picks between two catalogs by itself.
- Use the Agent Skills form of a name, lowercase with single hyphens, equal to the directory's name.
- Until your consumers read this field they refuse the overlay.
Declare what the overlay needs¶
- Environment: plain values, a path under the root, or a secret reference (
{ provider = "env", key = "TOKEN" },{ secret = "name" }), never a secret value. Env files hold the same. - Search paths:
bin/andlib/python/need nothing.[[paths]]adds other directories, or adds to another list variable, with the separator of each OS. - Runtime: the OSes, the commands that must exist, a minimum Python with a locked requirements file and its digest.
- Dependencies: list packages in
lib/python/requirements.txtandlib/node/package.json. Pin them: a--hashon every requirement (pip-compile --generate-hasheswrites one), and apackage-lock.jsonbesidepackage.json; an unpinned file still installs, and is reported. They go into the scope's shared environment, where every overlay's packages are installed together, so two overlays pinning one package to two versions both fail to activate. To keep yours apart, choose a name several overlays share, orisolated:
[[runtime.python]]
environment = "isolated"
An ES module reads a package from NODE_PATH through createRequire(import.meta.url).
- Setup: a script per OS with its interpreter, a timeout, and whether it needs the network.
Setup writes into $AOS_OVERLAY_STATE, never into the overlay; that directory is kept from one
sync to the next. Its first argument (and $AOS_SETUP_PHASE) is the phase: install on the
first add, sync on every sync (also when nothing changed, and when the user asks to run setup
again), remove before the overlay and its state are deleted. Make sync cheap when there is
nothing to do, and update the state in place so a failure leaves the old state usable. Do
nothing, successfully, for a phase you do not know; a script that ignores the phase still
works, and returns early on remove if its setup is slow:
case "${1:-}" in
install|sync) prepare ;;
remove) cleanup ;;
*) ;;
esac
Each of these is a non-default setting when it loosens a default (network for setup or for installing dependencies, reading the host's environment, unlocked dependencies, no timeout), and consumers report it. Declare only what you need.
Hooks¶
A hook runs at a session's events. With no manifest, hook.py (or .js, .ps1,
.sh, chosen as env.<ext> is) is told of the events that carry nothing the user wrote: pre-env,
session-start, session-end, turn-end, cd and pre-compact. Its first argument is the event; a
JSON payload is on its standard input. Exit 0 with no output for an event you do not handle, including
one a later edition adds:
import json, sys
event = sys.argv[1] if len(sys.argv) > 1 else ""
payload = json.load(sys.stdin)
if event == "session-start" and payload["reason"] == "new":
print(json.dumps({"context": "Run the tests before you report a task done."}))
hooks says what runs at each event, and gives a hook the events that carry content: prompt (the
user's words) and pre-tool and post-tool (a tool's input). Naming them is how a reader of your
manifest learns what your hook is told:
[hooks]
pre-tool = { match = ["execute"], timeout = 5, on_failure = "refuse" } # hook.py, for shell calls
post-tool = { run = "hooks/after_edit.py", match = ["edit"] }
turn-end = false # nothing at turn-end
What a hook may print, as one JSON object: context; decision (block for prompt and
pre-compact, deny, ask or allow for pre-tool, an allow with an input that replaces the call's) with a reason; and env, which a consumer applies
where the harness lets it, for the variables the entry lists in sets
(session-start = { sets = ["TOOL_MODE"] }). Text holds no terminal escapes or other control
characters but tabs and line ends. pre-env prints what an env script prints. An allow approves the call
only where the user would have been asked: it never lifts their own refusals, an ask or a deny from
another hook beats it, and any decision but those fails the run. A hook runs in the session's folder with the
session's environment, so it can read a variable another overlay declared. A hook that fails is reported and the
session goes on; write on_failure = "refuse" on a guard, so that a crash or a timeout refuses the call
instead of letting it through.
Your users allow your hooks and env scripts at your overlay's digest, so every release asks them again, and an overlay
with a refuse guard is not activated until they do. Keep a hook
small and quick (30 seconds by default, and a consumer may allow less), and expect prompt and the tool
events to be missing on some harnesses: a consumer reports what it cannot fire, but cannot fire it.
See examples/hook-script/
and examples/hooks-table/.
Skills and commands¶
Put a skill in skills/<skill-name>/SKILL.md. To offer only some of them, set
[defaults] skills = false and list them in skills.
A [scripts] entry names a command and its script; give the interpreter when the extension does not
say it.
Listing in a store¶
A store shows your overlay's name and description, and what you put in [about]. Every field
is optional and only shown: nothing in [about] changes what the overlay does, and a mistake in it
never stops the overlay from working.
[about]
summary = "Release notes and changelogs, written the same way in every repository."
icon = "icon.webp"
homepage = "https://example.org/overlays/release-notes"
repository = "https://github.com/example/overlays"
license = "MIT OR Apache-2.0"
authors = ["Example Docs Team <docs@example.org>"]
tags = ["documentation", "release", "changelog"]
- Keep
summaryto one short line;descriptionholds the longer text. - Ship the icon as a square PNG or WebP of 256 by 256 pixels or more, under 512 KiB and at most
1024 pixels a side, the limits stores use by default. SVG is not accepted. Name it in
icon: no file is an icon by its name. - Links are
https.licenseis an SPDX expression (MIT,MIT OR Apache-2.0). - Tags are lowercase words joined by
-; a store filters and searches by them.
To offer several overlays, or skills overlays can name, publish a catalog: a TOML, JSON or YAML
file, named by its format, listing each one's source. A registry is already one; add tables where you
want a store to show more, and a pin where you reviewed a revision:
name = "Example overlays"
[overlays]
engineering = "../engineering"
[overlays.release-notes]
source = "https://github.com/example/overlays.git#release-notes"
ref = "v1.4.0"
pin = "sha256:8280aaf5de7c4f61342f648586d534e481ae095cef223dded70f5b1db5bd84a1"
[overlays.release-notes.about]
summary = "Release notes and changelogs, written the same way in every repository."
icon = "icons/release-notes.png"
[skills]
pdf = "https://github.com/example/skills.git#skills/pdf"
Relative sources and icons resolve beside the catalog file. A store shows what a catalog says
until it fetches the overlay, then shows the overlay's own manifest, so keep the two in step. See
examples/registry/catalog.toml.
Checks¶
Validate the parsed manifest against the schema and check that every
file a field names exists. Review setup, scripts, hooks and dependency declarations as code, and the
env.<ext>, setup.<ext> and hook.<ext> files that run by default. In this
repository, python -m pytest runs every example and fixture.
Validate a catalog against the schema's $defs/catalog, and its icons as a store would.