Riferimento dei plugin

Riferimento tecnico completo per il sistema di plugin di Claude Code, inclusi schemi, comandi CLI e specifiche dei componenti.

Questo riferimento fornisce specifiche tecniche complete per il sistema di plugin di Claude Code, inclusi schemi dei componenti, comandi CLI e strumenti di sviluppo.

Un plugin è una directory autonoma di componenti che estende Claude Code con funzionalità personalizzate. I componenti del plugin includono skills, agents, hooks, server MCP, server LSP e monitor.

Riferimento dei componenti del plugin

Skills

I plugin aggiungono skills a Claude Code, creando scorciatoie /name che Lei o Claude potete invocare.

Posizione: Directory skills/ o commands/ nella radice del plugin

Formato file: Le skills sono directory con SKILL.md; i comandi sono semplici file markdown

Struttura della skill:

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (opzionale)
│   └── scripts/ (opzionale)
└── code-reviewer/
    └── SKILL.md

Comportamento dell'integrazione:

• Le skills e i comandi vengono rilevati automaticamente quando il plugin viene installato
• Claude può invocarli automaticamente in base al contesto dell'attività
• Le skills possono includere file di supporto insieme a SKILL.md

Per i dettagli completi, vedi Skills.

Agents

I plugin possono fornire subagents specializzati per attività specifiche che Claude può invocare automaticamente quando appropriato.

Posizione: Directory agents/ nella radice del plugin

Formato file: File markdown che descrivono le capacità dell'agent

Struttura dell'agent:

---
name: agent-name
description: In cosa si specializza questo agent e quando Claude dovrebbe invocarlo
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Prompt di sistema dettagliato per l'agent che descrive il suo ruolo, competenza e comportamento.

I plugin agents supportano i campi frontmatter name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background e isolation. L'unico valore valido per isolation è "worktree". Per motivi di sicurezza, hooks, mcpServers e permissionMode non sono supportati per gli agents forniti dai plugin.

Punti di integrazione:

• Gli agents appaiono nell'interfaccia /agents
• Claude può invocare gli agents automaticamente in base al contesto dell'attività
• Gli agents possono essere invocati manualmente dagli utenti
• I plugin agents funzionano insieme agli agents Claude integrati

Per i dettagli completi, vedi Subagents.

Hooks

I plugin possono fornire gestori di eventi che rispondono automaticamente agli eventi di Claude Code.

Posizione: hooks/hooks.json nella radice del plugin, o inline in plugin.json

Formato: Configurazione JSON con matcher di eventi e azioni

Configurazione dell'hook:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

I plugin hooks rispondono agli stessi eventi del ciclo di vita degli hooks definiti dall'utente:

Tipi di hook:

• command: esegui comandi shell o script
• http: invia l'evento JSON come richiesta POST a un URL
• mcp_tool: chiama uno strumento su un server MCP configurato
• prompt: valuta un prompt con un LLM (usa il placeholder $ARGUMENTS per il contesto)
• agent: esegui un verificatore agentico con strumenti per attività di verifica complesse

MCP servers

I plugin possono raggruppare server Model Context Protocol (MCP) per connettere Claude Code con strumenti e servizi esterni.

Posizione: .mcp.json nella radice del plugin, o inline in plugin.json

Formato: Configurazione standard del server MCP

Configurazione del server MCP:

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

Comportamento dell'integrazione:

• I server MCP del plugin si avviano automaticamente quando il plugin è abilitato
• I server appaiono come strumenti MCP standard nel toolkit di Claude
• Le capacità del server si integrano perfettamente con gli strumenti esistenti di Claude
• I server del plugin possono essere configurati indipendentemente dai server MCP dell'utente

LSP servers

I plugin possono fornire server Language Server Protocol (LSP) per dare a Claude intelligenza del codice in tempo reale mentre lavori sul tuo codebase.

L'integrazione LSP fornisce:

• Diagnostica istantanea: Claude vede errori e avvisi immediatamente dopo ogni modifica
• Navigazione del codice: vai alla definizione, trova riferimenti e informazioni al passaggio del mouse
• Consapevolezza del linguaggio: informazioni sul tipo e documentazione per i simboli del codice

Posizione: .lsp.json nella radice del plugin, o inline in plugin.json

