SpyBara
Go Premium

plugins.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 47 additions and 77 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Wed 23 23:57 Fri 25 23:58

Creare plugin

Crea plugin personalizzati per estendere Claude Code con skills, agents, hooks e MCP servers.

I plugin ti permettono di estendere Claude Code con funzionalità personalizzate che possono essere condivise tra progetti e team. Questa guida copre la creazione dei tuoi plugin con skills, agents, hooks e MCP servers.

Stai cercando di installare plugin esistenti? Vedi Scopri e installa plugin. Per le specifiche tecniche complete, vedi Riferimento plugin.

Quando usare plugin rispetto alla configurazione standalone

Claude Code supporta due modi per aggiungere skills, agents e hooks personalizzati:

Approccio Nomi skill Migliore per
Standalone (directory .claude/) /hello Flussi di lavoro personali, personalizzazioni specifiche del progetto, esperimenti rapidi
Plugin (directory con skills, agents, hooks o un manifest .claude-plugin/plugin.json) /plugin-name:hello Condivisione con i colleghi, distribuzione alla comunità, rilasci versionati, riutilizzabili tra progetti

Quickstart

Questo quickstart ti guida attraverso la creazione di un plugin con uno skill personalizzato. Creerai un manifest (il file di configurazione che definisce il tuo plugin), aggiungerai uno skill e lo testerai localmente usando il flag --plugin-dir.

Prerequisiti

Crea il tuo primo plugin

1

Crea la directory del plugin

Ogni plugin vive nella sua directory contenente i tuoi skill, agent o hook, facoltativamente insieme a un manifest .claude-plugin/plugin.json. La posizione non importa per questo quickstart perché punterai Claude Code alla directory con --plugin-dir nel passaggio di test. Crealo ovunque sia conveniente, ad esempio in una cartella scratch o in una directory di progetti:

mkdir my-first-plugin

I passaggi rimanenti vengono eseguiti dalla directory padre e fanno riferimento a percorsi come my-first-plugin/... relativi ad essa.

2

Crea il manifest del plugin

Il file manifest in .claude-plugin/plugin.json definisce l'identità del tuo plugin: il suo nome, descrizione e versione. Claude Code usa questi metadati per visualizzare il tuo plugin nel plugin manager.

Crea la directory .claude-plugin dentro la cartella del tuo plugin:

mkdir my-first-plugin/.claude-plugin

Poi crea my-first-plugin/.claude-plugin/plugin.json con questo contenuto:

{
"name": "my-first-plugin",
"description": "A greeting plugin to learn the basics",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}
Campo Scopo
name Identificatore univoco e namespace dello skill. Gli skill sono prefissati con questo (ad es., /my-first-plugin:hello).
description Mostrato nel plugin manager quando si sfogliano o si installano plugin.
version Opzionale. Se impostato, gli utenti ricevono aggiornamenti solo quando aumenti questo campo, eccetto per una command source; vedi gestione della versione. Se omesso, la versione proviene dalla prossima source in gestione della versione.
author Opzionale. Utile per l'attribuzione.

Per campi aggiuntivi come homepage, repository e license, vedi lo schema manifest completo.

3

Aggiungi uno skill

Gli skill vivono nella directory skills/. Ogni skill è una cartella contenente un file SKILL.md. Il nome della cartella diventa il nome dello skill, prefissato con il namespace del plugin (hello/ in un plugin denominato my-first-plugin crea /my-first-plugin:hello).

Crea una directory skill nella cartella del tuo plugin:

mkdir -p my-first-plugin/skills/hello

Poi crea my-first-plugin/skills/hello/SKILL.md con questo contenuto:

---
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.
4

Testa il tuo plugin

Esegui Claude Code con il flag --plugin-dir per caricare il tuo plugin:

claude --plugin-dir ./my-first-plugin

Una volta che Claude Code si avvia, prova il tuo nuovo skill:

/my-first-plugin:hello

Vedrai Claude rispondere con un saluto. Esegui /help e apri la scheda Custom commands per vedere il tuo skill elencato sotto il namespace del plugin.

5

Aggiungi argomenti dello skill

Rendi il tuo skill dinamico accettando input dell'utente. Il placeholder $ARGUMENTS cattura qualsiasi testo che l'utente fornisce dopo il nome dello skill.

Aggiorna il tuo file SKILL.md:

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

Esegui /reload-plugins per raccogliere i cambiamenti. Poi prova lo skill con il tuo nome:

/my-first-plugin:hello Alex

Claude ti saluterà per nome. Per ulteriori informazioni sul passaggio di argomenti agli skill, vedi Skills.

Sviluppa un plugin nella tua directory skills

Invece di passare --plugin-dir ad ogni avvio, puoi mantenere un plugin nella tua directory skills e fare in modo che Claude Code lo carichi automaticamente. claude plugin init ne crea uno:

