Plugins reference

​

Riferimento dei componenti del plugin

​

Skills

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

​

Agents

---
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.

• Nessun name: Claude Code nomina l’agent in base al file, quindi agents/reviewer.md in un plugin denominato my-plugin viene caricato come my-plugin:reviewer
• Frontmatter che non viene analizzato: Claude Code nomina l’agent in base al file, utilizza Agent from my-plugin plugin come sua descrizione e ignora ogni campo nel file

• Un plugin con un manifest: claude plugin validate ./my-plugin
• Un plugin senza un manifest: claude plugin validate ./my-plugin/agents. Richiede Claude Code v2.1.233 o successivo.

​

Hooks

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

• command: eseguire comandi shell o script
• http: inviare l’evento JSON come richiesta POST a un URL
• mcp_tool: chiamare uno strumento su un server MCP configurato
• prompt: valutare un prompt con un LLM (utilizza il placeholder $ARGUMENTS per il contesto)
• agent: eseguire un verificatore agentico con strumenti per compiti di verifica complessi

​

MCP servers

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

• I server MCP del plugin si avviano automaticamente quando il plugin è abilitato
• I server vengono visualizzati come strumenti MCP standard nel toolkit di Claude
• I server del plugin possono essere configurati indipendentemente dai server MCP dell’utente
• Se esegui /reload-plugins a metà sessione, Claude Code mantiene le connessioni live dei server la cui configurazione è invariata

​

LSP servers

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

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

​

Monitors

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

​

Themes

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

​

Ambiti di installazione dei plugin

​

Plugin della directory skills

​

Scegli da dove il plugin viene caricato

• I server MCP che dichiara passano attraverso la stessa approvazione per server di un .mcp.json del progetto
• I server LSP si avviano solo dopo che hai fiducia nell’area di lavoro
• I monitor in background non vengono caricati

​

Modifica, ricarica e disabilita un plugin della directory skills

claude plugin disable my-tool@skills-dir

​

Plugin sincronizzati da claude.ai

• Disabilitarne uno: nella sessione sincronizzata, eseguite claude plugin disable <name>@synced, oppure chiedete a Claude di eseguirlo. Claude Code salva la scelta come "<name>@synced": false nel enabledPlugins a livello di utente di quell’ambiente. Per riabilitare il plugin, eseguite claude plugin enable <name>@synced nella stessa sessione. Per escludere un plugin da ogni sessione sincronizzata, disabilitatelo per il vostro account claude.ai. Per escluderlo dalle sessioni sincronizzate di un progetto in ogni ambiente, impostate "<name>@synced": false sotto enabledPlugins nel .claude/settings.json committato del progetto.
• Gestite il plugin stesso su claude.ai: claude plugin install, update e uninstall non si applicano a un plugin sincronizzato. Per rimuoverne uno, disabilitate il plugin per il vostro account claude.ai; la prossima sessione sincronizzata inizierà senza di esso.

​

Schema del manifest del plugin

​

Schema completo

{
  "name": "plugin-name",
  "displayName": "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"],
  "metadata": { "catalogId": "cat-123", "tier": "pro" },
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json",
    "evals": "quality/evals"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

​

Campi obbligatori

​

Campi non riconosciuti

• La maggior parte dei campi: il plugin non si carica. Ad esempio, un valore keywords che è una stringa invece di un array è un errore di caricamento, e claude plugin validate lo segnala come tale.
• experimental e metadata: Claude Code ignora un valore non-oggetto, e claude plugin validate segnala un avviso.

claude plugin validate ./my-plugin --strict

​

Campi di metadati

​

Abilitazione predefinita

• L’impostazione dell’utente: una voce per il plugin in enabledPlugins in qualsiasi ambito di impostazioni. Una volta scritta, persiste tra gli aggiornamenti e le reinstallazioni del plugin, quindi modificare defaultEnabled in una versione successiva non capovolge un utente esistente.
• Un requisito di dipendenza: quando un plugin è richiesto da un altro che è attivo, Claude Code scrive true per esso al momento dell’installazione o dell’abilitazione. Questo gli dà un’impostazione esplicita, quindi il suo valore predefinito non si applica più. Vedere Abilitare o disabilitare un plugin con dipendenze.

​

Campi del percorso del componente

​

Componenti sperimentali

​

Configurazione utente

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

• Impostazioni utente: ~/.claude/settings.json, il file in cui la richiesta al momento dell’abilitazione scrive
• --settings: il flag CLI o le impostazioni inline SDK
• Impostazioni gestite: politica controllata dall’organizzazione

​

Canali

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

​

Regole di comportamento del percorso