Formato: Configurazione JSON che mappa i nomi dei server di linguaggio alle loro configurazioni

Formato del file .lsp.json:

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

Inline in plugin.json:

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

Campi obbligatori:

Campi opzionali:

Plugin LSP disponibili:

Installa il server di linguaggio per primo, quindi installa il plugin dal marketplace.

Monitors

I plugin possono dichiarare monitor in background che Claude Code avvia automaticamente quando il plugin è attivo. Ogni monitor esegue un comando shell per la durata della sessione e fornisce ogni riga stdout a Claude come notifica, in modo che Claude possa reagire alle voci di log, ai cambiamenti di stato o agli eventi sottoposti a polling senza essere chiesto di avviare il watch stesso.

I monitor dei plugin utilizzano lo stesso meccanismo dello strumento Monitor e condividono i suoi vincoli di disponibilità. Vengono eseguiti solo in sessioni CLI interattive, vengono eseguiti senza sandbox allo stesso livello di fiducia degli hooks e vengono saltati su host in cui lo strumento Monitor non è disponibile.

Posizione: monitors/monitors.json nella radice del plugin, o inline in plugin.json

Formato: Array JSON di voci di monitor

Il seguente monitors/monitors.json monitora un endpoint di stato di distribuzione e un log di errore locale:

[
  {
    "name": "deploy-status",
    "command": "${CLAUDE_PLUGIN_ROOT}/scripts/poll-deploy.sh ${user_config.api_endpoint}",
    "description": "Deployment status changes"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log",
    "when": "on-skill-invoke:debug"
  }
]

Per dichiarare monitor inline, imposta la chiave monitors in plugin.json sullo stesso array. Per caricare da un percorso non predefinito, imposta monitors su una stringa di percorso relativo come "./config/monitors.json".

Campi obbligatori:

Campi opzionali:

Il valore command supporta le stesse sostituzioni di variabili delle configurazioni dei server MCP e LSP: ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}, ${user_config.*} e qualsiasi ${ENV_VAR} dall'ambiente. Prefissa il comando con cd "${CLAUDE_PLUGIN_ROOT}" && se lo script ha bisogno di essere eseguito dalla directory del plugin stesso.

La disabilitazione di un plugin a metà sessione non interrompe i monitor già in esecuzione. Si interrompono quando la sessione termina.

Themes

I plugin possono fornire temi di colore che appaiono in /theme insieme ai preset integrati e ai temi locali dell'utente. Un tema è un file JSON in themes/ con un preset base e una mappa sparsa overrides di token di colore.

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

Selezionando un tema del plugin si persiste custom:<plugin-name>:<slug> nella configurazione dell'utente. I temi del plugin sono di sola lettura; premendo Ctrl+E su uno in /theme lo copia in ~/.claude/themes/ in modo che l'utente possa modificare la copia.

Ambiti di installazione del plugin

Quando installi un plugin, scegli un ambito che determina dove il plugin è disponibile e chi altro può usarlo:

I plugin utilizzano lo stesso sistema di ambito di altre configurazioni di Claude Code. Per le istruzioni di installazione e i flag di ambito, vedi Installa plugin. Per una spiegazione completa degli ambiti, vedi Ambiti di configurazione.

Schema del manifest del plugin

Il file .claude-plugin/plugin.json definisce i metadati e la configurazione del tuo plugin. Questa sezione documenta tutti i campi e le opzioni supportati.

Il manifest è opzionale. Se omesso, Claude Code scopre automaticamente i componenti nelle posizioni predefinite e deriva il nome del plugin dal nome della directory. Usa un manifest quando hai bisogno di fornire metadati o percorsi di componenti personalizzati.

Schema completo

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "themes": "./themes/",
  "lspServers": "./.lsp.json",
  "monitors": "./monitors.json",
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Campi obbligatori

Se includi un manifest, name è l'unico campo obbligatorio.

Questo nome viene utilizzato per lo spazio dei nomi dei componenti. Ad esempio, nell'interfaccia utente, l'agent agent-creator per il plugin con nome plugin-dev apparirà come plugin-dev:agent-creator.

Campi di metadati

Campi del percorso del componente

Configurazione utente

