Getting started¶
Create your first overlay¶
An overlay can be as small as a directory with one instruction file:
review-basics/
└── instructions.md
There is no required manifest. Add OVERLAY.md when you want metadata or declarations, with what the
agent should read first as its body:
---
name: review-basics
description: Shared code review guidance.
---
Review the change for what it does, not how it is written.
The front matter is YAML unless its first line names another format (#!toml, #!json), and a body
takes the place of CONTEXT.md. A tool that writes manifests can write overlay.cfg instead, with the
same fields; an overlay never has both:
name = "review-basics"
description = "Shared code review guidance."
routing = ["- Reviewing code → `$REVIEW_BASICS_OVERLAY_ROOT/instructions.md`"]
overlay.cfg is TOML unless its first line names another format. The same file in JSON:
#!json
{
"name": "review-basics",
"description": "Shared code review guidance.",
"routing": ["- Reviewing code → `$REVIEW_BASICS_OVERLAY_ROOT/instructions.md`"]
}
Refer to the overlay's own files with relative paths, and keep credentials out of it: an overlay names where a secret comes from, never its value.
Give it tools¶
Put helpers in bin/. That is all: a consumer puts bin/ first on PATH, with or without a
manifest.
review-basics/
├── instructions.md
└── bin/review-check
Files in other conventional places work the same way: lib/python/ for Python modules, skills/
for skills, env for environment values, lib/python/requirements.txt for packages, setup.sh
or setup.py for a setup step, hook.py for code at a session's events, which runs only once the
user allows it. To turn one
off, set its key in [defaults] (bin = false). A runtime and secret references are declared; see
Authoring, Environment and
Runtime and setup.
Use it¶
Choose a consumer that reads overlay directories. dotagents, the reference implementation, installs one from a directory of overlays:
dotagents overlays add review-basics --repo ./overlays
That is one manager's command; AOS requires neither dotagents nor a command line. A read-only integration can show the files without installing them.
dotagents 0.9.0 and Canoa read
overlay.cfgand not yetOVERLAY.md; see Compatibility.
Next¶
Read Authoring, then the manifest, composition and security.