claude plugin init my-tool

Questo crea ~/.claude/skills/my-tool/ con un manifest .claude-plugin/plugin.json e uno starter SKILL.md. Nella sessione successiva si carica come my-tool@skills-dir senza alcun passaggio di marketplace o installazione.

Per le regole di caricamento automatico, l'ambito personale rispetto a quello del progetto, il requisito di fiducia dell'area di lavoro e come aggiornare o rimuoverne uno, vedi Plugin della directory skills.

Panoramica della struttura del plugin

Hai creato un plugin con uno skill, ma i plugin possono includere molto di più: agents personalizzati, hooks, MCP servers, LSP servers e monitor in background.

Directory Posizione Scopo
.claude-plugin/ Radice del plugin Contiene il manifest plugin.json (opzionale se i componenti usano posizioni predefinite)
skills/ Radice del plugin Skills come directory <name>/SKILL.md
commands/ Radice del plugin Skills come file Markdown flat. Usa skills/ per i nuovi plugin
agents/ Radice del plugin Definizioni di agent personalizzati
hooks/ Radice del plugin Gestori di eventi in hooks.json
.mcp.json Radice del plugin Configurazioni del server MCP
.lsp.json Radice del plugin Configurazioni del server LSP per l'intelligenza del codice
monitors/ Radice del plugin Configurazioni del monitor in background in monitors.json
bin/ Radice del plugin Eseguibili aggiunti al PATH dello strumento Bash mentre il plugin è abilitato. Non puoi includere questa directory in un plugin che distribuisci tramite le impostazioni dell'organizzazione claude.ai
settings.json Radice del plugin Impostazioni predefinite applicate quando il plugin è abilitato

Un plugin che fornisce esattamente uno skill può posizionare SKILL.md direttamente alla radice del plugin invece di creare una directory skills/. Claude Code lo carica come uno skill singolo e utilizza il campo name del frontmatter per il nome di invocazione. Usa il layout skills/ per i plugin che potrebbero crescere fino a più di uno skill.

Sviluppa plugin più complessi

Una volta che hai familiarità con i plugin di base, puoi creare estensioni più sofisticate.

Aggiungi Skills al tuo plugin

I plugin possono includere Agent Skills per estendere le capacità di Claude. Gli skill sono invocati dal modello: Claude li usa automaticamente in base al contesto dell'attività.

Aggiungi una directory skills/ alla radice del tuo plugin con cartelle Skill contenenti file SKILL.md:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── code-review/
        └── SKILL.md

Ogni SKILL.md contiene frontmatter YAML e istruzioni. Includi una description in modo che Claude sappia quando usare lo skill:

---
description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
---

When reviewing code, check for:
1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage

Dopo aver installato il plugin, controlla il riepilogo dell'installazione: se segnala Run /reload-plugins to activate., esegui quel comando per caricare gli Skills. Per una guida completa sulla creazione di Skill inclusa la divulgazione progressiva e le restrizioni degli strumenti, vedi Agent Skills.

Aggiungi server LSP al tuo plugin

I plugin LSP (Language Server Protocol) danno a Claude l'intelligenza del codice in tempo reale. Se hai bisogno di supportare un linguaggio che non ha un plugin LSP ufficiale, puoi crearne uno tuo aggiungendo un file .lsp.json al tuo plugin:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

Gli utenti che installano il tuo plugin devono avere il binario del language server installato sulla loro macchina.

Per confermare che il server si avvia, avvia Claude Code con il plugin abilitato e controlla la scheda /plugin Errors: un language server che non riesce ad avviarsi appare lì, ad esempio con Executable not found in $PATH quando il binario non è installato. Una voce con una configurazione non valida viene saltata; esegui claude --debug per vedere il motivo.

Per le opzioni di configurazione LSP complete, vedi LSP servers.

Aggiungi monitor in background al tuo plugin

I monitor in background permettono al tuo plugin di osservare log, file o stato esterno in background e notificare Claude quando gli eventi arrivano. Claude Code avvia automaticamente ogni monitor quando il plugin è attivo, quindi non hai bisogno di istruire Claude ad avviare la sorveglianza.

Aggiungi un file monitors/monitors.json alla radice del plugin con un array di voci di monitor:

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

Ogni riga stdout da command viene consegnata a Claude come notifica durante la sessione. Per lo schema completo, incluso il trigger when e la sostituzione delle variabili, vedi Monitors.

Spedisci impostazioni predefinite con il tuo plugin

I plugin possono includere un file settings.json alla radice del plugin per applicare la configurazione predefinita quando il plugin è abilitato. Attualmente, sono supportate solo le chiavi agent e subagentStatusLine.

