Riferimento plugin

Per tutorial pratici e utilizzo pratico, vedi Plugin. Per la gestione dei plugin tra team e comunità, vedi Marketplace dei plugin.

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

Riferimento componenti plugin

Questa sezione documenta i quattro tipi di componenti che i plugin possono fornire.

Comandi

I plugin aggiungono comandi slash personalizzati che si integrano perfettamente con il sistema di comandi di Claude Code. Posizione: directory commands/ nella radice del plugin Formato file: File Markdown con frontmatter Per dettagli completi sulla struttura dei comandi plugin, pattern di invocazione e funzionalità, vedi Comandi plugin.

Agenti

I plugin possono fornire subagenti specializzati per compiti specifici che Claude può invocare automaticamente quando appropriato. Posizione: directory agents/ nella radice del plugin Formato file: File Markdown che descrivono le capacità dell’agente Struttura agente:

---
description: In cosa si specializza questo agente
capabilities: ["compito1", "compito2", "compito3"]
---

# Nome Agente

Descrizione dettagliata del ruolo dell'agente, competenze e quando Claude dovrebbe invocarlo.

## Capacità
- Compito specifico in cui l'agente eccelle
- Un'altra capacità specializzata
- Quando usare questo agente rispetto ad altri

## Contesto ed esempi
Fornire esempi di quando questo agente dovrebbe essere usato e che tipi di problemi risolve.

Punti di integrazione:

Gli agenti appaiono nell’interfaccia /agents
Claude può invocare agenti automaticamente basandosi sul contesto del compito
Gli agenti possono essere invocati manualmente dagli utenti
Gli agenti plugin lavorano insieme agli agenti integrati di Claude

Hook

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 hook:

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

Eventi disponibili:

PreToolUse: Prima che Claude usi qualsiasi strumento
PostToolUse: Dopo che Claude usa qualsiasi strumento
UserPromptSubmit: Quando l’utente invia un prompt
Notification: Quando Claude Code invia notifiche
Stop: Quando Claude tenta di fermarsi
SubagentStop: Quando un subagente tenta di fermarsi
SessionStart: All’inizio delle sessioni
SessionEnd: Alla fine delle sessioni
PreCompact: Prima che la cronologia della conversazione venga compattata

Tipi di hook:

command: Esegue comandi shell o script
validation: Valida contenuti di file o stato del progetto
notification: Invia avvisi o aggiornamenti di stato

Server MCP

I plugin possono includere 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 server MCP standard Configurazione 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 di 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 plugin possono essere configurati indipendentemente dai server MCP dell’utente

Schema manifest plugin

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

Schema completo

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Breve descrizione del plugin",
  "author": {
    "name": "Nome Autore",
    "email": "[email protected]",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "commands": ["./custom/commands/special.md"],
  "agents": "./custom/agents/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json"
}

Campi obbligatori

Campo	Tipo	Descrizione	Esempio
`name`	string	Identificatore unico (kebab-case, senza spazi)	`"deployment-tools"`

Campi metadati

Campo	Tipo	Descrizione	Esempio
`version`	string	Versione semantica	`"2.1.0"`
`description`	string	Breve spiegazione dello scopo del plugin	`"Strumenti di automazione deployment"`
`author`	object	Informazioni autore	`{"name": "Dev Team", "email": "[email protected]"}`
`homepage`	string	URL documentazione	`"https://docs.example.com"`
`repository`	string	URL codice sorgente	`"https://github.com/user/plugin"`
`license`	string	Identificatore licenza	`"MIT"`, `"Apache-2.0"`
`keywords`	array	Tag di scoperta	`["deployment", "ci-cd"]`

Campi percorso componenti

Campo	Tipo	Descrizione	Esempio
`commands`	string\|array	File/directory comandi aggiuntivi	`"./custom/cmd.md"` o `["./cmd1.md"]`
`agents`	string\|array	File agenti aggiuntivi	`"./custom/agents/"`
`hooks`	string\|object	Percorso config hook o config inline	`"./hooks.json"`
`mcpServers`	string\|object	Percorso config MCP o config inline	`"./mcp.json"`

Regole comportamento percorsi

Importante: I percorsi personalizzati integrano le directory predefinite - non le sostituiscono.

Se commands/ esiste, viene caricata in aggiunta ai percorsi comandi personalizzati
Tutti i percorsi devono essere relativi alla radice del plugin e iniziare con ./
I comandi da percorsi personalizzati usano le stesse regole di denominazione e namespace
Percorsi multipli possono essere specificati come array per flessibilità

Esempi percorsi:

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

Variabili ambiente

${CLAUDE_PLUGIN_ROOT}: Contiene il percorso assoluto alla directory del tuo plugin. Usa questo negli hook, server MCP e script per assicurare percorsi corretti indipendentemente dalla posizione di installazione.

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

