Agent Skills vs MCP: scegliere l’interfaccia giusta
Agent skills vs MCP a confronto: istruzioni, connessioni agli strumenti, confini di sicurezza, versioning e casi in cui combinarli per ottenere agenti AI affidabili.
La scelta tra agent skills e MCP viene spesso presentata come una competizione tra due modi per «dare strumenti a un’AI». Questa impostazione è incompleta. Una skill e un server del Model Context Protocol risolvono livelli diversi del problema: la prima insegna a un agente come operare in un determinato dominio, mentre il secondo espone funzionalità e contesto attraverso una connessione standardizzata.
Dockup usa un SKILL.md perché la sua interfaccia principale è uno strumento a riga di comando già esistente. La skill insegna a Claude Code e Codex a usare quella CLI in sicurezza: richiedere sempre JSON, autenticarsi senza interazione, risolvere i target esatti, attendere gli stati terminali del deployment e fermarsi prima di eseguire operazioni distruttive.
Che cos’è un’agent skill e perché SKILL.md è importante?
Un’agent skill è una directory di istruzioni operative e riferimenti di supporto che un agente può caricare quando un’attività corrisponde allo scopo della skill. SKILL.md è il punto di ingresso: il frontmatter ne descrive la funzionalità, mentre il corpo spiega workflow, vincoli, esempi e regole decisionali.
Una skill è particolarmente utile quando l’interfaccia eseguibile esiste già. L’agente non ha bisogno di un nuovo protocol adapter solo per eseguire una CLI ben progettata. Ha bisogno di informazioni accurate su:
- Quali comandi sono autorevoli.
- Quali flag sono obbligatori per l’uso da parte delle macchine.
- Come funziona l’autenticazione in una sandbox.
- Quali output dimostrano il successo.
- Quali azioni richiedono l’intervento di una persona.
- Dove possono comparire i secret.
- Come diagnosticare i failure più comuni.
L’installazione di Dockup è volutamente semplice:
npm install -g dockup-cli
dockup skill install
dockup skill status --json
Una copia canonica viene scritta in ~/.agents/skills/dockup/ e collegata sia a Claude Code sia a Codex. La skill è inclusa nel package della CLI e dockup update aggiorna entrambi insieme. Questa scelta di packaging previene un failure mode comune: istruzioni che descrivono comandi non disponibili nel binary installato.
La skill non è il deployment engine. La CLI esegue le operazioni, produce JSON e restituisce exit code. La skill è il manuale operativo che l’agente segue.
Che cos’è il Model Context Protocol?
Il Model Context Protocol, comunemente chiamato MCP, è un protocollo aperto per collegare un’applicazione AI a strumenti, risorse e prompt esterni attraverso un’architettura client-server. Un server MCP può esporre tool invocabili, risorse leggibili e prompt riutilizzabili. Un client MCP all’interno dell’agent host rileva e invoca queste funzionalità.
MCP è utile quando un sistema ha bisogno di un confine di protocollo duraturo invece della semplice esecuzione locale da shell. Tra gli esempi:
- Una SaaS API remota che deve esporre operazioni attentamente tipizzate.
- Una sorgente dati che fornisce risorse esplorabili.
- Un’applicazione desktop che vuole il tool discovery senza distribuire una CLI.
- Un servizio centralizzato usato da molti agent host e sistemi operativi.
- Un’integrazione in cui il server deve gestire credenziali e policy.
Il server controlla l’implementazione alla base di ogni tool. L’agent host vede il nome dichiarato, la descrizione, lo schema di input e l’output. Transport, lifecycle e authorization dipendono dalla configurazione MCP scelta.
MCP non fornisce automaticamente il giudizio sul dominio. Un server può esporre delete_service, ma l’agente ha comunque bisogno di una policy che stabilisca quando la cancellazione è appropriata. Al contrario, una skill può spiegare un workflow, ma non può creare funzionalità assenti dalla CLI o dall’API sottostante.
In che modo agent skills e MCP differiscono nella pratica?
Il confronto più chiaro consiste nell’osservare le responsabilità:
| Dimensione | Agent skill / SKILL.md | Server MCP |
|---|---|---|
| Obiettivo principale | Insegnare workflow e vincoli | Esporre strumenti, risorse e prompt |
| Esecuzione | Usa CLI, file, API o app esistenti | Il server implementa funzionalità invocabili |
| Discovery | L’agente carica le istruzioni della skill corrispondente | Il client rileva le funzionalità del server |
| Deployment | Spesso una cartella installata insieme a un package | Un processo server locale o remoto |
| Rischio di versioning | Le istruzioni possono divergere dallo strumento | Lo schema del server può divergere dal comportamento del backend |
| Utilizzo ideale | Un’interfaccia esistente necessita di indicazioni operative esperte | Una funzionalità necessita di un confine di protocollo standardizzato |
| Focus sulla sicurezza | Regole comportamentali e sicurezza dei comandi | Connessione, trust del server, scope e autorizzazione dei tool |
| Utilizzo offline/locale | Eccellente con CLI locali | Possibile con un server MCP locale |
| Riutilizzo tra client | Copiare o distribuire la skill per ogni host | Un server può supportare più client compatibili |
Nessuna delle due colonne è intrinsecamente più «agentic». L’affidabilità deriva dall’abbinare l’interfaccia al sistema.
Per Dockup, la CLI dispone già di 135 comandi, JSON strutturato, exit code reali, un timeout di deployment predefinito di 900 secondi, masking dei secret e confirmation gate. Avvolgere ogni comando in un altro server locale aggiungerebbe un translation layer senza modificare la verità sottostante del deployment. Una skill è la scelta più adatta perché insegna all’agente a usare il contratto eseguibile già disponibile.
Una piattaforma remota priva di CLI può arrivare alla conclusione opposta. Un server MCP può fornire la tool surface tipizzata mancante e mantenere le credenziali API al di fuori dell’ambiente shell dell’agente.
Quando usare una skill, MCP o entrambi?
Usa solo una skill quando sono vere tutte le seguenti condizioni:
- Esiste già una CLI o un’applicazione locale matura che espone la funzionalità necessaria.
- L’agent host è autorizzato a eseguirla.
- L’output machine-readable e la semantica degli exit code sono adeguati.
- Il problema principale è la conoscenza procedurale, non la connettività.
- Il packaging può mantenere allineate le istruzioni e l’eseguibile.
Usa solo MCP quando l’agente ha bisogno di una connessione native al protocollo e il server è in grado di fornire contesto sufficiente per un’operatività sicura. È una scelta comune per l’accesso a dati in prevalenza read-only, servizi remoti e applicazioni che vogliono un’interfaccia di tool stabile e condivisa tra client diversi.
Usa entrambi quando i tool del protocollo hanno bisogno di un playbook operativo più ricco. Un server MCP può esporre primitive sicure e tipizzate, mentre una skill spiega il workflow di business articolato su più passaggi, le regole di escalation e i criteri di validazione. La skill può dire all’agente quando e perché chiamare ciascun tool MCP.
Un’architettura combinata può essere simile a questa:
Richiesta dell’utente
↓
Skill: workflow, policy, regole di validazione
↓
Client MCP: rileva funzionalità tipizzate
↓
Server MCP: autentica ed esegue
↓
Sistema esterno
Un’architettura incentrata sulla CLI è più semplice:
Richiesta dell’utente
↓
Skill: workflow, policy, regole di validazione
↓
CLI: output JSON + exit code + semantica di attesa
↓
API della piattaforma
La complessità deve essere giustificata da un confine che contribuisce a migliorare. Aggiungere MCP solo perché è di moda può creare un altro processo da distribuire, autenticare, monitorare e sottoporre a versioning.
Esempi di decisione
| Situazione | Punto di partenza migliore | Motivo |
|---|---|---|
| CLI di deployment locale con output JSON | Skill | La connettività esiste già |
| Knowledge base aziendale con risorse strutturate | MCP | Il resource discovery è centrale |
| API per l’amministrazione di database senza CLI | MCP | Le operazioni remote tipizzate sono utili |
| Runbook di release complesso tra strumenti esistenti | Skill | Il bisogno principale è procedurale e trasversale |
| Operazioni remote regolamentate più policy dettagliate | Entrambi | Il server applica lo scope; la skill guida il comportamento |
| Automazione personale una tantum | Skill o CLI diretta | Minore overhead operativo |
La risposta giusta può cambiare nel tempo. Un team può iniziare con una skill basata su una CLI e aggiungere in seguito un server MCP quando diventano importanti l’accesso remoto da più client o la gestione centralizzata delle credenziali.
Come si confrontano sicurezza e trust boundary?
Le skill sono istruzioni, quindi il rischio che comportano è simile a quello della documentazione tecnica con influenza operativa. Una skill malevola o negligente può indicare a un agente di esporre secret, disabilitare protezioni o eseguire comandi distruttivi. Esamina l’intera directory, non solo il titolo.
Per esaminare una skill, chiediti:
- Chi l’ha pubblicata?
- Invoca comandi esterni allo scopo dichiarato?
- Indica all’agente di stampare token o credenziali?
- Bypassa le conferme?
- Gli esempi di comando derivano dalla versione installata?
- Gli aggiornamenti possono sostituire la skill senza revisione?
- La skill definisce un processo delimitato per la target discovery?
MCP introduce un trust boundary del server. Il client deve sapere a quale server si sta connettendo, quali tool espone, quali dati lasciano la macchina e come sono definiti gli scope di autorizzazione. Un server può modificare il comportamento dietro un nome di tool stabile, quindi la provenienza del deployment e il versioning del server sono importanti.
Per esaminare un’implementazione MCP, chiediti:
- Il server è locale o remoto?
- Chi lo gestisce?
- Come vengono conservate e ruotate le credenziali?
- Quali chiamate ai tool possono modificare o cancellare dati?
- Gli input dei tool vengono validati lato server?
- Gli output vengono trattati come contenuti non attendibili?
- Ogni chiamata è sottoposta ad audit?
- Il client può limitare i tool disponibili?
L’agent host non deve considerare «sicuro» tutto ciò che viene «rilevato tramite MCP». La standardizzazione del protocollo migliora l’interoperabilità, non l’affidabilità di ogni server.
La skill di Dockup codifica diverse regole di sicurezza: usa DOCKUP_TOKEN invece del login interattivo, non stampare mai le credenziali, rileva i target con dockup services --json, usa --wait e fermati su needs_confirm. La CLI rafforza queste istruzioni mascherando i secret e rifiutando le operazioni distruttive senza approvazione esplicita. Questo modello di defense in depth è descritto in guardrail di produzione per agenti AI.
Come dovrebbero funzionare il versioning e il failure recovery?
Il version drift è possibile con entrambi gli approcci, ma si manifesta in modo diverso.
Una skill può diventare obsoleta quando cambia il comando documentato. La mitigazione più efficace consiste nel distribuire la skill insieme all’eseguibile e aggiornarli entrambi attraverso un unico processo di release. Dockup segue questo modello. L’agente può verificare la skill installata:
dockup skill status --json
Un aggiornamento rinnova insieme la CLI e la skill inclusa:
dockup update
Un client MCP può rilevare gli schemi dei tool correnti del server, ma la compatibilità dello schema non garantisce quella semantica. Un tool può mantenere gli stessi input modificando authorization, side effect, latenza o interpretazione dell’output. Il server dovrebbe pubblicare versioni, mantenere la backward compatibility quando possibile e restituire errori strutturati.
Anche la gestione dei failure è diversa. Una CLI offre naturalmente exit code di processo. Una chiamata a un tool MCP necessita di un risultato a livello applicativo altrettanto chiaro. In entrambi i casi, l’agente non dovrebbe dedurre il successo da un semplice acknowledgment a livello di transport.
Una checklist utile per l’affidabilità è:
| Requisito | Implementazione skill + CLI | Implementazione MCP |
|---|---|---|
| Capability discovery | Schema della CLI | Elenco dei tool del server |
| Output strutturato | JSON/NDJSON | Risultato del tool tipizzato |
| Segnale di failure | Exit non zero + codice | Risultato di errore esplicito |
| Operazione lunga | --wait / stream documentato | Protocollo di progress o completamento |
| Protezione dei secret | Masking e disciplina su stderr | Redazione lato server |
| Approvazione delle operazioni distruttive | Confirmation gate della CLI | Policy del server o conferma del client |
| Audit | Audit log della piattaforma | Audit log del server e del backend |
| Verifica della versione | Stato di skill/binary | Metadati e schemi del server |
L’interfaccia dovrebbe rendere più difficile riportare erroneamente un failure rispetto a un successo.
Quale architettura dovrebbe scegliere un team di produzione?
Inizia identificando il problema reale.
Scegli un’architettura skill-first quando il team si fida già di una CLI e la gestisce operativamente. Investi nel suo machine contract: JSON, exit code reali, error code stabili, istruzioni allineate alla versione e conferme. Poi distribuisci la skill insieme allo strumento. È il percorso più breve per il deployment con Claude Code e il deployment end-to-end con Codex attraverso Dockup.
Scegli MCP-first quando la funzionalità è naturalmente remota, orientata alle risorse o condivisa tra molti client. Tratta il server come software di produzione: autenticane l’accesso, definiscine gli scope, monitoralo e sottoponi a revisione ogni mutazione.
Scegli entrambi quando policy e connettività sono complesse in modo indipendente. Mantieni chiare le responsabilità. La skill non dovrebbe duplicare l’implementazione del server e la descrizione del server non dovrebbe trasformarsi in un manuale operativo interminabile.
Un workshop pratico di valutazione
Esegui una piccola proof con un’operazione di lettura, una scrittura reversibile, un’operazione di lunga durata e un’operazione distruttiva che deve essere bloccata. Assegna un punteggio a ogni design in base a:
- Come l’agente rileva l’operazione.
- Come vengono fornite le credenziali.
- Come viene dimostrato il successo.
- Come viene classificato il failure.
- Come una persona approva le operazioni pericolose.
- Come vengono recuperati log ed evidenze di audit.
- Come vengono mantenute allineate le versioni.
- Come l’integrazione viene rimossa senza residui.
Non decidere basandoti solo su un diagramma. Osserva i failure path. Un design che appare elegante nel percorso positivo può diventare ambiguo quando un deployment va in timeout, un server si disconnette o un file di istruzioni è indietro di una release.
La referenza della CLI di Dockup offre un esempio concreto di contratto CLI basato su una skill. L’articolo più ampio sullo sviluppo basato sull’AI spiega perché queste interfacce sono importanti, mentre gli agenti assumono una parte sempre più ampia del development loop.
Considera la responsabilità operativa
Il responsabile dell’integrazione conta quanto la sua architettura. Una skill basata su una CLI eredita in genere i processi di installazione, release e supporto della CLI stessa. Il team che pubblica il binary può distribuire le istruzioni corrispondenti e testarle insieme.
Un server MCP crea un componente di produzione separato. Qualcuno deve occuparsi di hosting, certificati o avvio del processo locale, autenticazione, monitoraggio, incident response, compatibilità degli schemi e aggiornamento delle dipendenze. Questo investimento può essere giustificato quando il server costituisce un confine condiviso significativo. È overhead superfluo quando inoltra soltanto chiamate locali a un eseguibile già sufficiente.
Durante la valutazione, assegna per iscritto un responsabile a ogni livello:
| Livello | Responsabile skill-first | Responsabile MCP-first |
|---|---|---|
| Istruzioni sul dominio | Publisher della skill | Prompt del client o skill associata |
| Comportamento dell’eseguibile | Publisher della CLI | Team del server MCP |
| Gestione delle credenziali | CLI e ambiente runtime | Server e connessione del client |
| Disponibilità | Eseguibile locale e API della piattaforma | Processo server, transport e backend |
| Compatibilità degli schemi | Processo di release della CLI | Processo di release del server MCP |
| Evidenze degli incidenti | Output della CLI e audit della piattaforma | Log del client, log del server e audit del backend |
Questa tabella delle responsabilità spesso risolve il dibattito su agent skills e MCP più chiaramente di una checklist delle funzionalità.
Valuta latenza e failure surface
Una chiamata locale basata su skill e CLI ha un percorso breve: agent host, processo, API della piattaforma. Un percorso MCP può aggiungere l’avvio del server, la negoziazione del transport, il routing remoto e un ulteriore livello di autenticazione. Queste aggiunte non sono intrinsecamente negative, ma ciascuna crea una failure surface distinta.
Testa disconnessioni, credenziali scadute, input malformati, operazioni parziali di lunga durata e aggiornamenti del server. L’agente deve poter stabilire se il failure si è verificato nell’host, nella connessione al protocollo, nel server o nella piattaforma esterna. Un risultato generico come «tool failed» non è sufficiente per il lavoro in produzione.
Per i deployment lunghi, l’interfaccia deve preservare la semantica dello stato terminale. Che si tratti di un’operazione CLI --wait o di un tool MCP con progress, l’agente non deve trasformare un acknowledgment in un successo. La scelta tra agent skills e MCP non elimina questo requisito.
Pianifica la portabilità senza sacrificare la verità
MCP può migliorare la portabilità tra client compatibili perché lo stesso server pubblicizza i tool attraverso un protocollo condiviso. Anche le skill possono essere portabili quando più agenti supportano la stessa directory e le convenzioni SKILL.md, come fanno Claude Code e Codex nel modello di installazione di Dockup.
La portabilità è utile solo se la semantica rimane precisa. Un tool chiamato deploy deve definire se restituisce il controllo quando l’operazione viene accodata o quando il servizio è healthy. Un’istruzione della skill che dice «esegui il deployment e verifica» deve rimandare a un comando in grado di fornire effettivamente quella prova.
Il design più solido mantiene la verità del dominio vicino al livello eseguibile e usa quello superiore per spiegare l’intento. Nel confronto tra agent skills e MCP, né un protocollo standardizzato né un file di istruzioni ben scritto compensano un’operazione backend ambigua.
Porta il workflow in produzione
Usa l’architettura più semplice in grado di creare un confine affidabile. Per Dockup, installa la skill inclusa nel package e lascia che la CLI rimanga la fonte eseguibile della verità sul deployment.
npm install -g dockup-cli
dockup skill install
Il primo comando installa la CLI. Il secondo installa la skill Dockup corrispondente per Claude Code e Codex. Inizia gratuitamente su app.dockup.ai.
FAQ
Agent skills e MCP sono la stessa cosa?
No. Una skill fornisce principalmente istruzioni e conoscenze operative. MCP fornisce un protocollo per esporre strumenti, risorse e prompt attraverso una connessione client-server.
Un file SKILL.md esegue direttamente i comandi?
No. Indica all’agente come usare funzionalità sottostanti come una CLI, file, API o tool MCP. È l’interfaccia eseguibile a compiere l’azione.
Quando è meglio una skill rispetto a MCP?
Una skill è spesso la scelta più semplice quando una CLI locale matura offre già operazioni sicure e machine-readable e ciò che manca è la guida al workflow.
Un agente può usare insieme una skill e MCP?
Sì. Una skill può descrivere un workflow articolato su più passaggi e la relativa policy, mentre un server MCP espone i tool e le risorse tipizzati utilizzati da quel workflow.
Perché Dockup distribuisce la skill all’interno del package della CLI?
Distribuirle insieme consente a dockup update di aggiornare l’eseguibile e le relative istruzioni in un solo passaggio, riducendo il rischio che la skill descriva una versione diversa dei comandi.