Riferimento del manifest del plugin

Riferimento completo per plugin.json: ogni campo con il suo tipo e valore predefinito, forme di percorso accettate, e gli schemi userConfig e variabili di ambiente.

Un manifest del plugin è il file plugin.json nella directory .claude-plugin/ di un plugin. Contiene i metadati del plugin e i valori userConfig che Claude Code richiede all'utente. Dichiara inoltre qualsiasi componente che definite inline o mantenete al di fuori della sua posizione predefinita.

Questo riferimento è per i creatori di plugin e per i proprietari di marketplace che inseriscono campi di componenti in una voce di marketplace.

Iniziate dalla sezione che corrisponde a quello che state cercando:

• Un campo: la tabella Fields fornisce il tipo di ogni campo, se è obbligatorio, il valore predefinito e cosa accetta. Path rules copre il prefisso ./ e il contenimento per ogni percorso di componente
• Un'opzione userConfig o una voce channels: gli schemi User configuration e Channels
• ${CLAUDE_PLUGIN_ROOT} o un'altra variabile a cui un plugin può fare riferimento: Environment variables
• Dove vanno i file di ogni componente: Standard layout
• Un messaggio da claude plugin validate: la pagina di troubleshooting elenca ogni messaggio con la sua correzione e i link alle sezioni rilevanti di questa pagina

Manifest file

Il manifest è facoltativo. Senza di esso, Claude Code carica i componenti che trova nel standard layout. Il nome del plugin proviene quindi dalla voce di marketplace, o dal nome della directory quando caricate il plugin con --plugin-dir.

Scrivete un manifest quando volete metadati, un componente al di fuori della sua directory predefinita, userConfig, o una definizione di componente inline.

Salvate il manifest in .claude-plugin/plugin.json sotto la radice del plugin. Mettete ogni altro file del plugin alla radice del plugin, non dentro .claude-plugin/. Questo include skills/, commands/ e hooks/.

L'esempio seguente imposta la maggior parte delle chiavi nella tabella Fields. Passa la validazione in una directory di plugin che contiene ogni percorso referenziato.

{
  "name": "deploy-tools",
  "displayName": "Deploy Tools",
  "version": "1.2.0",
  "description": "Deployment commands, a review agent, and a status monitor",
  "author": {
    "name": "Example Team",
    "email": "dev@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/docs/deploy-tools",
  "repository": "https://github.com/example/deploy-tools",
  "license": "MIT",
  "keywords": ["deployment", "ci"],
  "defaultEnabled": true,
  "dependencies": ["secrets-vault"],
  "metadata": { "catalogId": "cat-123" },
  "skills": ["./extra-skills/"],
  "commands": {
    "status": {
      "source": "./commands/status.md",
      "description": "Show the current deployment status"
    },
    "about": {
      "content": "Explain what the deploy-tools plugin provides.",
      "description": "Describe this plugin"
    }
  },
  "agents": ["./agents/reviewer.md"],
  "hooks": "./config/extra-hooks.json",
  "mcpServers": {
    "deploy-api": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  },
  "lspServers": "./.lsp.json",
  "outputStyles": "./styles/",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./config/monitors.json"
  },
  "userConfig": {
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for the deployment API",
      "sensitive": true
    }
  }
}

Unrecognized fields

Una chiave di primo livello non riconosciuta viene rimossa, e una chiave non riconosciuta dentro un'opzione userConfig, una voce channels, una configurazione lspServers, o una voce monitors viene rifiutata:

• Top-level fields: il campo viene rimosso e il plugin si carica. claude plugin validate segnala ogni campo di primo livello non riconosciuto come un avviso
• Strict objects: le opzioni userConfig, le voci channels, le configurazioni lspServers e le voci monitors sono rigorose. Una chiave sconosciuta dentro una di esse è un errore, e il plugin non si carica

Validate the manifest

claude plugin validate è il controllo autorevole per un manifest. Eseguitelo dalla vostra shell contro la directory del plugin:

claude plugin validate ./my-plugin

Il comando segnala uno di questi risultati:

• Validation passed: il manifest si carica
• Validation passed with warnings: il manifest si carica, ma il validatore ha trovato qualcosa da correggere, come un campo di primo livello sconosciuto che Claude Code rimuove, un name che non è in kebab-case, o un version, description, o author mancante. Passate --strict per trasformare gli avvisi in errori in CI
• Validation failed: il manifest ha una mancata corrispondenza di tipo, un percorso mancante o che esce dalla radice del plugin, o una chiave sconosciuta dentro un'opzione userConfig, una voce channels, una configurazione lspServers, o una voce monitors. Claude Code segnala lo stesso problema quando carica il plugin