Il campo userConfig dichiara i valori per i quali Claude Code chiede all'utente quando il plugin è abilitato. Usa questo invece di richiedere agli utenti di modificare manualmente settings.json.

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Your team's API endpoint"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "API authentication token",
      "sensitive": true
    }
  }
}

Le chiavi devono essere identificatori validi. Ogni opzione supporta questi campi:

Ogni valore è disponibile per la sostituzione come ${user_config.KEY} nelle configurazioni dei server MCP e LSP, nei comandi degli hooks, nei comandi dei monitor e nel contenuto delle skills e degli agents (solo per i valori non sensibili). Tutti i valori vengono esportati ai sottoprocessi del plugin come variabili di ambiente CLAUDE_PLUGIN_OPTION_<KEY>.

I valori non sensibili vengono archiviati in settings.json sotto pluginConfigs[<plugin-id>].options. I valori sensibili vanno al portachiavi di sistema (o ~/.claude/.credentials.json dove il portachiavi non è disponibile). L'archiviazione del portachiavi è condivisa con i token OAuth e ha un limite totale approssimativo di 2 KB, quindi mantieni i valori sensibili piccoli.

Channels

Il campo channels consente a un plugin di dichiarare uno o più canali di messaggi che iniettano contenuto nella conversazione. Ogni canale si associa a un server MCP fornito dal plugin.

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Your Telegram user ID"
        }
      }
    }
  ]
}

Il campo server è obbligatorio e deve corrispondere a una chiave in mcpServers del plugin. Il userConfig facoltativo per canale utilizza lo stesso schema del campo di livello superiore, consentendo al plugin di richiedere token bot o ID proprietario quando il plugin è abilitato.

Regole del comportamento del percorso

Per skills, commands, agents, outputStyles, themes e monitors, un percorso personalizzato sostituisce il valore predefinito. Se il manifest specifica skills, la directory predefinita skills/ non viene scansionata; se specifica monitors, il valore predefinito monitors/monitors.json non viene caricato. Hooks, MCP servers e LSP servers hanno semantica diversa per gestire più fonti.

• Tutti i percorsi devono essere relativi alla radice del plugin e iniziare con ./
• I componenti dai percorsi personalizzati utilizzano le stesse regole di denominazione e spazio dei nomi
• È possibile specificare più percorsi come array
• Per mantenere la directory predefinita e aggiungere più percorsi per skills, commands, agents o output styles, includi il valore predefinito nel tuo array: "skills": ["./skills/", "./extras/"]
• Quando un percorso di skill punta a una directory che contiene direttamente un SKILL.md, ad esempio "skills": ["./"] che punta alla radice del plugin, il campo frontmatter name in SKILL.md determina il nome di invocazione della skill. Questo fornisce un nome stabile indipendentemente dalla directory di installazione. Se name non è impostato nel frontmatter, il nome della directory viene utilizzato come fallback.

Esempi di percorso:

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

Variabili di ambiente

Claude Code fornisce due variabili per fare riferimento ai percorsi del plugin. Entrambe vengono sostituite inline ovunque appaiano nel contenuto delle skills, nel contenuto degli agents, nei comandi degli hooks, nei comandi dei monitor e nelle configurazioni dei server MCP o LSP. Entrambe vengono anche esportate come variabili di ambiente ai processi degli hooks e ai sottoprocessi dei server MCP o LSP.

${CLAUDE_PLUGIN_ROOT}: il percorso assoluto della directory di installazione del tuo plugin. Usalo per fare riferimento a script, binari e file di configurazione forniti con il plugin. Questo percorso cambia quando il plugin viene aggiornato. La directory della versione precedente rimane su disco per circa sette giorni dopo un aggiornamento prima della pulizia, ma trattala come effimera e non scrivere stato qui.

Quando un plugin viene aggiornato a metà sessione, i comandi degli hooks, i monitor, i server MCP e i server LSP continuano a utilizzare il percorso della versione precedente. Esegui /reload-plugins per passare gli hooks, i server MCP e i server LSP al nuovo percorso; i monitor richiedono un riavvio della sessione.

${CLAUDE_PLUGIN_DATA}: una directory persistente per lo stato del plugin che sopravvive agli aggiornamenti. Usalo per le dipendenze installate come node_modules o ambienti virtuali Python, codice generato, cache e qualsiasi altro file che dovrebbe persistere tra le versioni del plugin. La directory viene creata automaticamente la prima volta che questa variabile viene referenziata.

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

