Agent Skills

Divulgazione progressiva

Tre livelli, gli stessi tre che descrive la specifica:

• Il catalogo. A ogni turno il prompt dell'agente porta un menu delle skill che sembrano pertinenti: titolo, descrizione di una riga, slug. Mai il corpo. Tre skill per turno come impostazione predefinita, sei al massimo.
• L'attivazione. L'agente chiama lo strumento load_playbook con uno slug per leggere i passi completi. L'argomento slug è vincolato, turno per turno, a un enum contenente esattamente gli slug di quel menu: un nome inventato viene rifiutato prima della dispatch invece di costare all'agente un giro a vuoto. Quando non c'è un menu, lo strumento non viene nemmeno registrato.
• Le risorse. Non ancora. Qui una skill è un solo SKILL.md; scripts/, references/ e assets/ allegati vengono letti e ignorati, anziché supportati a metà.

Una volta caricata, una skill resta caricata. Le esecuzioni degli agenti comprimono i risultati più vecchi degli strumenti per contenere i costi, e le skill attivate ne sono esenti: le loro istruzioni sopravvivono alla lettera per tutto il resto dell'esecuzione, per quanto lunga diventi. Una skill che svanisce in silenzio a metà lavoro è peggio di una che non si è mai caricata.

Quali skill arrivano al menu

Due passaggi. Le parole chiave dei trigger corrispondono al turno come sottostringhe senza distinzione di maiuscole; poi un passaggio semantico completa l'elenco partendo da un embedding di titolo, descrizione, trigger e apertura del corpo di ogni skill, ammesso solo sopra una soglia di somiglianza calibrata. Una skill senza trigger è sempre attiva e sempre proposta. Cosa attivare lo decide il modello: qui nulla gli impone una skill.

Far entrare una skill

• La libreria. Pacchetti curati, installabili su un agente con un clic. È la superficie di scoperta che usano quasi tutti.
• Scriverne una. Titolo, descrizione, parole chiave e i passi, nella scheda Playbook dell'agente.
• L'API. POST /api/agents/:id/playbooks/import accetta { files: [{ name, content }] } e importa ogni file in modo indipendente: un file guasto fallisce da solo e gli altri arrivano comunque. Ogni file passa uno scan di sicurezza prima che qualcosa venga salvato, e un import non sovrascrive mai una skill esistente: una collisione di slug torna indietro come saltata.
• Ricavarne una da un documento. POST /api/agents/:id/playbooks/generate accetta { artifactId } — un documento già nello spazio di lavoro — oppure { content, sourceName }, e ne ricava una procedura: quando si applica, i passi, le regole di decisione, il lessico. Non è la pipeline di caricamento, che trasforma un documento in passaggi da consultare; qui diventa qualcosa che l'agente fa. La procedura è riscritta da zero, mai estratta: la fonte può essere il manuale protetto di qualcun altro, e un playbook che lo cita ne sarebbe una copia. I documenti lunghi vengono letti dall'inizio fino a un limite, e la risposta dice quando il testo è stato tagliato. Il risultato arriva disattivato: quelle parole non le ha scritte nessuno, quindi una persona legge la bozza e la accende, oppure non gira mai.

Nell'interfaccia non c'è un pulsante di caricamento, ed è voluto. Un SKILL.md diventa istruzione permanente per un agente che ha in mano gli strumenti di uno spazio di lavoro: un file caricato a piacere è un vettore di prompt injection, non una comodità. La rotta API qui sopra, riservata al proprietario, è l'eccezione deliberata.

Far uscire una skill

Qualunque skill si esporta come uno zip che contiene <nome>/SKILL.md — la forma a cartella descritta dalla specifica, non un file sciolto. Scompattalo in ~/.agents/skills/ o .claude/skills/ e si carica in quel client senza rinominare nulla, e skills-ref validate passa così com'è. Chi chiama l'API e vuole il file nudo può chiedere text/markdown.

Il frontmatter porta name e description. Le nostre estensioni — parole chiave, ordinamento e un marcatore che dice da dove arriva il file — viaggiano sotto metadata, perché il validatore di riferimento della specifica rifiuta le chiavi di primo livello sconosciute e una nostra esportazione non deve mai essere il file che lo fa fallire.

Cosa rifiutiamo di onorare

• allowed-tools viene sempre scartato. La specifica lo definisce come l'elenco degli strumenti da pre-approvare per una skill, che è esattamente la cosa sbagliata da accettare da un file che arriva via API o da un pacchetto condiviso: lascerebbe a un contenuto importato la facoltà di allargarsi da solo i permessi. Quali strumenti un agente può chiamare è una proprietà del suo ruolo, mai di un file che ha letto.
• compatibility viene scartato per un motivo più noioso: descrive l'ambiente per cui la skill è stata scritta, che non dice nulla del nostro.
• Tutto ciò che sta fuori dal frontmatter documentato viene ignorato invece che indovinato. Il parser accetta la forma piccola e fissa definita dalla specifica, e niente di esotico.

Limiti

Trenta skill per agente, 64 kB per file importato e un corpo con un tetto: una skill che non ci sta più dentro sono due skill. I nomi sono lettere minuscole, cifre e trattini singoli: la specifica permette di più, ma qui il nome è anche un URL.

Altrove

La specifica è l'autorità sul formato. Per l'API HTTP con cui gli agenti agiscono sulla rete, vedi la documentazione API.