# Agent skills

Bird publishes **agent skills**: packaged procedure files a coding agent loads that teach it the [`bird` CLI](/docs/ai/cli-for-agents) workflows. Instead of the agent rediscovering flags and failure modes from `--help` output, a skill hands it the operation's happy path, the state checks to run first, and the traps that waste loop iterations — so the agent gets to a correct command on the first try, not the fifth.

They ship as the **`bird-ai` marketplace plugin**, which installs the skills into Claude Code, Cursor, Codex, GitHub Copilot, and Factory Droid from one source — each reads the plugin's skills natively. On Claude Code, installing the plugin also wires up the [hosted MCP server](/docs/ai/mcp-server) (see [Skills, the plugin, and MCP](#skills-the-plugin-and-mcp) below).

Each skill encodes **one operation per task**. The agent picks the one that matches the request; there is no ordering among them beyond the shared authentication prerequisite below.

## Install the plugin

The marketplace lives at `messagebird/bird-ai`. On Claude Code, Copilot, and Droid — which read the Claude-format plugin manifest directly:

```text
/plugin marketplace add messagebird/bird-ai
/plugin install bird
```

On Cursor, add the marketplace and install the `bird` plugin from **Settings → Plugins** (or `/add-plugin bird`). On Codex, run `codex plugin marketplace add messagebird/bird-ai`, then `/plugins` inside `codex` and install the **bird** plugin. The skills install natively in every case.

## The operations

- **Send and inspect email** — send a message with `bird email send`, then answer "did it bounce?" with `bird email get <em_…>` or `bird email list --status bounced`. The skill encodes the critical distinction: a send returns `202` with `status: accepted`, which means Bird took the message — not that it landed. Delivery is asynchronous, so the skill teaches the agent to read the message back for the real outcome instead of declaring victory at `accepted`.
- **Manage sending domains, and find a verified `from`** — a message's `from` address must be on a **verified** sending domain, so before any send the skill has the agent find a usable sender (`bird email domains list`, filtering for a verified sending capability) or run the setup loop: `bird email domains create` → add the returned DNS records → `bird email domains verify` → repeat until `verified`. It also encodes the trap that DNS propagation is asynchronous — verifying immediately after creating almost always still reads `pending`.
- **Manage outbound webhook endpoints** — register, list, inspect, test, and delete the endpoints Bird delivers events to. The skill encodes the create-time-only signing secret (capture it from the create response; it is never returned again), and that `bird webhooks test` makes a real delivery to the live URL.

## The shared prerequisite: authenticate first

Every operation hits the **live Bird API**, so every skill starts the same way: confirm credentials with `bird auth status` before doing anything else. The check is idempotent — a no-op when the CLI already reports `valid: true` — so it is safe (and recommended) to run first every time. Without it, a missing login fails identically to a real API error, and the agent burns iterations debugging the wrong problem.

```bash
bird auth status --format json
# gate on "valid": true, then run the operation
```

If credentials are missing, the skill routes the agent through `bird auth login` (browser-based, with a device-code flow for headless hosts) and back to the task — it never stalls at "please authenticate".

## Failures surface the same way everywhere

Because every operation is a thin wrapper over the live API, failures come back through the CLI's uniform contract rather than per-skill error handling:

- **JSON by default** — successes print structured JSON to stdout, errors go to stderr, so the agent's loop can parse outcomes without scraping prose.
- **Semantic exit codes** — `2` invalid usage or input, `3` not found, `4` auth or permission denied, `1` anything else. The agent branches on the category without parsing the message: exit `4` means re-run the auth step; exit `3` means the resource ID is wrong, and retrying won't help.

This is the same contract the CLI presents to humans and scripts — the skills add no layer on top, they just teach the agent to use it. The full contract, including output formats and configuration, is on the [CLI for agents](/docs/ai/cli-for-agents) page.

## Composing skills into an agent loop

Because each skill is one self-checking operation with a machine-readable outcome, they compose into a loop without glue code. A realistic task — "send the launch email and confirm it delivered" — decomposes as:

1. **Authenticate** — `bird auth status`; log in only if needed.
2. **Find a sender** — domains skill: pick a `from` on a verified domain (exit `0` + a verified domain in the JSON, or fall into the create-and-verify loop).
3. **Send** — email skill: `bird email send …`; success is `202` with an `em_…` ID and `status: accepted`.
4. **Confirm the outcome** — email skill again: `bird email get <em_…>` until the counts show `delivered` (or `bounced`, in which case the agent reports the failure instead of guessing).

Each step's "done when" condition is checkable from the previous step's JSON output, which is what makes the loop reliable: the agent never has to infer state from prose.

## Skills, the plugin, and MCP

Skills are one of three ways to point an agent at Bird, and they layer rather than compete:

- The [`bird` CLI](/docs/ai/cli-for-agents) is the execution surface — skills assume a shell-capable agent that can run it.
- The [MCP server](/docs/ai/mcp-server) is the alternative for agents that call tools instead of running commands; the operations are equivalent, the transport differs.
- [AI onboarding](/docs/get-started/ai-onboarding) is the hand-held setup path that gets either one connected in minutes.

Whether the plugin install also configures the MCP server depends on the client. Claude Code lets a plugin declare a remote MCP server, so installing `bird-ai` there connects you to `https://mcp.bird.com` automatically. The other clients support remote MCP but don't let a plugin pre-declare it, so on Cursor, Codex, Copilot, and Droid the plugin ships the skills and you add the MCP server once by hand — the one-line config is on the [MCP server](/docs/ai/mcp-server) page.

| Client         | Skills via plugin | MCP server bundled                          |
| -------------- | ----------------- | ------------------------------------------- |
| Claude Code    | Yes               | Yes — connects to `mcp.bird.com` on install |
| Cursor         | Yes               | Manual — add the remote server once         |
| Codex          | Yes               | Manual — add the remote server once         |
| GitHub Copilot | Yes               | Manual — add the remote server once         |
| Factory Droid  | Yes               | Manual — add the remote server once         |

## Next steps

- [Set up your coding agent](/docs/ai/set-up-your-agent) — the one-prompt setup that installs the plugin for you.
- [MCP server](/docs/ai/mcp-server) — the tool surface the plugin bundles, and how to add it manually.
- [CLI for agents](/docs/ai/cli-for-agents) — the command surface the skills teach, for shell-capable agents.
- [AI onboarding](/docs/get-started/ai-onboarding) — the hand-held, end-to-end setup with the docs corpus wired in.