Estendi Claude con skills

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

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

Crea una skill quando continui a incollare le stesse istruzioni, checklist, o procedura multi-step nella chat, oppure quando una sezione di CLAUDE.md è cresciuta in una procedura piuttosto che in 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 finché non ne hai bisogno.

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 in subagent, e l'iniezione di contesto dinamico.

Skills raggruppate

Claude Code include un set di skills raggruppate che sono disponibili in ogni sessione a meno che non siano disabilitate con l'impostazione disableBundledSkills, incluse /code-review, /batch, /debug, /loop, e /claude-api. A differenza della maggior parte dei comandi integrati, che eseguono logica fissa direttamente, le skills raggruppate sono basate su prompt: danno a Claude istruzioni dettagliate e gli permettono di orchestrare il lavoro utilizzando i suoi strumenti. Le invochi allo stesso modo di qualsiasi altra skill, digitando / seguito dal nome della skill.

Le skills raggruppate sono elencate insieme ai comandi integrati nel riferimento dei comandi, contrassegnate come Skill nella colonna Scopo.

Esegui e verifica la tua app

Tre skills raggruppate lavorano insieme per avviare la tua app e confermare le modifiche rispetto all'app in esecuzione invece di limitarsi ai test:

{/* min-version: 2.1.145 */}Tutte e tre le skills richiedono Claude Code v2.1.145 o successivo.

/run e /verify funzionano senza configurazione. Deducono l'avvio dal tipo di progetto (CLI, server, TUI, guidato dal browser) e da ciò che si trova nel tuo README, package.json, o Makefile. Questa deduzione diventa inaffidabile per i progetti che richiedono qualcosa di più di un avvio standard: un database, un file env, una sessione grafica, una compilazione multi-step.

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

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.

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

---
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.

What did I change?

/summarize-changes

Dove vivono le skills

Dove archivi una skill determina chi può usarla:

Quando le skills condividono lo stesso nome tra i livelli, enterprise ha la priorità su personale, e personale ha la priorità su progetto. Una skill a uno qualsiasi di questi livelli sostituisce anche una skill raggruppata con lo stesso nome. Ad esempio, una skill code-review nella .claude/skills/ del tuo progetto sostituisce la /code-review raggruppata. Le skills dei plugin utilizzano uno spazio dei nomi plugin-name:skill-name, quindi non possono entrare in conflitto con altri livelli. Se hai file in .claude/commands/, funzionano allo stesso modo, ma se una skill e un comando condividono lo stesso nome, la skill ha la precedenza.

Le skills vengono caricate anche da directory .claude/skills/ annidate al di sotto della tua directory di lavoro. Quando Claude legge o modifica un file in una sottodirectory, le skills dalla .claude/skills/ di quella sottodirectory diventano disponibili. Questo consente a un pacchetto monorepo di fornire le proprie skills che si applicano quando si lavora su quel pacchetto, anche se la sessione è iniziata alla radice del repository.

Se una skill annidata condivide un nome con un'altra skill, entrambe rimangono disponibili. Ad esempio, con una skill deploy alla radice del progetto e un'altra in apps/web/.claude/skills/:

• Quella annidata appare con un nome qualificato dalla directory, apps/web:deploy.
• La sua descrizione dice quale directory si applica.
• Claude sceglie la variante che corrisponde ai file su cui sta lavorando.

Digitando /deploy esegui la skill della radice del progetto. Digita il nome qualificato /apps/web:deploy per eseguire esplicitamente la variante annidata.

Rilevamento dei cambiamenti in tempo reale

Claude Code osserva le directory delle skills per i cambiamenti dei file. Aggiungere, modificare o rimuovere una skill in ~/.claude/skills/, nel progetto .claude/skills/, o in una .claude/skills/ all'interno di una directory --add-dir ha effetto nella sessione attuale senza riavviare. Creare una directory di skills di primo livello che non esisteva quando la sessione è iniziata richiede il riavvio di Claude Code in modo che la nuova directory possa essere osservata.

Scoperta automatica da directory padre e annidate

