Riferimento dei plugin - Claude Code Docs

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 dei componenti del plugin

Questa sezione documenta i cinque 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 del plugin, modelli di invocazione e funzionalità, vedi Comandi del plugin.

Agenti

I plugin possono fornire subagenti specializzati per attività specifiche 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 dell’agente:

---
description: In cosa si specializza questo agente
capabilities: ["task1", "task2", "task3"]
---

# Nome dell'agente

Descrizione dettagliata del ruolo dell'agente, della sua competenza e di quando Claude dovrebbe invocarlo.

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

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

Punti di integrazione:

Gli agenti appaiono nell’interfaccia /agents
Claude può invocare gli agenti automaticamente in base al contesto dell’attività
Gli agenti possono essere invocati manualmente dagli utenti
Gli agenti del plugin funzionano insieme agli agenti Claude integrati

Competenze

I plugin possono fornire Agent Skills che estendono le capacità di Claude. Le competenze sono invocate dal modello: Claude decide autonomamente quando usarle in base al contesto dell’attività. Posizione: directory skills/ nella radice del plugin Formato file: Directory contenenti file SKILL.md con frontmatter Struttura della competenza:

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

Comportamento di integrazione:

Le competenze del plugin vengono scoperte automaticamente quando il plugin viene installato
Claude invoca autonomamente le competenze in base al contesto dell’attività corrispondente
Le competenze possono includere file di supporto insieme a SKILL.md

Per il formato SKILL.md e la guida completa alla creazione di competenze, vedi:

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 dell’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: Esegui comandi shell o script
validation: Valida il contenuto dei file o lo stato del progetto
notification: Invia avvisi o aggiornamenti di stato

Server MCP

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

Schema del manifest del plugin

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

Schema completo

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "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 univoco (kebab-case, senza spazi)	`"deployment-tools"`

Campi di metadati

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

Campi del percorso del componente

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

Regole del comportamento del percorso

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

Se commands/ esiste, viene caricato in aggiunta ai percorsi dei comandi personalizzati
Tutti i percorsi devono essere relativi alla radice del plugin e iniziare con ./
I comandi dai percorsi personalizzati utilizzano le stesse regole di denominazione e namespacing
È possibile specificare più percorsi come array per flessibilità

Esempi di percorso:

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

Variabili di ambiente

${CLAUDE_PLUGIN_ROOT}: Contiene il percorso assoluto della directory del tuo plugin. Usalo negli hook, nei server MCP e negli script per garantire percorsi corretti indipendentemente dalla posizione di installazione.

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

Struttura della directory del plugin

Layout standard del plugin

Un plugin completo segue questa struttura:

enterprise-plugin/
├── .claude-plugin/           # Directory dei metadati
│   └── plugin.json          # Obbligatorio: manifest del plugin
├── commands/                 # Posizione predefinita del comando
│   ├── status.md
│   └──  logs.md
├── agents/                   # Posizione predefinita dell'agente
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── skills/                   # Agent Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── hooks/                    # Configurazioni degli hook
│   ├── hooks.json           # Configurazione principale dell'hook
│   └── security-hooks.json  # Hook aggiuntivi
├── .mcp.json                # Definizioni del server MCP
├── scripts/                 # Script degli hook e utilità
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # File di licenza
└── CHANGELOG.md             # Cronologia delle versioni

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

Riferimento delle posizioni dei file

Componente	Posizione predefinita	Scopo
Manifest	`.claude-plugin/plugin.json`	File di metadati obbligatorio
Comandi	`commands/`	File Markdown dei comandi slash
Agenti	`agents/`	File Markdown dei subagenti
Competenze	`skills/`	Agent Skills con file SKILL.md
Hook	`hooks/hooks.json`	Configurazione dell’hook
Server MCP	`.mcp.json`	Definizioni del server MCP

Strumenti di debug e sviluppo

Comandi di debug

Usa claude --debug per vedere i dettagli del caricamento del plugin:

claude --debug

Questo mostra:

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

Problemi comuni

Problema	Causa	Soluzione
Plugin non caricato	`plugin.json` non valido	Convalida la sintassi JSON
Comandi non visualizzati	Struttura di directory errata	Assicurati che `commands/` sia nella radice, non in `.claude-plugin/`
Hook non attivati	Script non eseguibile	Esegui `chmod +x script.sh`
Errore del server MCP	`${CLAUDE_PLUGIN_ROOT}` mancante	Usa la variabile per tutti i percorsi del plugin
Errori di percorso	Percorsi assoluti utilizzati	Tutti i percorsi devono essere relativi e iniziare con `./`

Riferimento di distribuzione e versioning

Gestione della versione

Segui il versionamento semantico per i rilasci del plugin:

## Vedi anche

- [Plugin](/it/plugins) - Tutorial e utilizzo pratico
- [Marketplace dei plugin](/it/plugin-marketplaces) - Creazione e gestione dei marketplace
- [Comandi slash](/it/slash-commands) - Dettagli dello sviluppo dei comandi
- [Subagenti](/it/sub-agents) - Configurazione e capacità dell'agente
- [Agent Skills](/it/skills) - Estendi le capacità di Claude
- [Hook](/it/hooks) - Gestione degli eventi e automazione
- [MCP](/it/mcp) - Integrazione degli strumenti esterni
- [Impostazioni](/it/settings) - Opzioni di configurazione per i plugin

Riferimento

​Riferimento dei componenti del plugin

​Comandi

​Agenti

​Competenze

​Hook

​Server MCP

​Schema del manifest del plugin

​Schema completo

​Campi obbligatori

​Campi di metadati

​Campi del percorso del componente

​Regole del comportamento del percorso

​Variabili di ambiente

​Struttura della directory del plugin

​Layout standard del plugin

​Riferimento delle posizioni dei file

​Strumenti di debug e sviluppo

​Comandi di debug

​Problemi comuni

​Riferimento di distribuzione e versioning

​Gestione della versione

Riferimento dei componenti del plugin

Comandi

Agenti

Competenze

Hook

Server MCP

Schema del manifest del plugin

Schema completo

Campi obbligatori

Campi di metadati

Campi del percorso del componente

Regole del comportamento del percorso

Variabili di ambiente

Struttura della directory del plugin

Layout standard del plugin

Riferimento delle posizioni dei file

Strumenti di debug e sviluppo

Comandi di debug

Problemi comuni

Riferimento di distribuzione e versioning

Gestione della versione