Skip to content

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.cfg and not yet OVERLAY.md; see Compatibility.

Next

Read Authoring, then the manifest, composition and security.