Le skills del progetto vengono caricate da .claude/skills/ nella tua directory di avvio e in ogni directory padre fino alla radice del repository, quindi avviare Claude in una sottodirectory raccoglie comunque le skills definite alla radice. Quando lavori con file in sottodirectory al di sotto della tua directory di avvio, Claude Code scopre anche le skills da directory .claude/skills/ annidate su richiesta. Ad esempio, se stai modificando un file in packages/frontend/, Claude Code cerca anche le skills in packages/frontend/.claude/skills/. Questo supporta configurazioni monorepo dove i pacchetti hanno le loro proprie skills.

Ogni skill è una directory con SKILL.md come punto di ingresso:

my-skill/
├── SKILL.md           # Istruzioni principali (obbligatorio)
├── template.md        # Template per Claude da compilare
├── examples/
│   └── sample.md      # Output di esempio che mostra il formato previsto
└── scripts/
    └── validate.sh    # Script che Claude può eseguire

SKILL.md contiene le istruzioni principali ed è obbligatorio. Gli altri file sono opzionali e ti permettono di costruire skills più potenti: template per Claude da compilare, output di esempio che mostrano il formato previsto, script che Claude può eseguire, o documentazione di riferimento dettagliata. Fai riferimento a questi file da SKILL.md in modo che Claude sappia cosa contengono e quando caricarli. Vedi Aggiungi file di supporto per più dettagli.

Skills da directory aggiuntive

Il flag --add-dir e il comando /add-dir concedono l'accesso ai file piuttosto che la scoperta della configurazione, ma le skills sono un'eccezione: .claude/skills/ all'interno di una directory aggiunta viene caricato automaticamente. Questa eccezione si applica solo a --add-dir e /add-dir. L'impostazione permissions.additionalDirectories in settings.json concede solo l'accesso ai file e non carica le skills. Vedi Rilevamento dei cambiamenti in tempo reale per come gli edits vengono rilevati durante una sessione.

Altre configurazioni .claude/ come subagent, comandi e stili di output non vengono caricate da directory aggiuntive. Vedi la tabella delle eccezioni per l'elenco completo di ciò che viene e non viene caricato, e i modi consigliati per condividere la configurazione tra i progetti.

Configura le skills

Le skills vengono configurate tramite frontmatter YAML in cima a SKILL.md e il contenuto markdown che segue.

Tipi di contenuto della skill

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

Contenuto di riferimento aggiunge conoscenza che Claude applica al tuo lavoro attuale. Convenzioni, pattern, guide di stile, conoscenza del dominio. Questo contenuto viene eseguito inline in modo che Claude possa 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

Contenuto di attività dà a Claude istruzioni passo-passo per un'azione specifica, come deployment, commit o generazione di codice. Spesso sono azioni che vuoi invocare direttamente con /skill-name piuttosto che lasciare che Claude decida quando eseguirle. Aggiungi disable-model-invocation: true per impedire a Claude di attivarla automaticamente.

---
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

Il tuo SKILL.md può contenere qualsiasi cosa, ma pensare a come vuoi che la skill venga invocata (da te, da Claude, o da entrambi) e dove vuoi che venga eseguita (inline o in un subagent) aiuta a guidare cosa includere. Per skills complesse, puoi anche aggiungere file di supporto per mantenere la skill principale focalizzata.

Mantieni il corpo stesso conciso. Una volta che una skill si carica, il suo contenuto rimane nel contesto tra i turni, quindi ogni riga è un costo di token ricorrente. Dichiara cosa fare piuttosto che narrare come o perché, e applica lo stesso test di concisione che faresti per il contenuto di CLAUDE.md.

Riferimento del frontmatter

Oltre al contenuto markdown, puoi configurare il comportamento della skill utilizzando campi frontmatter YAML tra i marcatori --- in cima al tuo file SKILL.md:

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

Your skill instructions here...

Tutti i campi sono opzionali. Solo description è consigliato in modo che Claude sappia quando usare la skill.

Come una skill ottiene il suo nome di comando

