Habilidades del agente

Bird publica habilidades del agente (agent skills): archivos de procedimiento empaquetados que enseñan a un agente de codificación los flujos de trabajo del CLI bird. Una habilidad proporciona la ruta exitosa de la operación, las comprobaciones de estado que debe ejecutar primero y las trampas que desperdician iteraciones del bucle. Esta guía ayuda al agente a llegar al comando correcto sin redescubrir flags y modos de fallo a partir de la salida de --help.

Se distribuyen como el plugin de marketplace bird-ai, una única fuente que Claude Code, Cursor, Codex y GitHub Copilot leen como plugin. Factory Droid en cambio copia los archivos de habilidades manualmente (ver Instalar el plugin). En Claude Code, instalar el plugin también registra el servidor MCP alojado, al que luego inicias sesión una vez con /mcp (ver Habilidades, el plugin y MCP).

Cada referencia codifica una operación por tarea. El agente elige la que corresponda a la solicitud. Aparte del prerrequisito compartido de autenticación, no tienen un orden.

Instalar el plugin

El marketplace se encuentra en messagebird/bird-ai. El plugin sigue Agent Plugins, por lo que un cliente que implemente la especificación lo instala desde ese repositorio tal cual, habilidades y servidor MCP juntos.

Los pasos por cliente a continuación cubren el resto. En Claude Code, ejecuta:

Ejemplo de código

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

En Cursor, añade el marketplace e instala el plugin bird desde Settings > Plugins. En Codex, ejecuta codex plugin marketplace add messagebird/bird-ai, luego codex plugin add bird@bird-ai. En GitHub Copilot, ejecuta copilot plugin marketplace add messagebird/bird-ai, luego copilot plugin install bird@bird-ai. Factory Droid no tiene un formato de plugin que leer: clona messagebird/bird-ai y copia ambos directorios de habilidades de plugins/bird/skills/ en .factory/skills/ manualmente.

Las habilidades

El plugin incluye dos habilidades.

bird-cli es la general. Dirige una solicitud a una referencia por grupo de comandos del CLI, de modo que el agente carga la página de la operación que tiene delante y nada más. Su tabla de enrutamiento abarca el envío e inspección de mensajes en cada canal que Bird opera, la configuración que necesita cada canal antes de poder enviar, verificación de códigos de un solo uso, búsqueda de destinatarios, contactos y audiencias, preferencias de mensajería, aprovisionamiento de Realtime, webhooks, API keys, tickets de soporte y búsqueda en la documentación. El propio SKILL.md de la habilidad contiene esa tabla, y es la lista autoritativa: esta página deliberadamente no la copia, porque una segunda copia es una copia que se desactualiza.

Todas las entradas comparten un hábito que vale la pena mencionar aquí, porque es el que los agentes cometen mal: un envío devuelve 202 con status: accepted, lo que significa que Bird aceptó el mensaje y la entrega aún está pendiente. Las habilidades enseñan al agente a releer el mensaje para conocer el resultado final en lugar de declarar éxito con accepted.

email-audit es una especialista. Ejecuta bird email tools audit <domain> para resolver y calificar los registros DMARC, SPF, DKIM, BIMI y MX en producción de un dominio, luego lee los hallazgos etiquetados por severidad como una lista priorizada de correcciones. Es solo DNS, por lo que no necesita autenticación y no envía correo.

El prerrequisito compartido: autenticarse primero

Casi cada operación accede a la API en producción de Bird, por lo que bird-cli comienza cada una confirmando las credenciales con bird auth status. La comprobación es idempotente y no hace nada cuando el CLI ya reporta valid: true, por lo que es seguro ejecutarla siempre primero. Sin ella, la ausencia de inicio de sesión falla de forma idéntica a un error real de la API y puede llevar al agente por la ruta de depuración equivocada.

Las excepciones son las operaciones que leen algo público en lugar de tu workspace: email-audit resuelve DNS, y la búsqueda en la documentación lee los docs publicados. Ninguna necesita inicio de sesión, y ninguna se bloquea por la ausencia de uno.

Ejemplo de código

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

Si faltan las credenciales, la habilidad dirige al agente a través de bird auth login y de vuelta a la tarea. La autenticación usa un navegador, con un flujo de código de dispositivo para hosts sin interfaz gráfica, por lo que el flujo de trabajo no se detiene en un prompt de autenticación.

Los fallos se manifiestan de la misma manera en todas partes

Dado que cada operación es un wrapper delgado sobre la API en producción, los fallos se devuelven a través del contrato uniforme del CLI en lugar de un manejo de errores por habilidad:

