Agent skills

Bird publishes agent skills: packaged procedure files that teach a coding agent the bird CLI workflows. A skill provides the operation's happy path, the state checks to run first, and the traps that waste loop iterations. This guidance helps the agent reach a correct command without rediscovering flags and failure modes from --help output.

They ship as the bird-ai marketplace plugin, one source that Claude Code, Cursor, Codex, and GitHub Copilot each read as a plugin. Factory Droid instead copies the skill files in by hand (see Install the plugin). On Claude Code, installing the plugin also registers the hosted MCP server, which you then sign in to once with /mcp (see Skills, the plugin, and MCP).

Each skill encodes one operation per task. The agent picks the one that matches the request. Apart from the shared authentication prerequisite, the skills have no ordering.

Install the plugin

The marketplace lives at messagebird/bird-ai. On Claude Code, run:

Code example

claude plugin marketplace add messagebird/bird-ai
claude plugin install bird@bird-ai

On Cursor, add the marketplace and install the bird plugin from Settings > Plugins. On Codex, run codex plugin marketplace add messagebird/bird-ai, then codex plugin add bird@bird-ai. On GitHub Copilot, run copilot plugin marketplace add messagebird/bird-ai, then copilot plugin install bird@bird-ai. Factory Droid has no plugin format to read: clone messagebird/bird-ai and copy plugins/bird/skills/bird-cli into .factory/skills/bird-cli by hand.

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. A send returns 202 with status: accepted, which means Bird took the message and delivery is pending. The skill teaches the agent to read the message back for the final outcome instead of declaring success at accepted.
Manage sending domains, and find a verified from: A message's from address must be on a verified sending domain. Before a send, the skill has the agent find a usable sender with bird email domains list or run the setup loop: bird email domains create → add the returned DNS records → bird email domains verify → repeat until verified. DNS propagation is asynchronous, so verification immediately after creation usually still reads pending.
Manage outbound webhook endpoints: Register, list, inspect, test, and delete the endpoints Bird delivers events to. The skill tells the agent to capture the create-time-only signing secret from the create response because it is never returned again. It also warns 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 by confirming credentials with bird auth status. The check is idempotent and does nothing when the CLI already reports valid: true, so it is safe to run first every time. Without it, a missing login fails identically to a real API error and can send the agent down the wrong debugging path.

Code example

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 and back to the task. Authentication uses a browser, with a device-code flow for headless hosts, so the workflow does not stall at an authentication prompt.

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 and errors go to stderr, so the agent's loop can parse outcomes without scraping prose.
Semantic exit codes: one of six codes tells the agent the failure category before it reads a message. See the full table in CLI. The agent branches on the category without parsing the message: exit 4 means re-run the auth step, and exit 3 means the resource ID is wrong, so retrying does not help.

This is the same contract the CLI presents to humans and scripts. The skills add no layer; they teach the agent to use the existing contract. See CLI for agents for the full contract, including output formats and configuration.

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. For example, "send the launch email and confirm it delivered" decomposes as follows:

Authenticate: Run bird auth status; log in only if needed.
Find a sender: Use the domains skill to pick a from address on a verified domain. Exit 0 plus a verified domain in the JSON means this step is complete; otherwise, enter the create-and-verify loop.
Send: Use the email skill to run bird email send …. A successful request returns 202, an em_… ID, and status: accepted.
Confirm the outcome: Use the email skill again to run bird email get <em_…> until the counts show delivered. If they show bounced, report the failure.

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 guided 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 registers https://mcp.bird.com for you. Other clients support remote MCP, but their plugins cannot pre-declare a server. On Cursor, Codex, and Copilot, the plugin installs the skills; on Droid, you copy the skill files in by hand. Every client but Claude Code needs the server added manually, using the one-line configuration in the MCP server guide.

What no plugin can do is authenticate for you. The hosted server is OAuth-gated, so on every client, including Claude Code, you sign in once after the server is registered: in Claude Code that is /mcp, then select bird, then Authenticate. Until you do, the tools are listed and every call fails. The per-client authenticate steps cover the rest.

Client	Skills via plugin	MCP server registered	Sign-in
Claude Code	Yes	Yes, declared by the plugin	You: /mcp > bird > Authenticate
Cursor	Yes	Manual, add the remote server once	You: Needs login in Tools & Integrations
Codex	Yes	Manual, add the remote server once	You: codex mcp login bird
GitHub Copilot	Yes	Manual, add the remote server once	VS Code opens the browser on first start
Factory Droid	Manual, copy the skill files in	Manual, add the remote server once	You: /mcp inside droid

Next steps

Set up your coding agent: the one-prompt setup that installs the plugin for you.
MCP server: the tool surface the plugin bundles, and how to add it manually.
CLI for agents: the command surface the skills teach, for shell-capable agents.
AI onboarding: the guided, end-to-end setup with the docs corpus wired in.