Il comando che digiti per invocare una skill proviene da dove risiede il file della skill. Il campo frontmatter name imposta l'etichetta di visualizzazione mostrata negli elenchi delle skills e, ad eccezione di un SKILL.md nella radice del plugin, non cambia quello che digiti dopo /.

La tabella seguente mostra da dove proviene il nome del comando per ogni layout:

Il caso della radice del plugin è l'unico posto dove name imposta il nome del comando, perché non c'è una directory della skill da cui prenderlo. Se name non è impostato nel frontmatter, il nome della directory del plugin viene utilizzato invece.

Sostituzioni di stringhe disponibili

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

Gli argomenti indicizzati utilizzano le virgolette in stile shell, quindi racchiudi i valori multi-parola tra virgolette per passarli come un singolo argomento. Ad esempio, /my-skill "hello world" second fa sì che $0 si espanda a hello world e $1 a second. Il placeholder $ARGUMENTS si espande sempre alla stringa di argomenti completa come digitata.

Per includere un $ letterale prima di una cifra, ARGUMENTS, o un nome di argomento dichiarato, come $1.00 in prosa, sfuggilo 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 lo sfugge. Una barra rovesciata doppia come \\$1 lascia entrambe le barre rovesciate in posizione, e $1 si espande comunque al valore dell'argomento.

Esempio usando sostituzioni:

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

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

$ARGUMENTS

Aggiungi file di supporto

Le skills possono includere più file nella loro directory. Questo mantiene SKILL.md focalizzato sull'essenziale mentre permette a Claude di accedere a materiale di riferimento dettagliato solo quando necessario. Grandi documenti di riferimento, specifiche API, o collezioni di esempi non hanno bisogno di caricarsi nel contesto ogni volta che la skill viene eseguita.

my-skill/
├── SKILL.md (obbligatorio - panoramica e navigazione)
├── reference.md (documentazione API dettagliata - caricata quando necessario)
├── examples.md (esempi di utilizzo - caricati quando necessario)
└── scripts/
    └── helper.py (script di utilità - eseguito, non caricato)

Fai riferimento ai file di supporto da SKILL.md in modo che Claude sappia cosa contiene ogni file e quando caricarlo:

## Additional resources

- For complete API details, see [reference.md](/anthropic/claude-code/history/docs/it/2026-06-16-2157..2026-06-17-1702/reference/)
- For usage examples, see [examples.md](/anthropic/claude-code/history/docs/it/2026-06-16-2157..2026-06-17-1702/examples/)

Controlla chi invoca una skill

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

• disable-model-invocation: true: Solo tu puoi invocare la skill. Usa questo per i flussi di lavoro con effetti collaterali o che vuoi controllare il timing, come /commit, /deploy, o /send-slack-message. Non vuoi che Claude decida di fare il deploy perché il tuo codice sembra pronto.

• user-invocable: false: Solo Claude può invocare la skill. Usa questo per la conoscenza di background che non è azionabile come comando. Una skill legacy-system-context spiega come funziona un vecchio sistema. Claude dovrebbe saperlo quando rilevante, ma /legacy-system-context non è un'azione significativa per gli utenti da intraprendere.

Questo esempio crea una skill di deploy che solo tu puoi attivare. Il campo disable-model-invocation: true impedisce a Claude di eseguirla 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

Ecco come i due campi influenzano l'invocazione e il caricamento del contesto:

Ciclo di vita del contenuto della skill

Quando tu o Claude invocate una skill, il contenuto SKILL.md renderizzato entra nella conversazione come un singolo messaggio e rimane lì per il resto della sessione. Claude Code non rilegge il file della skill nei turni successivi, quindi scrivi la guida che dovrebbe applicarsi durante un'attività come istruzioni permanenti piuttosto che come passaggi una tantum.

Auto-compaction porta avanti le skills invocate all'interno di un budget di token. Quando la conversazione viene riassunta per liberare contesto, Claude Code riallega l'invocazione più recente di ogni skill dopo il riassunto, mantenendo i primi 5.000 token di ciascuna. Le skills riallegate condividono un budget combinato di 25.000 token. Claude Code riempie questo budget a partire dalla skill invocata più di recente, quindi le skills più vecchie possono essere completamente eliminate dopo la compaction se ne hai invocate molte in una sessione.