• Sostituisce il valore predefinito: commands, agents, workflows, outputStyles, experimental.themes, experimental.monitors. Ad esempio, quando il manifest specifica 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 predefinita skills/ viene sempre scansionata, e le directory elencate in skills vengono caricate insieme ad essa. Eccezione: per una voce del marketplace la cui source si risolve nella radice del marketplace, dichiarare sottodirectory specifiche sostituisce la scansione predefinita skills/
• Regole di merge proprie: hooks, server MCP, e server LSP. Vedere ogni sezione per come più fonti si combinano

• Tutti i percorsi devono essere relativi alla radice del plugin e iniziare con ./, tranne che il campo skills accetta anche "."
  • Sia "." che "./" denotano la radice del plugin stesso
  • Prima della v2.1.221, "." falliva la convalida del manifest e il plugin non si caricava, quindi utilizzare "./" per supportare versioni precedenti
• I componenti da percorsi personalizzati utilizzano le stesse regole di denominazione e spazio dei nomi
• Più percorsi possono essere specificati come array
• Un percorso di skill può puntare a una directory che contiene direttamente un SKILL.md, ad esempio "skills": ["."] per la radice del plugin
  • Claude Code prende il nome di invocazione della skill dal campo frontmatter name in SKILL.md, quindi il nome rimane stabile indipendentemente da come viene denominata la directory di installazione
  • Se name non è impostato nel frontmatter, Claude Code ritorna al nome della directory di base

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

​

Variabili di ambiente

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

​

Directory di dati persistenti

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

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

​

Caching dei plugin e risoluzione dei file

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

​

Dipendenze dei pacchetti Node.js

• Risoluzione congelata: Bun e npm installano esattamente ciò che il lockfile fissa, e falliscono piuttosto che ri-risolvere le versioni quando package.json e il lockfile non concordano.
• Nessuno script del ciclo di vita: --ignore-scripts impedisce l’esecuzione degli script preinstall, install e postinstall, in modo che le dipendenze che compilano moduli nativi in questi script scarichino ma non compilino durante questa installazione.
• Timeout di 60 secondi: Claude Code interrompe un’installazione che dura più a lungo e la tratta come non riuscita.

​

Limitazioni dell’attraversamento dei percorsi

​

Condividere file all’interno di un marketplace con symlink

• All’interno della directory del plugin: il symlink viene preservato come symlink relativo nella cache, in modo che continui a risolvere il target copiato in fase di esecuzione.
• Altrove all’interno dello stesso marketplace: il symlink viene dereferenziato. Il contenuto del target viene copiato nella cache al suo posto. Ciò consente alla directory skills/ di un meta-plugin di collegarsi alle skill definite da altri plugin nel marketplace.
• Al di fuori del marketplace: il symlink viene saltato per motivi di sicurezza. Ciò impedisce ai plugin di estrarre file host arbitrari come percorsi di sistema nella cache.

ln -s ../../shared-plugin/skills/foo ./skills/foo

​

Struttura della directory dei plugin

​

Layout standard dei plugin

enterprise-plugin/
├── .claude-plugin/           # Directory dei metadati (opzionale)
│   └── plugin.json             # plugin manifest
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills come file .md flat
│   ├── status.md
│   └── logs.md
├── agents/                   # Definizioni dei subagent
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── workflows/                # Script dei workflow
│   └── release-audit.js
├── output-styles/            # Definizioni dello stile di output
│   └── terse.md
├── themes/                   # Definizioni dei temi 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 in Bash tool
├── settings.json            # Impostazioni predefinite per il plugin
├── .mcp.json                # Definizioni dei server MCP
├── .lsp.json                # Configurazioni dei server LSP
├── scripts/                 # Script degli hook e script di utilità
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # File di licenza
└── CHANGELOG.md             # Cronologia delle versioni

​

Riferimento delle posizioni dei file

​

Riferimento dei comandi CLI

​

plugin init

claude plugin init <name> [options]

• <name>: Nome del plugin. Diventa lo spazio dei nomi della skill e il nome della directory sotto ~/.claude/skills/, quindi non può contenere spazi o separatori di percorso.

# Crea lo scaffolding di un plugin minimo
claude plugin init my-helper

# Crea lo scaffolding con cartelle skill e hook
claude plugin init my-helper --with skills hooks

# Sovrascrivi uno scaffolding esistente
claude plugin init my-helper --force

​

plugin install

claude plugin install <plugin> [options]

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

• command: il sottocomando che è stato eseguito, come install
• outcome: ok o failed
• message: una descrizione leggibile del risultato

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

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

# Installa nell'ambito locale (non condiviso con il team)
claude plugin install formatter@my-marketplace --scope local

​

plugin uninstall

claude plugin uninstall <plugin> [options]

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

​

plugin prune

claude plugin prune [options]

​

plugin enable

claude plugin enable <plugin> [options]

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

​

plugin disable

claude plugin disable [plugin] [options]

• [plugin]: Nome del plugin o plugin-name@marketplace-name. Facoltativo quando si usa --all

​

plugin update

claude plugin update <plugin> [options]

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

​

plugin list

