SpyBara
Go Premium

plugins/manifest-reference.md 2026-09-24 22:57 UTC to 2026-09-25 23:58 UTC

This page contains 710 additions and 0 deletions.

2026
Fri 25 23:58

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.

Field Type Description
$schema String URL dello schema JSON per l'autocompletamento dell'editor. Claude Code lo ignora al momento del caricamento
name String Identificatore del plugin, obbligatorio. Usate kebab-case. Ogni componente è namespacato sotto di esso
displayName String Nome mostrato nell'interfaccia utente al posto di name
version String Stringa di versione. Impostarla mantiene gli utenti su quella versione finché non la cambiate
description String Breve spiegazione di cosa fornisce il plugin
author Object name, che è obbligatorio, più email e url opzionali
homepage String URL della documentazione. Deve essere analizzabile come URL, altrimenti il plugin non si carica
repository String URL del repository di origine. Non convalidato
license String Identificatore SPDX come MIT o Apache-2.0
keywords Array of strings Tag di scoperta
metadata Object Oggetto in forma libera per i vostri dati. Claude Code non lo legge
defaultEnabled Boolean Se il plugin inizia abilitato quando l'utente non lo ha impostato. Predefinito a true
dependencies Array of strings or objects Plugin che devono essere abilitati affinché questo funzioni
settings Object Impostazioni che Claude Code applica mentre il plugin è abilitato. Solo agent e subagentStatusLine hanno effetto
userConfig Object Valori che Claude Code richiede all'utente quando il plugin è abilitato
channels Array of objects Canali di messaggi che il plugin fornisce, ciascuno associato a uno dei suoi server MCP
skills Path, or array of paths Directory da scansionare per skills, ciascuna una directory di cartelle <name>/SKILL.md o una cartella che contiene SKILL.md direttamente. "." nomina la radice del plugin. Aggiunge alla scansione predefinita skills/
commands Path, array of paths, or object File di comando .md piatti, directory di essi, o una mappa di oggetti del nome del comando a source o content. Sostituisce la scansione predefinita commands/
agents Path, or array of paths File di agente .md. Le directory non sono accettate. Sostituisce la scansione predefinita agents/
hooks Path, object, or array of either File hook .json o configurazione hook inline. Caricati insieme a hooks/hooks.json
mcpServers Path, object, or array of either File di configurazione MCP .json, bundle .mcpb o .dxt, o configurazioni di server inline con chiave per nome. Caricati insieme a .mcp.json; un nome di server dichiarato successivamente sostituisce uno precedente
lspServers Path, object, or array of either File di configurazione LSP .json o configurazioni di server inline con chiave per nome. Caricati insieme a .lsp.json
outputStyles Path, or array of paths File di stile di output o directory. Sostituisce la scansione predefinita output-styles/
workflows Path, or array of paths File Workflow .js o directory. Sostituisce la scansione predefinita workflows/
experimental Object Contenitore per themes, monitors e evals, la cui forma di manifest potrebbe ancora cambiare
experimental.themes Path, or array of paths File di tema o directory. Sostituisce la scansione predefinita themes/. Una chiave themes di primo livello si carica ancora, con un avviso claude plugin validate
experimental.monitors Path, or inline array Un file .json che contiene l'array monitors, o l'array stesso. Predefinito a monitors/monitors.json. Una chiave monitors di primo livello si carica ancora, con un avviso claude plugin validate. I monitor vengono eseguiti solo in sessioni interattive, e non su Amazon Bedrock, Google Cloud's Agent Platform, o Microsoft Foundry
experimental.evals Path, or array of paths Directory che contiene i casi di eval del plugin quando non è la directory predefinita evals/. claude plugin eval --eval-dir la sostituisce

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:

Field Type Description
source string Percorso al file Markdown del comando, relativo alla radice del plugin
content string Markdown inline per il corpo del comando, invece di source
description string Descrizione mostrata per il comando
argumentHint string Suggerimento di argomento mostrato dopo il nome del comando, come [file]
model string Modello predefinito per il comando
allowedTools array of strings Strumenti che il comando può utilizzare senza chiedere

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:

Shape Example value What Claude Code does
.json file path "./mcp/servers.json" Legge il file come una mappa mcpServers
MCP bundle path "./bundle.mcpb" Estrae il bundle .mcpb o .dxt in .mcpb-cache/ sotto la radice del plugin e legge la sua configurazione del server
MCP bundle URL "https://example.com/server.mcpb" Scarica il bundle in .mcpb-cache/, poi lo legge
Inline map { "deploy-api": { "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"] } } Usa la mappa come configurazioni del server con chiave per nome

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.

Field Required Description
command Yes Binario del language server. Nessuno spazio a meno che il valore non inizi con /; mettete gli argomenti in args
extensionToLanguage Yes Mappa dell'estensione di file all'ID di linguaggio LSP, almeno una voce. Le chiavi iniziano con un punto, come ".go"
args No Argomenti passati al server
transport No Trasporto di comunicazione: stdio (predefinito) o socket. Claude Code accetta socket ma esegue ogni server su stdio, quindi le regole del protocollo stdout si applicano a tutti i server
env No Variabili di ambiente per il processo del server
initializationOptions No Opzioni inviate nella richiesta di inizializzazione
settings No Impostazioni inviate da workspace/didChangeConfiguration
workspaceFolder No Percorso della cartella di lavoro per il server
startupTimeout No Millisecondi da attendere per l'avvio, un intero positivo
shutdownTimeout No Millisecondi da attendere per un arresto elegante, un intero positivo. Quando il timeout scade, Claude Code termina il processo del server. Quando non impostato, non si applica alcun timeout
restartOnCrash No Se riavviare il server dopo che si arresta in modo anomalo. Predefinito a true. Impostate a false per lasciare un server arrestato in modo anomalo fermo invece di riavviarlo
maxRestarts No Tentativi di riavvio prima di rinunciare, zero o più
diagnostics No Se spingere la diagnostica nel contesto dopo le modifiche. Predefinito a true

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.

