Progettazione, affinamento e mantenimento delle agent skills in Perplexity

I prodotti frontier agent di Perplexity si basano su un fondamento di know-how ed esperienza di settore racchiusi in moduli Agent Skills. Manteniamo una libreria accuratamente curata di Skills nei nostri ambienti tecnici. Queste Skills includono molte delle utility generiche che alimentano Perplexity Computer; funzionalità specifiche verticali in aree come finanza, giurisprudenza e salute; e una lunghissima serie di moduli per soddisfare le esigenze degli utenti. Alcune Skills vengono richiamate raramente ma sono critiche quando vengono richiamate. Per garantire un'esperienza utente costantemente eccellente, il team di Agenti di Perplexity dà priorità alla qualità delle Skills tanto quanto alla qualità del codice.

Le intuizioni e le migliori pratiche necessarie per sviluppare una Skill di alta qualità differiscono significativamente da quelle necessarie per creare software tradizionale. Il team di Agenti esamina molte pull request da parte di eccellenti ingegneri che sviluppano Skills nel corso del proprio lavoro. Il risultato è quasi sempre costituito da numerosi commenti e suggerimenti per la revisione. Questo perché molti modelli utili per scrivere codice diventano antipattern nella creazione di Skills.

Ad esempio, se si prendono alcuni degli aforismi da PEP20 – The Zen of Python, diventa rapidamente chiaro che scrivere buon codice Python è diverso dallo scrivere buone Skills. Delle 20 linee di saggezza, almeno la metà sono completamente errate o attivamente fuorvianti quando si scrivono Skills. Eccone cinque:

Cinque contrasti tra lo Zen di Python e le indicazioni dell’articolo per scrivere Skills.

Questa guida è il documento che gli ingegneri di Perplexity utilizzano durante lo sviluppo e la revisione delle Skills. Stiamo inoltre rilasciando questa guida al pubblico affinché le nostre scoperte e i nostri apprendimenti possano beneficiare la comunità più ampia. Che tu sia un ingegnere che progetta Skills di produzione nel proprio lavoro quotidiano, un utente Computer che cerca di sviluppare la propria Skill in un'area che conosci meglio, o entrambi, questa guida è per te.

Cos'è una Skill?

Quando scrivi una Skill, non stai scrivendo semplice software (anche se le Skills ora fanno parte dei principali motori logici per i sistemi di agenti). Piuttosto, stai costruendo contesto per i modelli e i loro ambienti. Una Skill ha vincoli diversi e principi di progettazione diversi. Se scrivi una Skill come fai con il codice, fallirai.

Una Skill è almeno quattro cose, specialmente nel contesto di come le costruiamo in Perplexity.

Una Skill è una Directory

Una Skill non è solo un singolo file SKILL.md. In molti casi, una Skill include diversi file. Sotto la directory denominata con il nome della tua Skill, potresti avere:

SKILL.md: frontmatter e istruzioni

scripts/: codice che l'agente esegue, non reinventa

references/: documenti pesanti, caricati in modo condizionale

assets/: modelli, schemi e dati

config.json: configurazione utente al primo avvio

Questo modello hub-and-spoke ti consente di mantenere le Skills molto focalizzate e compatte, e si può utilizzare la struttura delle cartelle in modo molto creativo. A volte, Skills particolarmente complesse beneficiano di più livelli di gerarchia per aiutare il modello a navigare meglio. Supponiamo che una Skill richieda conoscenza su 300 argomenti, raggruppabili in 20 aree tematiche. Scegliere in modo affidabile l'argomento giusto tra 300 è una sfida irrisolta anche per i migliori modelli frontier di oggi. È un problema di scelta molto più semplice per un modello concentrarsi su una delle 20 aree, piuttosto che tra i 15 argomenti all'interno di quell'area.

Come esempio di come la gerarchia multilivello fornisca valore, il nostro team ha impiegato tre livelli di annidamento tematico all'interno delle Skills che alimentano le capacità dell'imposta sul reddito statunitense di Computer durante la scorsa stagione fiscale. Questa gerarchia era assolutamente indispensabile data la complessità della legge fiscale: nei nostri primi test, presentare al modello una singola cartella contenente tutte le 1.945 sezioni del Codice delle Entrate Internal Revenue degli Stati Uniti ha portato a prestazioni peggiori rispetto al non caricare affatto la Skill. Organizzare le informazioni in suddivisioni logiche è stato indispensabile per garantire operazioni di lettura ad alta precisione.