Directory di dati persistenti

La directory ${CLAUDE_PLUGIN_DATA} si risolve in ~/.claude/plugins/data/{id}/, dove {id} è l'identificatore del plugin con caratteri al di fuori di a-z, A-Z, 0-9, _ e - sostituiti da -. Per un plugin installato come formatter@my-marketplace, la directory è ~/.claude/plugins/data/formatter-my-marketplace/.

Un uso comune è installare le dipendenze del linguaggio una volta e riutilizzarle tra le sessioni e gli aggiornamenti del plugin. Poiché la directory dei dati sopravvive a qualsiasi singola versione del plugin, un controllo dell'esistenza della directory da solo non può rilevare quando un aggiornamento cambia il manifest delle dipendenze del plugin. Il modello consigliato confronta il manifest fornito con una copia nella directory dei dati e reinstalla quando differiscono.

Questo hook SessionStart installa node_modules alla prima esecuzione e di nuovo ogni volta che un aggiornamento del plugin include un package.json modificato:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

Il diff esce con codice diverso da zero quando la copia archiviata è mancante o differisce da quella fornita, coprendo sia la prima esecuzione che gli aggiornamenti che cambiano le dipendenze. Se npm install non riesce, il trailing rm rimuove il manifest copiato in modo che la prossima sessione riprovi.

Gli script forniti in ${CLAUDE_PLUGIN_ROOT} possono quindi essere eseguiti contro il node_modules persistente:

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

La directory dei dati viene eliminata automaticamente quando disinstalli il plugin dall'ultimo ambito in cui è installato. L'interfaccia /plugin mostra la dimensione della directory e chiede conferma prima di eliminare. La CLI elimina per impostazione predefinita; passa --keep-data per preservarla.

Caching del plugin e risoluzione dei file

I plugin vengono specificati in uno di due modi:

• Tramite claude --plugin-dir, per la durata di una sessione.
• Tramite un marketplace, installato per sessioni future.

Per motivi di sicurezza e verifica, Claude Code copia i plugin del marketplace nella cache dei plugin locale dell'utente (~/.claude/plugins/cache) piuttosto che usarli sul posto. Comprendere questo comportamento è importante quando si sviluppano plugin che fanno riferimento a file esterni.

Ogni versione installata è una directory separata nella cache. Quando aggiorni o disinstalli un plugin, la directory della versione precedente viene contrassegnata come orfana e rimossa automaticamente 7 giorni dopo. Il periodo di grazia consente alle sessioni di Claude Code concorrenti che hanno già caricato la versione precedente di continuare a funzionare senza errori.

Gli strumenti Glob e Grep di Claude saltano le directory delle versioni orfane durante le ricerche, quindi i risultati dei file non includono il codice del plugin obsoleto.

Limitazioni dell'attraversamento dei percorsi

I plugin installati non possono fare riferimento a file al di fuori della loro directory. I percorsi che attraversano al di fuori della radice del plugin (come ../shared-utils) non funzioneranno dopo l'installazione perché questi file esterni non vengono copiati nella cache.

Lavorare con dipendenze esterne

Se il tuo plugin ha bisogno di accedere a file al di fuori della sua directory, puoi creare link simbolici a file esterni all'interno della directory del tuo plugin. I symlink vengono preservati nella cache piuttosto che dereferenziati e si risolvono al loro target in fase di esecuzione. Il seguente comando crea un link dall'interno della directory del tuo plugin a una posizione di utilità condivise:

ln -s /path/to/shared-utils ./shared-utils

Questo fornisce flessibilità mantenendo i vantaggi di sicurezza del sistema di caching.

Struttura della directory del plugin

Layout standard del plugin

Un plugin completo segue questa struttura:

