Vai al contenuto principale
I plugin ti permettono di estendere Claude Code con funzionalità personalizzate che possono essere condivise tra i progetti. Attraverso l’Agent SDK, puoi caricare programmaticamente i plugin da directory locali per aggiungere skills, agenti, hooks e server MCP alle tue sessioni di agente.

Cosa sono i plugin?

I plugin sono pacchetti di estensioni di Claude Code che possono includere:
  • Skills: Capacità richiamate dal modello che Claude utilizza autonomamente (possono anche essere richiamate con /skill-name)
  • Agents: Subagenti specializzati per compiti specifici
  • Hooks: Gestori di eventi che rispondono all’uso degli strumenti e ad altri eventi
  • MCP servers: Integrazioni di strumenti esterni tramite Model Context Protocol
La directory commands/ è un formato legacy. Usa skills/ per i nuovi plugin. Claude Code continua a supportare entrambi i formati per la compatibilità con le versioni precedenti.
Per informazioni complete sulla struttura dei plugin e su come creare plugin, vedi Plugins.

Caricamento dei plugin

Carica i plugin fornendo i loro percorsi del file system locale nella configurazione delle opzioni. Il campo type deve essere "local", l’unico valore che l’SDK accetta. Per utilizzare un plugin distribuito tramite un marketplace o un repository remoto, scaricalo prima e fornisci il percorso della directory locale. L’SDK supporta il caricamento di più plugin da posizioni diverse.

Specifiche dei percorsi

I percorsi dei plugin possono essere:
  • Percorsi relativi: Risolti rispetto alla tua directory di lavoro corrente (ad esempio, "./plugins/my-plugin")
  • Percorsi assoluti: Percorsi completi del file system (ad esempio, "/home/user/plugins/my-plugin")
Il percorso deve puntare alla directory radice del plugin: la directory padre di skills/, agents/, hooks/, commands/ (legacy), o .claude-plugin/, non una sottodirectory.

Verifica dell’installazione del plugin

Quando i plugin si caricano correttamente, appaiono nel messaggio di inizializzazione del sistema. Puoi verificare che i tuoi plugin siano disponibili:

Utilizzo delle skills dei plugin

Le skills dai plugin vengono automaticamente associate allo spazio dei nomi del plugin per evitare conflitti. Per richiamare una direttamente, invia /plugin-name:skill-name come prompt.
Se hai installato un plugin tramite la CLI (ad esempio, /plugin install my-plugin@marketplace), puoi comunque utilizzarlo nell’SDK fornendo il suo percorso di installazione. Controlla ~/.claude/plugins/ per i plugin installati tramite CLI.

Esempio completo

Ecco un esempio completo che dimostra il caricamento e l’utilizzo dei plugin:

Riferimento della struttura del plugin

Una directory di plugin contiene tipicamente un file manifest .claude-plugin/plugin.json. Il manifest è facoltativo. Quando omesso, Claude Code scopre automaticamente i componenti dal layout della directory. La directory può includere:
Per informazioni dettagliate sulla creazione di plugin, vedi:

Casi d’uso comuni

Sviluppo e test

Carica i plugin durante lo sviluppo senza installarli globalmente:

Estensioni specifiche del progetto

Includi i plugin nel tuo repository di progetto per la coerenza a livello di team:

Più fonti di plugin

Combina i plugin da posizioni diverse:

Troubleshooting

Plugin non caricato

Se il tuo plugin non appare nel messaggio di init:
  1. Controlla il percorso: assicurati che il percorso punti alla directory radice del plugin, la directory padre di skills/, agents/, hooks/, commands/ (legacy), o .claude-plugin/
  2. Valida plugin.json: se il tuo plugin include un manifest, assicurati che abbia una sintassi JSON valida
  3. Controlla i permessi dei file: assicurati che la directory del plugin sia leggibile

Skills non appaiono

Se le skills dei plugin non funzionano:
  1. Usa lo spazio dei nomi: richiama le skills dei plugin come /plugin-name:skill-name
  2. Controlla il messaggio di init: verifica che la skill appaia nell’elenco skills con lo spazio dei nomi corretto
  3. Valida i file delle skills: assicurati che ogni skill abbia un file SKILL.md nella sua sottodirectory sotto skills/, ad esempio skills/my-skill/SKILL.md

Problemi di risoluzione dei percorsi

Se i percorsi relativi non funzionano:
  1. Controlla la directory di lavoro: i percorsi relativi vengono risolti dalla tua directory di lavoro corrente
  2. Usa percorsi assoluti: per l’affidabilità, considera l’utilizzo di percorsi assoluti
  3. Normalizza i percorsi: usa le utility dei percorsi per costruire i percorsi correttamente

Vedi anche