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 référence 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é, elles 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 les deux répertoires de compétences depuis plugins/bird/skills/ dans .factory/skills/ manuellement.

Les compétences

Deux compétences sont incluses dans le plugin.

bird-cli est la compétence générale. Elle route une requête vers une référence par groupe de commandes CLI, de sorte que l'agent charge la page correspondant à l'opération en cours et rien d'autre. Sa table de routage couvre l'envoi et l'inspection de messages sur chaque canal opéré par Bird, la configuration nécessaire à chaque canal avant de pouvoir envoyer, la vérification par code à usage unique, la recherche de destinataires, les contacts et audiences, les préférences de messagerie, le provisionnement Realtime, les webhooks, les clés API, les tickets de support et la recherche dans la documentation. Le fichier SKILL.md de la compétence contient cette table, et c'est la liste de référence : cette page ne la copie délibérément pas, car une seconde copie est une copie qui devient obsolète.

Toutes les entrées partagent une habitude qui mérite d'être mentionnée ici, car c'est celle que les agents se trompent : un envoi retourne 202 avec status: accepted, ce qui signifie que Bird a pris en charge le message et que la livraison est encore en attente. Les compétences enseignent à l'agent à relire le message pour connaître le résultat final au lieu de déclarer le succès à accepted.

email-audit est une compétence spécialisée. Elle exécute bird email tools audit <domain> pour résoudre et évaluer les enregistrements DMARC, SPF, DKIM, BIMI et MX actifs d'un domaine, puis lit les résultats annotés par niveau de sévérité sous forme de liste de corrections priorisée. Elle ne fait que du DNS, donc elle ne nécessite pas d'authentification et n'envoie aucun e-mail.

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

Presque chaque opération appelle l'API Bird en production, donc bird-cli commence chacune 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.

Les exceptions sont les opérations qui lisent quelque chose de public plutôt que votre espace de travail : email-audit résout du DNS, et la recherche dans la documentation lit la documentation publiée. Aucune des deux ne nécessite de connexion, et aucune n'est bloquée par une connexion manquante.

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 référence 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 référence 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 référence 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 référence 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é.