Eppure questa gerarchia non è stata gratuita. Livelli crescenti di gerarchia richiedono livelli crescenti di cura attraverso l'architettura dell'informazione per gestire l'indirezione risultante. Abbiamo ideato guide di riferimento rapido, utility di ricerca personalizzate e altri strumenti per supportare il modello nell'individuazione delle informazioni con un minimo di indirezione. In questo caso, svolgere il duro lavoro di curatela ha infine prodotto un risultato finale positivo: una Skill che ha permesso ai modelli di eseguire compiti legati alle tasse in modo molto più capace rispetto all'uso dei soli strumenti generali.

Espandi

Una Skill è un Formato

Una Skill è un formato. Il file root principale SKILL.md deve avere sia un nome che una descrizione. Inoltre, la Skill deve mappare esattamente al nome della directory in cui si trova la Skill. Il nome deve essere composto da caratteri tutti minuscoli, non deve contenere Spazi e può utilizzare trattini. La descrizione è il trigger di routing. Questo è un comune punto di fallimento: la descrizione non è documentazione interna per ciò che fa la Skill. Equivale a istruzioni per il modello su quando caricare la Skill. Quindi, vedrai frequentemente “Carica quando”, non “Questa Skill fa”. Questo è importante a causa del modo in cui la maggior parte delle implementazioni inietta la descrizione nel contesto del modello.

All'interno del frontmatter, c'è anche “depends:”, che ti consente di creare dipendenze gerarchiche tra Skills, e “metadata:”, che viene utilizzato per revisioni e valutazioni. Diversi sistemi di agenti possono persino definire i propri campi frontmatter, da utilizzare in modo specifico per quei sistemi. Come alternativa, i metadati specifici per la Skill possono essere impacchettati in un file di configurazione JSON o YAML ausiliario. Ciò è desiderabile quando si costruiscono sistemi di agenti che devono facilitare diversi tipi di comportamento di runtime per Skill senza inquinare il contesto del modello con minuzie. Infine, un comportamento simile è ottenibile tramite la rimozione del frontmatter della Skill durante la lettura. Computer impiega questa metodologia, che consente di preservare la configurazione nel file root SKILL.md. È richiesta un'attenta attenzione ai dettagli nella logica di parsing, e si potrebbe desiderare di implementare una rimozione condizionale se ci sono determinati campi che è utile avere all'interno del contesto del modello.

Una Skill è Invocabile

Una Skill è invocabile. L'agente carica una Skill durante il runtime. È importante notare che le Skills non sono sempre incluse nel contesto. Per impostazione predefinita, la maggior parte dei sistemi di agenti distribuisce le Skills progressivamente in base a specifiche esigenze.

Ci sono almeno tre livelli di costi di contesto nel modo in cui abbiamo implementato le Skills in Computer. Ecco il processo:

Computer chiama load_skill(name="...")

Computer copia la directory della Skill nella sandbox di esecuzione isolata

Computer carica automaticamente in modo ricorsivo le dipendenze nel tag “depends:”

Computer quindi rimuove il frontmatter e l'agente vede così solo il corpo e i file aggiuntivi

Diversi sistemi di agenti possono scegliere di esporre il contenuto della Skill in modi diversi. Ad esempio, alcuni sistemi potrebbero scegliere di non esporre affatto la gerarchia dei file, lasciando al modello il compito di scoprire la gerarchia attraverso le operazioni del filesystem. Altri sistemi possono scegliere di fornire al modello una mappatura dell'intero filetree fino a un certo limite di troncamento e/o profondità. Per mantenere il contesto pulito, Computer omette le gerarchie di file complete dal contesto di invocazione; tuttavia, questo è sovrascrivibile su base individuale per Skill.

Una Skill è Progressiva

Le Skills sono progressive. In Computer, ci sono tre diversi livelli di costi di contesto, e incorriamo in tutti e tre in varie fasi:

I tre livelli di contesto di una Skill: indice, caricamento completo della Skill e file di riferimento a runtime.