claude plugin list [options]

• I plugin caricati dalle directory delle skill appaiono nell’interfaccia /plugin e in claude plugin list, ma non nell’output inline /plugin list.
• Su Claude Code v2.1.239 o successivo, i plugin sincronizzati da claude.ai appaiono in claude plugin list quando lo esegui nell’ambiente in cui una sessione sincronizzata li ha scaricati. Non appaiono nell’output inline /plugin list.
• I plugin caricati per la sessione con --plugin-dir o --plugin-url appaiono nell’interfaccia /plugin e in claude plugin list solo quando lo stesso flag precede il sottocomando, come in claude --plugin-dir <dir> plugin list. Solo il nome del flag identifica la loro posizione, quindi un semplice claude plugin list non può trovarli, a differenza dei plugin sincronizzati e dei plugin della directory delle skill, le cui directory fisse Claude Code scansiona.

​

plugin details

claude plugin details <name>

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

• Always-on: token aggiunti a ogni sessione dal testo dell’elenco del plugin, come descrizioni delle skill, descrizioni degli agent e nomi dei comandi, indipendentemente dal fatto che un componente si attivi.
• On-invoke: token che un componente costa quando si attiva. Mostrato per componente, non come totale del plugin, perché una sessione tipica invoca solo un sottoinsieme di componenti.

dependency-guard 1.2.0
  Dependency analysis for Claude Code sessions
  Source: dependency-guard@example-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  SessionStart  (harness-only — no model context cost)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~180 tok   added to every session

Per-component (rounded)
  component            always-on  on-invoke
  scan-dependencies        ~100      ~2400
  review-changes            ~80      ~1800

  On-invoke cost is paid each time a skill or agent fires.
  Token counts are estimates and may differ from actual usage.

​

plugin validate

claude plugin validate <path> [options]

• <path>: Percorso a una directory di plugin o una directory di marketplace. Vedi Validate a plugin or a directory without a manifest per quali file una esecuzione di plugin copre.

• success: lo stesso verdetto che il codice di uscita fornisce
• strict: se l’esecuzione ha trattato gli avvisi come errori
• target: il percorso risolto che Claude Code ha convalidato
• manifest: il risultato del manifest stesso, o null per un’esecuzione senza manifest
• contents: risultati per file, ognuno nominando il suo file e portando array errors, warnings e notes

​

plugin eval

claude plugin eval [target] [options]

​

plugin eval init

claude plugin eval init [name] [options]

​

plugin tag

claude plugin tag [path] [options]

• [path]: Percorso alla directory del plugin. Predefinito è la directory corrente.

​

Strumenti di debug e sviluppo

​

Comandi di debug

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

​

Problemi comuni

​

Messaggi di errore di esempio

• Invalid JSON syntax: Unexpected token } in JSON at position 142: controllare la presenza di virgole mancanti, virgole extra o stringhe non quotate
• Plugin <name> has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Invalid input: expected string, received undefined: un campo obbligatorio è mancante
• Plugin <name> has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: errore di sintassi JSON. Prima della versione 2.1.246, Claude Code produceva anche questo errore per un plugin.json salvato come UTF-8 con un byte order mark (BOM) iniziale, anche quando il JSON era altrimenti valido.

• 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.: rimuovere le definizioni di componenti duplicate o rimuovere strict: false nella voce del marketplace

​

Risoluzione dei problemi degli hook

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

1. Verificare che il nome dell’evento sia corretto (sensibile alle maiuscole): PostToolUse, non postToolUse
2. Verificare che il pattern del matcher corrisponda ai vostri strumenti: "matcher": "Write|Edit" per le operazioni su file
3. Confermare che il tipo di hook sia valido: command, http, mcp_tool, prompt o agent

​

Risoluzione dei problemi del server MCP

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

1. Assicurarsi che il server sia configurato correttamente in .mcp.json o plugin.json
2. Verificare che il server implementi correttamente il protocollo MCP
3. Controllare i timeout di connessione nell’output di debug

​

Errori di struttura della directory

1. Eseguire claude --debug e cercare i messaggi “loading plugin”
2. Verificare che ogni directory di componenti sia elencata nell’output di debug
3. Verificare che i permessi dei file consentano la lettura dei file del plugin

​

Riferimento di distribuzione e versioning

​

Gestione delle versioni

1. Il campo version nel plugin.json del plugin
2. Il campo version nella voce del plugin nel marketplace in marketplace.json
3. Lo SHA del commit git della sorgente del plugin, per le sorgenti github, url, git-subdir e relative-path in un marketplace ospitato su git
4. Il digest SHA-256, per le sorgenti archive: il pin sha256 nella voce del marketplace, o il digest del file scaricato quando non imposti alcun pin. Claude Code lo accorcia ai primi 12 caratteri
5. unknown, per le sorgenti npm o le directory locali non all’interno di un repository git

​

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