Reference

oz0-plugin.yaml

Every field of the plugin manifest, and the rules plugin lint checks.

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.

oz0-plugin.yaml
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

Top level

apiVersion
string required
Must be oz0/v1.
name
string required
Lowercase letters, digits and dashes, at most 63 characters, starting and ending with a letter or digit.
version
string required
A semantic version such as 1.4.0, with an optional pre-release or build suffix.
description
string
One line about what the plugin does. Missing it is a warning.
kind
string
The plugin's kind:
  • connector: one outside system, with its tools, connection, event sources and at most one generic delegate agent tagged delegate.
  • capability: one job, with agents, skills, flows and evals, reaching connectors through uses: 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. See members.
Installs accept a plugin without a kind. 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.
license
string
The plugin's licence as an SPDX licence expression: identifiers of the SPDX License List in any case, joined with 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.
runtime
string
The language of the plugin's own code: 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.json must 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).
agents
string[]
Agent definition files, or folders of them, relative to the plugin's root: YAML files (.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.
skills
string[]
Skill folders (with a SKILL.md), or folders of them.
flows
string[]
Flow files, or folders of *.yaml flows, each with apiVersion (optional, oz0/v1; a flow file on its own must say it), name, description, input_schema, output_schema (the output's contract, which a flow tool carries), trigger.webhook.secret or trigger.event, steps and output. See Flows.
evals
string[]
Eval files, or folders of *.yaml evals, each with agent or flow, threshold and cases. See Evals.
harnesses
list
Agent harnesses this plugin provides. See below.
events
list
Event sources: deliveries from other systems that the edge takes on 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.
egress
string[]
Hosts the plugin's processes may reach when they run in sandbox tier 1: its harness sessions, its tools in jobs a webhook starts, and its servers on a node with --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
string[]
Records of the core the plugin's tools fill beyond their own calls, each a permission a tenant admin grants at install. See provides below.
reads
string[]
Records of the core the plugin's functions read beyond their own calls, each a permission a tenant admin grants at install. See reads below.
records
object
The plugin's tools keep versioned records through the platform, in its own namespace: scopes, any of agent, project and tenant (all three when left out). See records and start-up text.
startup
object
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.
tool_tokens
integer
The most all the plugin's own tool functions may come to together, as an estimate of the tokens of their definitions (name, description and input schema) from the measured listing. Unset is 16,000. 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
list
The plugin's suggested policy for its own functions: rules that only tighten, which an install writes as the tenant's rules. See policy.
members
list
Only with kind: set: the plugins of the set, each pinned. See members.
procedure
object
The written procedure the plugin's agents follow, approved by a named expert: 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.yaml and .claude-plugin/plugin.json or plugin.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.md at the root, without Claude Code's folders (skills/, commands/, agents/, hooks/hooks.json, .mcp.json) beside it.
  • 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, dev and run also take the part's file itself, such as ./triage.md, which is packed alone, without what lies beside it. oz0 agent new writes an agent in one file, and oz0 plugin eject writes the full folder a part stands for (oz0-plugin.yaml with this manifest's name, kind and uses: 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:

the manifest of triage.md
# 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 under agents:, flows: or skills:, no runtime, and uses: 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:
    OriginVersion
    a semantic-version tag, v1.2.0 or 1.2.01.2.0
    a commit0.0.0-g<12 hex>
    a digest (a bundle, an upload, plugin install of a folder, which uploads it, an image)0.0.0-d<12 hex>
    a workspace revision0.0.0-w<revision>
    none (oz0 dev, and plugin lint or plugin inspect of 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.

Copyright © 2026