Computer costruisce un indice di Skills che contiene il nome e la descrizione per ogni Skill disponibile. Il budget per questo è di circa 100 token per Skill (più corto è ancora meglio). È così stretto perché stai pagando questo costo in ogni Sessione, per ogni utente. Questo viene iniettato nel prompt di sistema proprio all'inizio della conversazione. Il modello ha accesso a un gruppo di Skills denominate e descrizioni in modo che possa decidere se chiamare “load_skill()”. La soglia per entrare in questo indice è estremamente alta. La tua Skill deve essere molto utile, e la descrizione deve essere estremamente densa e concisa perché tutti stanno pagando il costo tutto il tempo.

Dopo che il sistema di agenti carica la Skill, c'è il corpo completo SKILL.md. Idealmente, il testo del corpo non supera i 5.000 token. Anche allora, vuoi che ogni frase conti perché una volta caricata una Skill, il resto della conversazione deve pagarne il costo fino al raggiungimento del limite di compattazione. Molti thread caricano ovunque tra tre e cinque diverse Skills, moltiplicando questo costo. Le Skills con molti riempitivi degraderanno quasi certamente altre Skills così come le capacità agentiche complessive. In breve, se la tua Skill carica e non fa la cosa giusta, quello è contesto sprecato.

Il livello finale di progressione sono gli script o i casi speciali, come subskills o formattazione. È qui che vuoi inserire la logica ramificata condizionale illimitata. L'agente la userà solo quando ne ha bisogno, il che significa che c'è una soglia molto più bassa per ciò che vuoi inserire qui.

Nell'indice, ogni token è importante. Il corpo della Skill caricata è più rilassato, e il runtime è il più rilassato. Questo potrebbe essere 20.000 token o zero token. Questo è il livello a cui potresti pensare di espandere il contesto del modello in modo progressivo.

Quando hai bisogno di una Skill?

Al team di Agenti viene spesso chiesto di esprimere un parere se una Skill sia veramente necessaria per un dato dominio o caso d'uso. Raramente abbiamo una risposta definitiva basata solo sui principi primi. L'unico modo per capirlo davvero è iniziare con il tuo agente senza la Skill, eseguire diverse query hero, e poi capire se l'agente sta facendo un buon lavoro.

Quando hai bisogno di una Skill

Ci sono molti compiti che sono in distribuzione per modelli addestrati. Devi applicare una Skill solo se vuoi cambiare quel comportamento in un modo specifico che non puoi fare con, diciamo, una frase nel tuo prompt. Quindi, hai bisogno di una Skill quando l'agente sbaglierà senza contesto speciale, o se c'è qualche incoerenza o non determinismo che devi rendere estremamente coerente tra le esecuzioni.

Potrebbe essere che la tua conoscenza sia durevole ma non nei dati di addestramento. Potrebbero esserci interruzioni o flussi di lavoro specifici per l'azienda, o potrebbe essere una questione di gusto. Ad esempio, abbiamo diverse Skills legate al design in Computer scritte da Henry Modisett (il nostro capo del design). Il motivo per cui ogni token esiste in quelle Skills è perché Henry ha molto buon gusto quando si tratta di progettare siti web e PDF. Henry specifica quali font usare e quali font non usare, come quei font si sentono, e altre questioni di giudizio che il modello non può apprendere dai soli dati di addestramento.

Quando non hai bisogno di una Skill

Vediamo molte Skills in cui gli ingegneri hanno scritto una serie di comandi git che devono essere eseguiti in ordine. Questo non è necessario perché il modello sa già come farlo, il che significa che è ottima documentazione ma una pessima Skill.

Vediamo esempi in cui le Skills ricapitolano le istruzioni dal prompt di sistema. Non hai bisogno di una Skill per quello. La conoscenza rilevante per la maggior parte delle richieste dovrebbe essere inclusa nel contesto globale, non in una Skill caricata condizionalmente

Se c'è qualcosa che sta cambiando più velocemente di quanto tu possa mantenerlo, non hai bisogno di una Skill. Ad esempio, se stai colpendo qualche endpoint MCP remoto e i suoi strumenti o le versioni di quegli strumenti stanno cambiando frequentemente, non dovresti iniettarli in una Skill. Se lo fai, finirai solo con la deriva e il modello farà errori.

Ogni Skill è una tassa

