Vai al contenuto principale
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.
Per i comandi integrati come /help e /compact, consulta il riferimento dei comandi integrati.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 sei tu o Claude a invocarle, 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 in subagent, e l’iniezione di contesto dinamico.

​
Skills raggruppate

Le skills raggruppate vengono fornite con Claude Code e sono disponibili in ogni sessione. A differenza dei comandi integrati, che eseguono logica fissa direttamente, le skills raggruppate sono basate su prompt: danno a Claude un playbook dettagliato e gli permettono di orchestrare il lavoro utilizzando i suoi strumenti. Questo significa che le skills raggruppate possono generare agenti paralleli, leggere file e adattarsi al tuo codebase. Invochi le skills raggruppate allo stesso modo di qualsiasi altra skill: digita / seguito dal nome della skill. Nella tabella sottostante, <arg> indica un argomento obbligatorio e [arg] indica uno opzionale.
SkillScopo
/batch <instruction>Orchestra cambiamenti su larga scala in un codebase in parallelo. Ricerca il codebase, decompone il lavoro in 5-30 unità indipendenti e presenta un piano. Una volta approvato, genera un agente di background per unità in un git worktree isolato. Ogni agente implementa la sua unità, esegue i test e apre una pull request. Richiede un repository git. Esempio: /batch migrate src/ from Solid to React
/claude-apiCarica il materiale di riferimento dell’API Claude per il linguaggio del tuo progetto (Python, TypeScript, Java, Go, Ruby, C#, PHP, o cURL) e il riferimento dell’Agent SDK per Python e TypeScript. Copre l’uso degli strumenti, lo streaming, i batch, gli output strutturati e le insidie comuni. Si attiva anche automaticamente quando il tuo codice importa anthropic, @anthropic-ai/sdk, o claude_agent_sdk
/debug [description]Abilita la registrazione del debug per la sessione attuale e risolvi i problemi leggendo il log di debug della sessione. La registrazione del debug è disattivata per impostazione predefinita a meno che non hai avviato con claude --debug, quindi eseguire /debug a metà sessione inizia a catturare i log da quel momento in poi. Opzionalmente descrivi il problema per focalizzare l’analisi
/loop [interval] <prompt>Esegui un prompt ripetutamente a intervalli mentre la sessione rimane aperta. Utile per il polling di un deployment, la supervisione di una PR, o l’esecuzione periodica di un’altra skill. Esempio: /loop 5m check if the deploy finished. Vedi Esegui prompt su una pianificazione
/simplify [focus]Rivedi i tuoi file modificati di recente per problemi di riutilizzo del codice, qualità ed efficienza, quindi correggili. Genera tre agenti di revisione in parallelo, aggrega i loro risultati e applica le correzioni. Passa il testo per focalizzare su preoccupazioni specifiche: /simplify focus on memory efficiency

​
Iniziare

​
Crea la tua prima skill

Questo esempio crea una skill che insegna a Claude di spiegare il codice usando diagrammi visivi e analogie. Poiché utilizza frontmatter predefinito, Claude può caricarla automaticamente quando chiedi come funziona qualcosa, oppure puoi invocarla direttamente con /explain-code.
1

Crea la directory della skill

Crea una directory per la skill nella tua cartella di skills personali. Le skills personali sono disponibili su tutti i tuoi progetti.
mkdir -p ~/.claude/skills/explain-code
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 istruzioni che Claude segue quando la skill viene invocata. Il campo name diventa il /slash-command, e la description aiuta Claude a decidere quando caricarla automaticamente.Crea ~/.claude/skills/explain-code/SKILL.md:
---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

Keep explanations conversational. For complex concepts, use multiple analogies.
3

Testa la skill

Puoi testarla in due modi:Lascia che Claude la invochi automaticamente chiedendo qualcosa che corrisponda alla descrizione:
How does this code work?
O invocarla direttamente con il nome della skill:
/explain-code src/auth/login.ts
In entrambi i casi, Claude dovrebbe includere un’analogia e un diagramma ASCII nella sua spiegazione.

​
Dove vivono le skills

Dove archivi una skill determina chi può usarla:
PosizionePercorsoSi applica a
EnterpriseVedi impostazioni gestiteTutti gli utenti della tua organizzazione
Personale~/.claude/skills/<skill-name>/SKILL.mdTutti i tuoi progetti
Progetto.claude/skills/<skill-name>/SKILL.mdSolo questo progetto
Plugin<plugin>/skills/<skill-name>/SKILL.mdDove il plugin è abilitato
Quando le skills condividono lo stesso nome tra i livelli, le posizioni con priorità più alta vincono: enterprise > personale > progetto. 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.

​
Scoperta automatica da directory annidate

Quando lavori con file in sottodirectory, Claude Code scopre automaticamente le skills da directory .claude/skills/ annidate. 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.
I file in .claude/commands/ continuano a funzionare e supportano lo stesso frontmatter. Le skills sono consigliate poiché supportano funzionalità aggiuntive come i file di supporto.

​
Skills da directory aggiuntive

Le skills definite in .claude/skills/ all’interno di directory aggiunte tramite --add-dir vengono caricate automaticamente e rilevate dal rilevamento dei cambiamenti in tempo reale, quindi puoi modificarle durante una sessione senza riavviare.
I file CLAUDE.md da directory --add-dir non vengono caricati per impostazione predefinita. Per caricarli, imposta CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1. Vedi Carica da directory aggiuntive.

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

​
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.
CampoObbligatorioDescrizione
nameNoNome visualizzato per la skill. Se omesso, utilizza il nome della directory. Solo lettere minuscole, numeri e trattini (max 64 caratteri).
descriptionConsigliatoCosa fa la skill e quando usarla. Claude utilizza questo per decidere quando applicare la skill. Se omesso, utilizza il primo paragrafo del contenuto markdown.
argument-hintNoSuggerimento mostrato durante l’autocompletamento per indicare gli argomenti previsti. Esempio: [issue-number] o [filename] [format].
disable-model-invocationNoImposta su true per impedire a Claude di caricare automaticamente questa skill. Usa per i flussi di lavoro che vuoi attivare manualmente con /name. Predefinito: false.
user-invocableNoImposta su false per nascondere dal menu /. Usa per la conoscenza di background che gli utenti non dovrebbero invocare direttamente. Predefinito: true.
allowed-toolsNoStrumenti che Claude può usare senza chiedere il permesso quando questa skill è attiva.
modelNoModello da usare quando questa skill è attiva.
effortNoLivello di sforzo quando questa skill è attiva. Sostituisce il livello di sforzo della sessione. Predefinito: eredita dalla sessione. Opzioni: low, medium, high, max (solo Opus 4.6).
contextNoImposta su fork per eseguire in un contesto subagent con fork.
agentNoQuale tipo di subagent usare quando context: fork è impostato.
hooksNoHooks limitati al ciclo di vita di questa skill. Vedi Hooks in skills e agents per il formato di configurazione.

​
Sostituzioni di stringhe disponibili

Le skills supportano la sostituzione di stringhe per valori dinamici nel contenuto della skill:
VariabileDescrizione
$ARGUMENTSTutti gli argomenti passati quando si invoca la skill. Se $ARGUMENTS non è presente nel contenuto, gli argomenti vengono aggiunti come ARGUMENTS: <value>.
$ARGUMENTS[N]Accedi a un argomento specifico per indice a base 0, come $ARGUMENTS[0] per il primo argomento.
$NAbbreviazione per $ARGUMENTS[N], come $0 per il primo argomento o $1 per il secondo.
${CLAUDE_SESSION_ID}L’ID della sessione attuale. Utile per il logging, la creazione di file specifici della sessione, o la correlazione dell’output della skill con le sessioni.
${CLAUDE_SKILL_DIR}La directory contenente il file SKILL.md della skill. Per le skills dei plugin, questa è la sottodirectory della skill all’interno del plugin, non la radice del plugin. Usa questo nei comandi di iniezione bash per fare riferimento a script o file raggruppati con la skill, indipendentemente dalla directory di lavoro attuale.
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](reference.md)
- For usage examples, see [examples.md](examples.md)
Mantieni SKILL.md sotto 500 righe. Sposta il materiale di riferimento dettagliato in file separati.