Impostare agent attiva uno dei custom agents del plugin come thread principale, applicando il suo system prompt, le restrizioni degli strumenti e il modello. Questo consente a un plugin di cambiare il comportamento predefinito di Claude Code quando abilitato.

{
  "agent": "security-reviewer"
}

Questo esempio attiva l'agent security-reviewer definito nella directory agents/ del plugin. Le impostazioni da settings.json hanno priorità rispetto alle settings dichiarate in plugin.json. Le chiavi sconosciute vengono silenziosamente ignorate.

Organizza plugin complessi

Per i plugin con molti componenti, organizza la tua struttura di directory per funzionalità. Per i layout di directory completi e i modelli di organizzazione, vedi Struttura della directory del plugin.

Testa i tuoi plugin localmente

Usa il flag --plugin-dir per testare i plugin durante lo sviluppo. Questo carica il tuo plugin direttamente senza richiedere l'installazione.

claude --plugin-dir ./my-plugin

Il flag accetta anche un archivio .zip della directory del plugin.

claude --plugin-dir ./my-plugin.zip

Quando un plugin --plugin-dir ha lo stesso nome di un plugin marketplace installato, la copia locale ha la precedenza per quella sessione. Questo ti consente di testare le modifiche a un plugin che hai già installato senza disinstallarlo prima. L'eccezione è rappresentata dai plugin le cui impostazioni gestite forzano l'abilitazione o la disabilitazione: --plugin-dir non può sovrascrivere quelli.

Man mano che apporti modifiche al tuo plugin, esegui /reload-plugins per raccogliere gli aggiornamenti senza riavviare. Questo ricarica plugin, skill, agent, hook, server MCP del plugin e server LSP del plugin; in una sessione senza un terminale interattivo, le modifiche al server MCP del plugin attendono la tua prossima sessione. Testa i componenti del tuo plugin:

  • Prova i tuoi skill con /plugin-name:skill-name
  • Verifica che gli agents appaiano in /context sotto Custom Agents, o @-menziona uno per il suo nome con scope
  • Attiva l'evento che ogni hook corrisponde, ad esempio chiedendo a Claude di modificare un file per un hook PostToolUse, e conferma il suo effetto. Claude Code registra quali hook corrispondono, i loro codici di uscita e il loro output nel debug log

Per testare un plugin che è già stato confezionato come archivio .zip e ospitato su un URL, come un artefatto di build CI, usa --plugin-url invece. Claude Code recupera l'archivio all'avvio e lo carica solo per quella sessione. Se Claude Code non riesce a recuperare l'archivio, o l'archivio non è valido, si avvia senza il plugin e registra un errore di caricamento del plugin che puoi rivedere nella scheda Errors del gestore /plugin. Le stesse considerazioni sulla fiducia si applicano come per qualsiasi fonte di plugin: punta questo flag solo ad archivi che controlli o di cui ti fidi.

Per caricare più plugin, ripeti il flag per ogni URL:

claude --plugin-url https://example.com/my-plugin.zip --plugin-url https://example.com/other.zip

Oppure passa URL separati da spazi come un singolo argomento tra virgolette:

claude --plugin-url "https://example.com/my-plugin.zip https://example.com/other.zip"

Esegui il debug dei problemi del plugin

Se il tuo plugin non funziona come previsto:

  1. Controlla la struttura: Assicurati che le tue directory siano alla radice del plugin, non dentro .claude-plugin/
  2. Testa i componenti individualmente: Controlla ogni skill, agent e hook separatamente
  3. Usa strumenti di validazione e debug: Vedi Strumenti di debug e sviluppo per i comandi CLI e le tecniche di troubleshooting

Condividi i tuoi plugin

Quando il tuo plugin è pronto per essere condiviso:

  1. Aggiungi documentazione: Includi un README.md con istruzioni di installazione e utilizzo
  2. Scegli una strategia di versionamento: Decidi se impostare una version esplicita o affidarti al fallback descritto in gestione della versione.
  3. Crea o usa un marketplace: Distribuisci tramite marketplace di plugin per l'installazione
  4. Testa con altri: Fai testare il plugin ai colleghi del team prima di una distribuzione più ampia

Una volta che il tuo plugin è in un marketplace, altri possono installarlo usando le istruzioni in Scopri e installa plugin. Per mantenere un plugin interno al tuo team, ospita il marketplace in un repository privato.

Invia il tuo plugin al marketplace della comunità