enterprise-plugin/
├── .claude-plugin/           # Directory dei metadati (opzionale)
│   └── plugin.json             # manifest del plugin
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills come file markdown flat
│   ├── status.md
│   └── logs.md
├── agents/                   # Definizioni dei subagent
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── output-styles/            # Definizioni dello stile di output
│   └── terse.md
├── themes/                   # Definizioni del tema colore
│   └── dracula.json
├── monitors/                 # Configurazioni dei monitor in background
│   └── monitors.json
├── hooks/                    # Configurazioni degli hook
│   ├── hooks.json           # Configurazione principale degli hook
│   └── security-hooks.json  # Hook aggiuntivi
├── bin/                      # Eseguibili del plugin aggiunti a PATH
│   └── my-tool               # Invocabile come comando bare nello strumento Bash
├── settings.json            # Impostazioni predefinite per il plugin
├── .mcp.json                # Definizioni del server MCP
├── .lsp.json                # Configurazioni del server LSP
├── scripts/                 # Script degli hook e utilità
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # File di licenza
└── CHANGELOG.md             # Cronologia delle versioni

Un file CLAUDE.md nella radice del plugin non viene caricato come contesto del progetto. I plugin contribuiscono al contesto attraverso skills, agents e hooks piuttosto che tramite CLAUDE.md. Per fornire istruzioni che si carichino nel contesto di Claude, inseritele in uno skill.

Riferimento delle posizioni dei file

Riferimento dei comandi CLI

Claude Code fornisce comandi CLI per la gestione non interattiva dei plugin, utile per scripting e automazione.

plugin install

Installa un plugin dai marketplace disponibili.

claude plugin install <plugin> [options]

Argomenti:

• <plugin>: Nome del plugin o plugin-name@marketplace-name per un marketplace specifico

Opzioni:

L'ambito determina quale file di impostazioni viene aggiunto al plugin installato. Ad esempio, --scope project scrive in enabledPlugins in .claude/settings.json, rendendo il plugin disponibile a tutti coloro che clonano il repository del progetto.

Esempi:

# Installa nell'ambito utente (predefinito)
claude plugin install formatter@my-marketplace

# Installa nell'ambito del progetto (condiviso con il team)
claude plugin install formatter@my-marketplace --scope project

# Installa nell'ambito locale (gitignored)
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

Rimuovi un plugin installato.

claude plugin uninstall <plugin> [options]

Argomenti:

• <plugin>: Nome del plugin o plugin-name@marketplace-name

Opzioni:

Alias: remove, rm

Per impostazione predefinita, la disinstallazione dall'ultimo ambito rimanente elimina anche la directory ${CLAUDE_PLUGIN_DATA} del plugin. Usa --keep-data per preservarla, ad esempio quando reinstalli dopo aver testato una nuova versione.

plugin prune

Rimuovi le dipendenze auto-installate dei plugin che non sono più richieste da nessun plugin installato. Le dipendenze che Claude Code ha incluso per soddisfare il campo dependencies di un altro plugin vengono rimosse; i plugin che hai installato direttamente non vengono mai toccati.

claude plugin prune [options]

Opzioni:

Alias: autoremove

Il comando elenca le dipendenze orfane e chiede conferma prima di rimuoverle. Per rimuovere un plugin e pulire le sue dipendenze in un unico passaggio, esegui claude plugin uninstall <plugin> --prune.

plugin enable

Abilita un plugin disabilitato.

claude plugin enable <plugin> [options]

Argomenti:

• <plugin>: Nome del plugin o plugin-name@marketplace-name

Opzioni:

plugin disable

Disabilita un plugin senza disinstallarlo.

claude plugin disable <plugin> [options]

Argomenti:

• <plugin>: Nome del plugin o plugin-name@marketplace-name

Opzioni:

plugin update

Aggiorna un plugin all'ultima versione.

claude plugin update <plugin> [options]

Argomenti:

• <plugin>: Nome del plugin o plugin-name@marketplace-name

Opzioni:

plugin list

Elenca i plugin installati con la loro versione, marketplace di origine e stato di abilitazione.

claude plugin list [options]

Opzioni:

plugin tag

Crea un tag git di rilascio per il plugin nella directory corrente. Esegui dall'interno della cartella del plugin. Vedi Tag plugin releases.

claude plugin tag [options]

Opzioni:

Strumenti di debug e sviluppo

Comandi di debug

Usa claude --debug per vedere i dettagli del caricamento del plugin:

Questo mostra:

• Quali plugin vengono caricati
• Eventuali errori nei manifest del plugin
• Registrazione di skill, agent e hook
• Inizializzazione del server MCP

Problemi comuni

Messaggi di errore di esempio

Errori di convalida del manifest:

