Pattern di composizione delle Agent Skill

Quando hai più di una Skill, le domande interessanti smettono di riguardare un singolo file. Riguardano i confini: che cosa è una Skill e che cosa sono due, che cosa va distribuito insieme e che cosa succede quando più Skill potrebbero attivarsi nello stesso momento.

Ultimo articolo di una serie sulle Agent Skill.

Pattern 1 — l’hub e i suoi riferimenti

La forma più comune per una Skill sostanziosa: uno SKILL.md snello che descrive il workflow e una directory references/ che contiene i dettagli.

automation-recommender/
├── SKILL.md            (la procedura decisionale)
└── references/
    ├── hooks-patterns.md
    ├── mcp-servers.md
    ├── plugins-reference.md
    ├── skills-reference.md
    └── subagent-templates.md

Cinque file di riferimento, circa 32KB complessivi. Una richiesta sugli hook apre un solo file da 6KB; quello da 8KB sui server MCP non viene mai toccato. Questa è progressive disclosure usata intenzionalmente, non per caso.

Usalo quando la Skill ha un solo workflow ma diversi argomenti profondi.

Pattern 2 — la separazione per verbo

Diversi plugin ufficiali distribuiscono Skill accoppiate con lo stesso soggetto e verbi diversi: una per configurare un servizio, una per accedervi. Configurare una connessione Slack e leggere i messaggi da quella connessione sono attività diverse, svolte in momenti diversi, da persone con obiettivi diversi.

Separa quando le condizioni di attivazione sono davvero differenti. Tenerle insieme produce una descrizione costretta a dire “usa quando devi configurare o usare”, che finisce per corrispondere a tutto e quindi non discrimina nulla.

Pattern 3 — orchestratore più codice

Ne abbiamo parlato nell’articolo precedente, ma è anche un pattern di composizione: lo SKILL.md contiene il giudizio e la sequenza, mentre gli script inclusi contengono ogni passaggio che ha una sola risposta corretta. La Skill diventa una procedura sottile e leggibile costruita sopra una libreria testata.

Pattern 4 — il bundle di plugin

Skill correlate che condividono un dominio possono essere distribuite insieme come plugin e versionate come un’unica unità. È così che un team distribuisce uno stile di lavoro comune: la Skill di review, quella di implementazione e quella di release arrivano insieme e restano allineate.

Il vantaggio pratico non è tecnico. È che una persona mantiene l’insieme e tutti gli altri ricevono l’aggiornamento.

Dove la composizione si rompe davvero

La Skill che fa tutto. Una sola Skill che gestisce l’intero dominio, con una descrizione che elenca otto trigger non correlati. Si attiva continuamente, anche quando non dovrebbe, e trascina ogni volta tutto il suo corpo nel contesto. Separala.

Vicini sovrapposti. Due Skill le cui descrizioni non segnano un confine. Se esiste una Skill sorella, ciascuna dovrebbe anche dire per che cosa non è pensata.

Il riferimento che nessuno legge. Un file incluso che SKILL.md non cita è peso morto: non costa token, ed è proprio per questo che marcisce inosservato. Se il corpo non punta a quel file, eliminalo.

Istruzioni che dovrebbero essere codice. Una lunga descrizione in prosa di un algoritmo è uno script che non è ancora stato scritto. Verrà rideducato, in modo leggermente diverso, a ogni esecuzione.

Prima di distribuire qualsiasi cosa

Due vincoli che conviene pianificare invece di scoprire dopo. Le Skill non si sincronizzano tra le diverse superfici: l’agente di coding, l’API e l’app di chat hanno ciascuno bisogno della propria copia, con modelli di condivisione diversi: personale, a livello di workspace e per utente. E una Skill è capacità eseguibile, quindi installarne una di terze parti va trattato come aggiungere una dipendenza: leggi gli script, cerca chiamate di rete che non corrispondono allo scopo dichiarato e presta particolare attenzione ovunque la Skill possa toccare dati di produzione.

Che cosa portarsi a casa

I confini sono tutto il design. Una Skill per condizione di attivazione, dettagli spostati nei riferimenti, determinismo spostato negli script, Skill correlate distribuite come insieme. Se queste cose sono giuste, i singoli file diventano facili: gran parte di una buona Skill è una pagina di istruzioni chiare e una descrizione scritta per la persona che non sa nemmeno che quella Skill esiste.

Articoli precedenti della serie: che cos’è una Skill, i tre livelli di caricamento, come scrivere una descrizione che si attiva e come distribuire script che non consumano contesto.