​
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:
FrontmatterPuoi invocareClaude può invocareQuando caricato nel contesto
(predefinito)SìSìLa descrizione è sempre nel contesto, la skill completa si carica quando invocata
disable-model-invocation: trueSìNoLa descrizione non è nel contesto, la skill completa si carica quando la invochi
user-invocable: falseNoSìLa descrizione è sempre nel contesto, la skill completa si carica quando invocata
In una sessione regolare, le descrizioni delle skills vengono caricate nel contesto in modo che Claude sappia cosa è disponibile, ma il contenuto completo della skill si carica solo quando invocato. I subagents con skills precaricate funzionano diversamente: il contenuto completo della skill viene iniettato all’avvio.

​
Limita l’accesso agli strumenti

Usa il campo allowed-tools per limitare quali strumenti Claude può usare quando una skill è attiva. Questa skill crea una modalità di sola lettura dove Claude può esplorare i file ma non modificarli: 
---
name: safe-reader
description: Read files without making changes
allowed-tools: Read, Grep, Glob
---

​
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.
Per abilitare il pensiero esteso in una skill, includi la parola “ultrathink” da qualche parte nel contenuto della tua skill.

​
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.
context: fork ha senso solo per skills con istruzioni esplicite. Se la tua skill contiene linee guida come “usa queste convenzioni API” senza un’attività, il subagent riceve le linee guida ma nessun prompt azionabile, e ritorna senza output significativo.
Le skills e i subagents funzionano insieme in due direzioni:
ApproccioSystem promptAttivitàCarica anche
Skill con context: forkDal tipo di agent (Explore, Plan, ecc.)Contenuto di SKILL.mdCLAUDE.md
Subagent con campo skillsCorpo markdown del subagentMessaggio di delega di ClaudeSkills precaricate + CLAUDE.md
Con context: fork, scrivi l’attività nella tua skill e scegli un tipo di agent per eseguirla. Per l’inverso (definire 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. I comandi integrati come /compact e /init non sono disponibili tramite lo strumento Skill. 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.
Il campo user-invocable controlla solo la visibilità del menu, non l’accesso allo strumento Skill. Usa disable-model-invocation: true per bloccare l’invocazione programmatica.

​
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
Crea ~/.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: 
---
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(python *)
---

# 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
python ~/.claude/skills/codebase-visualizer/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
Crea ~/.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 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 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>📁 {data["name"]}</h1>
      <ul class="tree" id="root"></ul>
    </div>
  </div>
  <script>
    const data = {json.dumps(data)};
    const colors = {json.dumps(colors)};
    function fmt(b) {{ if (b < 1024) return b + ' B'; if (b < 1048576) return (b/1024).toFixed(1) + ' KB'; return (b/1048576).toFixed(1) + ' MB'; }}
    function render(node, parent) {{
      if (node.children) {{
        const det = document.createElement('details');
        det.open = parent === document.getElementById('root');
        det.innerHTML = `<summary><span class="folder">📁 ${{node.name}}</span><span class="size">${{fmt(node.size)}}</span></summary>`;
        const ul = document.createElement('ul'); ul.className = 'tree';
        node.children.sort((a,b) => (b.children?1:0)-(a.children?1:0) || a.name.localeCompare(b.name));
        node.children.forEach(c => render(c, ul));
        det.appendChild(ul);
        const li = document.createElement('li'); li.appendChild(det); parent.appendChild(li);
      }} else {{
        const li = document.createElement('li'); li.className = 'file';
        li.innerHTML = `<span class="dot" style="background:${{colors[node.ext]||'#6b7280'}}"></span>${{node.name}}<span class="size">${{fmt(node.size)}}</span>`;
        parent.appendChild(li);
      }}
    }}
    data.children.forEach(c => render(c, document.getElementById('root')));
  </script>
</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

​
Claude non vede tutte le mie skills

Le descrizioni delle skills vengono caricate nel contesto in modo che Claude sappia cosa è disponibile. Se hai molte skills, potrebbero superare il budget dei caratteri. Il budget si ridimensiona dinamicamente al 2% della finestra di contesto, con un fallback di 16.000 caratteri. Esegui /context per verificare un avviso sulle skills escluse. Per sovrascrivere il limite, imposta la variabile di ambiente SLASH_COMMAND_TOOL_CHAR_BUDGET.

​
Risorse correlate

  • 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
  • Built-in commands: riferimento per i comandi / integrati
  • Permissions: controlla l’accesso agli strumenti e alle skills