Aggiungi componenti a un plugin

​

Esplora la directory dei plugin

• Una skill di revisione e un comando about
• Un subagent di security-review
• Un hook che formatta i file dopo che Claude li modifica, e la cartella scripts/ che chiama
• Un monitor di log
• Uno stile di output e un tema di colore
• Un workflow route-audit
• Un eseguibile hello-plugin
• Impostazioni predefinite
• Un server MCP locale e un language server Go

​

Aggiungi ogni tipo di componente

​

Skills

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

---
description: Reviews a pull request for style and test coverage. Use when asked to review code.
---

Review the changed files. Report style problems first, then missing tests.

• Nome del comando: /<plugin>:<directory>, quindi skills/review/SKILL.md in my-plugin è /my-plugin:review. Se imposti name nel frontmatter, sostituisce l’ultimo segmento e il prefisso del plugin rimane. Vedere come una skill ottiene il suo nome di comando
• Chi la invoca: Claude, l’utente o entrambi, controllato dal frontmatter. Vedere Controlla chi invoca una skill

• Directory aggiuntive: elencale nella chiave manifest skills. Aggiungono alla scansione predefinita skills/ piuttosto che sostituirla, a differenza di commands e agents
• Una singola skill alla radice del plugin: senza directory skills/ e senza chiave manifest skills, un SKILL.md alla radice del plugin carica come una skill. Imposta name nel suo frontmatter, perché altrimenti un’installazione del marketplace nomina la skill dopo la sua directory cache piuttosto che il tuo plugin

​

Comandi

​

Definisci comandi nel manifest

{
  "name": "my-plugin",
  "commands": {
    "about": {
      "content": "Summarize what this repository does in three sentences.",
      "description": "Summarize the repository"
    }
  }
}

​

Agenti

---
name: security-reviewer
description: Reviews code changes for security issues. Use after edits to authentication or input handling.
model: sonnet
---

You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

​

Organizza agenti in sottocartelle

• Frontmatter name: sostituisce solo il nome del file, quindi name: audit in agents/review/security.md carica come my-plugin:review:audit
• Campo manifest agents: un file che elenchi lì carica senza nomi di sottocartella, quindi "agents": "./custom/review/security.md" carica come my-plugin:security

​

Campi frontmatter negli agenti del plugin

• Campi supportati: name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, omitClaudeMd, isolation, color, e la chiave cacheTtl di experimental. L’unico valore isolation valido è "worktree". Vedere campi frontmatter supportati per quello che fa ciascuno
• Campi ignorati: permissionMode, hooks, mcpServers, e initialPrompt. Un file agente non può aggiungere hook o server MCP da solo, quindi aggiungili come plugin hooks e server MCP invece
• Frontmatter che non analizza: l’agente carica comunque con ogni campo ignorato. È denominato dopo il file, e la sua descrizione legge Agent from my-plugin plugin. Esegui claude plugin validate nella shell per trovare questi file

​

Hooks

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

​

Quando gli hook del plugin si attivano

​

Ambiente, quoting e corrispondenza degli strumenti MCP

• Ambiente: ogni processo hook riceve CLAUDE_PLUGIN_ROOT e CLAUDE_PLUGIN_DATA nel suo ambiente, più CLAUDE_PLUGIN_OPTION_<KEY> per ogni valore di configurazione utente, in modo che lo script possa leggerli da lì
• Quoting: quando command non ha args, viene eseguito attraverso una shell, quindi avvolgi il percorso ${CLAUDE_PLUGIN_ROOT} tra virgolette doppie, come fa l’esempio hooks/hooks.json sotto Hooks, per mantenere il percorso espanso una parola shell. Quando passi args invece, ogni elemento viene passato come un argomento senza shell e non ha bisogno di quoting. Vedere exec form e shell form
• Corrispondenza degli strumenti MCP del plugin: uno strumento da un server MCP che questo plugin dichiara è denominato mcp__plugin_<plugin>_<server>__<tool>, quindi scrivi quel nome completo nel matcher. Un matcher sul solo nome del server non si attiva mai. Vedere Match MCP tools

​

Server MCP