Fields

La tabella elenca le chiavi di primo livello in plugin.json. name è l'unica chiave obbligatoria. Dove un nome di campo è un link, la sezione collegata ha le sue regole complete.

Per le chiavi di componente come commands e hooks, Component path forms mostra ogni forma accettata con un esempio, e ogni percorso segue le path rules per il prefisso ./, le estensioni e il contenimento.

Nella colonna Type, un percorso è una stringa relativa alla radice del plugin, come "./custom/commands".

`name`

L'identificatore del plugin. Deve essere non vuoto, senza spazi, @, :, separatori di percorso, caratteri di controllo, o caratteri di formattazione bidirezionale; usate kebab-case.

Claude Code namespaccia ogni componente sotto di esso, quindi un agente reviewer nel plugin deploy-tools appare come deploy-tools:reviewer.

`displayName`

Il nome mostrato nell'interfaccia utente al posto di name. Può contenere spazi e qualsiasi maiuscola/minuscola, e non viene utilizzato per il namespacing o la ricerca.

Per un plugin installato da marketplace, un displayName sulla voce di marketplace ha la precedenza su questo valore.

`version`

Una stringa di versione, non controllata rispetto a semver. Impostarla fissa il plugin a quella versione finché non la cambiate; vedere Versions and updates. Un plugin con una command source, un plugin da un marketplace ospitato su claude.ai, e un plugin caricato in place da un marketplace aggiunto come directory locale non sono fissati da questo campo.

`metadata`

Un oggetto in forma libera per i vostri dati, come campi di catalogo o di diritto. Claude Code non lo legge. Richiede Claude Code v2.1.222 o successivo.

`defaultEnabled`

Se il plugin inizia abilitato quando l'utente non lo ha impostato in enabledPlugins. Predefinito a true. Un plugin da cui dipende un plugin abilitato inizia abilitato indipendentemente. Lo stesso campo nella voce di marketplace sostituisce questo.

Una volta che la voce enabledPlugins di un utente è scritta, persiste attraverso gli aggiornamenti del plugin, quindi cambiare defaultEnabled in una versione successiva non cambia l'impostazione per un utente esistente.

`dependencies`

Plugin che devono essere abilitati affinché questo funzioni. Ogni voce è "name", "name@marketplace", o { "name": "...", "marketplace": "...", "version": "..." }. I nomi nudi si risolvono rispetto al proprio marketplace del plugin. Vedere dependency constraints.

`settings`

Impostazioni che Claude Code applica mentre il plugin è abilitato. Solo agent e subagentStatusLine hanno effetto; altre chiavi vengono eliminate al caricamento. Un settings.json alla radice del plugin ha la precedenza su questa chiave. Vedere Default settings.

Component path forms

Ogni chiave di componente accetta un percorso relativo alla radice del plugin. hooks, mcpServers, lspServers e experimental.monitors accettano anche configurazione inline, commands accetta anche una mappa di oggetti, e mcpServers accetta anche percorsi di bundle MCP e URL. Gli esempi che seguono mostrano ogni forma accettata una volta. Per cosa fa ogni componente al runtime, vedere Plugin components.

Path-only fields

agents, skills, outputStyles, workflows e experimental.themes accettano un percorso o un array di percorsi. Le voci agents devono essere file .md, e le voci skills devono essere directory. Gli altri tre accettano una directory o un file.

{
  "agents": ["./custom-agents/reviewer.md", "./custom-agents/tester.md"],
  "skills": ["./extra-skills/", "."],
  "outputStyles": "./styles/"
}

`commands`

commands accetta un percorso, un array di percorsi, o una mappa di oggetti. Un percorso nomina un file di comando .md piatto o una directory. Nella mappa di oggetti, ogni chiave diventa il nome del comando dopo il prefisso del plugin. Ad esempio, "about" nel plugin deploy-tools viene eseguito come /deploy-tools:about.

Ogni valore imposta esattamente uno di source o content, e una voce che imposta entrambi o nessuno dei due non passa la validazione. Gli altri campi in questa tabella sono opzionali:

Questa mappa dichiara un comando da un file e uno da contenuto inline:

{
  "commands": {
    "status": { "source": "./commands/status.md", "argumentHint": "[env]" },
    "about": { "content": "Explain what this plugin provides." }
  }
}

`hooks`

