---
title: "oz0-plugin.yaml"
description: "Every field of the plugin manifest, and the rules plugin lint checks."
canonical_url: "https://docs.oz0.ai/reference/plugin-manifest"
---
# 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](https://docs.oz0.ai/concepts/limits-and-scaling/limits#the-limits)). `oz0 plugin lint` runs the same checks as the edge.

```yaml [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](https://docs.oz0.ai/build/plugins/sources)).

A folder that is one part on its own needs no manifest: the loader generates one ([A plugin that is one
part](https://docs.oz0.ai/reference/plugin-manifest#a-plugin-that-is-one-part)). References to another plugin's parts name that plugin, as
`<plugin>/<part>` ([Addresses](https://docs.oz0.ai/reference/plugin-manifest/dependencies#addresses)).

## In this guide

- [Dependencies and cross-plugin access](https://docs.oz0.ai/reference/plugin-manifest/dependencies): Look up the fields for dependencies and cross-plugin access.
- [Tool declarations](https://docs.oz0.ai/reference/plugin-manifest/tools): Look up the fields for tool declarations.
- [Harnesses, events and channels](https://docs.oz0.ai/reference/plugin-manifest/runtimes): Look up the fields for harnesses, events and channels.
- [Connections and hooks](https://docs.oz0.ai/reference/plugin-manifest/connections): Look up the fields for connections and hooks.
- [Plugin sets and policies](https://docs.oz0.ai/reference/plugin-manifest/sets-policy): Look up the fields for plugin sets and policies.
- [Data, evidence and mail](https://docs.oz0.ai/reference/plugin-manifest/data): Look up the fields for data, evidence and mail.
- [Generated OpenAPI manifests](https://docs.oz0.ai/reference/plugin-manifest/openapi): Look up the fields for generated openapi manifests.

## Top level

<field-group>
<field name="apiVersion" type="string" :required="true">

Must be `oz0/v1`.

</field>

<field name="name" type="string" :required="true">

Lowercase letters, digits and dashes, at most 63 characters, starting and ending with a letter or digit.

</field>

<field name="version" type="string" :required="true">

A semantic version such as `1.4.0`, with an optional pre-release or build suffix.

</field>

<field name="description" type="string">

One line about what the plugin does. Missing it is a warning.

</field>

<field name="kind" type="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`](https://docs.oz0.ai/reference/plugin-manifest/sets-policy#members).

Installs accept a plugin without a kind. `plugin lint` warns ([OZ-S001](https://docs.oz0.ai/build/plugins/structure/lint-rules#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](https://docs.oz0.ai/build/plugins/structure).

</field>

<field name="license" type="string">

The plugin's licence as an SPDX licence expression: identifiers of the [SPDX License List](https://spdx.org/licenses/)
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](https://docs.oz0.ai/build/plugins/limits/documentation#the-licence) explains each check,
and those of the README.

</field>

<field name="runtime" type="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](https://docs.oz0.ai/concepts/security/plugins#plugins-are-trusted-code). 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](https://docs.oz0.ai/build/plugins/packages#lockfiles)).

</field>

<field name="agents" type="string[]">

Agent definition files, or folders of them, relative to the plugin's root: YAML files (`.yaml`, `.yml`) and
[Markdown agents](https://docs.oz0.ai/reference/agent-definition#a-markdown-agent) (`.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.

</field>

<field name="skills" type="string[]">

Skill folders (with a `SKILL.md`), or folders of them.

</field>

<field name="flows" type="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](https://docs.oz0.ai/build/parts/flows/flow-tools#flows-as-tools) carries), `trigger.webhook.secret` or `trigger.event`, `steps` and `output`. See [Flows](https://docs.oz0.ai/build/parts/flows).

</field>

<field name="evals" type="string[]">

Eval files, or folders of `*.yaml` evals, each with `agent` or `flow`, `threshold` and `cases`. See [Evals](https://docs.oz0.ai/improve/evals).

</field>

<field name="harnesses" type="list">

Agent harnesses this plugin provides. See below.

</field>

<field name="events" type="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](https://docs.oz0.ai/build/parts/event-sources) and below.

</field>

<field name="egress" type="string[]">

Hosts the plugin's processes may reach when they run in [sandbox tier 1](https://docs.oz0.ai/concepts/security/sandbox-tiers#sandboxes): 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](https://docs.oz0.ai/concepts/security/sandbox-tiers#sandboxes)).

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](https://docs.oz0.ai/build/plugins/structure/lint-rules#oz-s022)); the install's review shows the same note and never refuses for it.

</field>

<field name="provides" type="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`](https://docs.oz0.ai/reference/plugin-manifest/data#provides) below.

</field>

<field name="reads" type="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`](https://docs.oz0.ai/reference/plugin-manifest/data#reads) below.

</field>

<field name="records" type="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](https://docs.oz0.ai/build/parts/records-and-startup).

</field>

<field name="startup" type="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](https://docs.oz0.ai/build/parts/records-and-startup#start-up-text).

</field>

<field name="tool_tokens" type="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](https://docs.oz0.ai/reference/plugin-manifest/tools#toolslistingjson). 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](https://docs.oz0.ai/build/parts/tools/definitions#the-size-budget)). A whole number from 1 to 1,000,000.

</field>

<field name="policy" type="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`](https://docs.oz0.ai/reference/plugin-manifest/sets-policy#policy).

</field>

<field name="members" type="list">

Only with `kind: set`: the plugins of the set, each pinned. See [`members`](https://docs.oz0.ai/reference/plugin-manifest/sets-policy#members).

</field>

<field name="procedure" type="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](https://docs.oz0.ai/build/plugins/develop-and-test/tests-and-drills#start-from-a-written-procedure).

</field>
</field-group>

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](https://docs.oz0.ai/reference/agent-definition#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:

```yaml [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:<table>
<thead>
  <tr>
    <th>
      Origin
    </th>
    
    <th>
      Version
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      a semantic-version tag, <code>
        v1.2.0
      </code>
      
       or <code>
        1.2.0
      </code>
    </td>
    
    <td>
      <code>
        1.2.0
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      a commit
    </td>
    
    <td>
      <code>
        0.0.0-g&lt;12 hex>
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      a digest (a bundle, an upload, <code>
        plugin install
      </code>
      
       of a folder, which uploads it, an image)
    </td>
    
    <td>
      <code>
        0.0.0-d&lt;12 hex>
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      a workspace revision
    </td>
    
    <td>
      <code>
        0.0.0-w&lt;revision>
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      none (<code>
        oz0 dev
      </code>
      
      , and <code>
        plugin lint
      </code>
      
       or <code>
        plugin inspect
      </code>
      
       of a folder)
    </td>
    
    <td>
      <code>
        0.0.0-dev
      </code>
    </td>
  </tr>
</tbody>
</table>

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

- <span id="a-plugin-written-by-plugin-import-openapi">

a-plugin-written-by-plugin-import-openapi

</span>

: [open this section](https://docs.oz0.ai/reference/plugin-manifest/openapi#a-plugin-written-by-plugin-import-openapi).
- <span id="addresses">

addresses

</span>

: [open this section](https://docs.oz0.ai/reference/plugin-manifest/dependencies#addresses).
- <span id="card-keywords-in-schemas">

card-keywords-in-schemas

</span>

: [open this section](https://docs.oz0.ai/reference/plugin-manifest/data#card-keywords-in-schemas).
- <span id="channels">

channels

</span>

: [open this section](https://docs.oz0.ai/reference/plugin-manifest/runtimes#channels).
- <span id="connections">

connections

</span>

: [open this section](https://docs.oz0.ai/reference/plugin-manifest/connections#connections).
- <span id="events">

events

</span>

: [open this section](https://docs.oz0.ai/reference/plugin-manifest/runtimes#events).
- <span id="files-between-tools">

files-between-tools

</span>

: [open this section](https://docs.oz0.ai/reference/plugin-manifest/tools#files-between-tools).
- <span id="harnesses">

harnesses

</span>

: [open this section](https://docs.oz0.ai/reference/plugin-manifest/runtimes#harnesses).
- <span id="hooks">

hooks

</span>

: [open this section](https://docs.oz0.ai/reference/plugin-manifest/connections#hooks).
- <span id="mail">

mail

</span>

: [open this section](https://docs.oz0.ai/reference/plugin-manifest/data#mail).
- <span id="members">

members

</span>

: [open this section](https://docs.oz0.ai/reference/plugin-manifest/sets-policy#members).
- <span id="policy">

policy

</span>

: [open this section](https://docs.oz0.ai/reference/plugin-manifest/sets-policy#policy).
- <span id="provides">

provides

</span>

: [open this section](https://docs.oz0.ai/reference/plugin-manifest/data#provides).
- <span id="reads">

reads

</span>

: [open this section](https://docs.oz0.ai/reference/plugin-manifest/data#reads).
- <span id="requires">

requires

</span>

: [open this section](https://docs.oz0.ai/reference/plugin-manifest/dependencies#requires).
- <span id="tools">

tools

</span>

: [open this section](https://docs.oz0.ai/reference/plugin-manifest/tools#tools).
- <span id="toolslistingjson">

toolslistingjson

</span>

: [open this section](https://docs.oz0.ai/reference/plugin-manifest/tools#toolslistingjson).
- <span id="uses">

uses

</span>

: [open this section](https://docs.oz0.ai/reference/plugin-manifest/dependencies#uses).


## Sitemap

See the full [sitemap](https://docs.oz0.ai/sitemap.md) for all pages.