JSON por defecto: Los éxitos imprimen JSON estructurado en stdout y los errores van a stderr, por lo que el bucle del agente puede analizar los resultados sin extraer texto de prosa.
Códigos de salida semánticos: uno de seis códigos indica al agente la categoría del fallo antes de que lea un mensaje. Consulta la tabla completa en CLI. El agente bifurca según la categoría sin analizar el mensaje: salida 4 significa volver a ejecutar el paso de autenticación, y salida 3 significa que el ID del recurso es incorrecto, por lo que reintentar no ayudará.

Este es el mismo contrato que el CLI presenta a humanos y scripts. Las habilidades no añaden ninguna capa; enseñan al agente a usar el contrato existente. Consulta CLI para agentes para el contrato completo, incluyendo formatos de salida y configuración.

Componer habilidades en un bucle del agente

Dado que cada referencia es una operación autocomprobable con un resultado legible por máquina, se componen en un bucle sin código de unión. Por ejemplo, "envía el correo de lanzamiento y confirma que se entregó" se descompone así:

Autenticarse: Ejecuta bird auth status; iniciar sesión solo si es necesario.
Encontrar un remitente: Usa la referencia de dominios para elegir una dirección from en un dominio verificado. Salida 0 más un dominio verificado en el JSON significa que este paso está completo; de lo contrario, entrar en el bucle de crear y verificar.
Enviar: Usa la referencia de correo electrónico para ejecutar bird email send …. Una solicitud exitosa devuelve 202, un ID em_… y status: accepted.
Confirmar el resultado: Usa la referencia de correo electrónico de nuevo para ejecutar bird email get <em_…> hasta que los contadores muestren delivered. Si muestran bounced, reportar el fallo.

La condición de "completado cuando" de cada paso es verificable a partir de la salida JSON del paso anterior, que es lo que hace que el bucle sea fiable: el agente nunca tiene que inferir estado a partir de texto en prosa.

Habilidades, el plugin y MCP

Las habilidades son una de tres maneras de conectar un agente con Bird, y se complementan en lugar de competir:

El CLI bird es la superficie de ejecución. Las habilidades asumen un agente con capacidad de shell que puede ejecutarlo.
El servidor MCP es la alternativa para agentes que invocan herramientas en lugar de ejecutar comandos; las operaciones son equivalentes, el transporte difiere.
La incorporación con IA es la ruta de configuración guiada que conecta cualquiera de los dos en minutos.

Que la instalación del plugin también configure el servidor MCP depende del cliente. Claude Code permite que un plugin declare un servidor MCP remoto, por lo que instalar bird-ai allí registra https://mcp.bird.com automáticamente. Los otros clientes soportan MCP remoto, pero sus plugins no pueden pre-declarar un servidor. En Cursor, Codex y Copilot, el plugin instala las habilidades; en Droid, copias los archivos de habilidades manualmente. Todos los clientes excepto Claude Code necesitan que el servidor se añada manualmente, usando la configuración de una línea en la guía del servidor MCP.

Lo que ningún plugin puede hacer es autenticarte. El servidor alojado está protegido con OAuth, por lo que en cada cliente, incluido Claude Code, inicias sesión una vez después de que el servidor está registrado: en Claude Code eso es /mcp, luego selecciona bird, luego Authenticate. Hasta que lo hagas, las herramientas aparecen listadas y cada llamada falla. Los pasos de autenticación por cliente cubren el resto.

Cliente	Habilidades vía plugin	Servidor MCP registrado	Inicio de sesión
Claude Code	Sí	Sí, declarado por el plugin	Tú: /mcp > bird > Authenticate
Cursor	Sí	Manual, añadir el servidor remoto una vez	Tú: Needs login en Tools & Integrations
Codex	Sí	Manual, añadir el servidor remoto una vez	Tú: codex mcp login bird
GitHub Copilot	Sí	Manual, añadir el servidor remoto una vez	VS Code abre el navegador en el primer inicio
Factory Droid	Manual, copiar los archivos de habilidades	Manual, añadir el servidor remoto una vez	Tú: /mcp dentro de droid

Próximos pasos

Configura tu agente de codificación: la configuración con un solo prompt que instala el plugin por ti.
Servidor MCP: la superficie de herramientas que incluye el plugin, y cómo añadirlo manualmente.
CLI para agentes: la superficie de comandos que enseñan las habilidades, para agentes con capacidad de shell.
Incorporación con IA: la configuración guiada de extremo a extremo con el corpus de documentación conectado.