hooks accetta un percorso di file .json, un oggetto hooks inline nella stessa forma di hooks in settings.json, o un array che mescola entrambi. Per gli eventi hook e i campi del gestore, vedere il riferimento hooks.

Claude Code unisce tutto ciò che dichiarate con hooks/hooks.json quando quel file esiste.

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

`mcpServers`

mcpServers accetta un percorso di file .json, un percorso di bundle MCP o URL, una mappa inline, o un array che mescola loro. Per i campi di configurazione del server, vedere plugin-provided MCP servers.

Claude Code carica .mcp.json alla radice del plugin per primo, poi ogni forma dichiarata in ordine. Un nome di server dichiarato successivamente sostituisce uno precedente.

Un valore mcpServers assume una di queste forme:

Un percorso di bundle o URL deve terminare in .mcpb o .dxt. Qualsiasi altra estensione non passa la validazione.

`lspServers`

lspServers accetta un percorso di file .json, una mappa inline di nome del server a configurazione, o un array di uno qualsiasi.

Claude Code carica .lsp.json alla radice del plugin per primo, poi ogni configurazione dichiarata in ordine. Un nome di server dichiarato successivamente sostituisce uno precedente.

Ogni configurazione del server è un oggetto rigoroso con questi campi. Una chiave sconosciuta non passa la validazione.

Questa configurazione inline esegue gopls per i file .go:

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

Per i language server che Anthropic pubblica come plugin e come i server si comportano al runtime, vedere Code intelligence.

`monitors`

experimental.monitors accetta un percorso di file .json o l'array inline. Quando omettete la chiave, Claude Code carica monitors/monitors.json se esiste.

Ogni voce è un oggetto rigoroso con questi campi.

Questo array inline dichiara un monitor che inizia la prima volta che la skill deploy viene eseguita:

{
  "experimental": {
    "monitors": [
      {
        "name": "deploy-status",
        "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
        "description": "Deployment status changes",
        "when": "on-skill-invoke:deploy"
      }
    ]
  }
}

Un command di monitor non può fare riferimento a ${user_config.*}. Vedere Fields that run through a shell.

Regole dei percorsi

Ogni percorso di componente in un manifest è relativo alla radice del plugin e deve iniziare con ./. Un percorso come commands/foo.md non supera la convalida. skills e mcpServers accettano ciascuno una forma al di fuori di questa regola:

• skills: accetta anche ".". Sia "." che "./" indicano la radice del plugin. Prima della v2.1.221, "." non superava la convalida del manifest, quindi utilizzare "./" quando il plugin deve caricarsi su versioni precedenti
• mcpServers: accetta anche un URL di bundle https://

Contenimento ed esistenza

Ogni percorso di componente deve risolversi all'interno della radice del plugin e deve esistere. claude plugin validate non controlla i percorsi outputStyles, lspServers, monitors o themes, quindi un percorso errato in questi campi non riesce solo quando il plugin si carica:

• Contenimento: un percorso che si risolve al di fuori della radice del plugin non si carica e la scheda Errors di /plugin mostra <component> path escapes plugin directory: <path>. Un percorso contenente .. è il caso più comune e claude plugin validate lo segnala come Path contains ".." which could be a path traversal attempt
• Esistenza: un percorso che non esiste non si carica e la scheda Errors di /plugin mostra <component> path not found: <path>. claude plugin validate lo segnala come Path not found

Come ogni chiave si combina con la sua posizione predefinita

Ogni chiave di componente sostituisce la sua posizione predefinita, si aggiunge ad essa o si unisce ad essa:

• Sostituisce il valore predefinito: commands, agents, outputStyles, workflows, experimental.themes, experimental.monitors. Quando si imposta commands, la directory predefinita commands/ non viene scansionata. Per mantenere il valore predefinito e aggiungerne altri, elencarli esplicitamente: "commands": ["./commands/", "./extras/"]
• Si aggiunge al valore predefinito: skills. La directory skills/ viene ancora scansionata e le directory elencate si caricano insieme ad essa
• Si unisce: hooks, mcpServers, lspServers. Il file predefinito si carica per primo e ciò che il manifest dichiara si unisce ad esso, come descritto in Component path forms

Se un plugin ha una cartella predefinita come commands/ e imposta anche la chiave del manifest che la sostituisce, Claude Code carica i percorsi del manifest e non la cartella. claude plugin list e l'interfaccia /plugin mostrano quindi l'avviso Default <folder>/ folder is ignored because the manifest sets "<key>".