Field Required Description
name Yes Identificatore unico all'interno del plugin
command Yes Comando shell che Claude Code esegue come processo di background persistente nella directory di lavoro della sessione
description Yes Breve riepilogo mostrato nel pannello dei task e nei riepiloghi delle notifiche
when No Con "always", il predefinito, il monitor inizia all'avvio della sessione e al ricaricamento del plugin. Con "on-skill-invoke:<skill>", inizia la prima volta che quella skill viene eseguita

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.

Campo Obbligatorio Descrizione
type Sì Uno di string, number, boolean, directory, o file
title Sì Etichetta mostrata nella finestra di dialogo di configurazione
description Sì Testo di aiuto mostrato sotto il campo
required No Se true, la finestra di dialogo di configurazione non accetta un valore vuoto
default No Valore utilizzato quando l'utente non fornisce nulla: una stringa, un numero, un booleano, o un array di stringhe
options No Per string, i valori che il campo accetta, mostrati come un selettore in /config. Vedi Limitare un campo a opzioni fisse. Richiede Claude Code v2.1.271 o successivo
multiple No Per string, consente un array di stringhe
sensitive No Se true, maschera l'input e memorizza il valore nell'archiviazione sicura invece di settings.json
min / max No Limiti per number

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.

Campo Come il valore può raggiungerlo
Comandi hook in forma shell Utilizzare la forma exec con args, oppure leggere CLAUDE_PLUGIN_OPTION_<KEY> dall'ambiente dell'hook
Comandi di monitoraggio Non attraverso Claude Code. I processi di monitoraggio non ricevono CLAUDE_PLUGIN_OPTION_<KEY>, quindi lo script di monitoraggio deve ottenere il valore autonomamente
MCP headersHelper Non attraverso Claude Code. L'ambiente dell'helper contiene CLAUDE_PLUGIN_ROOT, CLAUDE_CODE_MCP_SERVER_NAME, e CLAUDE_CODE_MCP_SERVER_URL ma nessun valore di opzione, quindi lo script helper deve ottenere il valore autonomamente

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:

Field Required Description
server Yes Chiave del server MCP nel mcpServers di questo plugin a cui il canale si associa
displayName No Nome mostrato nel titolo della finestra di dialogo di configurazione. Predefinito al nome del server
userConfig No Opzioni da chiedere, nella stessa forma di userConfig di primo livello. I valori salvati si sostituiscono nei riferimenti ${user_config.KEY} nell'env del server

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.

Variable Resolves to Use it for
${CLAUDE_PLUGIN_ROOT} Percorso assoluto della versione installata del plugin Script, binari e file di configurazione forniti con il plugin
${CLAUDE_PLUGIN_DATA} ~/.claude/plugins/data/<id>/, creato al primo riferimento e mantenuto attraverso gli aggiornamenti del plugin. <id> è l'identificatore del plugin con ogni carattere diverso da una lettera, cifra, _, o - sostituito da - Dipendenze installate come node_modules, codice generato e cache
${CLAUDE_PROJECT_DIR} La radice del progetto Script e file di configurazione locali del progetto

${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:

Plugin component Fields where ${...} resolves Exported to the process
Hook commands Ovunque in command e args CLAUDE_PLUGIN_ROOT, CLAUDE_PLUGIN_DATA, CLAUDE_PROJECT_DIR e CLAUDE_PLUGIN_OPTION_<KEY>
Monitor commands Ovunque in command Non esportato
MCP stdio servers command, args, env CLAUDE_PLUGIN_ROOT, CLAUDE_PLUGIN_DATA
MCP http, sse, ws servers url, headers, headersHelper Non applicabile
LSP servers command, args, env, workspaceFolder CLAUDE_PLUGIN_ROOT, CLAUDE_PLUGIN_DATA, CLAUDE_PROJECT_DIR
Skill, command, and agent content Ovunque nel corpo Markdown Non applicabile

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.

Component Default location Contents
Manifest .claude-plugin/plugin.json Metadati e configurazione del plugin. Facoltativo
Skills skills/ Un <name>/SKILL.md per skill. Un plugin con SKILL.md alla sua radice, nessun skills/, e nessuna chiave skills si carica come una singola skill
Commands commands/ File di comando Markdown piatti. Preferite skills/ per i nuovi plugin
Agents agents/ File Markdown di agente. Le sottocartelle fanno parte del nome dell'agente
Hooks hooks/hooks.json Configurazione hook
MCP servers .mcp.json Definizioni del server MCP
LSP servers .lsp.json Configurazioni del server LSP
Output styles output-styles/ File di stile di output Markdown
Workflows workflows/ File Workflow .js
Themes themes/ File tema JSON
Monitors monitors/monitors.json L'array monitors
Executables bin/ I file qui sono sul PATH dello strumento Bash mentre il plugin è abilitato, quindi Claude li esegue come comandi nudi. claude.ai e Cowork non installano un plugin che ha questa directory, incluso uno che distribuite attraverso le impostazioni dell'organizzazione claude.ai
Settings settings.json Impostazioni predefinite agent e subagentStatusLine applicate mentre il plugin è abilitato

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