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
/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
model 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
subagent: true
subagent: true per eseguire la skill come subagent usando il profilo predefinito subagent_general:
agent: <profile>
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
/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
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.

