Compétences d'agent

Bird publie des compétences d'agent (agent skills) : des fichiers de procédures packagés qui enseignent à un agent de codage les workflows du CLI bird. Une compétence fournit le chemin nominal de l'opération, les vérifications d'état à exécuter en amont, et les pièges qui gaspillent des itérations de boucle. Ces indications aident l'agent à atteindre une commande correcte sans redécouvrir les options et les modes d'échec à partir de la sortie --help.

Elles sont distribuées sous forme du plugin marketplace bird-ai, une source unique que Claude Code, Cursor, Codex et GitHub Copilot lisent chacun comme un plugin. Factory Droid copie plutôt les fichiers de compétences manuellement (voir Installer le plugin). Sur Claude Code, l'installation du plugin enregistre également le serveur MCP hébergé, auquel vous vous connectez ensuite une seule fois avec /mcp (voir Compétences, le plugin et MCP).

Chaque compétence encode une opération par tâche. L'agent sélectionne celle qui correspond à la requête. En dehors du prérequis d'authentification partagé, les compétences n'ont pas d'ordre.

Installer le plugin

Le marketplace se trouve à messagebird/bird-ai. Le plugin suit la spécification Agent Plugins, donc un client qui implémente la spécification l'installe depuis ce dépôt tel quel, compétences et serveur MCP ensemble.

Les étapes par client ci-dessous couvrent le reste. Sur Claude Code, exécutez :

Exemple de code

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

Sur Cursor, ajoutez le marketplace et installez le plugin bird depuis Settings > Plugins. Sur Codex, exécutez codex plugin marketplace add messagebird/bird-ai, puis codex plugin add bird@bird-ai. Sur GitHub Copilot, exécutez copilot plugin marketplace add messagebird/bird-ai, puis copilot plugin install bird@bird-ai. Factory Droid n'a pas de format de plugin à lire : clonez messagebird/bird-ai et copiez plugins/bird/skills/bird-cli dans .factory/skills/bird-cli manuellement.

Les opérations

Envoyer et inspecter des e-mails : envoyer un message avec bird email send, puis répondre à « a-t-il rebondi ? » avec bird email get <em_…> ou bird email list --status bounced. Un envoi retourne 202 avec status: accepted, ce qui signifie que Bird a pris en charge le message et que la livraison est en attente. La compétence apprend à l'agent à relire le message pour connaître le résultat final au lieu de déclarer le succès à accepted.
Gérer les domaines d'envoi et trouver un from vérifié : l'adresse from d'un message doit être sur un domaine d'envoi vérifié. Avant un envoi, la compétence demande à l'agent de trouver un expéditeur utilisable avec bird email domains list ou d'exécuter la boucle de configuration : bird email domains create → ajouter les enregistrements DNS retournés → bird email domains verify → répéter jusqu'à verified. La propagation DNS est asynchrone, donc la vérification immédiatement après la création retourne généralement encore pending.
Gérer les endpoints de webhooks sortants : enregistrer, lister, inspecter, tester et supprimer les endpoints auxquels Bird livre les événements. La compétence indique à l'agent de capturer le secret de signature disponible uniquement à la création depuis la réponse de création car il n'est jamais retourné par la suite. Elle prévient également que bird webhooks test effectue une livraison réelle vers l'URL active.

Le prérequis partagé : s'authentifier d'abord

Chaque opération appelle l'API Bird en production, donc chaque compétence commence par confirmer les identifiants avec bird auth status. La vérification est idempotente et ne fait rien quand le CLI rapporte déjà valid: true, donc elle est sûre à exécuter systématiquement en premier. Sans elle, une connexion manquante échoue de manière identique à une vraie erreur API et peut envoyer l'agent sur la mauvaise piste de débogage.

Exemple de code

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

Si les identifiants sont absents, la compétence oriente l'agent vers bird auth login puis revient à la tâche. L'authentification utilise un navigateur, avec un flux device-code pour les hôtes sans interface graphique, donc le workflow ne reste jamais bloqué sur une invite d'authentification.

Les échecs remontent de la même manière partout

Comme chaque opération est un wrapper léger sur l'API en production, les échecs reviennent via le contrat uniforme du CLI plutôt que par une gestion d'erreurs propre à chaque compétence :