Per evitare l'avviso, impostare la chiave su un percorso all'interno di quella cartella: "commands": ["./commands/deploy.md"] nomina un file nella cartella predefinita e non produce alcun avviso.

Configurazione utente

userConfig dichiara i valori che Claude Code richiede all'utente quando il plugin è abilitato, in modo che gli utenti non debbano modificare settings.json direttamente.

Le chiavi sono identificatori composti da lettere, cifre e caratteri di sottolineatura, e non possono iniziare con una cifra.

Ogni valore è un oggetto rigoroso con questi campi. Una chiave sconosciuta non supera la convalida.

Ogni opzione di ogni plugin abilitato appare anche come una riga nel pannello /config, ad eccezione delle opzioni sensitive e degli elenchi multiple. Le righe /config richiedono Claude Code v2.1.269 o successivo.

Questo userConfig dichiara un endpoint e un token mascherato:

{
  "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
    }
  }
}

Limitare un campo a opzioni fisse

Impostare options su un campo userConfig per fare in modo che gli utenti scelgano il suo valore da un elenco fisso.

Per limitare un campo tone a tre opzioni, elencarle in options e impostare default su una di esse:

{
  "userConfig": {
    "tone": {
      "type": "string",
      "title": "Tone",
      "description": "Voice for generated replies",
      "options": ["neutral", "warm", "formal"],
      "default": "neutral"
    }
  }
}

Se si dichiara options su qualsiasi campo, gli utenti su versioni di Claude Code precedenti a v2.1.271 non possono caricare il plugin.

options si applica a un campo string che non è multiple o sensitive. Impostare default su uno dei valori elencati, oppure impostare required: true in modo che l'utente debba sceglierne uno. Ogni opzione è un'etichetta semplice di 1 a 64 caratteri, e claude plugin validate, che si esegue nella shell, segnala tutto il resto che rifiuta. Un plugin le cui options violano queste regole non riesce a caricarsi.

Dove vengono memorizzati i valori

I valori non sensibili vengono salvati sotto pluginConfigs nel settings.json dell'utente. I valori sensibili vanno invece nell'archivio di credenziali sicure della piattaforma. La pagina delle impostazioni elenca da quali file di impostazioni viene letto pluginConfigs.

Fare riferimento a un valore salvato

Fare riferimento a un valore salvato dove il plugin ne ha bisogno, in una di due forme:

• ${user_config.KEY}: sostituito nella configurazione del server MCP, nella configurazione del server LSP, negli args dell'hook in forma exec, e nel contenuto di skill e agent. Nel contenuto di skill e agent, solo i valori non sensibili vengono sostituiti, e un valore sensibile lì diventa un segnaposto
• CLAUDE_PLUGIN_OPTION_<KEY>: esportato ai processi hook per ogni opzione, con <KEY> in maiuscolo. Un hook in forma shell legge $CLAUDE_PLUGIN_OPTION_API_TOKEN per api_token

Campi che passano attraverso una shell

I comandi hook in forma shell, i comandi di monitoraggio, e l'MCP headersHelper rifiutano ${user_config.*}. Un componente che lo riferisce in uno di questi campi non riesce con un errore invece di eseguirsi, perché il valore del campo viene passato a una shell che riparsificherebbe il valore sostituito.

La tabella mostra come il valore può raggiungerlo per ciascuno di questi campi.

Channels

channels dichiara i canali di messaggi che un plugin fornisce, come un ponte a un'app di chat. Quando ne dichiarate uno, Claude Code può chiedere la configurazione del canale quando il plugin è abilitato. Per come il server inietta i messaggi, vedere il riferimento channels.

Ogni voce è un oggetto rigoroso associato a uno dei server MCP del plugin, con questi campi:

Questo manifest associa un canale al server MCP telegram del plugin e chiede un token bot che si sostituisce nell'env del server:

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [
    {
      "server": "telegram",
      "displayName": "Telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        }
      }
    }
  ]
}

Environment variables

Claude Code fornisce tre variabili di percorso ai componenti del plugin. Fate loro riferimento come ${NAME} nei campi elencati sotto Where each variable resolves, e leggetele come variabili di ambiente nei processi che le ricevono.

${CLAUDE_PLUGIN_ROOT} cambia quando il plugin si aggiorna, quindi non scrivete lo stato lì. Per dove si sposta la radice e quando la directory vecchia viene pulita, vedere la pagina di caricamento.

