Skip to content

Agent Overlay Specification

A vendor-neutral format for agent overlays: directories of instructions, skills, tools and environment that any agent manager can read without running anything. Teams keep their engineering guidance, skills and helpers in focused overlays, and each project or agent takes the ones it needs.

An overlay is a directory, and files in conventional places (bin/, skills/, env) work without a manifest. Its optional manifest is the front matter of OVERLAY.md, whose body is its context, or overlay.cfg: TOML unless its first line names another format, and always static data. It declares what the overlay needs (environment variables, path additions, a runtime, a setup step) so a consumer can decide where it can run before running anything, and it can be pinned by one digest of the whole tree.

Installation

Nothing to install. The format is this text, a JSON Schema of the manifest's data model, and conformance vectors any implementation can test against.

30-second tour

team-review/
├── overlay.cfg
├── kb/review.md
├── bin/review-check.py
└── skills/review/SKILL.md
name = "team-review"
description = "Review conventions for shared services."
requires = ["engineering"]
routing = ["- Service reviews → `$TEAM_REVIEW_OVERLAY_ROOT/kb/review.md`"]

[env]
REVIEW_TOKEN = { provider = "env", key = "REVIEW_TOKEN", optional = true }

A consumer reads this without executing anything, sets TEAM_REVIEW_OVERLAY_ROOT, takes the token from its own environment (and reports that it did), and, because they are where it looks, puts bin/ first on PATH and offers the review skill.

Learn more

The current edition is 0.1.0-draft, not a 1.0 standard. dotagents is the reference implementation, not a required dependency.