SKILL.md all’interno di una directory con un nome specifico. Questa pagina illustra tutto ciò che devi sapere per scrivere skills efficaci.
Struttura dei file
Colloca le skills nella directory appropriata in base all’ambito:/my-skill). Il file SKILL.md contiene un frontmatter YAML facoltativo e il contenuto del prompt della skill.
Su Windows,
%APPDATA% corrisponde in genere a C:\Users\<YourUser>\AppData\Roaming.Riferimento del frontmatter
Tutti i campi del frontmatter
Override del modello
Usa il campomodel per eseguire una skill con un modello diverso da quello attivo nella sessione corrente. È utile se vuoi usare un modello più rapido per attività semplici o uno più potente per quelle complesse:
--model (ad es. opus, sonnet, swe, codex). Consulta Models per l’elenco completo.
Eseguire le skill come subagent
Per impostazione predefinita, il prompt di una skill viene iniettato nella conversazione corrente e l’agente lo elabora inline. In alternativa, puoi eseguire una skill come subagent, che avvia un processo indipendente con una propria finestra di contesto. Questa opzione è utile per skill che svolgono attività mirate e autonome, quando non vuoi che l’output appesantisca la conversazione principale. Esistono due modi per eseguire una skill come subagent:subagent: true
Imposta subagent: true per eseguire la skill come subagent usando il profilo predefinito subagent_general:
agent: <profile>
Utilizza il campo agent per eseguire la skill come subagent con un profilo subagente personalizzato:
agent deve corrispondere al nome di un profilo subagent registrato (integrato, come subagent_explore / subagent_general, oppure un profilo personalizzato che hai definito). Il subagent eredita il system prompt del profilo, le restrizioni sugli strumenti e il modello, mentre il contenuto della skill diventa l’attività. Il campo allowed-tools di un profilo personalizzato costituisce una vera restrizione (gli strumenti non elencati non sono disponibili per il subagent): è quindi il modo per eseguire una skill con un set limitato di strumenti.
Se sono impostati sia
agent sia subagent, agent ha la precedenza. Il campo model della skill esegue l’override del modello del profilo subagent quando sono specificati entrambi.Le skill eseguite come subagent non generano subagent nidificati: se la skill è già in esecuzione all’interno di un subagent, viene invece eseguita inline per evitare una ricorsione infinita.
Orchestrare i subagenti con le skill
Poiché le skill possono essere eseguite come subagenti, puoi usarle per orchestrare attività articolate in più passaggi. Definisci un insieme di skill di subagent, ciascuna dedicata a un’attività specifica, quindi scrivi una normale skill che le invochi. La skill esterna diventa l’orchestratore: richiama ogni subagent, raccoglie i risultati e decide cosa fare successivamente. Ad esempio, ecco due skill di subagent e un orchestratore che le coordina:/health-check esegue l’orchestratore nell’agente principale. Questo richiama /research-changes, che genera un subagent per esplorare la repo. Una volta completato, richiama /validate-tests, che genera un altro subagent per eseguire i test. L’orchestratore sintetizza quindi entrambi i risultati in un riepilogo finale.
Una skill di un subagent non utilizza mai un subagent quando richiama altre skill, anche se queste hanno subagent: true: vengono invece eseguite inline. Questo significa che non devi preoccuparti di un annidamento illimitato. Il modello di orchestrazione ha sempre un solo livello di profondità: l’orchestratore genera i subagent e questi eseguono tutto il resto inline.
Contenuto del prompt
Il contenuto del file SKILL.md (dopo il frontmatter) è il prompt che viene aggiunto quando la skill viene invocata.Autorizzazioni
Le Skills possono definire il proprio ambito di autorizzazione usando la stessa sintassi della configurazione principale delle autorizzazioni:allow— Questi ambiti vengono approvati automaticamente durante l’esecuzione della skilldeny— Questi ambiti vengono bloccati durante l’esecuzione della skillask— Questi ambiti richiedono sempre la conferma dell’utente
deny è il modo per bloccare completamente uno strumento in una skill inline. Le voci con il nome dello strumento, come exec o edit, bloccano l’intero strumento, mentre i pattern mcp__server__tool bloccano gli strumenti MCP — vedi Autorizzazioni basate sugli strumenti.
Le autorizzazioni delle skill sono cumulative rispetto alle autorizzazioni di base della sessione (non le sostituiscono). Una skill non può concedere autorizzazioni negate a un livello superiore (configurazione del progetto o dell’organizzazione).
Le autorizzazioni delle skill si applicano solo quando la skill viene eseguita inline. Non vengono applicate quando la skill viene eseguita come subagent (
subagent: true o agent:).Strumenti approvati automaticamente
allowed-tools elenca gli strumenti approvati automaticamente durante l’esecuzione della skill, così l’agent può usarli senza permission prompt:
permissions.allow per quel nome di strumento. Nomi di strumento disponibili: read, edit, grep, glob, exec
È anche possibile approvare automaticamente gli strumenti MCP:
Esempi
Skill per la revisione del codice
Generatore di componenti
Checklist per la distribuzione
Esperto di ricerca
Suggerimenti
Mantieni i prompt focalizzati
Una skill dovrebbe fare bene una sola cosa. Crea più skill invece di un’unica mega-skill.
Includi esempi
Nel prompt, mostra all’agente che aspetto dovrebbe avere un buon output.
Nega ciò che una skill non deve fare
Usa
permissions.deny (o un profilo di subagent personalizzato) per bloccare gli strumenti. allowed-tools si limita a saltare i prompt.Prova con /skill-name
Invoca la tua skill e perfeziona il prompt finché l’output non è quello che vuoi.