Quando disinstallate il plugin dall'ultimo posto in cui è installato, la directory ${CLAUDE_PLUGIN_DATA} viene eliminata a meno che non passiate --keep-data.

Where each variable resolves

In ogni componente del plugin, i riferimenti ${...} si risolvono inline in campi specifici, e alcuni componenti ricevono anche le variabili nel loro ambiente di processo:

Le variabili non sono presenti nell'ambiente dei comandi che Claude esegue attraverso lo strumento Bash, nella sessione principale o in un subagent. Nel contenuto di skill, comando e agente, scrivete il riferimento ${...} nel corpo Markdown invece, e Claude Code sostituisce il percorso inline quando carica il contenuto.

Quoting and path separators

Mantenete ogni percorso sostituito un singolo argomento:

• Hook commands: usate exec form con args in modo che ogni percorso sia un argomento senza virgolette
• Shell-form hooks and monitor commands: avvolgete la variabile tra virgolette doppie in modo che un percorso con spazi rimanga una parola

Questo hook in forma shell esegue uno script fornito con il plugin:

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

Su Windows, i percorsi sostituiti usano barre in avanti in modo che una shell non legga le barre rovesciate come escape.

Standard layout

Ogni tipo di componente ha una posizione predefinita sotto la radice del plugin, utilizzata quando il manifest non punta altrove.

Un plugin che usa ogni posizione predefinita, più una cartella scripts/ che i suoi hook chiamano, è disposto così:

deploy-tools/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── deploy/
│       └── SKILL.md
├── commands/
│   └── status.md
├── agents/
│   └── reviewer.md
├── hooks/
│   └── hooks.json
├── monitors/
│   └── monitors.json
├── output-styles/
│   └── terse.md
├── themes/
│   └── dracula.json
├── workflows/
│   └── release-audit.js
├── bin/
│   └── deploy-tool
├── scripts/
│   └── format.sh
├── settings.json
├── .mcp.json
└── .lsp.json

Per fare clic attraverso questo layout e leggere cosa fa ogni file, aprite l'esplora plugin.

Un CLAUDE.md alla radice del plugin non viene caricato come contesto, e claude plugin validate avvisa quando ne trova uno. Per includere istruzioni che si caricano nel contesto di Claude, mettetele in una skill.

Marketplace entries and the manifest

Una voce di marketplace accetta ogni campo su questa pagina insieme ai suoi propri campi, incluso strict.

Il campo strict decide se la voce può aggiungere componenti a un plugin che ha il suo plugin.json. Predefinito a true.

How entry fields combine with `plugin.json`

La voce serve come manifest, aggiunge componenti ad esso, o entra in conflitto con esso:

• No plugin.json: la voce è il manifest, indipendentemente da strict. L'hooks della voce si carica solo nella forma di oggetto inline. Per un percorso di file o array lì, la scheda /plugin Errors mostra un errore not yet supported in a marketplace entry
• plugin.json presente, strict non impostato o true: Claude Code carica il manifest e aggiunge i commands, agents, skills, outputStyles e themes della voce ad esso. Per hooks, i matcher della voce per un evento sostituiscono i matcher del manifest per lo stesso evento, e gli eventi che solo il manifest dichiara mantengono i loro
• plugin.json presente, strict: false: una voce che dichiara qualsiasi di commands, agents, skills, hooks, outputStyles o themes è un conflitto, e il plugin non si carica con Plugin <name> has conflicting manifests

Quando una voce di marketplace la cui source è la radice del marketplace elenca sottodirectory skills specifiche, solo quelle sottodirectory si caricano, e la directory predefinita skills/ del plugin non viene scansionata. Una chiave skills nel manifest invece aggiunge al predefinito.

Metadata precedence

Alcuni campi di metadati hanno una precedenza fissa indipendentemente da strict:

• defaultEnabled e campi di visualizzazione: il defaultEnabled della voce e i suoi campi di visualizzazione come displayName sostituiscono quelli del manifest
• version: il version del manifest sostituisce quello della voce
• name: quando la voce elenca il plugin sotto un name diverso da quello del manifest, enabledPlugins usa il nome della voce, e i componenti sono namespacciati sotto il nome del manifest

Per la tabella di precedenza completa, vedere Strict mode.

Next steps

• Add components to a plugin: cosa fa ogni componente al runtime, con un esempio che passa la validazione
• Marketplace reference: i campi della voce che un marketplace può impostare per il vostro plugin
• Plugin commands reference: flag e output di claude plugin validate
• Troubleshoot plugins: ogni messaggio di validazione con la sua correzione