JSON par défaut : les succès affichent du JSON structuré sur stdout et les erreurs vont sur stderr, ce qui permet à la boucle de l'agent d'analyser les résultats sans scraper du texte libre.
Codes de sortie sémantiques : l'un des six codes indique à l'agent la catégorie d'échec avant qu'il ne lise un message. Voir le tableau complet dans CLI. L'agent branche sur la catégorie sans analyser le message : un code de sortie 4 signifie relancer l'étape d'authentification, et un code 3 signifie que l'ID de la ressource est incorrect, donc réessayer n'aidera pas.

C'est le même contrat que le CLI présente aux humains et aux scripts. Les compétences n'ajoutent aucune couche ; elles enseignent à l'agent à utiliser le contrat existant. Voir CLI for agents pour le contrat complet, y compris les formats de sortie et la configuration.

Composer les compétences dans une boucle d'agent

Comme chaque compétence est une opération auto-vérifiante avec un résultat lisible par machine, elles se composent dans une boucle sans code de liaison. Par exemple, « envoyer l'e-mail de lancement et confirmer qu'il a été livré » se décompose ainsi :

S'authentifier : exécuter bird auth status ; se connecter uniquement si nécessaire.
Trouver un expéditeur : utiliser la compétence domaines pour choisir une adresse from sur un domaine vérifié. Un code de sortie 0 plus un domaine vérifié dans le JSON signifie que cette étape est terminée ; sinon, entrer dans la boucle de création et vérification.
Envoyer : utiliser la compétence e-mail pour exécuter bird email send …. Une requête réussie retourne 202, un ID em_… et status: accepted.
Confirmer le résultat : utiliser la compétence e-mail à nouveau pour exécuter bird email get <em_…> jusqu'à ce que les compteurs montrent delivered. S'ils montrent bounced, signaler l'échec.

La condition « terminé quand » de chaque étape est vérifiable à partir de la sortie JSON de l'étape précédente, ce qui rend la boucle fiable : l'agent n'a jamais à inférer l'état à partir de texte libre.

Compétences, le plugin et MCP

Les compétences sont l'un des trois moyens de connecter un agent à Bird, et ils se superposent plutôt que de se concurrencer :

Le CLI bird est la surface d'exécution. Les compétences supposent un agent capable d'exécuter des commandes shell.
Le serveur MCP est l'alternative pour les agents qui appellent des outils au lieu d'exécuter des commandes ; les opérations sont équivalentes, le transport diffère.
L'onboarding IA est le parcours de configuration guidé qui connecte l'un ou l'autre en quelques minutes.

Le fait que l'installation du plugin configure également le serveur MCP dépend du client. Claude Code permet à un plugin de déclarer un serveur MCP distant, donc installer bird-ai y enregistre https://mcp.bird.com pour vous. Les autres clients supportent le MCP distant, mais leurs plugins ne peuvent pas pré-déclarer un serveur. Sur Cursor, Codex et Copilot, le plugin installe les compétences ; sur Droid, vous copiez les fichiers de compétences manuellement. Tous les clients sauf Claude Code nécessitent l'ajout manuel du serveur, en utilisant la configuration en une ligne du guide du serveur MCP.

Ce qu'aucun plugin ne peut faire, c'est s'authentifier à votre place. Le serveur hébergé est protégé par OAuth, donc sur chaque client, y compris Claude Code, vous vous connectez une fois après l'enregistrement du serveur : dans Claude Code c'est /mcp, puis sélectionnez bird, puis Authenticate. Tant que vous ne le faites pas, les outils sont listés mais chaque appel échoue. Les étapes d'authentification par client couvrent le reste.

Client	Compétences via plugin	Serveur MCP enregistré	Connexion
Claude Code	Oui	Oui, déclaré par le plugin	Vous : /mcp > bird > Authenticate
Cursor	Oui	Manuel, ajouter le serveur distant une fois	Vous : Needs login dans Tools & Integrations
Codex	Oui	Manuel, ajouter le serveur distant une fois	Vous : codex mcp login bird
GitHub Copilot	Oui	Manuel, ajouter le serveur distant une fois	VS Code ouvre le navigateur au premier lancement
Factory Droid	Manuel, copier les fichiers de compétences	Manuel, ajouter le serveur distant une fois	Vous : /mcp dans droid

Étapes suivantes

Configurer votre agent de codage : la configuration en un prompt qui installe le plugin pour vous.
Serveur MCP : la surface d'outils fournie par le plugin, et comment l'ajouter manuellement.
CLI for agents : la surface de commandes enseignée par les compétences, pour les agents capables d'exécuter des commandes shell.
Onboarding IA : la configuration guidée de bout en bout avec le corpus de documentation intégré.