oz0-plugin.yaml
For: Plugin authors looking up manifest fields.
The manifest is oz0-plugin.yaml at the root of the plugin's repository. It is read strictly: unknown fields are errors, so a typo does not pass silently. A manifest is at most 256 KiB, and a key may appear once in a mapping (the limits). oz0 plugin lint runs the same checks as the edge.
apiVersion: oz0/v1
name: acme-github
version: 1.4.0
description: Tools and agents for working in GitHub
license: Apache-2.0 # SPDX; LICENSE holds its text
runtime: python
requires:
oz0: ">=0.4"
platforms: [linux/amd64, darwin/arm64]
secrets: [GITHUB_TOKEN]
tools:
- id: acme_github
mcp: ["python", "-m", "acme_github.mcp"]
requires_approval: [acme_github.merge] # a person decides every merge
- id: acme_fetch
package: pypi:mcp-server-fetch==2026.8.18
affinity: any
agents: [agents/acme-reviewer.yaml]
skills: [skills/]
hooks:
- on: pre_tool_call
call: acme_github.check_merge
match: { tools: ["acme_github.merge"] }
timeout: 2s
on_timeout: escalate
flows: [flows/]
evals: [evals/]
A plugin's folder holds folders and regular files only: the loader refuses a symbolic link or a special file anywhere
it reads or packs, with the problem code files.link (Plugin sources).
A folder that is one part on its own needs no manifest: the loader generates one (A plugin that is one
part). References to another plugin's parts name that plugin, as
<plugin>/<part> (Addresses).
In this guide
- Dependencies and cross-plugin access: Look up the fields for dependencies and cross-plugin access.
- Tool declarations: Look up the fields for tool declarations.
- Harnesses, events and channels: Look up the fields for harnesses, events and channels.
- Connections and hooks: Look up the fields for connections and hooks.
- Plugin sets and policies: Look up the fields for plugin sets and policies.
- Data, evidence and mail: Look up the fields for data, evidence and mail.
- Generated OpenAPI manifests: Look up the fields for generated openapi manifests.
Top level
oz0/v1.1.4.0, with an optional pre-release or build suffix.connector: one outside system, with its tools, connection, event sources and at most one generic delegate agent taggeddelegate.capability: one job, with agents, skills, flows and evals, reaching connectors throughuses:with exact functions.policy: hooks and guardrail packs for the whole organisation.set: other plugins pinned to exact versions and installed together, with no parts of its own. Seemembers.
plugin lint warns (OZ-S001), and house rules that depend on the kind cannot run.Lint also warns about a policy with no hooks, or with a connection, event source or channel. It runs connector rules on any plugin with one of those, whatever its kind says. See How to structure plugins.AND, OR and WITH (an exception), with parentheses, a trailing +, or
LicenseRef-<name> for a licence of your own, at most 256 characters, such as MIT, Apache-2.0 OR MIT or
GPL-2.0-or-later WITH Classpath-exception-2.0.Each licence it names needs a file whose text reads as it:
LICENSE, LICENCE or COPYING (any case, .md or .txt), LICENSE-<id>, or LICENSES/<id>.txt; the placeholder
oz0 plugin new writes counts as none.A value that is not such an expression, NONE or NOASSERTION is an error
wherever the manifest is read (licence.id); an identifier the list deprecated, such as GPL-2.0, is a warning that
names what to write instead (licence.deprecated, which plugin lint --fix applies).Leaving it out declares no
licence: with a licence file that is a warning (licence.undeclared). The engine says what a file reads as and what
the manifest declares, never that a licence is valid for a use.A plugin of one part on its own declares none; an
imported Claude Code plugin or Agent Plugin takes the license of its own plugin.json when it is such an
expression, and an overlay's license: wins. Plugin limits explains each check,
and those of the README.python, node, go or binary. Only a plugin that starts code of its own
needs it: a tool with mcp: and no package:, or a harness whose command runs in the plugin's environment (no
package: and no binaries:); lint and the install refuse such a plugin without it. A plugin of agents, skills,
flows, hooks on other tools, package tools and remote tools leaves it out, and gets no environment on the nodes.Nodes build python plugins with a pyproject.toml by running uv sync from uv.lock. With --plugin-sandbox strict, the default, no plugin code runs during the build. The project's build-backend must therefore be uv_build, as oz0 plugin new writes it, and its dependencies must be wheels.Nodes build node plugins with a package.json by running npm ci --omit=dev --ignore-scripts from package-lock.json, using the node's Node.js 24. A tool command starting with node runs there, and TypeScript runs as it is.On a strict node:- The lock must be version 2 or 3.
- Every lock entry, including dev entries, and every dependency and override in
package.jsonmust come from a registry or a tarball inside the plugin's folder. - Workspaces, linked folders, Git dependencies, tarballs by URL and files outside the folder are refused. npm prepares a Git dependency by running its scripts.
- An
npm:tool installs only through the edge's lock.
go and binary are not built yet.The lockfile is required: an install or update of a plugin whose pyproject.toml has no uv.lock, or whose package.json has no package-lock.json, is refused, while oz0 dev and plugin lint only warn (lockfiles)..yaml, .yml) and
Markdown agents (.md, front matter and a body). In a folder, a
.md file without front matter is a note, such as a README, and is skipped.SKILL.md), or folders of them.POST /events/<tenant>/<name>, checks against a tenant secret, and hands to one of this plugin's functions to turn into events. See Event sources and below.--plugin-sandbox strict, the default.Each is a host name (ports 80 and 443), *.domain, a pattern with a whole-label * such as jenkins.*.example.com, host:port, host:*, host:port/tcp for raw TCP, !host to deny it, or an IP address, but not an internal address such as 127.0.0.1, 169.254.169.254 or 168.63.129.16, nor one on a private network such as 10.0.0.7 or fd00::1: only the tenant's list may open those (the full list).The plugin's entries reach public addresses only, also by name: a host on the company's network goes on the tenant's list. The tenant's list and the agent's come on top; everything else is denied.A host that serves files anyone can publish, such as raw.githubusercontent.com or a package registry, is a warning at plugin lint and an error with --verified (OZ-S022); the install's review shows the same note and never refuses for it.provides below.reads below.scopes, any of agent, project and tenant (all three when left out). See records and start-up text.call: one of the plugin's own local functions (<tool>.<function>, needing no approval) that the platform calls at the start of each job of an agent that uses the plugin, for text it adds to the agent's start-up context under limits.startup_tokens. See records and start-up text.plugin lint, plugin test, plugin pack and the studio fail past it, naming the biggest functions; the plugin index shows a warning and never refuses on it (the size budget). A whole number from 1 to 1,000,000.policy.kind: set: the plugins of the set, each pinned. See members.file (a Markdown file with a # title and the sections Inputs, Steps (numbered), Checks and When to escalate), approved_by (the person who approved its text), approved_at (the date, YYYY-MM-DD) and review_every (90d, 26w, 6mo or 1y, a day to three years). oz0 plugin procedure generates the agents' instructions and starter evals from it; lint warns when the review is due, and the inventory shows an installed plugin's review date. See Start from a written procedure.Paths must be relative to the plugin's root, use forward slashes and stay inside the plugin (no ..). A plugin with no tools, agents, skills, hooks or flows gets a warning.
A plugin that is one part
A folder without oz0-plugin.yaml that holds exactly one part loads as a plugin of that part, from any source: a Git
path, a bundle or upload, a workspace folder or a local folder.
- What counts as the part, after
oz0-plugin.yamland.claude-plugin/plugin.jsonorplugin.json, which load as before:- one Markdown file at the root whose front matter says
apiVersion: oz0/v1: a Markdown agent. Other Markdown files at the root, a README among them, are notes; - one flow file at the root that says
apiVersion: oz0/v1; - a
SKILL.mdat the root, without Claude Code's folders (skills/,commands/,agents/,hooks/hooks.json,.mcp.json) beside it.
- one Markdown file at the root whose front matter says
- Otherwise: a folder with Claude Code's folders imports as a Claude Code plugin, as before. Two parts, or a part
beside Claude Code's folders, is an error that says to write
oz0-plugin.yaml, which lists the parts (oz0 plugin eject <file> --out <folder>writes one around a part). A folder with none of these is the missing manifest's error, which names the three ways. - One file:
plugin install,devandrunalso take the part's file itself, such as./triage.md, which is packed alone, without what lies beside it.oz0 agent newwrites an agent in one file, andoz0 plugin ejectwrites the full folder a part stands for (oz0-plugin.yamlwith this manifest's name, kind anduses:and the version kept, the part in its folder, and for an agent or a flow an evals skeleton), so the plugin updated from it keeps its name, versions and rollouts.
The generated manifest:
# Generated by Orchestrator Zero from triage.md: the manifest of a plugin that is this one part.
apiVersion: oz0/v1
name: triage
version: 1.2.0
description: Triage new issues and label them
agents:
- triage.md
uses:
github:
tools:
- oz0_github.add_labels
- oz0_github.get_issue
kind: capability
- Its values: the part's name and description,
kind: capability, the part's path underagents:,flows:orskills:, noruntime, anduses:made from the part's addresses: each other plugin's functions, agents and skills, sorted, with no version (any) and no source. Nothing else. - A part on its own names other plugins' parts by address. A bare name that is not the part's own is an error there, since nothing else would ask for the grant.
- Its version comes from where the files came from, the first that applies:
Origin Version a semantic-version tag, v1.2.0or1.2.01.2.0a commit 0.0.0-g<12 hex>a digest (a bundle, an upload, plugin installof a folder, which uploads it, an image)0.0.0-d<12 hex>a workspace revision 0.0.0-w<revision>none ( oz0 dev, andplugin lintorplugin inspectof a folder)0.0.0-dev
A hub listing's version is its manifest's, so a listing of a part on its own comes from a tag. - The same files and origin give the same bytes, and the same bundle. The generated manifest is never written into the plugin's artifact: the artifact and its digest are the part's files, as they would be without one.
Every problem points at the part's file. plugin lint says the manifest is generated, and plugin lint --json shows it as the bundle's manifest, with generated naming the part.
Previous section links
- a-plugin-written-by-plugin-import-openapi: open this section.
- addresses: open this section.
- card-keywords-in-schemas: open this section.
- channels: open this section.
- connections: open this section.
- events: open this section.
- files-between-tools: open this section.
- harnesses: open this section.
- hooks: open this section.
- mail: open this section.
- members: open this section.
- policy: open this section.
- provides: open this section.
- reads: open this section.
- requires: open this section.
- tools: open this section.
- toolslistingjson: open this section.
- uses: open this section.