Skill per agenti

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

Vengono distribuite come plugin marketplace bird-ai, un'unica fonte che Claude Code, Cursor, Codex e GitHub Copilot leggono ciascuno come plugin. Factory Droid invece copia i file delle skill manualmente (vedi Installare il plugin). Su Claude Code, l'installazione del plugin registra anche il server MCP ospitato, a cui poi si effettua l'accesso una sola volta con /mcp (vedi Skill, il plugin e MCP).

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

Installare il plugin

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

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

Esempio di codice

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

Su Cursor, aggiungere il marketplace e installare il plugin bird da Settings > Plugins. Su Codex, eseguire codex plugin marketplace add messagebird/bird-ai, poi codex plugin add bird@bird-ai. Su GitHub Copilot, eseguire copilot plugin marketplace add messagebird/bird-ai, poi copilot plugin install bird@bird-ai. Factory Droid non ha un formato plugin da leggere: clonare messagebird/bird-ai e copiare entrambe le directory delle skill da plugins/bird/skills/ in .factory/skills/ manualmente.

Le skill

Nel plugin sono incluse due skill.

bird-cli è quella generale. Instrada una richiesta a un riferimento per gruppo di comandi della CLI, in modo che l'agente carichi la pagina relativa all'operazione che ha davanti e nient'altro. La sua tabella di routing copre l'invio e l'ispezione di messaggi su ogni canale gestito da Bird, la configurazione necessaria a ciascun canale prima di poter inviare, la verifica con one-time-passcode, la ricerca di destinatari, contatti e audience, preferenze di messaggistica, provisioning Realtime, webhook, API key, ticket di supporto e ricerca nella documentazione. Il file 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.

Ogni voce condivide un'abitudine che vale la pena citare qui, perché è quella che gli agenti sbagliano: un invio restituisce 202 con status: accepted, il che significa che Bird ha preso in carico il messaggio e il recapito è ancora in sospeso. Le skill insegnano all'agente a rileggere il messaggio per conoscere l'esito finale invece di dichiarare successo al momento dell'accepted.

email-audit è una skill specialistica. Esegue bird email tools audit <domain> per risolvere e valutare i record DMARC, SPF, DKIM, BIMI e MX live di un dominio, poi rilegge le evidenze taggate per severità come lista di correzioni prioritizzata. È solo DNS, quindi non richiede autenticazione e non invia email.

Il prerequisito condiviso: autenticarsi prima

Quasi ogni operazione interagisce con l'API live di Bird, quindi bird-cli inizia ciascuna confermando le credenziali con bird auth status. Il controllo è idempotente e non fa nulla quando la CLI riporta già valid: true, quindi è sicuro eseguirlo sempre per primo. Senza di esso, un login mancante fallisce in modo identico a un errore API reale e può mandare l'agente sulla strada sbagliata di debugging.

Le eccezioni sono le operazioni che leggono qualcosa di pubblico anziché il vostro workspace: email-audit risolve il DNS, e la ricerca nella documentazione legge la documentazione pubblicata. Nessuna delle due necessita di login, e nessuna delle due è bloccata dalla sua assenza.

Esempio di codice

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 lo riporta al task. L'autenticazione usa un browser, con un flusso device-code per host headless, quindi il flusso di lavoro non si blocca a un prompt di autenticazione.

I fallimenti emergono allo stesso modo ovunque

Poiché ogni operazione è un sottile wrapper sull'API live, i fallimenti ritornano attraverso il contratto uniforme della CLI anziché tramite gestione degli errori specifica per skill:

JSON per default: i successi stampano JSON strutturato su stdout e gli errori vanno su stderr, così il loop dell'agente può analizzare gli esiti senza dover estrarre informazioni da testo discorsivo.
Exit code semantici: uno dei sei codici indica all'agente la categoria del fallimento prima che legga un messaggio. Vedi la tabella completa in CLI. L'agente si dirama in base alla categoria senza analizzare il messaggio: exit 4 significa rieseguire il passaggio di autenticazione, ed exit 3 significa che l'ID della risorsa è errato, quindi riprovare non servirà.

Questo è lo stesso contratto che la CLI presenta a umani e script. Le skill non aggiungono alcun livello; insegnano all'agente a utilizzare il contratto esistente. Vedi CLI for agents per il contratto completo, inclusi formati di output e configurazione.

Comporre skill in un loop dell'agente

Poiché ogni riferimento è un'operazione auto-verificante con un esito leggibile dalla macchina, si compongono in un loop senza codice di collegamento. Per esempio, "invia l'email di lancio e conferma che è stata recapitata" si scompone come segue:

Autenticazione: eseguire bird auth status; effettuare il login solo se necessario.
Trovare un mittente: usare il riferimento dei domini per scegliere un indirizzo from su un dominio verificato. Exit 0 più un dominio verificato nel JSON significa che questo passaggio è completato; altrimenti, entrare nel loop crea-e-verifica.
Invio: usare il riferimento email per eseguire bird email send …. Una richiesta con successo restituisce 202, un ID em_… e status: accepted.
Confermare l'esito: usare di nuovo il riferimento email per eseguire bird email get <em_…> fino a quando i conteggi mostrano delivered. Se mostrano bounced, riportare il fallimento.

La condizione "completato quando" di ogni passaggio è verificabile dall'output JSON del passaggio precedente, ed è questo che rende il loop affidabile: l'agente non deve mai dedurre lo stato da testo discorsivo.

Skill, il plugin e MCP

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

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

Se l'installazione del plugin configura 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. Gli altri client supportano MCP remoto, ma i loro plugin non possono pre-dichiarare un server. Su Cursor, Codex e Copilot, il plugin installa le skill; su Droid, si copiano i file delle skill manualmente. Ogni client tranne Claude Code necessita che il server venga aggiunto manualmente, usando la configurazione in una riga nella guida al server MCP.

Quello che nessun plugin può fare è autenticarsi al posto vostro. Il server ospitato è protetto da OAuth, quindi su ogni client, incluso Claude Code, si effettua l'accesso una volta dopo la registrazione del server: in Claude Code si usa /mcp, poi si 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.

Client	Skill via plugin	Server MCP registrato	Accesso
Claude Code	Sì	Sì, dichiarato dal plugin	Tu: /mcp > bird > Authenticate
Cursor	Sì	Manuale, aggiungere il server remoto una volta	Tu: Needs login in Tools & Integrations
Codex	Sì	Manuale, aggiungere il server remoto una volta	Tu: codex mcp login bird
GitHub Copilot	Sì	Manuale, aggiungere il server remoto una volta	VS Code apre il browser al primo avvio
Factory Droid	Manuale, copiare i file delle skill	Manuale, aggiungere il server remoto una volta	Tu: /mcp dentro droid

Prossimi passi

Configura il tuo agente di codifica: la configurazione con un singolo prompt che installa il plugin per te.
Server MCP: la superficie di tool inclusa nel plugin, e come aggiungerla manualmente.
CLI for agents: la superficie di comandi insegnata dalle skill, per agenti con accesso alla shell.
Onboarding AI: la configurazione guidata, end-to-end, con il corpus documentale integrato.