Agent skills
Bird 发布了 agent skills：打包的流程文件，教会编码 agent bird CLI 工作流。一个 skill 提供操作的正常路径、需要先运行的状态检查，以及浪费循环迭代的陷阱。这些指引帮助 agent 直接找到正确的命令，无需从 --help 输出中重新摸索参数和失败模式。
它们以 bird-ai marketplace 插件的形式发布，Claude Code、Cursor、Codex 和 GitHub Copilot 都能将其作为插件读取。Factory Droid 需要手动复制 skill 文件（见安装插件）。在 Claude Code 上，安装插件还会注册托管的 MCP 服务器，之后你需要使用 /mcp 登录一次（见 Skills、插件和 MCP）。
每个参考编码每个任务一个操作。Agent 选择与请求匹配的那个。除了共享的身份验证前提之外，它们没有顺序要求。
安装插件
Marketplace 位于 messagebird/bird-ai。该插件遵循 Agent Plugins 规范，因此实现了该规范的客户端可以直接从该仓库安装，skills 和 MCP 服务器一起安装。
以下是各客户端的具体步骤。在 Claude Code 上，运行：
代码示例
claude plugin marketplace add messagebird/bird-ai
claude plugin install bird@bird-ai在 Cursor 上，添加 marketplace 并从 Settings > Plugins 安装 bird 插件。在 Codex 上，运行 codex plugin marketplace add messagebird/bird-ai，然后运行 codex plugin add bird@bird-ai。在 GitHub Copilot 上，运行 copilot plugin marketplace add messagebird/bird-ai，然后运行 copilot plugin install bird@bird-ai。Factory Droid 没有可读取的插件格式：克隆 messagebird/bird-ai，手动将 plugins/bird/skills/ 中的两个 skill 目录复制到 .factory/skills/。
Skills
插件中包含两个 skills。
bird-cli 是通用 skill。它将请求路由到每个 CLI 命令组的一个参考，这样 agent 只加载当前操作的页面，不加载其他内容。其路由表涵盖：在 Bird 运行的所有渠道上发送和检查消息、每个渠道发送前所需的设置、一次性验证码验证、收件人查找、联系人和受众、消息偏好设置、Realtime 配置、webhooks、API 密钥、支持工单和文档搜索。该 skill 自身的 SKILL.md 中包含该路由表，且它是权威列表：本页面有意不复制它，因为第二份副本终将过时。
所有条目都有一个值得在此说明的共同行为，因为这是 agent 最容易出错的地方：发送操作返回 202 和 status: accepted，表示 Bird 已接收消息但投递仍在进行中。Skills 教会 agent 回读消息以获取最终结果，而不是在 accepted 时就宣告成功。
email-audit 是一个专用 skill。它运行 bird email tools audit <domain> 来解析并评估域名的实时 DMARC、SPF、DKIM、BIMI 和 MX 记录，然后将带严重性标签的发现作为优先修复列表返回。它仅涉及 DNS，因此不需要身份验证，也不会发送邮件。
共享前提：先进行身份验证
几乎所有操作都访问实时 Bird API，因此 bird-cli 在每个操作开始时通过 bird auth status 确认凭据。该检查是幂等的，当 CLI 已报告 valid: true 时不会执行任何操作，所以每次先运行它都是安全的。如果缺少该检查，未登录的失败表现与真正的 API 错误完全相同，可能使 agent 走上错误的调试路径。
例外情况是读取公共内容而非你的工作区的操作：email-audit 解析 DNS，文档搜索读取已发布的文档。两者都不需要登录，也不会因未登录而被阻止。
代码示例
bird auth status --format json
# gate on "valid": true, then run the operation如果缺少凭据，skill 会引导 agent 通过 bird auth login 完成身份验证后返回任务。身份验证使用浏览器，对无界面主机使用设备码流程，因此工作流不会在身份验证提示处卡住。
失败以统一方式呈现
因为每个操作都是对实时 API 的薄封装，失败通过 CLI 的统一契约返回，而不是通过各 skill 单独的错误处理：
- 默认 JSON：成功时将结构化 JSON 输出到 stdout，错误输出到 stderr，agent 的循环可以直接解析结果，无需抓取文本。
- 语义退出码：六个退出码之一在 agent 读取消息之前就告知失败类别。完整表格见 CLI。Agent 根据类别分支，无需解析消息：退出码 4 表示重新运行身份验证步骤，退出码 3 表示资源 ID 错误，重试无效。
这与 CLI 向人类和脚本提供的契约相同。Skills 没有添加额外层；它们教会 agent 使用现有契约。完整契约（包括输出格式和配置）见 CLI for agents。
将 skills 组合为 agent 循环
因为每个参考都是一个自检操作且结果可机器读取，它们可以无需粘合代码地组合为循环。例如，"send the launch email and confirm it delivered" 分解如下：
- 身份验证：运行 bird auth status；仅在需要时登录。
- 查找发件人：使用域名参考在已验证的域上选择一个 from 地址。退出码 0 加上 JSON 中有已验证的域表示此步骤完成；否则进入创建并验证的循环。
- 发送：使用邮件参考运行 bird email send …。成功的请求返回 202、一个 em_… ID 和 status: accepted。
- 确认结果：再次使用邮件参考运行 bird email get <em_…>，直到计数显示 delivered。如果显示 bounced，则报告失败。
每一步的 "done when" 条件都可以从上一步的 JSON 输出中检查，这正是循环可靠的原因：agent 永远不需要从文本中推断状态。
Skills、插件和 MCP
Skills 是将 agent 指向 Bird 的三种方式之一，它们是分层而非竞争关系：
- bird CLI 是执行层。Skills 假定 agent 具有 shell 能力，可以运行它。
- MCP 服务器是调用工具而非运行命令的 agent 的替代方案；操作等价，传输方式不同。
- AI onboarding 是引导式的设置路径，可以在几分钟内连接好任一方式。
插件安装是否同时配置 MCP 服务器取决于客户端。Claude Code 允许插件声明远程 MCP 服务器，因此在该客户端安装 bird-ai 会自动为你注册 https://mcp.bird.com。OpenCode 的插件也会注册服务器：默认注册 https://mcp.bird.com/dynamic，开启 OpenCode 的实验性代码模式后则注册完整的 https://mcp.bird.com。其他客户端支持远程 MCP，但其插件无法预先声明服务器。在 Cursor、Codex 和 Copilot 上，插件会安装技能文件；在 Droid 上，你需要手动复制技能文件。这些客户端需要手动添加服务器，使用 MCP 服务器指南中的单行配置即可。
插件无法替你完成身份验证。托管服务器受 OAuth 保护，因此在所有客户端（包括 Claude Code）上，你都需要在服务器注册后登录一次：在 Claude Code 中依次点击 /mcp，选择 bird，然后点击 Authenticate。在此之前，工具虽然会列出但每次调用都会失败。其余步骤见各客户端的身份验证步骤。
| 客户端 | 通过插件获取 Skills | MCP 服务器已注册 | 登录 |
|---|---|---|---|
| Claude Code | 是 | 是，由插件声明 | 你：/mcp > bird > Authenticate |
| Cursor | 是 | 手动，添加远程服务器一次 | 你：Tools & Integrations 中的 Needs login |
| Codex | 是 | 手动，添加远程服务器一次 | 你：codex mcp login bird |
| GitHub Copilot | 是 | 手动，添加远程服务器一次 | VS Code 首次启动时打开浏览器 |
| Factory Droid | 手动，复制 skill 文件 | 手动，添加远程服务器一次 | 你：在 droid 内运行 /mcp |
| OpenCode | 是 | 是，由插件声明 | 你：opencode mcp auth bird |
后续步骤
- 设置你的编码 agent：一条提示即可完成设置并自动安装插件。
- MCP 服务器：插件捆绑的工具层，以及如何手动添加。
- CLI for agents：skills 教授的命令层，适用于具有 shell 能力的 agent。
- AI onboarding：引导式的端到端设置，包含文档语料库的接入。