• Invalid JSON syntax: Unexpected token } in JSON at position 142: controlla la mancanza di virgole, virgole extra o stringhe non quotate
• Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required: un campo obbligatorio è mancante
• Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: errore di sintassi JSON

Errori di caricamento del plugin:

• Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.: il percorso del comando esiste ma non contiene file di comando validi
• Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.: il percorso source in marketplace.json punta a una directory inesistente
• Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.: rimuovi le definizioni di componenti duplicate o rimuovi strict: false nella voce del marketplace

Risoluzione dei problemi degli hook

Script dell'hook non in esecuzione:

1. Controlla che lo script sia eseguibile: chmod +x ./scripts/your-script.sh
2. Verifica la riga shebang: La prima riga dovrebbe essere #!/bin/bash o #!/usr/bin/env bash
3. Controlla che il percorso usi ${CLAUDE_PLUGIN_ROOT}: "command": "${CLAUDE_PLUGIN_ROOT}/scripts/your-script.sh"
4. Testa lo script manualmente: ./scripts/your-script.sh

Hook non attivato su eventi previsti:

1. Verifica che il nome dell'evento sia corretto (sensibile alle maiuscole): PostToolUse, non postToolUse
2. Controlla che il pattern del matcher corrisponda ai tuoi tool: "matcher": "Write|Edit" per le operazioni sui file
3. Conferma che il tipo di hook sia valido: command, http, mcp_tool, prompt, o agent

Risoluzione dei problemi del server MCP

Server non si avvia:

1. Controlla che il comando esista e sia eseguibile
2. Verifica che tutti i percorsi utilizzino la variabile ${CLAUDE_PLUGIN_ROOT}
3. Controlla i log del server MCP: claude --debug mostra gli errori di inizializzazione
4. Testa il server manualmente al di fuori di Claude Code

Strumenti del server non visualizzati:

1. Assicurati che il server sia configurato correttamente in .mcp.json o plugin.json
2. Verifica che il server implementi correttamente il protocollo MCP
3. Controlla i timeout di connessione nell'output di debug

Errori di struttura della directory

Sintomi: Il plugin si carica ma i componenti (skills, agents, hooks) sono mancanti.

Struttura corretta: I componenti devono essere nella radice del plugin, non all'interno di .claude-plugin/. Solo plugin.json appartiene a .claude-plugin/.

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← Solo manifest qui
├── commands/            ← A livello di radice
├── agents/              ← A livello di radice
└── hooks/               ← A livello di radice

Se i tuoi componenti sono all'interno di .claude-plugin/, spostali nella radice del plugin.

Checklist di debug:

1. Esegui claude --debug e cerca i messaggi "loading plugin"
2. Controlla che ogni directory di componenti sia elencata nell'output di debug
3. Verifica che i permessi dei file consentano la lettura dei file del plugin

Riferimento di distribuzione e versioning

Gestione della versione

Claude Code utilizza la versione del plugin come chiave di cache che determina se un aggiornamento è disponibile. Quando esegui /plugin update o l'aggiornamento automatico si attiva, Claude Code calcola la versione corrente e salta l'aggiornamento se corrisponde a quella già installata.

La versione viene risolta dal primo di questi che è impostato:

1. Il campo version nel plugin.json del plugin
2. Il campo version nella voce del marketplace del plugin in marketplace.json
3. Lo SHA del commit git del plugin, per le fonti github, url, git-subdir e relative-path in un marketplace ospitato su git
4. unknown, per le fonti npm o le directory locali non all'interno di un repository git

Questo ti offre due modi per versionare un plugin:

Se utilizzi versioni esplicite, segui il versionamento semantico (MAJOR.MINOR.PATCH): aumenta MAJOR per modifiche di rilievo, MINOR per nuove funzionalità, PATCH per correzioni di bug. Documenta le modifiche in un CHANGELOG.md.

Vedi anche

• Plugin - Tutorial e utilizzo pratico
• Marketplace dei plugin - Creazione e gestione dei marketplace
• Skills - Dettagli dello sviluppo delle skill
• Subagents - Configurazione e capacità dell'agent
• Hooks - Gestione degli eventi e automazione
• MCP - Integrazione di strumenti esterni
• Impostazioni - Opzioni di configurazione per i plugin