Se una skill sembra smettere di influenzare il comportamento dopo la prima risposta, il contenuto è solitamente ancora presente e il modello sta scegliendo altri strumenti o approcci. Rafforza la description della skill e le istruzioni in modo che il modello continui a preferirla, o usa hooks per applicare il comportamento in modo deterministico. Se la skill è grande o ne hai invocate molte altre dopo, reinvocala dopo la compaction per ripristinare il contenuto completo.

Pre-approva gli strumenti per una skill

Il campo allowed-tools concede il permesso per gli strumenti elencati mentre la skill è attiva, in modo che Claude possa usarli senza chiederti l'approvazione per ogni uso. Non limita quali strumenti sono disponibili: ogni strumento rimane richiamabile, e le tue impostazioni di permesso governano comunque gli strumenti che non sono elencati.

Per le skills controllate in una directory .claude/skills/ di un progetto, allowed-tools ha effetto dopo che accetti la finestra di dialogo di trust dell'area di lavoro per quella cartella, come le regole di permesso in .claude/settings.json. Rivedi le skills del progetto prima di fidarti di un repository, poiché una skill può concedere a se stessa un ampio accesso agli strumenti.

Questa skill permette a Claude di eseguire comandi git senza approvazione per uso 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 gli strumenti dal pool disponibile di Claude mentre una skill è attiva, elencali in disallowed-tools nel frontmatter della skill. La restrizione si cancella quando invii il tuo prossimo messaggio. Per bloccare gli strumenti in tutte le skills e i prompt, aggiungi regole di negazione nelle tue impostazioni di permesso.

Passa argomenti alle skills

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

Questa skill corregge un problema GitHub per numero. Il placeholder $ARGUMENTS viene sostituito con qualsiasi 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 la skill non include $ARGUMENTS, Claude Code aggiunge ARGUMENTS: <your input> alla fine del contenuto della skill in modo che Claude veda comunque quello che hai digitato.

Per accedere agli argomenti individuali per posizione, usa $ARGUMENTS[N] o il più breve $N:

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

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

Eseguendo /migrate-component SearchBar React Vue sostituisce $ARGUMENTS[0] con SearchBar, $ARGUMENTS[1] con React, e $ARGUMENTS[2] con Vue. La stessa skill usando la scorciatoia $N:

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

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

Pattern avanzati

Inietta contesto dinamico

La sintassi !`<command>` esegue comandi shell prima che il contenuto della skill venga inviato a Claude. L'output del comando sostituisce il placeholder, in modo che Claude riceva dati effettivi, non il comando stesso.

Questa skill riassume una pull request recuperando dati PR in tempo reale 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...

Quando questa skill viene eseguita:

1. Ogni !`<command>` viene eseguito immediatamente (prima che Claude veda qualsiasi cosa)
2. L'output sostituisce il placeholder nel contenuto della skill
3. Claude riceve il prompt completamente renderizzato con dati PR effettivi

