# Skills, agents and tools

Source: https://docs.coderhelm.com/plugins/skills-agents-tools

How a plugin's agents are written, which tools they may call, and what read, write and consequential mean.

> 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>

## Skills [#skills]

A plugin's skills are ordinary [SKILL.md files](/concepts/skills#frontmatter): a name, a description that says when to use it, and instructions. They apply only to this plugin's runs; other plugins and the coding agents don't see them.

Use skills for what stays true across runs: the brand voice, a checklist, the format of a support reply.

## Agents [#agents]

An agent file is Markdown with frontmatter. The body is the agent's instructions for a run.

You write launch content for the team's product.

## What you get [#what-you-get]

- On a release: read the release notes CoderHelm wrote, and the merged pull requests in it, with `get_release_notes`.
- On the weekly schedule: the releases since last Monday. If there were none, stop and save nothing.
- On a brief: the person's brief and the channels they picked.

## What you do [#what-you-do]

1. Read the `brand-voice` and `launch-checklist` skills.
2. Look up earlier posts on the same feature with `query_documents`, so you do not repeat them.
3. Write one draft per channel:
   - **blog**: save it in Sanity with `create_draft`, then save a `blog` draft that links to it.
   - **social**: three LinkedIn variants as separate `social` drafts.
   - **email**: one `email` draft with a subject line.
4. Run the launch checklist on each draft and fix what fails.

## What you never do [#what-you-never-do]

- Never call `publish_post` yourself. Publishing happens only after an editor
  approves a draft, and CoderHelm makes that call with the approved text.
- Never invent numbers, customers or quotes.

| Field | Meaning |
| --- | --- |
| `name` | The agent's id. Defaults to the file name. |
| `description` | One line saying what it does. |
| `tools` | The tools it uses. Each must be granted in `plugin.yaml`; the [validator](/plugins/testing) refuses any that aren't. |

The plugin's page in the dashboard lists its skills and agents under **Skills and agents**.

## Tools [#tools]

Tools are declared in the manifest's `tools` list, in one of two shapes.

**Tools from an MCP server** on the team's Connections page. List the tool names (or `*` globs) the plugin may call; every other tool on that server is hidden from the run.

```yaml
tools:
  - ref: mcp:sanity
    allow: [get_document, query_documents, create_draft]
    risk: write
```

**Named tools**: one of CoderHelm's built-in tools (`kind: builtin`), or a tool the plugin defines to call an outside service with the team's connection (`kind: http`).

```yaml
tools:
  - name: get_release_notes
    kind: builtin
    risk: read
  - name: publish_post
    kind: http
    description: Publish an approved post to the company's LinkedIn page.
    risk: consequential
```

The plugin's page shows every tool and its risk under **What it can do**.

## Risk levels [#risk-levels]

Every tool has one of three risk levels.

| Risk | Means | Runs |
| --- | --- | --- |
| `read` | Only looks: search, fetch, list. | Whenever the agent calls it. |
| `write` | Changes something a person can still review before anyone sees it, such as a draft in a CMS. | Only if the team lets plugins save drafts without a person (below). |
| `consequential` | Reaches people or money: publish, send, post. | Only through a `publish` output, after a person approves the exact version of a draft. |

## What may happen without a person [#what-may-happen-without-a-person]

Each team chooses, on the **Plugins** page, the most a plugin may do on its own:

- **Plugins only read without a person**: every write waits for a yes too.
- **Plugins may save drafts without a person** (read and save drafts).

Publishing, sending and posting always wait for an approval, whatever the team picks.

A tool missing from the manifest can't be called, by any agent, in any run.