文档
Sign inGet started
立即开始
指南
API 参考
SDK
CLI
知识库
更新日志

Agent 技能

Bird 发布了 agent 技能：打包的流程文件，教会编码 agent bird CLI 工作流。技能提供操作的正确路径、需要先运行的状态检查，以及浪费循环迭代的陷阱。这些指导帮助 agent 无需从 --help 输出中重新摸索标志和失败模式即可得到正确的命令。
它们以 bird-ai 市场插件 的形式发布，来源统一，Claude Code、Cursor、Codex 和 GitHub Copilot 都能作为插件读取。Factory Droid 则需要手动复制技能文件（参见安装插件）。在 Claude Code 上，安装插件还会注册托管 MCP 服务器，之后只需通过 /mcp 登录一次（参见技能、插件和 MCP）。
每个参考文档编码每个任务一个操作。Agent 选择与请求匹配的参考文档。除了共享身份验证前提条件外，它们之间没有顺序要求。

安装插件

市场位于 messagebird/bird-ai。该插件遵循 Agent Plugins 规范，因此实现了该规范的客户端可以直接从该仓库安装，技能和 MCP 服务器一起安装。
以下是各客户端的具体步骤。在 Claude Code 上，运行：
代码示例
claude plugin marketplace add messagebird/bird-ai
claude plugin install bird@bird-ai
在 Cursor 上，添加市场并从 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/ 中的两个技能目录复制到 .factory/skills/。

技能列表

插件中包含两个技能。
bird-cli 是通用技能。它将请求路由到每个 CLI 命令组的一个参考文档，这样 agent 只加载当前操作对应的页面，不加载其他内容。它的路由表涵盖在 Bird 运行的所有渠道上发送和检查消息、每个渠道发送前所需的设置、一次性密码验证、收件人查找、联系人和受众、消息偏好、Realtime 配置、webhook、API 密钥、支持工单和文档搜索。技能自身的 SKILL.md 携带该路由表，它是权威列表：本页面故意不复制它，因为第二份副本终将过时。
所有条目都有一个值得在此提及的共同习惯，因为这是 agent 最容易犯错的地方：发送返回 202 和 status: accepted，这意味着 Bird 接收了消息，投递仍在进行中。技能教会 agent 回读消息以获取最终结果，而不是在 accepted 时就宣布成功。
email-audit 是一个专用技能。它运行 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
如果缺少凭据，技能会引导 agent 通过 bird auth login 然后回到任务。身份验证使用浏览器，为无头主机提供设备码流程，因此工作流不会卡在身份验证提示处。

失败在所有地方以相同方式呈现

因为每个操作都是对实时 API 的薄封装，失败通过 CLI 的统一契约返回，而不是每个技能各自的错误处理：
  • 默认 JSON：成功时将结构化 JSON 打印到 stdout，错误输出到 stderr，因此 agent 的循环可以解析结果而无需抓取文本。
  • 语义退出码：六个退出码之一在 agent 读取消息之前就告知其失败类别。完整表格参见 CLI。Agent 根据类别分支，无需解析消息：退出码 4 表示重新运行身份验证步骤，退出码 3 表示资源 ID 错误，因此重试无济于事。
这与 CLI 向人类和脚本呈现的契约相同。技能没有添加任何层；它们教会 agent 使用现有契约。完整的契约，包括输出格式和配置，参见 CLI for agents。

将技能组合到 agent 循环中

因为每个参考文档都是一个自检操作并具有机器可读的结果，它们无需粘合代码即可组合成循环。例如，"发送发布邮件并确认已送达"分解如下：
  1. 身份验证：运行 bird auth status；仅在需要时登录。
  2. 找到发件人：使用域名参考文档在已验证域名上选择一个 from 地址。退出码 0 加上 JSON 中包含已验证域名表示此步骤完成；否则进入创建并验证循环。
  3. 发送：使用电子邮件参考文档运行 bird email send …。成功的请求返回 202、一个 em_… ID 和 status: accepted。
  4. 确认结果：再次使用电子邮件参考文档运行 bird email get <em_…> 直到计数显示 delivered。如果显示 bounced，则报告失败。
每个步骤的"完成条件"都可以从上一步骤的 JSON 输出中检查，这正是循环可靠的原因：agent 永远不需要从文本中推断状态。

技能、插件和 MCP

技能是将 agent 指向 Bird 的三种方式之一，它们是分层而非竞争的关系：
  • bird CLI 是执行层。技能假定 agent 具有 shell 能力并可以运行它。
  • MCP 服务器是面向调用工具而非运行命令的 agent 的替代方案；操作等价，传输方式不同。
  • AI 引导入门是引导式的设置路径，可在几分钟内连接好任一方式。
插件安装是否同时配置 MCP 服务器取决于客户端。Claude Code 允许插件声明远程 MCP 服务器，因此在那里安装 bird-ai 会为你注册 https://mcp.bird.com。其他客户端支持远程 MCP，但其插件无法预声明服务器。在 Cursor、Codex 和 Copilot 上，插件安装技能；在 Droid 上，你需要手动复制技能文件。除 Claude Code 外的每个客户端都需要手动添加服务器，使用 MCP 服务器指南中的一行配置。
插件无法做的是替你进行身份验证。托管服务器受 OAuth 保护，因此在每个客户端上（包括 Claude Code），你需要在服务器注册后登录一次：在 Claude Code 中是 /mcp，然后选择 bird，然后点击 Authenticate。在此之前，工具会被列出但每次调用都会失败。各客户端身份验证步骤涵盖了其余内容。
客户端通过插件获取技能MCP 服务器注册登录
Claude Code是是，由插件声明你：/mcp > bird > Authenticate
Cursor是手动，添加一次远程服务器你：Tools & Integrations 中的 Needs login
Codex是手动，添加一次远程服务器你：codex mcp login bird
GitHub Copilot是手动，添加一次远程服务器VS Code 在首次启动时打开浏览器
Factory Droid手动，复制技能文件手动，添加一次远程服务器你：在 droid 中运行 /mcp

后续步骤