Manifest referenceComing soon
Every field of plugin.yaml, with its type, default and rules. Rendered from the same JSON Schema that the validator uses.
A plugin is described by one file, plugin.yaml, at the root of its repo. This page is generated from the manifest's JSON Schema, published at a stable URL:
https://docs.coderhelm.com/schema/plugin-manifest.v1.jsonPoint your editor at it for completion and inline errors. With the YAML extension for VS Code, put this comment on the first line:
# yaml-language-server: $schema=https://docs.coderhelm.com/schema/plugin-manifest.v1.jsonCheck a plugin against it before you push with the validator: see Test a plugin locally.
Top-level fields
The plugin.yaml file at the root of a CoderHelm plugin. A plugin is text plus approved tools: its behavior comes from its agents and skills, and this file declares what it may touch.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | yes | The plugin's id. Lowercase letters, digits and -, optionally namespaced by publisher as publisher/name. Must match ^([a-z0-9][a-z0-9-]\{0,38\}/)?[a-z0-9][a-z0-9-]\{0,63\}$. Example: marketing, acme/marketing. | |
version | string | yes | The plugin's version, in semantic versioning (MAJOR.MINOR.PATCH). Installs are pinned by content hash, so the version is a label for people; raise it whenever you publish. Must match ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$. Example: 1.2.0. | |
description | string | yes | One line saying what the plugin does. Shown in the catalog and on the plugin's page. At most 240 characters. | |
skills | list of string | no | ["skills/*/SKILL.md"] | Paths or globs of the plugin's skills, relative to the plugin's folder. Skills use the same SKILL.md format as skill repos and apply only to this plugin's runs. |
agents | list of string | no | ["agents/*.md"] | Paths or globs of the plugin's agents. Each agent file is Markdown with frontmatter; its body is the agent's instructions. |
settings | list of objects | no | [] | Values each team fills in on the plugin's page. Values live with the team, never in the plugin. |
tools | list of objects | no | [] | Every tool the plugin's agents may call. A tool that is not listed here does not exist for a plugin run. |
triggers | list of objects | no | [] | What starts a run of the plugin, besides a person writing a brief on the plugin's page. |
outputs | list of objects | no | [] | What a run produces. Drafts wait in the review queue; a publish output sends an approved draft out through a consequential tool. |
budget | object | no | The plugin's own monthly token limit. The team can change it on the plugin's page, and the team's limits apply too. |
Fields not listed here are refused, so a typo fails loudly instead of being ignored.
settings[]
Values each team fills in on the plugin's page. Values live with the team, never in the plugin.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
key | string | yes | The setting's name. Lowercase letters, digits and _, starting with a letter. Must match ^[a-z][a-z0-9_]\{0,63\}$. | |
type | string | secret | connection | yes | string is a value the team types. secret is sealed, never shown again once saved, and never given to a model. connection asks the team to connect an account. | |
provider | string | no | For a connection: how the account is connected, such as oauth2. Example: oauth2. | |
scopes | list of string | no | For an OAuth connection: the scopes asked for. Adding a scope in a new version waits for an admin. | |
sensitive | boolean | no | false | Keep the value out of every prompt and never send it back to the dashboard. secret and connection settings are always sensitive. |
A connection setting needs provider. secret and connection settings are always sensitive.
tools[]
Every tool the plugin's agents may call. A tool that is not listed here does not exist for a plugin run. Each entry is one of two shapes.
Tools from an MCP server
Tools from an MCP server the team has on its Connections page.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
ref | string | yes | mcp:\<id\>: the connection's MCP server. Must match ^mcp:[a-z0-9][a-z0-9_-]*$. Example: mcp:sanity. | |
allow | list of string | yes | Tool names, or * globs, from that server the plugin may call. Everything else on the server is hidden from the run. | |
risk | read | write | consequential | no | "read" | The highest risk among the allowed tools. |
A built-in or plugin-defined tool
A built-in CoderHelm tool, or a tool the plugin defines.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | yes | Lowercase letters, digits and _. Agents call the tool by this name. Must match ^[a-z][a-z0-9_]\{0,63\}$. | |
kind | builtin | http | yes | builtin is one of CoderHelm's own tools, such as reading release notes. http is a tool the plugin defines that calls an outside service with the team's connection. | |
description | string | no | When an agent should use the tool. At most 240 characters. | |
risk | read | write | consequential | yes | read only looks. write changes something a person can still review, such as a draft in a CMS. consequential reaches people or money (publish, send, post) and runs only after an approval. |
Risk levels
read only looks. write changes something a person can still review, such as a draft in a CMS. consequential reaches people or money (publish, send, post) and runs only after an approval.
triggers[]
What starts a run of the plugin, besides a person writing a brief on the plugin's page.
on: manual
A person starts a run from the plugin's page by filling in a short form.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
on | "manual" | yes | ||
form | map | no | \{"brief":"text"\} | The form's fields: text for a box to write in, or a list of choices to pick from. |
on: schedule
Runs on a schedule.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
on | "schedule" | yes | ||
cron | string | yes | Five-field cron: minute, hour, day of month, month, day of week. Must match ^\S+( \S+)\{4\}$. Example: 0 14 * * MON. |
on: github.release
Runs when a release is published on a GitHub repo the team connected. The run gets the release notes CoderHelm wrote.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
on | "github.release" | yes |
outputs[]
What a run produces. Drafts wait in the review queue; a publish output sends an approved draft out through a consequential tool.
type: draft
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | "draft" | yes | ||
kinds | list of blog | social | email | image | action | yes | The kinds of draft a run may save. action is a step to take, such as an update to a record, rather than something to read. |
type: publish
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | "publish" | yes | ||
via | string | yes | The name of a consequential tool from tools that sends an approved draft out. Must match ^[a-z][a-z0-9_]\{0,63\}$. | |
approval | object | no | The approval a draft needs before it is published. The person who asked for a draft never approves it. |
approval
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
role | string | no | Who should approve, as a short name such as marketing_editor. The team lists the actual approvers on the plugin's page. Must match ^[a-z][a-z0-9_]\{0,63\}$. | |
min | integer | no | 1 | How many different people must approve. |
budget
The plugin's own monthly token limit. The team can change it on the plugin's page, and the team's limits apply too.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
monthly_tokens | integer | no | Tokens the plugin may use per month. Empty or 0 means no limit of its own. |