Struttura directory plugin

Layout plugin standard

Un plugin completo segue questa struttura:

enterprise-plugin/
├── .claude-plugin/           # Directory metadati
│   └── plugin.json          # Obbligatorio: manifest plugin
├── commands/                 # Posizione comandi predefinita
│   ├── status.md
│   └──  logs.md
├── agents/                   # Posizione agenti predefinita
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── hooks/                    # Configurazioni hook
│   ├── hooks.json           # Config hook principale
│   └── security-hooks.json  # Hook aggiuntivi
├── .mcp.json                # Definizioni server MCP
├── scripts/                 # Script hook e utility
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # File licenza
└── CHANGELOG.md             # Cronologia versioni

La directory .claude-plugin/ contiene il file plugin.json. Tutte le altre directory (commands/, agents/, hooks/) devono essere nella radice del plugin, non dentro .claude-plugin/.

Riferimento posizioni file

Componente	Posizione Predefinita	Scopo
Manifest	`.claude-plugin/plugin.json`	File metadati obbligatorio
Comandi	`commands/`	File markdown comandi slash
Agenti	`agents/`	File markdown subagenti
Hook	`hooks/hooks.json`	Configurazione hook
Server MCP	`.mcp.json`	Definizioni server MCP

Strumenti debugging e sviluppo

Comandi debugging

Usa claude --debug per vedere dettagli caricamento plugin:

claude --debug

Questo mostra:

Quali plugin vengono caricati
Eventuali errori nei manifest plugin
Registrazione comandi, agenti e hook
Inizializzazione server MCP

Problemi comuni

Problema	Causa	Soluzione
Plugin non si carica	`plugin.json` non valido	Valida sintassi JSON
Comandi non appaiono	Struttura directory sbagliata	Assicurati `commands/` nella radice, non in `.claude-plugin/`
Hook non si attivano	Script non eseguibile	Esegui `chmod +x script.sh`
Server MCP fallisce	`${CLAUDE_PLUGIN_ROOT}` mancante	Usa variabile per tutti i percorsi plugin
Errori percorso	Percorsi assoluti usati	Tutti i percorsi devono essere relativi e iniziare con `./`

Riferimento distribuzione e versioning

Gestione versioni

Segui il versioning semantico per i rilasci plugin:


## Vedi anche

- [Plugin](/it/docs/claude-code/plugins) - Tutorial e utilizzo pratico
- [Marketplace plugin](/it/docs/claude-code/plugin-marketplaces) - Creazione e gestione marketplace
- [Comandi slash](/it/docs/claude-code/slash-commands) - Dettagli sviluppo comandi
- [Subagenti](/it/docs/claude-code/sub-agents) - Configurazione e capacità agenti
- [Hook](/it/docs/claude-code/hooks) - Gestione eventi e automazione
- [MCP](/it/docs/claude-code/mcp) - Integrazione strumenti esterni
- [Impostazioni](/it/docs/claude-code/settings) - Opzioni configurazione per plugin

Iniziare

Sviluppa con Claude Code

Claude Code SDK

Distribuzione

Amministrazione

Configurazione

Riferimento

Risorse

Riferimento componenti plugin

Comandi

Agenti

Hook

Server MCP

Schema manifest plugin

Schema completo

Campi obbligatori

Campi metadati

Campi percorso componenti

Regole comportamento percorsi

Variabili ambiente

Struttura directory plugin

Layout plugin standard

Riferimento posizioni file

Strumenti debugging e sviluppo

Comandi debugging

Problemi comuni

Riferimento distribuzione e versioning

Gestione versioni

Iniziare

Sviluppa con Claude Code

Claude Code SDK

Distribuzione

Amministrazione

Configurazione

Riferimento

Risorse

​Riferimento componenti plugin

​Comandi

​Agenti

​Hook

​Server MCP

​Schema manifest plugin

​Schema completo

​Campi obbligatori

​Campi metadati

​Campi percorso componenti

​Regole comportamento percorsi

​Variabili ambiente

​Struttura directory plugin

​Layout plugin standard

​Riferimento posizioni file

​Strumenti debugging e sviluppo

​Comandi debugging

​Problemi comuni

​Riferimento distribuzione e versioning

​Gestione versioni

Riferimento componenti plugin

Comandi

Agenti

Hook

Server MCP

Schema manifest plugin

Schema completo

Campi obbligatori

Campi metadati

Campi percorso componenti

Regole comportamento percorsi

Variabili ambiente

Struttura directory plugin

Layout plugin standard

Riferimento posizioni file

Strumenti debugging e sviluppo

Comandi debugging

Problemi comuni

Riferimento distribuzione e versioning

Gestione versioni