Anthropic mantiene due marketplace pubblici per i plugin di Claude Code:

  • claude-plugins-official: un insieme curato di plugin mantenuti da Anthropic. Claude Code lo registra automaticamente la prima volta che avvii Claude Code in modo interattivo. Se esegui Claude Code in modo non interattivo prima di quel primo avvio interattivo, o una politica del marketplace ha bloccato un tentativo precedente, registralo tu stesso con claude plugin marketplace add anthropics/claude-plugins-official.
  • claude-community: il marketplace pubblico della comunità dove gli invii di terze parti arrivano dopo la revisione. Gli utenti lo aggiungono con /plugin marketplace add anthropics/claude-plugins-community e lo installano come @claude-community.

Per inviare il tuo plugin per la revisione del marketplace della comunità, usa uno dei moduli in-app:

Il modulo claude.ai richiede un'organizzazione Team o Enterprise e accesso alla gestione della directory; i proprietari dell'organizzazione hanno questo accesso per impostazione predefinita. Gli autori individuali che non fanno parte di un'organizzazione Team o Enterprise possono utilizzare il modulo Console.

Esegui claude plugin validate ./your-plugin localmente prima di inviare, sostituendo ./your-plugin con il percorso della tua directory di plugin. La pipeline di revisione esegue lo stesso controllo su ogni invio, insieme a uno screening di sicurezza automatizzato. Quando la validazione passa, Claude Code stampa ✔ Validation passed, o ✔ Validation passed with warnings se ci sono avvisi. Gli avvisi non causano il fallimento della validazione; aggiungi --strict per trattarli come errori.

I plugin approvati sono fissati a uno specifico commit SHA nel catalogo anthropics/claude-plugins-community, e CI aumenta automaticamente il pin mentre esegui il push di nuovi commit nel tuo repository. Il catalogo pubblico si sincronizza ogni notte dalla pipeline di revisione, quindi può esserci un ritardo tra l'approvazione e la comparsa del tuo plugin in marketplace.json. Per verificare se il tuo plugin è già installabile, cerca il suo nome nel catalogo della comunità.

Il marketplace ufficiale, claude-plugins-official, è curato separatamente. Anthropic decide quali plugin includere a sua discrezione. Non c'è un processo di candidatura e il modulo di invio non aggiunge plugin al marketplace ufficiale.

Se Anthropic elenca il tuo plugin nel marketplace ufficiale, il tuo CLI può invitare gli utenti di Claude Code a installarlo. Vedi Consiglia il tuo plugin dal tuo CLI.

Converti configurazioni esistenti in plugin

Se hai già skill o hooks nella tua directory .claude/, puoi convertirli in un plugin per una condivisione e distribuzione più facile.

Passaggi di migrazione

1

Crea la struttura del plugin

Crea una nuova directory plugin nella radice del tuo progetto, accanto alla cartella .claude/ esistente, in modo che i percorsi relativi cp nel passaggio successivo si risolvano:

mkdir -p my-plugin/.claude-plugin

Crea il file manifest in my-plugin/.claude-plugin/plugin.json:

{
"name": "my-plugin",
"description": "Migrated from standalone configuration",
"version": "1.0.0"
}
2

Copia i tuoi file esistenti

Copia ogni directory di configurazione che hai nella radice del plugin. Potresti non avere tutti e tre: se una directory non esiste, cp stampa No such file or directory e non copia nulla, quindi salta quel comando o ignora l'errore.

cp -r .claude/commands my-plugin/

cp -r .claude/agents my-plugin/

cp -r .claude/skills my-plugin/

Il tuo plugin ora contiene copie delle directory che avevi sotto .claude/. Esegui ls my-plugin per confermare: dovresti vedere ogni directory che hai copiato.

3

Migra gli hook

Se hai hook nelle tue impostazioni, crea una directory hooks:

mkdir my-plugin/hooks

Crea my-plugin/hooks/hooks.json con la tua configurazione degli hook. Copia l'oggetto hooks dal tuo .claude/settings.json o settings.local.json, poiché il formato è lo stesso. Il comando riceve l'input dell'hook come JSON su stdin, quindi usa jq per estrarre il percorso del file:

{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]
}
]
}
}
4

Testa il tuo plugin migrato

Carica il tuo plugin per verificare che tutto funzioni:

claude --plugin-dir ./my-plugin

Testa ogni componente: esegui i tuoi comandi, verifica che gli agents appaiano in /context, e attiva l'evento che ogni hook corrisponde per confermare il suo effetto. Claude Code registra quali hook sono stati attivati e come sono usciti nel debug log.

Cosa cambia durante la migrazione

Standalone (.claude/) Plugin
Disponibile solo in un progetto Può essere condiviso tramite marketplace
File in .claude/commands/ File in plugin-name/commands/
Hook in settings.json Hook in hooks/hooks.json
Deve essere copiato manualmente per condividere Installa con /plugin install

Prossimi passi

Ora che comprendi il sistema di plugin di Claude Code, ecco i percorsi suggeriti per diversi obiettivi:

Per gli utenti di plugin

Per gli sviluppatori di plugin