Creare plugin - Claude Code Docs

I plugin ti permettono di estendere Claude Code con funzionalità personalizzate che possono essere condivise tra progetti e team. Questa guida copre la creazione di plugin personalizzati 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 `.claude-plugin/plugin.json`)	`/plugin-name:hello`	Condivisione con i colleghi, distribuzione alla comunità, rilasci versionati, riutilizzabili tra progetti

Usa la configurazione standalone quando:

Stai personalizzando Claude Code per un singolo progetto
La configurazione è personale e non ha bisogno di essere condivisa
Stai sperimentando con skills o hooks prima di pacchettizzarli
Vuoi nomi skill brevi come /hello o /review

Usa i plugin quando:

Vuoi condividere funzionalità con il tuo team o comunità
Hai bisogno degli stessi skills/agents in più progetti
Vuoi il controllo della versione e aggiornamenti facili per le tue estensioni
Stai distribuendo tramite un marketplace
Sei d’accordo con skills con namespace come /my-plugin:hello (il namespace previene conflitti tra plugin)

Inizia con la configurazione standalone in .claude/ per un’iterazione rapida, poi converti in un plugin quando sei pronto a condividere.

Avvio rapido

Questo avvio rapido 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

Claude Code installato e autenticato
Claude Code versione 1.0.33 o successiva (esegui claude --version per verificare)

Se non vedi il comando /plugin, aggiorna Claude Code all’ultima versione. Vedi Troubleshooting per le istruzioni di aggiornamento.

Crea il tuo primo plugin

Crea la directory del plugin

Ogni plugin vive nella sua directory contenente un manifest e i tuoi skills, agents o hooks. Creane uno ora:

mkdir my-first-plugin

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 gestore plugin.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:

my-first-plugin/.claude-plugin/plugin.json

