Estendi Claude con skills

Crea, gestisci e condividi skills per estendere le capacità di Claude in Claude Code. Include comandi personalizzati e skills raggruppate.

Skills estendono ciò che Claude può fare. Crea un file SKILL.md con istruzioni, e Claude lo aggiunge al suo toolkit. Claude utilizza skills quando rilevante, oppure puoi invocare uno direttamente con /skill-name.

Crea una skill quando continui a incollare le stesse istruzioni, checklist o procedure multi-step nella chat, oppure quando una sezione di CLAUDE.md è cresciuta fino a diventare una procedura piuttosto che un fatto. A differenza del contenuto di CLAUDE.md, il corpo di una skill si carica solo quando viene utilizzato, quindi il materiale di riferimento lungo costa quasi nulla fino a quando non ne hai bisogno.

[!NOTE]

Per i comandi integrati come /help e /compact, e per le skills raggruppate come /debug e /code-review, consulta il riferimento dei comandi.

I comandi personalizzati sono stati uniti alle skills. Un file in .claude/commands/deploy.md e una skill in .claude/skills/deploy/SKILL.md creano entrambi /deploy e funzionano allo stesso modo. I tuoi file .claude/commands/ esistenti continuano a funzionare. Le skills aggiungono funzionalità opzionali: una directory per i file di supporto, frontmatter per controllare se tu o Claude le invocate, e la capacità per Claude di caricarle automaticamente quando rilevante.

Le skills di Claude Code seguono lo standard aperto Agent Skills, che funziona su più strumenti AI. Claude Code estende lo standard con funzionalità aggiuntive come il controllo dell'invocazione, l'esecuzione di subagent, e l'iniezione di contesto dinamico. Consulta Utilizzo del frontmatter delle skills al di fuori di Claude Code per sapere quali campi frontmatter fanno parte dello standard e quali sono estensioni di Claude Code.

Skill raggruppati

Claude Code include un set di skill raggruppati, come /doctor, /code-review, /batch, /debug, /loop, e /claude-api. Gli skill raggruppati sono basati su prompt: forniscono a Claude istruzioni dettagliate e gli permettono di orchestrare il lavoro utilizzando i suoi strumenti. La maggior parte dei comandi built-in invece eseguono logica fissa direttamente.

Invochi una skill inclusa digitando / seguito dal nome della skill. Claude invoca automaticamente alcune skill incluse quando sono pertinenti; altre, tra cui /verify, vengono eseguite solo quando le invochi tu.

La maggior parte degli skill raggruppati sono disponibili in ogni sessione. Alcuni dipendono da una funzionalità specifica: /workflow-authoring, ad esempio, è disponibile solo quando i dynamic workflows sono abilitati.

Per disattivare gli skill raggruppati, utilizzate l'impostazione disableBundledSkills.

[!NOTE]

Il controllo della configurazione /doctor rimane digitabile quando disableBundledSkills è attivo. Per nasconderlo, imposta la variabile d'ambiente DISABLE_DOCTOR_COMMAND o una voce skillOverrides con "doctor": "off".

Gli skill raggruppati sono elencati insieme ai comandi built-in nel riferimento dei comandi, contrassegnati come Skill nella colonna Purpose.

Controlla la tua configurazione con /doctor

Esegui /doctor al prompt di Claude Code per un controllo della configurazione che diagnostica i problemi e può risolverli. Claude riporta prima i risultati e chiede conferma prima di modificare qualsiasi cosa. Il controllo copre queste aree:

• Stato dell'installazione: installazioni duplicate o residue, problemi di PATH, file di impostazioni non analizzabili e se è disponibile una versione più recente sul tuo canale di rilascio
• Estensioni: skill, server MCP e plugin inutilizzati confrontati con il loro costo in termini di contesto, e hook lenti
• File CLAUDE.md: file CLAUDE.md locali che duplicano quelli archiviati nel repository, contenuto di CLAUDE.md archiviato che Claude potrebbe ricavare dal codebase e le indicazioni sempre caricate che rimangono, che Claude propone di migrare in skill e in file CLAUDE.md annidati caricati su richiesta
• Permessi: una proposta per rendere la modalità auto la tua modalità di permesso predefinita e per pre-approvare i comandi di sola lettura che neghi frequentemente
• Utilizzo: con un piano Pro, Max, Ultra, Team o Enterprise, le modifiche consigliate da /usage per ridurre l'utilizzo del tuo piano, misurato negli ultimi 7 giorni. Claude propone le modifiche che può apportare autonomamente e riporta le altre come consigli, ad esempio un comando da eseguire. Il controllo dell'utilizzo richiede Claude Code v2.1.305 o versioni successive, e /doctor lo omette mentre Remote Control è connesso.

Per una diagnostica dell'installazione di sola lettura senza avviare una sessione, esegui invece claude doctor nel terminale.

Per verificare le tue istruzioni anziché la tua configurazione, esegui /doctor prompt-audit al prompt di Claude Code. Invece di eseguire il controllo, Claude esamina i tuoi file CLAUDE.md, le skill e altre configurazioni alla ricerca di istruzioni obsolete o in conflitto. Il sottocomando prompt-audit richiede Claude Code v2.1.283 o versioni successive.

Eseguire e verificare la vostra app

Tre skill incluse lavorano insieme per avviare la tua app e verificare le modifiche sull'app in esecuzione anziché solo tramite i test:

/run e /verify funzionano senza configurazione. Deducono il lancio dal tipo di progetto (CLI, server, TUI, browser-driven) e da ciò che si trova nel vostro README, package.json, o Makefile. Quella deduzione diventa inaffidabile per progetti che necessitano di qualcosa oltre a un lancio standard: un database, un file env, una sessione grafica, una compilazione multi-step.

