Agent skills

Bird publishes agent skills: packaged procedure files a coding agent loads that teach it the bird CLI 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 (see 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:

Esempio di codice

/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 domains list, filtering for a verified sending capability) or run the setup loop: bird domains create → add the returned DNS records → bird 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.

Esempio di codice

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

Authenticate — bird auth status; log in only if needed.
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).
Send — email skill: bird email send …; success is 202 with an em_… ID and status: accepted.
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 is the execution surface — skills assume a shell-capable agent that can run it.
The MCP server is the alternative for agents that call tools instead of running commands; the operations are equivalent, the transport differs.
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.platform.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 page.

Client	Skills via plugin	MCP server bundled
Claude Code	Yes	Yes — connects to mcp.platform.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