Questo è preprocessing, non qualcosa che Claude esegue. Claude vede solo il risultato finale.

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, usa un blocco di codice aperto con ```! invece della forma inline:

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

Per disabilitare questo comportamento per skills e comandi personalizzati da fonti utente, progetto, plugin, o directory aggiuntiva, imposta "disableSkillShellExecution": true nelle impostazioni. Ogni comando viene sostituito con [shell command execution disabled by policy] invece di essere eseguito. Le skills raggruppate e gestite non sono interessate. Questa impostazione è più utile nelle impostazioni gestite, dove gli utenti non possono sovrascriverla.

Esegui skills in un subagent

Aggiungi context: fork al tuo frontmatter quando vuoi che una skill venga eseguita in isolamento. Il contenuto della skill diventa il prompt che guida il subagent. Non avrà accesso alla tua cronologia di conversazione.

Le skills e i subagents funzionano insieme in due direzioni:

Con context: fork, scrivi l'attività nella tua skill e scegli un tipo di agent per eseguirla. Gli agent integrati Explore e Plan saltano CLAUDE.md e git status per mantenere il loro contesto piccolo, quindi una skill con fork che utilizza agent: Explore vede solo il contenuto di SKILL.md e il system prompt dell'agent stesso. Per l'inverso, dove definisci un subagent personalizzato che usa le skills come materiale di riferimento, vedi Subagents.

Esempio: Skill di ricerca usando l'agent Explore

Questa skill esegue la ricerca in un agent Explore con fork. Il contenuto della skill diventa l'attività, e l'agent fornisce strumenti di sola lettura ottimizzati per l'esplorazione del 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 ("Research $ARGUMENTS thoroughly...")
3. Il campo agent determina l'ambiente di esecuzione (modello, strumenti e permessi)
4. I risultati vengono riassunti e restituiti alla tua conversazione principale

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

Limita l'accesso alle skills di Claude

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

Tre modi per controllare quali skills Claude può invocare:

Disabilita tutte le skills negando lo strumento Skill in /permissions:

# Add to deny rules:
Skill

Consenti o nega skills 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.

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

Sovrascrivi la visibilità della skill dalle impostazioni

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

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

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

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

Le skills dei plugin non sono interessate da skillOverrides. Gestisci quelle tramite /plugin invece.

Condividi skills

Le skills possono essere distribuite a diversi ambiti a seconda del tuo pubblico:

• Skills di progetto: Esegui il commit di .claude/skills/ al controllo di versione
• Plugin: Crea una directory skills/ nel tuo plugin
• Gestito: Distribuisci a livello di organizzazione tramite impostazioni gestite

Genera output visuale

Le skills possono raggruppare ed eseguire script in qualsiasi linguaggio, dando a Claude capacità oltre ciò che è possibile in un singolo prompt. Un pattern potente è generare output visuale: file HTML interattivi che si aprono nel tuo browser per esplorare dati, eseguire il debug, o creare report.

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

Crea la directory della Skill:

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

Salva questo in ~/.claude/skills/codebase-visualizer/SKILL.md. La descrizione dice a Claude quando attivare questa 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 la skill sia installata 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

Salva 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 il codebase per tipo di file (i primi 8 per dimensione)
• Un albero comprimibile dove puoi 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, apri Claude Code in qualsiasi progetto e chiedi "Visualizza questo codebase." Claude esegue lo script, genera codebase-map.html, e lo apre nel tuo browser.

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

Risoluzione dei problemi

Skill non si attiva

Se Claude non usa la tua skill quando previsto:

1. Controlla che la descrizione includa parole chiave che gli utenti direbbero naturalmente
2. Verifica che la skill appaia in What skills are available?
3. Prova a riformulare la tua richiesta per corrispondere più strettamente alla descrizione
4. Invocarla direttamente con /skill-name se la skill è invocabile dall'utente

Skill si attiva troppo spesso

Se Claude usa la tua skill quando non vuoi:

1. Rendi la descrizione più specifica
2. Aggiungi disable-model-invocation: true se vuoi solo l'invocazione manuale

Le descrizioni delle skills vengono tagliate

Le descrizioni delle skills vengono caricate nel contesto in modo che Claude sappia cosa è disponibile. Tutti i nomi delle skills sono sempre inclusi, ma se hai molte skills, le descrizioni vengono accorciate per adattarsi al budget dei caratteri, il che può rimuovere le parole chiave di cui Claude ha bisogno per corrispondere alla tua richiesta. Il budget si ridimensiona all'1% della finestra di contesto del modello. Quando supera il limite, le descrizioni per le skills che invochi meno frequentemente vengono eliminate per prime, in modo che le skills che effettivamente usi mantengano il loro testo completo. Esegui /doctor per vedere quante descrizioni di skills vengono accorciate o eliminate e quali skills sono interessate.

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

Risorse correlate

• Debug della tua configurazione: diagnostica il motivo per cui una skill non appare o non si attiva
• 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