Skill per agenti

Bird pubblica le agent skill: file di procedura pacchettizzati che insegnano a un coding agent i workflow della bird CLI. Una skill fornisce il percorso corretto dell'operazione, i controlli di stato da eseguire prima e le trappole che sprecano iterazioni del loop. Questa guida aiuta l'agente a raggiungere il comando corretto senza riscoprire flag e modalità di errore dall'output di --help.

Sono distribuite come plugin marketplace bird-ai, un'unica sorgente che Claude Code, Cursor, Codex e GitHub Copilot leggono ciascuno come plugin. Antigravity installa un pacchetto costruito dalla stessa sorgente, e Factory Droid copia i file di skill manualmente (vedi Installare il plugin). Su Claude Code, l'installazione del plugin registra anche il server MCP hosted, a cui poi accedi una sola volta con /mcp (vedi Skill, plugin e MCP).

Ogni riferimento codifica un'operazione per task. L'agente sceglie quello corrispondente alla richiesta. A parte il prerequisito condiviso di autenticazione, non hanno un ordine.

Installare il plugin

Il marketplace si trova su messagebird/bird-ai. Il plugin segue la specifica Agent Plugins, quindi un client che la implementa lo installa da quel repository così com'è, skill e server MCP insieme.

I passaggi per client qui sotto coprono il resto. Su Claude Code, esegui:

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

Su Cursor, aggiungi Bird dal Cursor Marketplace o esegui /add-plugin bird. Puoi anche aggiungere il marketplace e installare il plugin bird da Settings > Plugins. Su ChatGPT e Codex, installa Bird in Codex o ChatGPT. Accedi al tuo spazio di lavoro Bird, poi chiedi al tuo agente di lavorare con Bird. In alternativa da terminale, esegui codex plugin marketplace add messagebird/bird-ai, poi codex plugin add bird@bird-ai. Su GitHub Copilot, esegui copilot plugin marketplace add messagebird/bird-ai, poi copilot plugin install bird@bird-ai. Su Antigravity, esegui curl -fsSL https://raw.githubusercontent.com/messagebird/bird-ai/main/antigravity.sh | bash, che installa il plugin in ~/.gemini/config/plugins/bird per ogni spazio di lavoro. Il README del repository descrive l'installazione per singolo progetto e Antigravity CLI. Factory Droid non ha un formato plugin da leggere: clona messagebird/bird-ai e copia entrambe le directory delle skill da plugins/bird/skills/ in .factory/skills/ manualmente.

Le skill

Il plugin contiene due skill.

bird-cli è quella generale. Instrada una richiesta a un riferimento per gruppo di comandi CLI, così l'agente carica la pagina dell'operazione che ha davanti e nient'altro. La sua tabella di routing copre invio e ispezione di messaggi su ogni canale supportato da Bird, la configurazione necessaria a ogni canale prima di poter inviare, verifica con codice monouso, ricerca destinatari, contatti e audience, preferenze di messaggistica, provisioning Realtime, webhook, chiavi API, ticket di supporto e ricerca nella documentazione. Il SKILL.md della skill contiene quella tabella ed è la lista autorevole: questa pagina deliberatamente non la replica, perché una seconda copia è una copia che diventa obsoleta.

Tutte le voci condividono un comportamento che vale la pena citare qui, perché è quello che gli agenti sbagliano: un invio restituisce 202 con status: accepted, il che significa che Bird ha accettato il messaggio e la consegna è ancora in corso. Le skill insegnano all'agente a rileggere il messaggio per il risultato finale invece di dichiarare successo al accepted.

email-audit è una skill specialistica. Esegue bird email tools audit <domain> per risolvere e valutare i record DMARC, SPF, DKIM, BIMI e MX attivi di un dominio, poi restituisce i risultati con tag di gravità come lista di correzioni prioritizzata. Opera solo su DNS, quindi non richiede autenticazione e non invia email.

Il prerequisito condiviso: autenticarsi prima

Quasi ogni operazione interroga la Bird API live, quindi bird-cli inizia ciascuna confermando le credenziali con bird auth status. Il controllo è idempotente e non fa nulla quando CLI riporta già valid: true, perciò è sicuro eseguirlo sempre per primo. Senza di esso, un login mancante fallisce in modo identico a un vero errore API e può portare l'agente su un percorso di debug sbagliato.

Le eccezioni sono le operazioni che leggono qualcosa di pubblico anziché il tuo spazio di lavoro: email-audit risolve il DNS e la ricerca nella documentazione legge i doc pubblicati. Nessuna delle due richiede un login, e nessuna delle due è bloccata da uno mancante.

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

