# What a plugin is

Source: https://docs.coderhelm.com/plugins

A plugin packages instructions, agents, tools, triggers and outputs so CoderHelm can do work for any team, with the same safety it applies to code.

> Coming soon: this page describes work that is not on main yet.

<Callout type="info" title="Coming soon">Plugins are being built and switched on team by team; they are not on main yet. This page follows the work in progress and will be updated when plugins ship.</Callout>

A **plugin** lets a team other than engineering put CoderHelm to work: marketing, support, sales operations, anyone. It brings its own instructions, agents and tools, says what starts it and what it produces, and CoderHelm runs it with the same safety it applies to code: pinned versions, a person's approval before anything goes out, metered tokens and a full record of every step.

For example, the [marketing plugin](/plugins/walkthrough) reads each release, drafts a blog post, three LinkedIn posts and an email in the team's brand voice, and waits for an editor to approve one before anything is published.

## A plugin is text plus approved tools [#a-plugin-is-text-plus-approved-tools]

A plugin is a folder in a git repo with a small manifest, `plugin.yaml`. It contains no code that CoderHelm runs.

- **Skills and agents** are Markdown, in the same format as [skill repos](/concepts/skills) and Claude Code. They are the plugin's behavior.
- **Tools** are declared in the manifest, each with a risk level. A tool that isn't declared does not exist for the plugin.
- **Settings** are the values each team fills in: a brand guide, an account to post from.
- **Triggers** say what starts a run: a person's brief, a schedule, a release.
- **Outputs** say what a run produces: drafts to review, and what may be published once approved.

```yaml title="plugin.yaml"
name: marketing
version: 1.0.0
description: Drafts launch posts from each release for an editor to approve.
tools:
  - ref: mcp:sanity
    allow: [query_documents, create_draft]
    risk: write
triggers:
  - on: github.release
outputs:
  - type: draft
    kinds: [blog, social]
```

Adding a plugin needs no deploy and no code from CoderHelm. Every field is listed in the [manifest reference](/plugins/manifest-reference).

## How a run works [#how-a-run-works]

```txt
trigger (brief, schedule, release)
  └─► plugin run ─► agent with only the granted tools ─► drafts
                                                           └─► approval ─► publish now or at a set time
```

1. A trigger starts a run, with the plugin's pinned version, the inputs and who asked.
2. The plugin's agent works with exactly the tools the manifest grants. A repository is optional.
3. What it makes is saved as **drafts** in the review queue (**Plugins** → **Review**).
4. A person approves a specific version of a draft. Only then can a consequential tool, such as publish, run.

## Words used in these docs [#words-used-in-these-docs]

| Word | Meaning |
| --- | --- |
| Plugin | The package: a repo with `plugin.yaml`. |
| Source | A git repository plugins come from. An admin adds it on the Plugins page. |
| Install | An admin adds a plugin from a source to the team, pinned to an exact version. |
| Connection | An outside account the plugin uses (a CMS, LinkedIn). Connected separately from installing. |
| Run | One piece of work by a plugin. |
| Draft | Something a run made, waiting for review. |
| Approval | A person's yes for one exact version of a draft. |

## In the dashboard [#in-the-dashboard]

| Page | What it is for |
| --- | --- |
| **Plugins** | Installed plugins, plugins you can install, plugin sources, and what plugins may do without a person. |
| A plugin's page | Its skills, agents and tools; settings; who approves; its monthly token limit; writing a brief. |
| **Review** | Drafts waiting for approval. |
| **Runs** | Every plugin run and what it produced. |
| **Audit log** | Every plugin step in one place. |
| **Connections** | The MCP servers your team has connected. A plugin declares which connections it needs; it is not itself a connection. |

Plugins are switched on team by team. Until then these pages say "Plugins are not turned on for this team".

## Next [#next]

- [Build the marketing plugin](/plugins/walkthrough), start to finish.
- [Repo layout](/plugins/layout) and the [manifest reference](/plugins/manifest-reference).
- [Security rules](/plugins/security) every plugin runs under.