Ecco un test utile che puoi applicare a ogni frase nella tua Skill: “L'agente sbaglierebbe senza questa istruzione?” Se la frase non ha bisogno di essere lì, non può permettersi di esserlo perché tutti stanno pagando questo costo ogni singola volta. Quando decidi se aggiungere una Skill o meno, ricorda questa tassa in cui ogni Sessione e ogni utente costa token.

La seguente famosa citazione, che suona molto meglio in francese, si traduce approssimativamente in “Ho fatto questa lettera più lunga solo perché non ho avuto il tempo di renderla più breve.”

« Je n’ai fait celle-ci plus longue que parce que je n’ai pas eu le loisir de la faire plus courte. » — Blaise Pascal, Lettres Provinciales, 1657

Proprio come Pascal, devi investire tempo in ogni Skill. È difficile scrivere una Skill breve. Se la tua Skill è facile da scrivere, probabilmente è troppo lunga o non dovrebbe esistere. Una buona Skill è quanto più breve possibile.

Se ti ritrovi a cercare di generare una Skill in un solo colpo e pubblicare PR in cinque minuti, i risultati saranno quasi certamente scadenti. Infatti, la ricerca iniziale ha dimostrato che se stai usando LLM per scrivere Skills, l'LLM probabilmente non ne trarrà beneficio: “Le Skills autogenerate non offrono alcun beneficio in media, mostrando che i modelli non possono autorizzare in modo affidabile la conoscenza procedurale di cui beneficiano nel consumarla.”

Come costruire una Skill

In altre parole, devi iniettare la tua opinione in qualsiasi Skill che scrivi. Segui questi passaggi.

Passaggio 0: Scrivi gli Eval

Scrivi prima alcuni degli eval. Puoi trovare casi di valutazione da:

Query utente reali: campione dalla produzione o dal tuo brain trust

Fallimenti noti: L'agente ha fallito perché la Skill non esisteva

Confusione tra vicini: Vicino al confine del tuo dominio ma instrada verso un'altra Skill

Almeno, dovresti assicurarti di testare che la Skill si carichi quando necessario. Idealmente, ne campioni alcuni, magari da un ambiente di produzione. Potresti anche considerare casi di errore noti: forse l'intero motivo per cui hai deciso di scrivere la Skill è dovuto a un fallimento specifico che hai notato o forse stai rifattorizzando e c'è una certa confusione in due domini vicini che sono coperti da una sola Skill.

Inizia con esempi negativi e positivi simili. Gli esempi negativi sono estremamente potenti e possono contare più degli esempi positivi.

Passaggio 1: La Descrizione

Questa è la riga più difficile nella Skill. È un trigger di routing, non documentazione. Per ottenere il nome e la descrizione giusti, non ti interessa il contenuto della Skill. Ti interessa solo se la Skill viene caricata e iniettata nei punti giusti ed è libera da effetti collaterali fuori bersaglio, che è la modalità di fallimento numero uno. Ogni volta che aggiungi una Skill aggiuntiva, rischi di rendere ogni altra Skill leggermente peggiore, quindi devi assicurarti di minimizzare la regressione.

Ancora, una brutta descrizione descrive cosa fa la Skill o perché è utile. Una buona descrizione dice quando l'agente dovrebbe caricare la Skill. Ad esempio, diciamo che hai qualcosa per il monitoraggio delle pull request. Non scrivere cosa fa la Skill. Scrivi cosa dicono gli ingegneri quando sono frustrati e vogliono che tu ti assicuri che la loro PR funzioni, come “babysit” o “watch CI” o “make sure this lands.”

Ecco una checklist rapida:

Inizia con "Carica quando..."

Punta a 50 parole o meno

Descrive l'intento dell'utente, idealmente da query reali

Non riassume il flusso di lavoro

Le query reali sono ciò che puoi coprire in un 80-20. Di solito, due o tre esempi funzionano bene. Non è facile aggiungere esattamente e solo quanto ti serve.

Passaggio 2: Scrivi il Corpo

Successivamente, scrivi il contenuto della Skill stessa. Nota che questo non è il Passaggio 0 o il Passaggio 1.