{
"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 skill. Gli skill sono prefissati con questo (ad es., `/my-first-plugin:hello`).
`description`	Mostrato nel gestore plugin quando si sfogliano o si installano plugin.
`version`	Traccia i rilasci usando il versionamento semantico.
`author`	Opzionale. Utile per l’attribuzione.

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

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:

my-first-plugin/skills/hello/SKILL.md

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

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

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

/my-first-plugin:hello

Vedrai Claude rispondere con un saluto. Esegui /help per vedere il tuo comando elencato sotto il namespace del plugin.

Perché il namespace? Gli skill del plugin hanno sempre il namespace (come /greet:hello) per prevenire conflitti quando più plugin hanno skill con lo stesso nome.Per cambiare il prefisso del namespace, aggiorna il campo name in plugin.json.

Aggiungi argomenti 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 hello.md:

my-first-plugin/commands/hello.md

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

# Hello Command

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

Riavvia Claude Code per raccogliere i cambiamenti, poi prova il comando 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.

Hai creato e testato con successo un plugin con questi componenti chiave:

Plugin manifest (.claude-plugin/plugin.json): descrive i metadati del tuo plugin
Directory commands (commands/): contiene i tuoi skill personalizzati
Argomenti skill ($ARGUMENTS): cattura l’input dell’utente per il comportamento dinamico

Il flag --plugin-dir è utile per lo sviluppo e il test. Quando sei pronto a condividere il tuo plugin con altri, vedi Crea e distribuisci un marketplace plugin.

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 e LSP servers.

Errore comune: Non mettere commands/, agents/, skills/ o hooks/ dentro la directory .claude-plugin/. Solo plugin.json va dentro .claude-plugin/. Tutte le altre directory devono essere al livello radice del plugin.

Directory	Posizione	Scopo
`.claude-plugin/`	Radice plugin	Contiene il manifest `plugin.json` (opzionale se i componenti usano posizioni predefinite)
`commands/`	Radice plugin	Skills come file Markdown
`agents/`	Radice plugin	Definizioni di agent personalizzate
`skills/`	Radice plugin	Agent Skills con file `SKILL.md`
`hooks/`	Radice plugin	Gestori di eventi in `hooks.json`
`.mcp.json`	Radice plugin	Configurazioni MCP server
`.lsp.json`	Radice plugin	Configurazioni LSP server per l’intelligenza del codice

Prossimi passi: Pronto ad aggiungere più funzionalità? Vai a Sviluppa plugin più complessi per aggiungere agents, hooks, MCP servers e LSP servers. Per le specifiche tecniche complete di tutti i componenti del plugin, vedi Riferimento plugin.

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 ha bisogno di frontmatter con campi name e description, seguiti da istruzioni:

---
name: code-review
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, riavvia Claude Code 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 LSP server al tuo plugin

Per linguaggi comuni come TypeScript, Python e Rust, installa i plugin LSP pre-costruiti dal marketplace ufficiale. Crea plugin LSP personalizzati solo quando hai bisogno di supporto per linguaggi non già coperti.

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:

.lsp.json

{
  "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 le opzioni di configurazione LSP complete, vedi LSP servers.

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

Man mano che apporti modifiche al tuo plugin, riavvia Claude Code per raccogliere gli aggiornamenti. Testa i componenti del tuo plugin:

Prova i tuoi comandi con /command-name
Verifica che gli agents appaiano in /agents
Verifica che gli hooks funzionino come previsto

Puoi caricare più plugin contemporaneamente specificando il flag più volte:

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

Esegui il debug dei problemi del plugin

Se il tuo plugin non funziona come previsto:

Controlla la struttura: Assicurati che le tue directory siano alla radice del plugin, non dentro .claude-plugin/
Testa i componenti individualmente: Controlla ogni comando, agent e hook separatamente
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:

Aggiungi documentazione: Includi un README.md con istruzioni di installazione e utilizzo
Versiona il tuo plugin: Usa il versionamento semantico nel tuo plugin.json
Crea o usa un marketplace: Distribuisci tramite marketplace plugin per l’installazione
Testa con altri: Fai testare il plugin ai colleghi del team prima della distribuzione più ampia

Una volta che il tuo plugin è in un marketplace, altri possono installarlo usando le istruzioni in Scopri e installa plugin.

Per le specifiche tecniche complete, le tecniche di debug e le strategie di distribuzione, vedi Riferimento plugin.

Converti configurazioni esistenti in plugin

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

Passaggi di migrazione

Crea la struttura del plugin

Crea una nuova directory plugin:

mkdir -p my-plugin/.claude-plugin

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

my-plugin/.claude-plugin/plugin.json

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

Copia i tuoi file esistenti

Copia le tue configurazioni esistenti nella directory del plugin:

# Copy commands
cp -r .claude/commands my-plugin/

# Copy agents (if any)
cp -r .claude/agents my-plugin/

# Copy skills (if any)
cp -r .claude/skills my-plugin/

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:

my-plugin/hooks/hooks.json

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

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 /agents e verifica che gli hook si attivino correttamente.

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`

Dopo la migrazione, puoi rimuovere i file originali da .claude/ per evitare duplicati. La versione del plugin avrà la precedenza quando caricata.

Prossimi passi

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

Per gli utenti di plugin

Scopri e installa plugin: sfoglia i marketplace e installa i plugin
Configura marketplace del team: configura plugin a livello di repository per il tuo team

Per gli sviluppatori di plugin

Crea e distribuisci un marketplace: pacchetto e condividi i tuoi plugin
Riferimento plugin: specifiche tecniche complete
Approfondisci i componenti specifici del plugin:
- Skills: dettagli dello sviluppo degli skill
- Subagents: configurazione e capacità degli agent
- Hooks: gestione degli eventi e automazione
- MCP: integrazione di strumenti esterni

Sviluppate con Claude Code

​Quando usare plugin rispetto alla configurazione standalone

​Avvio rapido

​Prerequisiti

​Crea il tuo primo plugin

​Panoramica della struttura del plugin

​Sviluppa plugin più complessi

​Aggiungi Skills al tuo plugin

​Aggiungi LSP server al tuo plugin

​Organizza plugin complessi

​Testa i tuoi plugin localmente

​Esegui il debug dei problemi del plugin

​Condividi i tuoi plugin

​Converti configurazioni esistenti in plugin

​Passaggi di migrazione

​Cosa cambia durante la migrazione

​Prossimi passi

​Per gli utenti di plugin

​Per gli sviluppatori di plugin

Quando usare plugin rispetto alla configurazione standalone

Avvio rapido

Prerequisiti

Crea il tuo primo plugin

Panoramica della struttura del plugin

Sviluppa plugin più complessi

Aggiungi Skills al tuo plugin

Aggiungi LSP server al tuo plugin

Organizza plugin complessi

Testa i tuoi plugin localmente

Esegui il debug dei problemi del plugin

Condividi i tuoi plugin

Converti configurazioni esistenti in plugin

Passaggi di migrazione

Cosa cambia durante la migrazione

Prossimi passi

Per gli utenti di plugin

Per gli sviluppatori di plugin