/run-skill-generator registra la ricetta invece. Fa funzionare la vostra app da un ambiente pulito, cattura ciò che ha funzionato (i comandi di installazione, le variabili d'ambiente, lo script di lancio), e lo commit come skill per-progetto in .claude/skills/run-<name>/. Dopo di ciò, /run, /verify, e qualsiasi altro agente nel repository seguono la ricetta registrata invece di riscoprirla. Eseguite /run-skill-generator una volta per progetto, e di nuovo se il processo di compilazione o lancio cambia.

/verify può anche registrare la propria procedura. Quando deve compilare e pilotare la tua app senza una procedura registrata, scrive ciò che ha funzionato in .claude/skills/verify/SKILL.md nella radice del repository, oppure nella directory del pacchetto interessato in un monorepo, così le esecuzioni successive e gli altri agenti seguono gli stessi passaggi. Nella radice del repository, la skill registrata sostituisce la skill inclusa /verify.

Claude modifica il file registrato solo quando ha guidato male un'esecuzione, ad esempio con un comando non riuscito o un passaggio mancante, così puoi fare il commit del file senza diff a ogni sessione.

Esegui i tuoi controlli prima di ogni commit

Quando una sessione si avvia con una skill denominata verify o simplify presente, le istruzioni di commit di Claude Code dicono a Claude di eseguirla subito prima di ogni commit, tranne che per le modifiche a documentazione o test. Questo richiede Claude Code v2.1.286 o versioni successive. Claude riceve questa istruzione quando all'avvio della sessione sono soddisfatte queste condizioni:

• Posizione: la skill viene caricata dalla posizione enterprise, personale, di progetto o di una directory aggiuntiva, oppure da un file .claude/commands/ con quel nome. La procedura che /verify registra nella radice del repository è una skill di progetto, quindi è valida. Le skill incluse /verify e /simplify, le skill dei plugin e le skill del tuo account claude.ai non sono valide.
• Invocazione: Claude può invocare la skill. Se hai impedito a Claude di invocarla, ad esempio con disable-model-invocation: true, Claude non riceve l'istruzione.
• Istruzioni Git: non hai disattivato includeGitInstructions. Disattivarla rimuove questa istruzione insieme al resto delle istruzioni integrate per commit e PR.

Lavorare su progetti Claude API

Lo skill raggruppato /claude-api carica il materiale di riferimento di Claude API e Managed Agents per il linguaggio del vostro progetto. Claude lo attiva anche automaticamente quando il vostro codice importa anthropic o @anthropic-ai/sdk.

Per avviare uno dei flussi di lavoro dello skill, digitate un sottocomando dopo il nome dello skill al prompt di Claude Code, ad esempio /claude-api migrate. La tabella elenca cosa fa ogni sottocomando e la versione più antica di Claude Code che lo include. migrate e managed-agents-onboard precedono v2.1.221, la versione più vecchia che la tabella traccia.

Iniziare

Crea la tua prima skill

Questo esempio crea una skill che riassume i cambiamenti non committati nel tuo repository git e segnala qualsiasi cosa rischiosa. Estrae il diff live nel prompt prima che Claude lo legga, quindi la risposta è basata sul tuo albero di lavoro effettivo piuttosto che su quello che Claude può indovinare dai file aperti. Claude carica la skill automaticamente quando chiedi dei tuoi cambiamenti, oppure puoi invocarla direttamente con /summarize-changes.

1. Crea la directory della skill

Crea una directory per la skill nella tua cartella skills personale. Le skill personali sono disponibili in tutti i tuoi progetti.

mkdir -p ~/.claude/skills/summarize-changes

2. Scrivi SKILL.md

Ogni skill ha bisogno di un file SKILL.md con due parti: frontmatter YAML tra i marcatori --- che dice a Claude quando usare la skill, e contenuto markdown con le istruzioni che Claude segue quando la skill viene eseguita. Il nome della directory diventa il comando che digiti, e la description aiuta Claude a decidere quando caricare la skill automaticamente.

Salva questo in ~/.claude/skills/summarize-changes/SKILL.md:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

La riga !`git diff HEAD` usa dynamic context injection: Claude Code esegue il comando e sostituisce la riga con il suo output prima che Claude veda il contenuto della skill, quindi le istruzioni arrivano con il diff attuale già inline.

3. Testa la skill

Apri un progetto git, fai una piccola modifica a qualsiasi file, e avvia Claude Code eseguendo claude. Puoi testare la skill in due modi.

Lascia che Claude la invochi automaticamente chiedendo qualcosa che corrisponda alla descrizione:

What did I change?

Oppure invocala direttamente con il nome della skill:

/summarize-changes

In entrambi i casi, Claude dovrebbe rispondere con un breve riassunto della tua modifica e un elenco di rischi.

Scegli dove caricare le skill

Il punto in cui salvi una skill decide quali sessioni la caricano. Salvala nella tua directory home per averla in ogni progetto, esegui il commit in un repository per condividerla con chiunque ci lavori, oppure distribuiscila tramite un plugin o le impostazioni gestite per raggiungere un intero team.

Le cartelle delle skill seguono anche queste regole:

• Cartelle con collegamento simbolico: una voce <skill-name> nella posizione enterprise, personale o di progetto può essere un collegamento simbolico a una directory altrove sul disco. Claude Code legge SKILL.md dalla destinazione e carica la skill una sola volta anche se più posizioni puntano alla stessa destinazione. Le skill dei plugin gestiscono i collegamenti simbolici in modo diverso.
• Nome riservato synced: non chiamare una cartella di skill synced, con qualsiasi combinazione di maiuscole e minuscole. Claude Code usa ~/.claude/skills/synced/ per le skill scaricate da claude.ai e ignora una skill che crei con quel nome nelle posizioni enterprise, personale e di progetto.
• Nome riservato anthropic-skills: al di fuori di un plugin, una cartella di skill o un file di comando il cui nome è anthropic-skills o inizia con anthropic-skills: non viene caricato. Consulta Nomi riservati alle skill sincronizzate.
• Caratteri nel nome: al di fuori di un plugin, una cartella di skill non viene caricata quando il suo nome contiene un carattere come uno spazio a larghezza zero o <. Consulta Caratteri che il nome di una skill non può contenere.
• File di comando: un file Markdown in .claude/commands/ è il formato precedente e funziona ancora. Supporta lo stesso frontmatter tranne name e paths. Per trovare il nome da digitare per invocarlo, consulta Come una skill ottiene il nome del suo comando. Per il nuovo lavoro preferisci una skill, poiché le skill supportano anche i file di supporto.
• Cartella di skill come plugin: aggiungi un .claude-plugin/plugin.json a una cartella di skill personale o di progetto e Claude Code può caricarla come plugin chiamato <name>@skills-dir con i propri agenti, hook e server MCP. Nella .claude/skills/ di un progetto, questo richiede prima di accettare la finestra di dialogo di attendibilità del workspace e, in entrambe le posizioni, richiede che il tuo amministratore non abbia bloccato i plugin della directory delle skill.

Caricare le skill in monorepo e sottodirectory

Claude Code carica le skill di progetto da .claude/skills/ nella directory in cui lo avvii e in ogni directory padre fino alla radice del repository, quindi avviandolo in packages/frontend/ rileva comunque le skill definite nella radice. Quando sposti la sessione con /cd nella v2.1.246 o successive, Claude Code aggiunge le skill di progetto della nuova directory.

In una sessione eseguita in un worktree git collegato che hai creato con --worktree o git worktree add, Claude Code cerca nelle directory padre solo fino alla radice del worktree. In Claude Code v2.1.277 o successive, quando il checkout del worktree non ha una directory .claude/skills nella sua radice, Claude Code carica invece le skill di progetto del checkout principale. Consulta Cosa condividono i worktree con il checkout principale.

Le skill in una directory .claude/skills/ al di sotto del punto in cui hai avviato la sessione non vengono caricate all'avvio. Vengono caricate la prima volta che Claude legge o modifica un file in quella sottodirectory e restano disponibili per il resto della sessione. Fino ad allora non compaiono nel menu / e non puoi invocarle per nome. Per caricarle prima, esegui /add-dir con il percorso della sottodirectory, cosa che richiede Claude Code v2.1.257 o successive. Per una sessione worktree che avvii dall'app desktop, consulta Cosa condividono i worktree con il checkout principale.

Quando il nome della directory di una skill annidata corrisponde al nome di un'altra skill, entrambe restano disponibili. Con una skill deploy nella radice del repository e un'altra in apps/web/.claude/skills/:

• /deploy esegue la skill della radice. Claude Code elenca anche le varianti qualificate dalla directory per Claude, con l'istruzione di invocare quella la cui directory contiene i file su cui sta lavorando, quindi la skill annidata si applica comunque al lavoro in apps/web/.
• /apps/web:deploy esegue solo la skill annidata. La sua descrizione indica la directory a cui si applica.

Caricare le skill da una directory esterna al progetto

Quando aggiungi una directory con --add-dir o /add-dir, Claude Code carica le skill nella .claude/skills/ di quella directory, insieme alle sue .claude/commands/ e .claude/agents/. Le directory che l'Agent SDK aggiunge tramite additionalDirectories in TypeScript o add_dirs in Python vengono caricate allo stesso modo, perché l'SDK le passa come --add-dir. L'impostazione permissions.additionalDirectories in settings.json concede solo l'accesso ai file e non carica nessuno di questi elementi.

Claude Code monitora .claude/skills/ in una directory che passi con --add-dir all'avvio, come descritto in Modificare una skill durante una sessione. Non monitora le .claude/commands/ o .claude/agents/ della directory aggiunta, quindi riavvia la sessione dopo aver modificato un file lì.

Questi caricamenti dipendono dalla fonte delle impostazioni project, attiva per impostazione predefinita. Una policy strictPluginOnlyCustomization, la modalità bare e --safe-mode li limitano ulteriormente, come descritto in quelle pagine. Consulta Le directory aggiuntive concedono l'accesso ai file, non la configurazione per la tabella completa di ciò che carica una directory aggiunta, inclusi CLAUDE.md e le impostazioni dei plugin.

Eseguire una skill con lo stesso nome da una directory aggiunta

La skill di una directory aggiunta riceve un prefisso quando il nome della sua cartella è in conflitto con una skill enterprise, personale o di progetto, o con una skill in una directory aggiunta in precedenza. Per eseguirla, digita /<prefix>:<skill-name> nel prompt di Claude Code. Il menu / elenca la skill con il suo nome con prefisso, e Come una skill ottiene il nome del suo comando descrive da dove proviene il prefisso. Quel nome richiede Claude Code v2.1.309 o successive.

Ad esempio, con --add-dir ../cli e una skill verify sia nel tuo progetto sia in ../cli:

• /verify esegue la skill del tuo progetto
• /cli:verify esegue la skill da ../cli

Risolvere le skill che condividono un nome

Quando due skill condividono il nome di una directory o di un file, la provenienza di ciascuna decide quale viene eseguita da /name. Per un nome impostato dal campo name del frontmatter, consulta Come una skill ottiene il nome del suo comando.

Usare le skill nelle sessioni Cowork e cloud

Le sessioni Cowork e le sessioni cloud, incluse le attività pianificate cloud, non leggono ~/.claude/skills/ sulla tua macchina. Sia le sessioni Cowork interattive sia quelle pianificate caricano le skill abilitate per il tuo account claude.ai, sincronizzate all'avvio della sessione. Gestiscile da Customize nella barra laterale dell'app Desktop o dalle impostazioni delle skill su claude.ai.

Se una skill esiste solo in ~/.claude/skills/ sulla tua macchina, Claude Code segnala che la skill non è stata trovata quando un'attività pianificata cloud la invoca. Questo accade perché ogni esecuzione parte come una nuova sessione cloud. Per rendere disponibile una skill personale in queste sessioni:

• Per le sessioni Cowork, le sessioni cloud e i thread cloud in un progetto, abilita la skill per il tuo account claude.ai. Nel thread cloud di un progetto, le skill sottoposte a commit nella .claude/skills/ di un repository non sono disponibili. Alcune sessioni in un ambiente self-hosted non caricano le skill del tuo account.
• Per le sessioni cloud diverse dai thread di progetto, puoi invece eseguire il commit della skill nella .claude/skills/ del repository. I plugin dichiarati nel .claude/settings.json del repository e i plugin abilitati solo nelle tue impostazioni utente non vengono caricati nelle sessioni cloud.

Le attività pianificate di Desktop vengono eseguite localmente sulla tua macchina, quindi caricano ~/.claude/skills/.

Skill sincronizzate da claude.ai

Questa sezione ti riguarda se usi le sessioni Cowork o cloud, oppure se accedi a Claude Code nel terminale con un account claude.ai. In quelle sessioni, Claude Code carica le skill abilitate per il tuo account claude.ai, senza alcuna configurazione da parte tua, come descritto in Dove vengono caricate le skill sincronizzate. Queste skill includono quelle che crei o attivi nelle impostazioni di claude.ai, le skill che la tua organizzazione fornisce lì e le skill integrate di Anthropic come pdf e xlsx.

Claude Code scarica una skill sincronizzata dal tuo account invece di leggere un file che hai scritto sulla macchina in cui viene eseguita la sessione, quindi applica alle skill sincronizzate regole che non si applicano alle skill che archivi nelle posizioni delle skill.

Dove vengono caricate le skill sincronizzate

In una sessione Cowork o cloud, Claude Code carica le skill abilitate per il tuo account claude.ai, e Skill nelle sessioni Cowork e cloud spiega come scegliere quali skill ricevono quelle sessioni.

Nel terminale, Claude Code sincronizza quelle skill nelle sessioni in cui accedi con il tuo account claude.ai. All'avvio della sessione, Claude Code scarica in background le skill del tuo account in ~/.claude/skills/synced/, poi controlla claude.ai per eventuali modifiche mentre la sessione è in esecuzione. Quando un controllo rileva che una skill è stata aggiunta, modificata o disattivata su claude.ai, Claude Code la aggiunge, la aggiorna o la rimuove nella sessione in esecuzione senza riavvio. La sincronizzazione nelle sessioni del terminale richiede Claude Code v2.1.273 o successive.

I controlli vengono eseguiti meno spesso mentre la sessione è inattiva:

• Mentre tu o Claude lavorate nella sessione: un controllo viene eseguito circa ogni 10 minuti.
• Mentre la sessione è inattiva: un controllo viene eseguito circa ogni 40 minuti. Quando digiti di nuovo nella sessione, Claude Code esegue un controllo entro pochi minuti se l'ultimo risale a più di 10 minuti prima.

La sincronizzazione non ritarda mai l'avvio, perché Claude attende il download di una skill solo quando la invoca. Un'esecuzione non interattiva breve può quindi terminare prima che una skill appena aggiunta venga scaricata, nel qual caso la scaricherà una sessione successiva. Per fare in modo che un'esecuzione non interattiva scarichi le tue skill e attenda l'elenco prima di rispondere al prompt, imposta CLAUDE_CODE_SYNC_SKILLS su 1. Prima della v2.1.273, le sessioni del terminale le scaricavano solo in un'esecuzione -p con questa variabile impostata.

Claude Code sincronizza solo in una sessione che accede con il tuo account claude.ai e recupera i feature flag da Anthropic. Non sincronizza in queste sessioni:

• Una sessione che non usa un accesso memorizzato da /login, ad esempio una che si autentica con una chiave API, o una in cui ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN o uno script apiKeyHelper fornisce la credenziale
• Una sessione che non recupera i feature flag, ad esempio una su Amazon Bedrock o una in cui imposti CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC
• Una sessione in modalità bare o una che avvii con --safe-mode
• Una sessione in cui le impostazioni gestite della tua organizzazione limitano le skill alle fonti plugin, o una che avvii con un elenco --setting-sources che esclude user

Se accedi con /login durante una sessione, riavvia Claude Code per iniziare la sincronizzazione.

Le skill sincronizzate da una sessione precedente restano sul disco. Claude Code le carica nelle sessioni successive con accesso allo stesso account, anche quando non riesce a raggiungere claude.ai.

Claude Code scarica le skill sincronizzate e non le invia mai a claude.ai: la sincronizzazione avviene solo in download, mai in upload. Se tu o Claude modificate un file in ~/.claude/skills/synced/, la modifica non viene salvata nel tuo account claude.ai, e una sincronizzazione successiva può sovrascriverla o rimuoverla. Per modificare una skill sincronizzata, aggiornala su claude.ai; la sincronizzazione successiva scarica la nuova versione.

Per vedere quali skill sono state sincronizzate, esegui /skills. Il menu le elenca sotto claude.ai sync.

Alcune skill di Anthropic, come pdf e xlsx, vengono sempre sincronizzate. Per le altre, attiva o disattiva una skill nelle impostazioni delle skill su claude.ai per modificare se viene sincronizzata.

Per interrompere la sincronizzazione su una macchina, imposta syncClaudeAiSkills su false nelle tue impostazioni utente. Claude Code smette di scaricare e, al successivo avvio, sposta le skill già sincronizzate in ~/.claude/skills/.trash/ e non le carica più. La tua organizzazione può disattivare la sincronizzazione per tutti disattivando le Skills su claude.ai. Per interrompere la sincronizzazione lasciando attive le Skills, può impostare la stessa chiave nelle impostazioni gestite.

Se la tua organizzazione disattiva le Skills su claude.ai, Claude Code rimuove le skill scaricate e queste smettono di essere caricate. Le skill rimosse vengono spostate in ~/.claude/skills/.trash/, dove puoi recuperare i file finché la pulizia periodica non li elimina. Quando la tua organizzazione riattiva le Skills, Claude Code scarica le skill che hai abilitato alla sincronizzazione successiva.

Quando il nome di una skill sincronizzata corrisponde a un altro comando

Puoi invocare una skill sincronizzata con il suo nome breve, /<name>, o con il suo nome completo, /anthropic-skills:<name>. Quando un altro comando usa il nome breve, /<name> esegue l'altro comando, e la skill sincronizzata viene eseguita solo come /anthropic-skills:<name>. Con una skill locale deploy e una skill sincronizzata deploy, /deploy esegue la skill locale e /anthropic-skills:deploy esegue quella sincronizzata. Prima della v2.1.269, una skill sincronizzata aveva solo il suo nome breve.

Nel menu /, in /skills e in /context, una skill sincronizzata compare con il suo nome breve, oppure con il suo nome completo quando un altro comando usa il nome breve. Esegui /skills nella tua sessione. Una nota sotto l'elenco spiega ogni skill sincronizzata che ha perso il suo nome breve. Se una delle tue skill personali o dei tuoi file di comando in ~/.claude/ usa quel nome, la nota indica anche cosa rinominare o eliminare per liberarlo.

Dalla v2.1.269 alla v2.1.280, questi elenchi mostravano ogni skill sincronizzata con il suo nome completo, e /skills non aveva questa nota; entrambe le cose sono cambiate nella v2.1.281.

Il comando che usa il nome breve può essere uno qualsiasi di questi:

• Un comando integrato o una skill inclusa, inclusa una non disponibile nella tua sessione, ad esempio dopo che hai disattivato le skill incluse
• Una skill a qualsiasi livello locale o un file in .claude/commands/
• Una skill di un plugin
• Un prompt MCP

Claude Code etichetta le skill sincronizzate così puoi capirne la provenienza. Il menu /skills e /context raggruppano le skill sincronizzate sotto claude.ai sync, e il menu dei comandi / le contrassegna come provenienti da claude.ai.

Quando confronta i nomi, Claude Code ignora maiuscole e minuscole, spaziatura e caratteri invisibili, e tratta le forme di compatibilità, come le lettere a larghezza piena e le varianti del trattino, come i loro equivalenti semplici. Ad esempio, una skill sincronizzata chiamata Commit e una skill locale chiamata commit contano come lo stesso nome, quindi /commit continua a eseguire la tua skill locale.

Un nome che differisce solo per una lettera simile di un altro alfabeto conta come un nome diverso, e l'etichetta claude.ai sync è il modo per distinguerli. Questi controlli ed etichette richiedono Claude Code v2.1.228 o successive.

Nomi riservati alle skill sincronizzate

Claude Code riserva il nome anthropic-skills, e ogni nome all'interno di quello spazio dei nomi come anthropic-skills:pdf, alle skill sincronizzate da claude.ai, così il nome completo di una skill sincronizzata non esegue mai nient'altro. Il nome è riservato in ogni sessione, che tu acceda o meno con un account claude.ai.

• Una cartella di skill, un name nel frontmatter, un file o una sottocartella in .claude/commands/, o un workflow salvato: non viene caricato. Un avviso all'avvio indica il primo elemento da rinominare o modificare.
• Un plugin chiamato anthropic-skills: viene caricato. Quando una delle sue skill e una skill sincronizzata si chiamano entrambe <name>, /anthropic-skills:<name> esegue la skill sincronizzata.
• Un server MCP chiamato anthropic-skills: si connette e i suoi strumenti funzionano, ma i suoi prompt non compaiono come comandi. Rinomina il server nella tua configurazione MCP per elencarli.

Come Claude Code gestisce il frontmatter di una skill sincronizzata

Claude Code applica due regole al frontmatter di una skill sincronizzata:

• Il frontmatter si applica in ogni tipo di sessione, quindi una concessione allowed-tools passa attraverso il normale flusso dei permessi. Se la tua organizzazione imposta allowManagedPermissionRulesOnly, la concessione non si applica.
• Claude Code sanifica il testo visualizzato fornito dalla skill, come la sua descrizione. Rimuove i caratteri di controllo e, nel testo che arriva a Claude, come la descrizione, applica anche l'escape alle parentesi angolari in modo che il testo non possa imitare la formattazione interna di Claude Code. Questa sanificazione richiede Claude Code v2.1.228 o successive.

Come Claude Code gestisce il corpo di una skill sincronizzata

Ciò che Claude Code fa con il corpo di una skill sincronizzata dipende da dove viene eseguita la sessione:

• In una sessione cloud, il corpo mantiene il comportamento di una skill locale, perché la sessione viene eseguita in un container isolato.
• In una sessione Cowork sul tuo desktop, il corpo mantiene il comportamento di una skill locale, tranne per il fatto che Claude Code sostituisce ogni riga di comando ! con il segnaposto disableSkillShellExecution, come fa per ogni skill che fornisci lì.
• In qualsiasi altra sessione sulla tua macchina, Claude Code non esegue i comandi !, non allega i file indicati dai riferimenti @ come fa per una skill locale e non sostituisce i segnaposto ${CLAUDE_PROJECT_DIR} e ${CLAUDE_SESSION_ID}, quindi i riferimenti @ ed entrambi i segnaposto arrivano a Claude come testo letterale. Anche una riga di comando ! arriva a Claude come testo letterale, oppure come quel segnaposto quando disableSkillShellExecution è attivo. Questa gestione richiede Claude Code v2.1.228 o successive.

Modificare una skill durante una sessione

Claude Code monitora le directory delle skill per rilevare modifiche ai file, tranne in modalità bare. Quando aggiungi, modifichi o rimuovi una skill in ~/.claude/skills/, nella .claude/skills/ del progetto o in una .claude/skills/ all'interno di una directory --add-dir, Claude Code rileva la modifica nella sessione corrente, senza riavvio.

Se crei una directory delle skill di primo livello che non esisteva all'avvio della sessione, esegui /reload-skills per rilevare le skill che vi hai inserito. Claude Code non sta ancora monitorando quella directory, quindi esegui di nuovo /reload-skills dopo ogni modifica successiva lì.

Il rilevamento delle modifiche in tempo reale copre solo il testo di SKILL.md. Per una cartella di skill che è anche un plugin, le modifiche a hooks/, .mcp.json, agents/ e output-styles/ richiedono /reload-plugins per avere effetto.

Rimuovere una skill

Il modo in cui rimuovi una skill dipende dalla sua provenienza:

• Skill personale o di progetto: elimina la directory della skill, ~/.claude/skills/<skill-name>/ o .claude/skills/<skill-name>/. Claude Code la rimuove da /skills nella sessione corrente; il contenuto che Claude Code ha già caricato da essa segue il ciclo di vita del contenuto delle skill.
• Skill enterprise: un amministratore elimina la directory della skill da .claude/skills/ all'interno della directory delle impostazioni gestite, ad esempio /etc/claude-code/.claude/skills/<skill-name>/ su Linux.
• Skill di un plugin: disabilita o disinstalla il plugin che la fornisce, dal menu /plugin o con /plugin uninstall <plugin-name>@<marketplace-name>. Claude Code scarica dalla memoria le skill del plugin quando la modifica viene applicata o quando riavvii.
• Skill sincronizzata da claude.ai: disattiva la skill per il tuo account claude.ai, nello stesso punto in cui l'hai abilitata. Claude Code la rimuove da ~/.claude/skills/synced/ la prossima volta che sincronizza le tue skill. Se invece elimini la directory manualmente, la sincronizzazione successiva la scarica di nuovo finché la skill resta abilitata su claude.ai.
• Skill inclusa: imposta disableBundledSkills su true per disattivare le skill incluse, oppure imposta una singola skill su "off" in skillOverrides per nasconderla.

Per mantenere una skill personale o di progetto ma impedire a Claude di invocarla di sua iniziativa, imposta disable-model-invocation: true nel suo frontmatter, oppure "user-invocable-only" in skillOverrides quando non vuoi modificare il file.

Configurare le skill

Le skill si configurano tramite il frontmatter YAML all'inizio di SKILL.md e il contenuto markdown che segue.

Tipi di contenuto delle skill

I file delle skill possono contenere qualsiasi istruzione, ma pensare a come vuoi invocarle aiuta a capire cosa includere:

Il contenuto di riferimento aggiunge conoscenze che Claude applica al tuo lavoro corrente. Convenzioni, pattern, guide di stile, conoscenze di dominio. Questo contenuto viene eseguito inline, così Claude può usarlo insieme al contesto della tua conversazione.

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

Il contenuto di attività fornisce a Claude istruzioni passo passo per un'azione specifica, come deploy, commit o generazione di codice. Spesso si tratta di azioni che vuoi invocare direttamente con /skill-name invece di lasciare che sia Claude a decidere quando eseguirle. Aggiungi disable-model-invocation: true per impedire a Claude di attivarla automaticamente. L'esempio seguente aggiunge context: fork, che esegue la skill nel proprio contesto di subagent; vedi Eseguire le skill in un subagent.

---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

Mantieni conciso il corpo stesso. Una volta caricata una skill, il suo contenuto resta nel contesto nei turni successivi, quindi ogni riga è un costo ricorrente in token. Indica cosa fare invece di raccontare come o perché, e applica lo stesso criterio di concisione che useresti per il contenuto di CLAUDE.md.

Riferimento del frontmatter

Configura una skill con il frontmatter YAML tra i marcatori --- all'inizio di SKILL.md e scrivi le istruzioni della skill in Markdown dopo il --- di chiusura. I nomi dei campi usano parole minuscole separate da trattini, tranne when_to_use. Un file di comando in .claude/commands/ accetta gli stessi campi tranne name e paths. Questo esempio imposta quattro campi:

---
name: my-skill
description: What this skill does
disable-model-invocation: true
allowed-tools: Read Grep
---

Your skill instructions here...

Tutti i campi sono facoltativi. Solo description è consigliato, così Claude sa quando usare la skill. Il nome di un campo deve corrispondere esattamente alla tabella, trattini inclusi: Claude Code ignora un campo che non riconosce senza segnalare alcun errore. I campi booleani accettano yes, no, on, off, 1 e 0 con qualsiasi combinazione di maiuscole e minuscole, oltre a true e false.

Claude Code legge il frontmatter solo quando il --- di apertura è la prima riga del file. Altrimenti tratta l'intero file, marcatori --- inclusi, come contenuto della skill. Se lo YAML tra i marcatori non viene analizzato correttamente, la skill viene comunque caricata senza alcun campo impostato; vedi La skill non si attiva per trovare e correggere l'errore.

Usare il frontmatter delle skill al di fuori di Claude Code

Claude Code accetta tutti i campi della tabella precedente. Al di fuori di Claude Code, puoi usare solo i campi della specifica Agent Skills:

Quando abiliti una skill personale per il tuo account claude.ai, ad esempio per usarla nelle sessioni Cowork e cloud e nelle attività pianificate, la carichi su claude.ai. Le stesse regole si applicano a quel caricamento.

Se includi un campo non consentito dalla specifica, il packaging o il caricamento non riesce con un errore bloccante invece di ignorare il campo:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Limitare il frontmatter ai sei campi della specifica evita l'errore di chiave imprevista riportato sopra. La specifica Agent Skills e i requisiti della Skills API definiscono tutto il resto che quei percorsi convalidano. Le funzionalità del corpo esclusive di Claude Code, come l'iniezione di contesto dinamico, non funzionano nella chat di claude.ai né tramite l'API. Claude Code accetta tutti e sei i campi, quindi un frontmatter conforme alla specifica viene caricato in Claude Code senza modifiche.

Come una skill ottiene il nome del comando

Il comando che digiti per invocare una skill deriva dalla posizione del file della skill e, per le directory delle skill e le skill dei plugin, dal campo name del frontmatter. In una directory di skill personale o di progetto, name imposta il comando mostrato dal menu / e quello che digiti, a meno che un altro comando non usi già quel nome. Anche il nome della directory invoca la skill. In una skill di un plugin, name imposta l'ultimo segmento del comando e il prefisso del plugin resta invariato.

La tabella seguente mostra da dove proviene il nome del comando per ciascuna struttura:

In una skill di un plugin, il name del frontmatter sostituisce il nome della directory nell'ultimo segmento del comando, quindi my-plugin/skills/review/SKILL.md con name: fancy diventa /my-plugin:fancy. Anche il semplice /fancy invoca la skill, a meno che un altro comando non usi già quel nome. Se il name che scrivi inizia già con il prefisso del plugin stesso, dalla v2.1.246 in poi Claude Code non aggiunge di nuovo il prefisso. Ad esempio, name: my-plugin:fancy diventa comunque /my-plugin:fancy. Dalla v2.1.216 alla v2.1.245, Claude Code raddoppiava il prefisso quando il name lo conteneva già.

Nelle sessioni non interattive, i nomi help e feedback non sono riservati ai rispettivi comandi integrati disponibili solo nel terminale, quindi una skill di un plugin con uno di questi nomi mantiene lì il suo comando semplice. Il nome di ogni altro comando integrato disponibile solo nel terminale, come /login, resta riservato anche se il comando non può essere eseguito in quelle sessioni.

Per un SKILL.md nella radice del plugin, non esiste una directory della skill da cui prendere il nome, quindi name fornisce l'intero segmento finale. Senza un campo name, Claude Code usa come fallback il nome della directory del plugin.

Caratteri che il nome di una skill non può contenere

Se una skill o un comando personalizzato non compare nel menu /, oppure il menu non mostra il name del frontmatter di una skill, controlla il nome. Claude Code rifiuta un nome di comando o un name del frontmatter che contiene caratteri come questi:

• Uno spazio a larghezza zero o un carattere di controllo
• Un carattere ad uso privato o non assegnato, come un glifo di un font di icone
• Un carattere che cambia la direzione del testo circostante
• Uno spazio bianco diverso da un singolo spazio semplice tra le parole, come uno spazio unificatore, due spazi consecutivi o uno spazio all'inizio o alla fine
• < o >

Un comando personalizzato o una skill non viene caricato quando Claude Code rifiuta il nome della sua directory o del suo file. Rinomina quella cartella o quel file per rimuovere i caratteri. Una skill viene comunque caricata quando questi caratteri si trovano solo nel nome della cartella di una skill di un plugin o nel suo name del frontmatter:

• Cartella nella directory skills/ di un plugin o nei percorsi skills del suo manifest: non devi rinominare la cartella. Questi caratteri diventano trattini nel nome del comando della skill, quindi digita il comando con i trattini.
• name del frontmatter: il menu / non mostra il valore di name e digitarlo non invoca la skill. Modifica la riga name: per rimuovere i caratteri.

Per scoprire quale nome Claude Code ha rifiutato, avvialo con claude --debug dalla tua shell e cerca [names] nel log di debug. In una sessione interattiva, anche un avviso all'avvio ti informa che alcuni nomi sono stati rifiutati. Dopo una ridenominazione o una modifica di name:, riavvia la sessione, a meno che il file non si trovi in una directory che Claude Code monitora per le modifiche.

Sostituzioni di stringhe disponibili

Le skill supportano la sostituzione di stringhe per valori dinamici nel contenuto della skill:

Claude Code sostituisce ${CLAUDE_SKILL_DIR} e ${CLAUDE_PROJECT_DIR} in due punti: il contenuto markdown della skill e le regole Bash nel frontmatter allowed-tools. In una skill di un plugin, Claude Code sostituisce ${CLAUDE_PLUGIN_ROOT} e ${CLAUDE_PLUGIN_DATA} negli stessi due punti. Usare la stessa variabile in entrambi i punti consente a una skill di eseguire uno script incluso senza una richiesta di permesso. La skill seguente mostra questo schema:

---
name: render-chart
description: Render a chart from a CSV file
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---

Run `${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` to render the chart.

Se questa skill è installata in ~/.claude/skills/render-chart/, entrambe le occorrenze di ${CLAUDE_SKILL_DIR} si espandono in quella directory. La regola allowed-tools corrisponde quindi esattamente al comando che il corpo della skill dice a Claude di eseguire, così lo script viene eseguito senza richieste.

Gli argomenti indicizzati usano le virgolette in stile shell, quindi racchiudi tra virgolette i valori composti da più parole per passarli come un singolo argomento. Ad esempio, /my-skill "hello world" second fa sì che $0 si espanda in hello world e $1 in second. Il segnaposto $ARGUMENTS si espande sempre nell'intera stringa di argomenti così come è stata digitata.

Un segnaposto indicizzato senza un argomento corrispondente, come $2 quando è stato passato un solo argomento, resta invariato nel contenuto. Un segnaposto con nome proveniente dal frontmatter arguments senza un argomento corrispondente si espande in una stringa vuota.

Se passi un valore di argomento che a sua volta contiene testo come $1 o $ARGUMENTS, Claude Code lo inserisce come testo letterale e non lo espande. Ad esempio, se il corpo di una skill contiene Summarize $0 ed esegui /summarize "$ARGUMENTS from yesterday", Claude riceve Summarize $ARGUMENTS from yesterday. Claude Code sostituisce comunque le variabili ${CLAUDE_*} come ${CLAUDE_SKILL_DIR} dopo aver inserito gli argomenti.

Per includere un $ letterale prima di una cifra, di ARGUMENTS o di un nome di argomento dichiarato, come $1.00 nel testo, usa l'escape con una barra rovesciata: \$1.00. Una barra rovesciata prima di qualsiasi altro $ viene lasciata invariata. Solo una singola barra rovesciata direttamente prima del token ne effettua l'escape. Una barra rovesciata doppia come \\$1 lascia entrambe le barre rovesciate al loro posto e $1 si espande comunque nel valore dell'argomento. L'escape con barra rovesciata riguarda solo questi segnaposto di argomenti. Una barra rovesciata non impedisce la sostituzione di una variabile ${CLAUDE_*} dove la variabile si applica.

Esempio con sostituzioni:

---
name: session-logger
description: Log activity for this session
---

Log the following to logs/${CLAUDE_SESSION_ID}.log:

$ARGUMENTS

Aggiungere file di supporto

Le skill possono includere più file nella propria directory. In questo modo SKILL.md resta concentrato sull'essenziale, mentre Claude può accedere al materiale di riferimento dettagliato solo quando serve. Documenti di riferimento di grandi dimensioni, specifiche API o raccolte di esempi non devono essere caricati nel contesto ogni volta che la skill viene eseguita.

my-skill/
├── SKILL.md (required - overview and navigation)
├── reference.md (detailed API docs - loaded when needed)
├── examples.md (usage examples - loaded when needed)
└── scripts/
    └── helper.py (utility script - executed, not loaded)

Fai riferimento ai file di supporto da SKILL.md, così Claude sa cosa contiene ciascun file e quando caricarlo:

## Additional resources

- For complete API details, see [reference.md](/anthropic/claude-code/history/docs/it/2026-11-12-2302..2026-11-13-0258/reference/)
- For usage examples, see [examples.md](/anthropic/claude-code/history/docs/it/2026-11-12-2302..2026-11-13-0258/examples/)

[!TIP]

Mantieni SKILL.md sotto le 500 righe. Sposta il materiale di riferimento dettagliato in file separati.

Controllare chi invoca una skill

Per impostazione predefinita, sia tu sia Claude potete invocare qualsiasi skill. Puoi digitare /skill-name per invocarla direttamente e Claude può caricarla automaticamente quando è pertinente alla conversazione. Due campi del frontmatter ti permettono di limitare questo comportamento:

• disable-model-invocation: true: Claude non può invocare la skill di sua iniziativa. Usalo per i workflow con effetti collaterali o di cui vuoi controllare il momento di esecuzione, come /commit, /deploy o /send-slack-message. Non vuoi che Claude decida di fare il deploy solo perché il tuo codice sembra pronto.

• user-invocable: false: solo Claude può invocare la skill. Usalo per conoscenze di base che non hanno senso come comando. Una skill legacy-system-context spiega come funziona un vecchio sistema. Claude dovrebbe saperlo quando è pertinente, ma /legacy-system-context non è un'azione significativa per gli utenti.

Questo esempio crea una skill di deploy. Se imposti disable-model-invocation: true, Claude non può eseguire la skill automaticamente:

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

Se Claude ci prova comunque, Claude Code blocca la chiamata e gli indica di non riprodurre i passaggi del deploy in altro modo, quindi aspettati che Claude ti suggerisca di eseguire /deploy tu stesso.

Ecco come i due campi influiscono sull'invocazione e sul caricamento nel contesto:

[!NOTE]

In una sessione normale, le descrizioni delle skill vengono caricate nel contesto così Claude sa cosa è disponibile, ma il contenuto completo della skill viene caricato solo quando viene invocata. I subagent con skill precaricate funzionano diversamente: il contenuto completo della skill viene iniettato all'avvio.

Dove scrivere il nome della skill

Per eseguire direttamente una skill, metti il suo nome all'inizio del messaggio. Dopo del testo normale, il nome dà a Claude il permesso di eseguire la skill ma non la esegue:

Per parlare della skill senza autorizzarne l'esecuzione, ometti la barra.

Ciclo di vita del contenuto della skill

Quando tu o Claude invocate una skill, il contenuto renderizzato di SKILL.md entra nella conversazione come un singolo messaggio e vi rimane nei turni successivi. Questa persistenza si applica alle istruzioni della skill, non ai suoi permessi: una concessione allowed-tools decade quando invii il messaggio successivo. Claude Code non rilegge il file della skill nei turni successivi, quindi scrivi le indicazioni che devono valere per tutta un'attività come istruzioni permanenti anziché come passaggi una tantum.

Quando Claude invoca di nuovo una skill il cui contenuto renderizzato è identico alla copia già presente nel contesto, Claude Code aggiunge una breve nota che indica che la skill è già caricata, invece di una seconda copia del contenuto. Quando il contenuto renderizzato è diverso, perché gli argomenti sono cambiati o un comando di contesto dinamico ha prodotto un nuovo output, Claude Code aggiunge di nuovo il contenuto completo.

La compattazione automatica porta avanti le skill invocate entro un budget di token. Quando la conversazione viene riassunta per liberare contesto, Claude Code ricollega dopo il riassunto l'invocazione più recente di ciascuna skill, mantenendo i primi 5.000 token di ognuna. Le skill ricollegate condividono un budget complessivo di 25.000 token. Claude Code riempie questo budget a partire dalla skill invocata più di recente, quindi le skill più vecchie possono essere eliminate del tutto dopo la compattazione se ne hai invocate molte in una sessione.

Se Claude smette di seguire una skill a metà sessione, vedi Claude smette di seguire una skill.

Pre-approvare gli strumenti per una skill

Il campo allowed-tools concede il permesso per gli strumenti elencati durante il turno che invoca la skill, così Claude può usarli senza chiederti l'approvazione. La concessione decade quando invii il messaggio successivo, anche se il contenuto della skill resta nel contesto; invocare di nuovo la skill la riapplica per quel turno. Non limita quali strumenti sono disponibili: ogni strumento resta richiamabile e le tue impostazioni dei permessi continuano a governare gli strumenti non elencati. Per pre-approvare gli strumenti per l'intera sessione anziché per un singolo turno, aggiungi invece regole di autorizzazione a quelle impostazioni dei permessi.

La fiducia nel workspace non vincola questo campo. Claude Code applica l'allowed-tools di una skill di progetto anche in un'esecuzione -p in una cartella di cui non ti sei mai fidato. Una skill può concedersi un ampio accesso agli strumenti, quindi esamina l'allowed-tools delle skill presenti in un repository prima di eseguire Claude Code lì. Per escludere il campo dalle skill dei repository in tutta la tua organizzazione, vedi Quando si applicano solo le regole di permesso gestite.

Questa skill consente a Claude di eseguire comandi git senza approvazione per ogni utilizzo ogni volta che la invochi:

---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

Per rimuovere strumenti dall'insieme disponibile per Claude mentre una skill è attiva, elencali in disallowed-tools nel frontmatter della skill. La restrizione decade quando invii il messaggio successivo. Come le regole di negazione, il campo non può rimuovere EndConversation finché rimane qualsiasi altro strumento. Per bloccare strumenti in tutte le skill e tutti i prompt, aggiungi regole di negazione nelle tue impostazioni dei permessi.

Quando le impostazioni gestite limitano gli hook ai plugin

Quando le impostazioni gestite della tua organizzazione elencano hooks in strictPluginOnlyCustomization, una skill personale o di progetto il cui frontmatter dichiara hooks perde la pre-approvazione di allowed-tools, a parte le skill che la mantengono.

• Verifica: digita /status in una sessione di Claude Code. Se /status mostra Enterprise managed settings, chiedi al tuo amministratore se strictPluginOnlyCustomization elenca hooks.
• Correzione: rimuovi hooks dal frontmatter della skill, perché i suoi hook non vengono eseguiti con quell'impostazione. Per mantenerli, sposta la skill in un plugin che installi da un marketplace.

Quando si applicano solo le regole di permesso gestite

Quando la tua organizzazione imposta allowManagedPermissionRulesOnly nelle impostazioni gestite, Claude Code ignora allowed-tools nelle skill di progetto e personali e nelle altre origini elencate nella voce dell'impostazione. Questo richiede Claude Code v2.1.282 o successivo.

Gli strumenti elencati da una skill interessata passano invece attraverso le regole gestite della tua organizzazione e la normale richiesta di permesso. Esegui /status per elencare ogni skill il cui allowed-tools Claude Code ha ignorato finora nella sessione. Un comando iniettato nella skill che nessuna regola gestita consente segue i Controlli dei permessi sui comandi iniettati.

Passare argomenti alle skill

Sia tu sia Claude potete passare argomenti quando invocate una skill. Gli argomenti sono disponibili tramite il segnaposto $ARGUMENTS.

Questa skill corregge una issue di GitHub in base al numero. Il segnaposto $ARGUMENTS viene sostituito con qualunque cosa segua il nome della skill:

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

Quando esegui /fix-issue 123, Claude riceve "Fix GitHub issue 123 following our coding standards..."

Se invochi una skill con argomenti ma nessun segnaposto nel contenuto della skill ne riceve uno, Claude Code aggiunge ARGUMENTS: <your input> alla fine del contenuto della skill, così Claude vede comunque ciò che hai digitato. Un segnaposto è $ARGUMENTS, una forma indicizzata come $1 o un argomento con nome. Un segnaposto indicizzato senza argomento nella sua posizione resta come testo letterale e non conta come ricezione di un argomento. Un segnaposto con nome conta anche quando nella sua posizione non c'è alcun argomento, perché si espande in una stringa vuota.

Per accedere ai singoli argomenti in base alla posizione, usa $ARGUMENTS[N] o la forma più breve $N:

---
name: migrate-component
description: Migrate a component from one language to another
---

Migrate the $ARGUMENTS[0] component from $ARGUMENTS[1] to $ARGUMENTS[2].
Preserve all existing behavior and tests.

L'esecuzione di /migrate-component SearchBar JavaScript TypeScript sostituisce $ARGUMENTS[0] con SearchBar, $ARGUMENTS[1] con JavaScript e $ARGUMENTS[2] con TypeScript. La stessa skill con la forma abbreviata $N:

---
name: migrate-component
description: Migrate a component from one language to another
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

Combinare più skill in un unico messaggio

Quando digiti nel prompt di Claude Code nel terminale, puoi combinare più skill all'inizio di un unico messaggio. Tramite l'Agent SDK o claude -p, Claude Code carica solo la prima skill, con il resto della riga come suoi argomenti. Nel prompt del terminale, digitare /write-tests /fix-issue 123 carica entrambe le skill e passa il testo finale 123 come $ARGUMENTS a ciascuna di esse.

Claude Code espande la prima skill più fino a cinque altre combinate dopo di essa. L'espansione si ferma al primo token che non è una skill inline invocabile dall'utente. Se combini una skill che viene eseguita come subagent forkato, come /code-review, o una i cui argomenti possono iniziare con un altro comando, come /loop, l'espansione termina lì. Quel token e tutto ciò che segue diventano il testo degli argomenti per ogni skill espansa.

Modelli avanzati

Iniettare contesto dinamico

La sintassi !`<command>` esegue comandi shell prima che il contenuto della skill sia inviato a Claude. L'output del comando sostituisce il placeholder, quindi Claude riceve dati effettivi, non il comando stesso. Claude Code non esegue questi comandi sulla tua macchina quando la skill è sincronizzata dal tuo account claude.ai. Questa restrizione richiede Claude Code v2.1.228 o successivo.

Questa skill riassume una pull request recuperando dati PR live con GitHub CLI. I comandi !`gh pr diff` e altri vengono eseguiti per primi, e il loro output viene inserito nel prompt:

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

La sostituzione viene eseguita una sola volta sul file originale. L'output del comando viene inserito come testo semplice e non viene nuovamente scansionato per ulteriori placeholder !`<command>`, quindi un comando non può emettere un placeholder per un passaggio successivo da espandere.

La forma inline viene riconosciuta solo quando ! appare all'inizio di una riga o immediatamente dopo uno spazio. Se ! segue un altro carattere, come in KEY=!`cmd`, il placeholder viene lasciato come testo letterale e il comando non viene eseguito.

Per comandi multi-riga, utilizza un blocco di codice delimitato con ```! invece della forma inline:

## Environment
```!
node --version
git status --short
```

Per disabilitare questo comportamento per le skill e i comandi personalizzati da fonti utente, progetto, plugin o additional-directory, imposta "disableSkillShellExecution": true in settings. Ogni comando viene sostituito con [shell command execution disabled by policy] invece di essere eseguito. Le skill bundled e gestite non sono interessate. Questa impostazione è più utile in managed settings, dove gli utenti non possono sovrascriverla.

Claude Code non esegue mai questi comandi sulla tua macchina quando appaiono in skill sincronizzate dal tuo account claude.ai, indipendentemente da questa impostazione. Questa restrizione richiede Claude Code v2.1.228 o successivo. How Claude Code handles the body of a synced skill dice cosa Claude riceve al posto del comando in ogni tipo di sessione.

[!TIP]

Per richiedere un ragionamento più profondo quando una skill viene eseguita, includi ultrathink da qualsiasi parte nel contenuto della skill. Vedi Use ultrathink for one-off deep reasoning.

Come vengono eseguiti i comandi iniettati

Claude Code sceglie lo strumento che esegue i comandi iniettati di una skill dalla chiave shell nel frontmatter della skill e dal tuo ambiente. Ogni combinazione esegue i comandi attraverso lo strumento Bash o lo strumento PowerShell, tranne una che fallisce completamente l'invocazione:

• shell: powershell, con lo strumento PowerShell abilitato: i comandi vengono eseguiti attraverso lo strumento PowerShell.
• shell: bash quando bash non è disponibile: l'invocazione fallisce prima che qualsiasi comando venga eseguito. Questo accade su Windows senza Git Bash. Claude Code mostra Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found.
• Qualsiasi altra combinazione: i comandi vengono eseguiti attraverso lo strumento Bash quando bash è disponibile. Quando non lo è, vengono eseguiti attraverso lo strumento PowerShell.

Entrambi gli strumenti eseguono i comandi nello stesso modo in cui Claude esegue i propri comandi shell. Condividono la directory di lavoro, il timeout e la gestione dell'output:

• Directory di lavoro: Claude Code esegue ogni comando nella directory di lavoro corrente della shell della sessione. Quella directory si sposta quando Claude esegue cd. Utilizza ${CLAUDE_SKILL_DIR} o ${CLAUDE_PROJECT_DIR} nei percorsi che devono risolversi nello stesso modo ogni volta.
• stderr: con la shell bash predefinita, Claude Code unisce stderr in stdout. Tutto ciò che il comando scrive su stderr appare nel testo iniettato.
• Timeout: ogni comando viene eseguito sotto il timeout predefinito di 2 minuti dello strumento Bash. Quando lo strumento Bash sposta un comando scaduto in background, la skill viene comunque renderizzata. Il testo iniettato segnala lo spostamento e nomina l'attività in background e il file che raccoglie l'output del comando. Quando il comando è uno che lo strumento Bash non mette mai automaticamente in background, Claude Code lo termina al timeout. Quel fallimento interrompe l'invocazione.
• Dimensione dell'output: l'output oltre il limite inline dello strumento Bash arriva come percorso file più un'anteprima breve, non testo troncato. Output limits copre il limite e come regolare ogni confine.

Lo strumento PowerShell applica lo stesso timeout, backgrounding e comportamento di output-ceiling ai comandi che esegue. Vedi la sezione PowerShell tool per i suoi dettagli.

Quando un comando iniettato fallisce

Un comando fallito interrompe l'intera invocazione della skill, non solo il suo placeholder. Claude non vede mai il contenuto della skill per quella invocazione. L'interruzione mostra Shell command failed for pattern "...". Il messaggio di errore include l'output del comando.

Con la shell bash predefinita, qualsiasi codice di uscita diverso da zero conta come un fallimento. Si applica un'eccezione: Claude Code tratta il codice di uscita 1 dai comandi di ricerca e confronto come un risultato normale e inietta il loro output. I codici di uscita 2 o superiori falliscono anche per quei comandi.

Quali comandi ottengono l'eccezione dipende dalla shell:

• Shell bash predefinita: i comandi elencati sotto Output limits
• shell: powershell, quando lo strumento PowerShell è abilitato: un set diverso che include grep e git diff ma non find o diff

Con la shell bash predefinita, aggiungi || true a qualsiasi altro comando che ti aspetti esca con un codice non zero. Uno script di controllo che esce con 1 quando trova problemi è un esempio.

Quando nessun comando shell è stato eseguito

No shell command in <name> was run significa che uno dei suoi comandi shell contiene un carattere che lo strumento non accetta. Per trovare e rimuovere il carattere, consulta il riferimento agli errori.

Controlli di permesso sui comandi iniettati

I comandi iniettati non richiedono mai il permesso mentre la skill viene renderizzata. Claude Code controlla ogni comando rispetto alle tue regole di permesso per primo. Un comando che una regola deny corrisponde interrompe l'invocazione con Shell command permission check failed for pattern "...".

Al di fuori della modalità auto, quando il controllo dei permessi di un comando restituisce qualcosa di diverso da allow, Claude Code interrompe l'invocazione con lo stesso errore. Questo include una regola che normalmente ti chiederebbe. Per evitare che un comando non corrispondente interrompa qui, pre-approvalo con allowed-tools. Se la tua organizzazione limita le regole di permesso alle impostazioni gestite, vedi When only managed permission rules apply. Le regole deny e ask sovrascrivono comunque allowed-tools. Vedi Manage permissions.

In modalità auto, un comando che altrimenti avrebbe bisogno della tua approvazione non interrompe l'invocazione. La skill si carica con un'istruzione che dice a Claude di eseguire il comando per primo, e la chiamata di Claude passa quindi attraverso i controlli usuali della modalità auto. L'invocazione interrompe comunque in una skill forkata che imposta agent, e in una sessione dove Claude non ha lo strumento shell che esegue i comandi iniettati.

Eseguire skill in un subagent

Aggiungi context: fork al tuo frontmatter quando vuoi che una skill venga eseguita in isolamento. Claude Code avvia un nuovo subagent del tipo impostato nel campo agent e gli fornisce il contenuto della skill come suo prompt. Il subagent non vede la cronologia della tua conversazione, quindi le istruzioni della skill devono stare da sole.

[!NOTE]

Nonostante il nome, una skill con context: fork non viene eseguita in un fork della conversazione corrente, che darebbe al subagent tutto ciò che hai discusso finora. Quando l'attività dipende da quella cronologia, fai il fork della conversazione invece di usare context: fork.

Il subagent forkato viene eseguito in background: continui a lavorare mentre viene eseguito, e il suo risultato arriva nella tua conversazione quando si completa. Imposta background: false nel frontmatter per invece attendere il risultato nel turno che ha invocato la skill.

Claude Code attende anche il risultato, anche quando la skill non imposta background: false, in casi come questi:

• In modalità non interattiva, con il flag -p o l'Agent SDK
• Quando imposti CLAUDE_CODE_DISABLE_BACKGROUND_TASKS a 1, che disattiva anche le altre funzionalità di attività in background
• Quando invochi una skill forkata mentre un'invocazione precedente della stessa skill è ancora in esecuzione
• Quando un'attività pianificata con ambito di sessione si attiva con la skill come suo prompt

Quando un agente in un workflow dinamico invoca una skill forkata, quell'agente attende e riceve il risultato, anche quando la skill non imposta background: false. Prima della v2.1.295, quando la skill veniva eseguita in background, quell'agente non la attendeva. Il risultato della skill arrivava quindi nella tua conversazione principale invece di raggiungere l'agente.

Un fork in background viene eseguito anche con il set di strumenti più ristretto che si applica ai subagent in background: il subagent della skill è un tipo di agent regolare, quindi l'esenzione per i subagent che forkano la conversazione non lo copre. Se i passaggi della tua skill dipendono da uno strumento al di fuori di quel set, imposta background: false per mantenere il set di strumenti completo.

Una skill forkata che viene eseguita in background applica le sue modifiche al di fuori dei checkpoint della tua sessione. Dopo una di queste esecuzioni, /rewind ripristina solo i file che Claude aveva già modificato nella tua conversazione. Le modifiche della skill ad altri file restano, quindi usa git per annullarle.

[!WARNING]

context: fork ha senso solo per skill con istruzioni esplicite. Se la tua skill contiene linee guida come "usa queste convenzioni API" senza un compito, il subagent riceve le linee guida ma nessun prompt azionabile, e ritorna senza output significativo.

Le skill e i subagent lavorano insieme in due direzioni:

Con context: fork, scrivi il compito nella tua skill e scegli un tipo di agent per eseguirlo. Gli agent Explore e Plan built-in si avviano senza CLAUDE.md e git status per mantenere il loro contesto piccolo. Metti tutto ciò di cui il compito ha bisogno nel tuo SKILL.md. Una skill forkata che usa agent: Explore parte con quel contenuto e il prompt di sistema dell'agent, e nessuno dei tuoi file CLAUDE.md.

Per l'inverso, dove definisci un subagent personalizzato che usa le skill come materiale di riferimento, vedi Subagents.

Esempio: Skill di ricerca usando l'agent Explore

Questa skill esegue ricerche in un agent Explore forkato. Il contenuto della skill diventa il compito, e l'agent fornisce strumenti di sola lettura ottimizzati per l'esplorazione della codebase:

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

Quando questa skill viene eseguita:

1. Viene creato un nuovo contesto isolato
2. Il subagent riceve il contenuto della skill come suo prompt (le istruzioni "Research $ARGUMENTS thoroughly")
3. Il campo agent determina l'ambiente di esecuzione (modello, strumenti e permessi)
4. Il subagent riassume i suoi risultati e li restituisce alla tua conversazione principale quando finisce

Il campo agent specifica quale configurazione di subagent utilizzare. Le opzioni includono agent built-in (Explore, Plan, general-purpose) o qualsiasi subagent personalizzato da .claude/agents/. Se omesso, utilizza general-purpose.

Limitare l'accesso alle skill di Claude

Per impostazione predefinita, Claude può invocare qualsiasi skill che non abbia disable-model-invocation: true impostato. Le skill che definiscono allowed-tools concedono a Claude l'accesso a quegli strumenti senza approvazione per uso durante il turno che invoca la skill; la concessione si cancella quando invii il tuo prossimo messaggio. Le tue impostazioni di permesso governano comunque il comportamento di approvazione di base per tutti gli altri strumenti. Alcuni comandi integrati sono anche disponibili attraverso lo strumento Skill, inclusi /init e /security-review. Altri comandi integrati come /compact non lo sono.

Tre modi per controllare quali skill Claude può invocare:

Disabilitare tutte le skill negando lo strumento Skill in /permissions:

# Add to deny rules:
Skill

Consentire o negare skill specifiche usando regole di permesso:

# Allow only specific skills
Skill(commit)
Skill(review-pr *)

# Deny specific skills
Skill(deploy *)

Sintassi di permesso: Skill(name) per corrispondenza esatta, Skill(name *) per corrispondenza di prefisso con qualsiasi argomento.

La tabella mostra cosa una regola deny blocca oltre al nome che scrivi, in base al tipo di nome nella regola.

Prima della v2.1.260, Claude Code non bloccava una skill annidata elencata sotto il suo nome qualificato quando la regola deny nominava solo il nome non qualificato.

Claude Code corrisponde a una regola allow solo contro il nome della skill stessa e il nome nell'invocazione di Claude. Per approvare una skill sincronizzata senza un prompt, nominala all'interno del suo spazio dei nomi riservato:

• Skill(anthropic-skills:pdf) approva la skill sincronizzata pdf
• Skill(anthropic-skills *) approva ogni skill sincronizzata
• Skill(anthropic *) non copre anthropic-skills:pdf, perché un prefisso al di fuori dello spazio dei nomi non corrisponde ai nomi al suo interno

Nascondere skill individuali aggiungendo disable-model-invocation: true al loro frontmatter. Questo rimuove la skill dal contesto di Claude interamente.

[!NOTE]

Con user-invocable: false, non puoi invocare la skill, ma Claude ancora può. Per impedire a Claude di invocarla attraverso lo strumento Skill, imposta disable-model-invocation: true.

Sovrascrivere la visibilità della skill dalle impostazioni

L'impostazione skillOverrides controlla la visibilità della skill dalle tue impostazioni invece dal frontmatter della skill stessa. Usala per skill il cui SKILL.md non vuoi modificare, come quelle controllate in un repo di progetto condiviso. Il menu /skills lo scrive per te: evidenzia una skill e premi Space per ciclo gli stati, quindi Esc per salvare in .claude/settings.local.json.

Ogni chiave è un nome di skill e ogni valore è uno di quattro stati:

Il menu /skills etichetta lo stato "user-invocable-only" come user-only.

"off" nasconde anche la skill dagli elenchi di comandi pubblicizzati ai client Remote Control e ai chiamanti Agent SDK, oltre al menu / del terminale. Invocare una skill nascosta per il suo nome completo restituisce l'errore skillOverrides invece di eseguirla.

Una skill assente da skillOverrides viene trattata come "on". L'esempio seguente comprime una skill al suo nome e disattiva completamente un'altra:

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

Alcune skill bundled hanno alias, come checkup per /doctor. Se imposti una voce skillOverrides sotto un alias in managed settings o in un file che passi con il flag --settings, Claude Code la applica alla skill dietro l'alias. Puoi solo limitare una skill ulteriormente attraverso un alias, mai renderla più visibile, e se imposti anche una voce sotto il nome della skill stessa in managed settings, quella voce ha la precedenza. Prima della v2.1.260, Claude Code non applicava una voce sotto un alias alla skill in nessuna fonte di impostazioni.

Nelle impostazioni utente, progetto e locale, Claude Code corrisponde alle voci solo contro i nomi delle skill. Se imposti una voce per review lì, si applica a una skill denominata review, non al bundled /code-review attraverso il suo alias /review.

Le skill dei plugin non sono interessate da skillOverrides. Gestisci quelle attraverso /plugin invece.

Trovare skill inutilizzate

Ogni skill nell'elenco delle skill aggiunge al tuo contesto ad ogni turno, indipendentemente dal fatto che Claude la usi mai. Esegui /skill-doctor per vedere cosa costa ogni tua skill e quanto spesso viene utilizzata, così puoi decidere quali disattivare. In una sessione interattiva, il rapporto si apre nella scheda Stats del gestore /plugin. In modalità non interattiva con -p, Claude Code lo stampa come testo.

Il rapporto copre le skill nella tua sessione diverse dalle skill bundled e dalle skill enterprise. Segnala le skill nell'elenco che non sono mai state invocate e dice dove disattivarle. Delle skill che ti dice dove disattivare, inizia con quelle che hanno il costo di contesto più alto. Il rapporto elenca anche i plugin che non hai utilizzato di recente.

/skill-doctor richiede Claude Code v2.1.252 o successivo e non è disponibile in sessioni che saltano feature-flag fetching. Se esegui /skill-doctor su Remote Control dal tuo telefono o browser, Claude Code risponde Skill usage reports are not available on this connection. invece. Esegui /skill-doctor nel terminale sulla macchina dove la sessione è in esecuzione.

Valutare e iterare su una skill

Vedere una skill attivata ti dice che Claude l'ha trovata, non che abbia fatto quello che intendevi. Per sapere che una skill funziona, misura separatamente se Claude la invoca sui prompt che dovrebbe, e se l'output corrisponde a quello che ti aspetti quando lo fa.

Il controllo per entrambi è un confronto di base. Raccogli alcuni prompt realistici, esegui ognuno in una sessione nuova con la skill disponibile e di nuovo con essa disattivata, e confronta i risultati. Una sessione nuova è importante perché il contesto residuo dalla creazione della skill maschererà le lacune nelle istruzioni scritte.

Come disattivi la skill per la seconda esecuzione dipende da dove proviene:

• Skill personale o di progetto: impostala su "off" in skillOverrides.
• Skill fornita da un plugin: skillOverrides non si applica alle skill dei plugin. Usa claude plugin eval invece, che ripete ogni esecuzione senza plugin caricato.

Due strumenti automatizzano il confronto di base. Per una skill fornita in un plugin, claude plugin eval esegue ogni prompt in una sessione isolata con e senza il plugin, la valuta con grader che definisci o che scrive per te, e esce con un codice diverso da zero al di sotto di una soglia in modo da poter controllare il CI su di essa. Per iterare su una singola skill all'interno di una conversazione Claude Code, il plugin skill-creator di seguito esegue un ciclo simile con il suo formato evals/evals.json. I due formati non sono intercambiabili.

Esegui eval con skill-creator

Il skill-creator plugin automatizza il ciclo di confronto all'interno di Claude Code. Nell'estensione VS Code o nell'app desktop, installalo dal marketplace ufficiale seguendo Installare un plugin. In un terminale, avvia Claude Code eseguendo claude, quindi inserisci questo al suo prompt:

/plugin install skill-creator@claude-plugins-official

Se l'installazione fallisce, fai corrispondere il messaggio che Claude Code segnala:

• Marketplace "claude-plugins-official" not found: aggiungi il marketplace con /plugin marketplace add anthropics/claude-plugins-official, quindi riprova l'installazione.
• Plugin "<name>" not found in marketplace "claude-plugins-official": la tua copia locale del catalogo del marketplace potrebbe non essere aggiornata. Aggiornala con /plugin marketplace update claude-plugins-official, quindi riprova l'installazione. Se il nuovo tentativo stampa lo stesso messaggio, consulta Plugin not found in marketplace.

Se il riepilogo dell'installazione segnala Run /reload-plugins to apply., Claude Code esegue quindi quel ricaricamento per te. Se il ricaricamento avverte che il tuo prossimo messaggio rileggerebbe la conversazione, esegui /reload-plugins --force per rendere disponibili le skill del plugin nella sessione corrente. Quindi chiedi a Claude di valutare una skill esistente, ad esempio evaluate my summarize-changes skill with skill-creator. Il plugin ti guida attraverso la scrittura dei test case ed esegue il ciclo:

• Test cases: memorizza prompt, file di input e comportamento previsto in evals/evals.json all'interno della directory della skill
• Isolated runs: genera un subagent per test case in modo che ogni esecuzione inizi con un contesto pulito, e registra il conteggio dei token e la durata
• Grading: controlla ogni asserzione rispetto all'output e scrive pass o fail con evidenza in grading.json
• Benchmark: aggrega il pass rate, il tempo e i token per with-skill versus without-skill in benchmark.json in modo da poter confrontare il miglioramento del pass-rate rispetto al sovraccarico di token e tempo
• Version comparison: esegue un blind A/B tra due versioni della skill in modo da poter confermare che una modifica è un miglioramento prima di eseguirne il commit
• Description tuning: genera prompt should-trigger e should-not-trigger, misura il hit rate e propone modifiche alla descrizione quando la skill si attiva su richieste sbagliate
• Review viewer: apre un report HTML dove puoi ispezionare ogni output e registrare feedback qualitativo che l'iterazione successiva legge

Per il formato del file eval e il flusso di lavoro di iterazione completo, vedi Evaluating skill output quality su agentskills.io. Per informazioni di base sui modi benchmark e comparison, vedi l'annuncio skill-creator.

Condividere skills

Gli skills possono essere distribuiti a diversi livelli a seconda del vostro pubblico:

• Project skills: Eseguire il commit di .claude/skills/ nel controllo versione
• Plugins: Creare una directory skills/ nel vostro plugin
• Managed: Distribuire a livello organizzativo tramite managed settings

Generare output visuale

Gli skills possono raggruppare ed eseguire script in qualsiasi linguaggio, fornendo a Claude capacità oltre ciò che è possibile in un singolo prompt. Un modello è la generazione di output visuale: file HTML interattivi che si aprono nel vostro browser per esplorare dati, eseguire il debug o creare report.

Questo esempio crea un codebase explorer: una vista ad albero interattiva dove potete espandere e comprimere directory, visualizzare le dimensioni dei file a colpo d'occhio e identificare i tipi di file per colore.

Creare la directory Skill:

mkdir -p ~/.claude/skills/codebase-visualizer/scripts

Salvare questo in ~/.claude/skills/codebase-visualizer/SKILL.md. La descrizione dice a Claude quando attivare questo Skill e le istruzioni dicono a Claude di eseguire lo script raggruppato. Il percorso dello script utilizza ${CLAUDE_SKILL_DIR} in modo che si risolva correttamente indipendentemente dal fatto che lo skill sia installato a livello personale, di progetto o di plugin:

---
name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
allowed-tools: Bash(python3 *)
---

# Codebase Visualizer

Generate an interactive HTML tree view that shows your project's file structure with collapsible directories.

## Usage

Run the visualization script from your project root:

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .
```

This creates `codebase-map.html` in the current directory and opens it in your default browser.

## What the visualization shows

- **Collapsible directories**: Click folders to expand/collapse
- **File sizes**: Displayed next to each file
- **Colors**: Different colors for different file types
- **Directory totals**: Shows aggregate size of each folder

Salvare questo in ~/.claude/skills/codebase-visualizer/scripts/visualize.py. Questo script scansiona un albero di directory e genera un file HTML autonomo con:

• Una barra laterale di riepilogo che mostra il conteggio dei file, il conteggio delle directory, la dimensione totale e il numero di tipi di file
• Un grafico a barre che suddivide la codebase per tipo di file (i primi 8 per dimensione)
• Un albero comprimibile dove potete espandere e comprimere directory, con indicatori di tipo di file codificati per colore

Lo script richiede Python 3 ma utilizza solo librerie integrate, quindi non ci sono pacchetti da installare:

#!/usr/bin/env python3
"""Generate an interactive collapsible tree visualization of a codebase."""

import json
import sys
import webbrowser
from html import escape
from pathlib import Path
from collections import Counter

IGNORE = {'.git', 'node_modules', '__pycache__', '.venv', 'venv', 'dist', 'build'}

def scan(path: Path, stats: dict) -> dict:
    result = {"name": path.name, "children": [], "size": 0}
    try:
        for item in sorted(path.iterdir()):
            if item.name in IGNORE or item.name.startswith('.'):
                continue
            if item.is_file():
                size = item.stat().st_size
                ext = item.suffix.lower() or '(no ext)'
                result["children"].append({"name": item.name, "size": size, "ext": ext})
                result["size"] += size
                stats["files"] += 1
                stats["extensions"][ext] += 1
                stats["ext_sizes"][ext] += size
            elif item.is_dir():
                stats["dirs"] += 1
                child = scan(item, stats)
                if child["children"]:
                    result["children"].append(child)
                    result["size"] += child["size"]
    except PermissionError:
        pass
    return result

def generate_html(data: dict, stats: dict, output: Path) -> None:
    ext_sizes = stats["ext_sizes"]
    total_size = sum(ext_sizes.values()) or 1
    sorted_exts = sorted(ext_sizes.items(), key=lambda x: -x[1])[:8]
    colors = {
        '.js': '#f7df1e', '.ts': '#3178c6', '.py': '#3776ab', '.go': '#00add8',
        '.rs': '#dea584', '.rb': '#cc342d', '.css': '#264de4', '.html': '#e34c26',
        '.json': '#6b7280', '.md': '#083fa1', '.yaml': '#cb171e', '.yml': '#cb171e',
        '.mdx': '#083fa1', '.tsx': '#3178c6', '.jsx': '#61dafb', '.sh': '#4eaa25',
    }
    lang_bars = "".join(
        f'<div class="bar-row"><span class="bar-label">{ext}</span>'
        f'<div class="bar" style="width:{(size/total_size)*100}%;background:{colors.get(ext,"#6b7280")}"></div>'
        f'<span class="bar-pct">{(size/total_size)*100:.1f}%</span></div>'
        for ext, size in sorted_exts
    )
    def fmt(b):
        if b < 1024: return f"{b} B"
        if b < 1048576: return f"{b/1024:.1f} KB"
        return f"{b/1048576:.1f} MB"

    html = f'''<!DOCTYPE html>
<html><head>
  <meta charset="utf-8"><title>Codebase Explorer</title>
  <style>
    body {{ font: 14px/1.5 system-ui, sans-serif; margin: 0; background: #1a1a2e; color: #eee; }}
    .container {{ display: flex; height: 100vh; }}
    .sidebar {{ width: 280px; background: #252542; padding: 20px; border-right: 1px solid #3d3d5c; overflow-y: auto; flex-shrink: 0; }}
    .main {{ flex: 1; padding: 20px; overflow-y: auto; }}
    h1 {{ margin: 0 0 10px 0; font-size: 18px; }}
    h2 {{ margin: 20px 0 10px 0; font-size: 14px; color: #888; text-transform: uppercase; }}
    .stat {{ display: flex; justify-content: space-between; padding: 8px 0; border-bottom: 1px solid #3d3d5c; }}
    .stat-value {{ font-weight: bold; }}
    .bar-row {{ display: flex; align-items: center; margin: 6px 0; }}
    .bar-label {{ width: 55px; font-size: 12px; color: #aaa; }}
    .bar {{ height: 18px; border-radius: 3px; }}
    .bar-pct {{ margin-left: 8px; font-size: 12px; color: #666; }}
    .tree {{ list-style: none; padding-left: 20px; }}
    details {{ cursor: pointer; }}
    summary {{ padding: 4px 8px; border-radius: 4px; }}
    summary:hover {{ background: #2d2d44; }}
    .folder {{ color: #ffd700; }}
    .file {{ display: flex; align-items: center; padding: 4px 8px; border-radius: 4px; }}
    .file:hover {{ background: #2d2d44; }}
    .size {{ color: #888; margin-left: auto; font-size: 12px; }}
    .dot {{ width: 8px; height: 8px; border-radius: 50%; margin-right: 8px; }}
  </style>
</head><body>
  <div class="container">
    <div class="sidebar">
      <h1>📊 Summary</h1>
      <div class="stat"><span>Files</span><span class="stat-value">{stats["files"]:,}</span></div>
      <div class="stat"><span>Directories</span><span class="stat-value">{stats["dirs"]:,}</span></div>
      <div class="stat"><span>Total size</span><span class="stat-value">{fmt(data["size"])}</span></div>
      <div class="stat"><span>File types</span><span class="stat-value">{len(stats["extensions"])}</span></div>
      <h2>By file type</h2>
      {lang_bars}
    </div>
    <div class="main">
      <h1>📁 {escape(data["name"])}</h1>
      <ul class="tree" id="root"></ul>
    </div>
  </div>
</body></html>'''
    output.write_text(html)

if __name__ == '__main__':
    target = Path(sys.argv[1] if len(sys.argv) > 1 else '.').resolve()
    stats = {"files": 0, "dirs": 0, "extensions": Counter(), "ext_sizes": Counter()}
    data = scan(target, stats)
    out = Path('codebase-map.html')
    generate_html(data, stats, out)
    print(f'Generated {out.absolute()}')
    webbrowser.open(f'file://{out.absolute()}')

Per testare, aprite Claude Code in qualsiasi progetto e chiedete "Visualize this codebase." Claude esegue lo script, che stampa il percorso del file generato, come Generated /path/to/codebase-map.html, e lo apre nel vostro browser. Se lavorate in un ambiente headless dove nessun browser si apre, il percorso stampato conferma che lo script ha avuto successo.

Questo modello funziona per qualsiasi output visuale: grafici di dipendenza, report di copertura dei test, documentazione API o visualizzazioni dello schema del database. Lo script raggruppato fa il lavoro mentre Claude gestisce l'orchestrazione.

Troubleshooting

Skill not triggering

Se Claude non utilizza la vostra skill quando previsto:

1. Verificate che la descrizione includa parole chiave che gli utenti direbbero naturalmente
2. Verificate che la skill appaia in What skills are available?
3. Provate a riformulare la vostra richiesta per corrispondere più strettamente alla descrizione
4. Invocatela direttamente con /skill-name se la skill è invocabile dall'utente
5. Se nemmeno /skill-name viene riconosciuto, verifica se Claude Code ha rifiutato il nome della skill
6. Se la skill imposta paths, verifica che i file che Claude legge, modifica o scrive si trovino all'interno della directory di lavoro corrente di Claude. La skill non si attiva per i file al di fuori di essa, come quelli in un worktree git adiacente, anche se lo hai aggiunto con /add-dir. Per far sì che la skill si attivi per quei file, avvia Claude Code in quel worktree oppure sposta lì la sessione con /cd.

Se il YAML del frontmatter è malformato, Claude Code carica il corpo della skill con metadati vuoti, quindi /skill-name funziona comunque ma Claude non può corrispondere alla vostra description. Eseguite con --debug per vedere l'errore di parsing.

Se la skill è fornita in un plugin, potete misurare con quale frequenza si attiva su prompt realistici piuttosto che controllare uno alla volta: scrivete un caso di eval con un grader tool_used: Skill ed eseguitelo con claude plugin eval dopo ogni modifica della descrizione.

Per trovare file SKILL.md il cui frontmatter non viene analizzato, eseguite claude plugin validate sulla directory delle skills, ad esempio claude plugin validate .claude/skills per le skills del progetto o claude plugin validate ~/.claude/skills per le skills personali. Richiede Claude Code v2.1.233 o successivo.

Skill triggers too often

Se Claude utilizza la vostra skill quando non lo desiderate:

1. Rendete la descrizione più specifica
2. Aggiungete disable-model-invocation: true se desiderate solo l'invocazione manuale

Claude stops following a skill

Se Claude segue una skill nella sua prima risposta e smette di seguirla in seguito, iniziate con il caso che corrisponde:

• Claude ha saltato una regola che deve valere ogni volta: spostate la regola in un hook. Claude Code esegue un hook ogni volta che si verifica il suo evento, ad esempio prima di ogni modifica di file, indipendentemente dal fatto che Claude stia seguendo la skill o meno. Per mantenere la regola con la skill, definite l'hook nel frontmatter hooks della skill. Quell'hook si applica dal momento in cui la skill viene invocata fino al termine della sessione.
• Claude ha saltato una guida che dovrebbe applicare con giudizio: riformulate la guida in modo che si applichi all'intero compito, ad esempio "Eseguite i test dopo ogni modifica" piuttosto che "Eseguite i test". Claude Code aggiunge il contenuto della skill alla conversazione quando la skill viene invocata e non rilegge il file nei turni successivi.
• La conversazione è stata compattata: invocate di nuovo la skill per ripristinare il suo contenuto completo. Dopo la compattazione, Claude Code può mantenere solo l'inizio di una skill invocata, quindi mettete le istruzioni più importanti vicino alla parte superiore di SKILL.md.

Skill descriptions are cut short

Claude Code carica un elenco di nomi e descrizioni delle skill nel contesto in modo che Claude sappia cosa è disponibile. L'elenco contiene sempre ogni nome di skill, ma se avete molte skills, Claude Code accorcia le descrizioni per adattarsi al budget di caratteri dell'elenco, il che può rimuovere le parole chiave di cui Claude ha bisogno per corrispondere alla vostra richiesta. Il budget si scala all'1% della finestra di contesto del modello. Quando l'elenco supera il limite, Claude Code elimina le descrizioni a partire dalle skills che invocate meno, quindi le skills che utilizzate di più mantengono il loro testo completo.

Eseguite /doctor per una stima del costo di contesto dell'elenco e dei suoi maggiori contributori. Per trovare le skills che vale la pena disattivare, eseguite /skill-doctor. Quando l'elenco supera il suo budget, Claude Code scrive anche un avviso nel log di debug, visibile con --debug.

La riga Skills in /context riporta la dimensione dell'elenco dopo l'applicazione del budget, quindi corrisponde a ciò che il modello riceve. Prima della v2.1.196, la riga contava il testo completo di ogni descrizione e poteva mostrare un valore diverse volte più grande del budget configurato.

Per aumentare il budget, impostate l'impostazione skillListingBudgetFraction (ad esempio 0.02 = 2%) o la variabile di ambiente SLASH_COMMAND_TOOL_CHAR_BUDGET a un conteggio di caratteri fisso. Per liberare budget per altre skills, impostate le voci a bassa priorità su "name-only" in skillOverrides in modo che si elenchino senza una descrizione. Potete anche ridurre il testo di description e when_to_use alla fonte: mettete il caso d'uso chiave per primo, poiché il testo combinato di ogni voce è limitato a 1.536 caratteri indipendentemente dal budget. Il limite è configurabile con skillListingMaxDescChars.

Le parentesi angolari in una descrizione della skill appaiono come < e >

Claude Code mostra < e > nei campi description e when_to_use come < e >. Per mostrare un segnaposto come <branch>, usa le parentesi quadre o argument-hint:

• Parentesi quadre: sostituisci <branch> con [branch], che viene mostrato così come lo digiti
• argument-hint: sposta il segnaposto in una nuova riga argument-hint: <branch>. Viene mostrato dopo il nome del comando. Se carichi la skill anche su claude.ai o sulla Skills API, verifica prima se argument-hint è accettato lì.

Personal skills disappeared

Se le cartelle delle skill che avete creato in ~/.claude/skills/ sono scomparse, cercate in ~/.claude/skills/.trash/. Quando Claude Code sincronizza le skills da claude.ai, le scarica nella sottocartella separata synced e non sposta o elimina le cartelle che create.

Prima della v2.1.280, un file denominato manifest.json in ~/.claude/skills/ causava a Claude Code di spostare le cartelle delle skill elencate in quel file in una cartella con timestamp sotto ~/.claude/skills/.trash/, e quelle skills smettevano di caricarsi.

Per ripristinare una skill, spostate la sua cartella dalla cartella con timestamp di nuovo in ~/.claude/skills/. Fatelo prima che la pulizia della conservazione elimini le voci del cestino, per impostazione predefinita 30 giorni dopo che sono state spostate nel cestino.

Risorse correlate

• Debug della tua configurazione: diagnostica il motivo per cui una skill non appare o non si attiva
• Valutazione della qualità dell'output della skill: il formato del file eval e il flusso di lavoro di iterazione su agentskills.io
• Best practice di authoring delle skills: guida di scrittura che si applica ai prodotti Claude
• Subagents: delega attività ad agenti specializzati
• Plugins: pacchetto e distribuisci skills con altre estensioni
• Hooks: automatizza i flussi di lavoro intorno agli eventi degli strumenti
• Memory: gestisci i file CLAUDE.md per il contesto persistente
• Commands: riferimento per i comandi integrati e le skills raggruppate
• Permissions: controlla l'accesso agli strumenti e alle skills
• Claude Tag skills: le skills del progetto sottoposte a commit in un repository si caricano anche quando quel repository viene utilizzato in un canale Claude Tag