Comunicare flussi di lavoro a un LLM è completamente diverso dal comunicare flussi di lavoro a un collega, o anche al tuo sistema di runtime. Quando si impara un nuovo strumento software, un ingegnere potrebbe aver bisogno di leggere la documentazione, ottenere una guida da qualcuno con esperienza, e imparare come usare lo strumento. Nel frattempo, per quasi ogni strumento software in circolazione da almeno un anno, basta menzionarne il nome e l'LLM ha tutte le informazioni di cui ha bisogno.

Quando scrivi il corpo, salta le cose ovvie. Molti ingegneri hanno molta esperienza nello scrivere file readme.md che elencano ogni comando che qualcuno deve eseguire. È facile ricadere in questo quando stai scrivendo una Skill perché sembra di scrivere documentazione, ma se lo fai, la tua Skill sarà spazzatura. Quindi, non scrivere una serie di comandi.

Ad esempio, non hai bisogno di scrivere, “git log # find the commit; git checkout main; git checkout -b <clean-branch>; git cherry-pick <commit>;”

Invece, scrivi, “Cherry-pick il commit su un branch pulito. Risolvi i conflitti preservando l'intento. Se non può approdare in modo pulito, spiega perché.”

Il modello farà un lavoro molto migliore con quest'ultimo rispetto alla serie di comandi eccessivamente prescrittiva del primo, specialmente quando le cose vanno male. Non forzare, o essere eccessivamente prescrittivo, il che è fragile, e invece sii flessibile dove possono funzionare più approcci. Ancora, buona documentazione per gli esseri umani è il più delle volte cattiva documentazione per i modelli.

Successivamente, concentrati sulle insidie o sugli esempi negativi. Questi sono contenuti ad alto segnale perché spesso guidano il modello in termini di cosa non fare. Se aggiungi una riga ogni volta che l'agente inciampa, imparerai eseguendolo e le insidie cresceranno organicamente.

Infine, se c'è una parte che è condizionale o estremamente pesante nel contenuto, rimuovila dal SKILL.md, che è l'hub, e mettila in uno dei raggi. Mettila in un file accessorio che può essere caricato progressivamente, in cui ci addentreremo dopo.

Passaggio 3: Usa la Gerarchia

Sfrutta la gerarchia della Skill quando hai uno script, riferimenti, o stai usando uno strumento specifico:

Usi consigliati per script, riferimenti, asset e configurazione all’interno di una Skill.

Per qualsiasi cosa condizionale o ramificata dalla Skill principale, spezzala in una cartella. Ricorda, inoltre, che la gerarchia multilivello può essere usata per Skills particolarmente complesse. Per queste, vorrai riflettere attentamente se la funzionalità debba essere implementata in modo monolitico o come una collezione di Skills (forse con relazioni di caricamento basate su depends:).

Passaggio 4: Itera

Successivamente, fai un sacco di iterazioni su un branch. Inizia sul branch principale senza Skill, fai alcune iterazioni, costruisci il tuo set di query hero, ed esegui una serie di eval. Chiunque revisioni il tuo codice Skill ti ringrazierà per aver inviato un unico changeset completo di un set di valutazione. Revisionare cambiamenti incrementali consecutivi (eccetto una nuova insidia) è molto difficile, quindi cerca di minimizzarlo.

Probabilmente farai molti piccoli cambiamenti di parole. Piccoli cambiamenti di parole nelle descrizioni possono avere un impatto sproporzionato sul routing (inclusi effetti di spillover su altre Skills), quindi fai tutto quel lavoro prima del Passaggio 5.

Passaggio 5: Spedisci

Spediscilo.

Come Mantenere una Skill

Ora che hai scritto una Skill, devi mantenerla.

Il Volano delle Insidie

Da questo punto in poi, la tua lista di insidie tende a crescere o cambiare molto. Vediamo spesso ingegneri che fanno PR che non sono valutate, ad esempio, cambiare la descrizione. Se stai cambiando la descrizione dopo che la tua Skill è stata unita, sei fuori strada. Se stai facendo cambiamenti alla cosa che decide se instradare la tua Skill, devi scrivere alcuni eval che supportino i cambiamenti.

Le Skills sono in gran parte basate sull'aggiunta. La sezione delle insidie matura il maggior valore nel tempo:

L'agente fallisce in qualcosa → Aggiungi un'insidia

L'agente carica la Skill fuori bersaglio → Stringi la descrizione e aggiungi eval negativi

L'agente non carica la Skill quando dovrebbe → Aggiungi parole chiave ed eval positivi