Se le credenziali mancano, la skill guida l'agente attraverso bird auth login e poi lo riporta al task. L'autenticazione usa un browser, con un flusso device-code per gli host headless, quindi il workflow non si blocca a un prompt di autenticazione.

Gli errori emergono allo stesso modo ovunque

Poiché ogni operazione è un sottile wrapper sulla API live, gli errori tornano attraverso il contratto uniforme della CLI anziché tramite gestione degli errori per skill:

• JSON di default: i successi stampano JSON strutturato su stdout e gli errori vanno su stderr, così il loop dell'agente può analizzare i risultati senza estrarre testo libero.
• Codici di uscita semantici: uno dei sei codici comunica all'agente la categoria di errore prima che legga il messaggio. La tabella completa è in CLI. L'agente si dirama sulla categoria senza analizzare il messaggio: exit 4 significa rieseguire il passaggio di autenticazione, ed exit 3 significa che l'ID della risorsa è sbagliato, quindi riprovare non serve.

È lo stesso contratto che CLI presenta a umani e script. Le skill non aggiungono alcun livello: insegnano all'agente a usare il contratto esistente. Vedi CLI per agenti per il contratto completo, inclusi formati di output e configurazione.

Comporre le skill in un loop dell'agente

Poiché ogni riferimento è un'operazione autocontrollata con un risultato leggibile dalla macchina, le skill si compongono in un loop senza codice di raccordo. Per esempio, "send the launch email and confirm it delivered" si scompone così:

1. Autenticazione: esegui bird auth status; accedi solo se necessario.
2. Trovare un mittente: usa il riferimento domains per scegliere un indirizzo from su un dominio verificato. Exit 0 più un dominio verificato nell'JSON significa che questo passaggio è completo; altrimenti, entra nel loop di creazione e verifica.
3. Invio: usa il riferimento email per eseguire bird email send …. Una richiesta riuscita restituisce 202, un ID em_… e status: accepted.
4. Confermare il risultato: usa di nuovo il riferimento email per eseguire bird email get <em_…> finché i contatori mostrano delivered. Se mostrano bounced, riporta l'errore.

La condizione "done when" di ogni passaggio è verificabile dall'output JSON del passaggio precedente, ed è ciò che rende il loop affidabile: l'agente non deve mai dedurre lo stato dal testo.

Skill, plugin e MCP

Le skill sono uno dei tre modi per collegare un agente a Bird, e si sovrappongono anziché competere:

• La bird CLI è la superficie di esecuzione. Le skill presuppongono un agente con accesso alla shell che possa eseguirla.
• Il server MCP è l'alternativa per gli agenti che chiamano tool invece di eseguire comandi; le operazioni sono equivalenti, il trasporto è diverso.
• AI onboarding è il percorso di setup guidato che collega entrambi in pochi minuti.

Il fatto che l'installazione del plugin configuri anche il server MCP dipende dal client. Claude Code consente a un plugin di dichiarare un server MCP remoto, quindi installare bird-ai lì registra https://mcp.bird.com automaticamente. Anche il plugin di OpenCode registra il server: https://mcp.bird.com/dynamic per impostazione predefinita, oppure il completo https://mcp.bird.com con la modalità codice sperimentale di OpenCode attiva. L'inserzione nel Cursor Marketplace di Bird e il plugin di Antigravity includono il server. Il plugin Bird in Codex e ChatGPT include il server MCP e le skill di Bird. Su Copilot, il plugin installa le skill; su Droid, copi i file delle skill manualmente. Copilot e Droid richiedono l'aggiunta manuale del server, usando la configurazione in una riga nella guida al server MCP.

Quello che nessun plugin può fare è autenticarti. Il server hosted è protetto da OAuth, quindi su ogni client, incluso Claude Code, accedi una volta dopo che il server è registrato: in Claude Code è /mcp, poi seleziona bird, poi Authenticate. Fino a quel momento, i tool sono elencati ma ogni chiamata fallisce. I passaggi di autenticazione per client coprono il resto.

Prossimi passi

• Configura il tuo coding agent: il setup con un solo prompt che installa il plugin per te.
• Server MCP: la superficie tool inclusa nel plugin e come aggiungerla manualmente.
• CLI per agenti: la superficie comandi che le skill insegnano, per agenti con accesso alla shell.
• AI onboarding: il setup guidato end-to-end con il corpus di documentazione collegato.