{
  "mcpServers": {
    "db": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}

​

Raggiungi gli utenti su claude.ai e Cowork

​

Nomi dei server, nomi degli strumenti e ricaricamenti

• Nome del server: plugin:<plugin>:<server>, quindi il server db in my-plugin è plugin:my-plugin:db in /mcp. Usa la stessa forma per nominare il server in un hook mcp_tool
• Nomi degli strumenti: mcp__plugin_<plugin>_<server>__<tool>, quindi uno strumento query su quel server db è mcp__plugin_my-plugin_db__query. Questo è il nome da usare in regole di permesso e matcher di hook
• Sostituzione: ${CLAUDE_PLUGIN_ROOT} e le altre variabili di percorso vengono sostituite in command, args, e env. Non è necessario quoting in args, perché ogni elemento viene passato come un argomento
• Ricaricamento: quando l’utente esegue /reload-plugins e il ricaricamento si applica, un server la cui configurazione è invariata mantiene la sua connessione. Un server la cui configurazione è cambiata si riconnette, e uno che hai rimosso si disconnette

​

Includi un server MCPB in pacchetto

{
  "name": "my-plugin",
  "mcpServers": "./servers/db.mcpb"
}

​

Server LSP

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

• Binario mancante: Claude Code avvia command per nome dal PATH dell’utente. Quando il binario non è lì, il server non si avvia e claude --debug registra LSP server <name> failed to start
• Conflitti di estensione: quando due server abilitati rivendicano la stessa estensione, il primo registrato gestisce quei file e l’altro non viene utilizzato per loro, che i server provengano da un plugin o da due. La scheda Errors di /plugin mostra l’avviso LSP server "<name>" is not used for <ext> files

​

Eseguibili

#!/bin/bash
echo "hello from my-plugin"

​

Impostazioni predefinite

{
  "agent": "security-reviewer"
}

• File su manifest: quando entrambi esistono e settings.json imposta almeno una chiave supportata, settings.json si applica e il settings del manifest viene ignorato
• Impostazioni utente su valori predefiniti del plugin: tra le fonti di impostazioni, i valori predefiniti del plugin sono il livello più basso, quindi un agent proprio dell’utente in ~/.claude/settings.json sostituisce il tuo
• Due plugin impostano la stessa chiave: il valore dal plugin caricato per ultimo si applica, e claude --debug registra overrides setting

​

Temi e stili di output

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

​

Canali

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

​

Monitor

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

• Solo sessioni interattive: i monitor del plugin si avviano in una sessione interattiva e mai in modalità non interattiva con il flag -p. Si avviano anche solo dove lo strumento Monitor è disponibile
• Nessuna configurazione utente: command ottiene le variabili di percorso e ${ENV_VAR} dall’ambiente, ma mai ${user_config.*}. Un monitor che fa riferimento a uno non si avvia, e i processi monitor non ricevono nemmeno CLAUDE_PLUGIN_OPTION_<KEY>
• Disabilitazione a metà sessione: se disabiliti un plugin a metà sessione, Claude Code non ferma i monitor che sono già in esecuzione. Si fermano quando la sessione finisce

​

Chiedi all’utente i valori di configurazione

{
  "name": "my-plugin",
  "userConfig": {
    "api_url": {
      "type": "string",
      "title": "API URL",
      "description": "Base URL of your team's API"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for your team's API",
      "sensitive": true
    }
  }
}

​

Quando appare la finestra di dialogo di configurazione

• Installa il plugin in /plugin
• Esegui /plugin install <plugin>@<marketplace> all’interno di una sessione
• Abilita il plugin dalla scheda Installed in /plugin

​

Fai riferimento ai percorsi del plugin e archivia i dati

• ${CLAUDE_PLUGIN_ROOT}: la directory di installazione del plugin. Ogni versione ha la sua directory cache, quindi il percorso cambia quando il plugin si aggiorna. Non scrivere stato lì
• ${CLAUDE_PLUGIN_DATA}: una directory che sopravvive agli aggiornamenti, per node_modules, ambienti virtuali e cache. Si risolve in ~/.claude/plugins/data/<id>/ e viene creata quando viene referenziata per la prima volta
• ${CLAUDE_PROJECT_DIR}: la radice del progetto, lo stesso valore che gli hook ricevono

​

Installa le dipendenze nella directory dei dati

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

​

Passaggi successivi

• Riferimento manifest del plugin: campi plugin.json, regole di percorso e layout standard
• Testa i plugin con evals: controlla che i componenti che hai aggiunto cambino il comportamento di Claude nel modo che intendi
• Pubblica e distribuisci un plugin: versiona il plugin e mettilo in un marketplace
• Risolvi i problemi dei plugin: cosa fare quando un componente non carica o un hook non si attiva