Il prompt di sistema cambia → Controlla la contesa o la duplicazione

È facile notare un singolo caso di fallimento nei test interni o in produzione e aggiungere un'insidia. È un esempio negativo quindi non sta cambiando davvero la guida esplicita, ma fa sapere al modello, “Ehi, c'è questo fallimento noto.”

Mentre ti sposti dall'80-20 al raggiungimento di un tasso di successo del 99,9% o 99,99%, è facile far crescere questa lista di insidie. Mentre vedi questi esempi negativi, dovresti aggiungere principalmente alla sezione delle insidie. Non dovresti aggiungere istruzioni più lunghe o cambiare la descrizione.

Suite di Eval

In Perplexity, eseguiamo molte suite di eval per controllare cose diverse. Ci sono il caricamento della Skill e le letture dei file della Skill, che controllano la precisione, il richiamo e i controlli proibiti del caricamento della Skill stessa. L'agente instraderà la tua Skill quando dovrebbe? Questi assicurano che le nuove Skills non rompano i confini esistenti.

Ci sono anche eval che possono controllare il corretto caricamento progressivo. L'agente potrebbe caricare la Skill, ma legge il file o i file accessori? Ad esempio, se hai una Skill finanziaria per query finanziarie, legge lo speciale file FORMATTING.md?

Ci sono anche eval per Skills che testano il completamento dei task end-to-end all'interno dei domini. Eseguiamo il ciclo completo dell'agente e usiamo un giudice LLM per valutare i risultati basati su una rubrica di criteri ben definiti.

Infine, è importante eseguire questi eval contro modelli diversi. Computer supporta almeno tre diverse famiglie di modelli di orchestrazione: GPT, Claude Opus e Claude Sonnet. Vuoi eseguire il caricamento della tua Skill e le Skills di dominio contro questi diversi orchestratori di agenti per assicurarti di non ottenere comportamenti diversi. Sonnet e GPT si comportano in modo molto diverso quando si tratta di Skills.

Pensieri finali e conclusioni

Più Skills costruisci, meglio diventerai nel costruirle. Se non stai automatizzando o cercando di rendere più riproducibili i compiti che svolgi quotidianamente usando le Skills, inizia immediatamente.

L'atto di costruire Skills ti rende migliore nel costruire più Skills, ma inoltre, sono estremamente buone nell'automatizzare i processi aziendali. Se puoi descrivere qualcosa che fai ogni settimana prima del tuo standup, alla fine di ogni sprint, o qualsiasi cosa che fai come ingegnere su base giornaliera, settimanale o persino trimestrale, dovresti scrivere una Skill per recuperare il tuo tempo.

Puoi automatizzare i postmortem? Puoi revisionare le pull request? Qualsiasi compito tu possa fare, puoi almeno far sì che il primo passaggio sia un'Agent Skill. Ti farà risparmiare tempo significativo.

Detto questo, ricorda che una Skill non è facile o nemmeno sempre necessaria. Less is more. Alcune altre conclusioni:

Scrivi gli eval prima della Skill. Includi esempi negativi e caricamenti proibiti per abilità adiacenti ma distinte.

La descrizione è la parte difficile. "Carica quando..." (ogni parola costa attenzione).

Le insidie sono contenuti ad alto valore. Inizia leggero, cresci man mano che l'agente fallisce.

Ricorda che è facile rompere altre Skills preesistenti aggiungendo una nuova Skill, anche se non l'hai toccata (fai attenzione all'azione a distanza).

Usa tutti gli strumenti disponibili ogni volta che scrivi e mantieni una Skill. Se vuoi saperne di più, il sito web di Agent Skills ha molti esempi buoni, e sia il nostro repository interno che l'ecosistema pubblico contengono molti esempi di Skills ben progettate.

Citazione

@online{perplexity2026DesigningRefiningAndMaintainingAgentSkillsAtPerplexity,
  author = {{Perplexity} and Marshall Kiely and Daisy Lee and Jerry Ma and Lauren Kolm},
  title = {{Designing, refining, and maintaining agent skills at Perplexity}},
  date = {2026-05-01},
  url = {https://perplexity.coolkeypoint.com/hub/blog/designing-refining-and-maintaining-agent-skills-at-perplexity}
}