Riferimento dei plugin

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

Riferimento dei componenti del plugin

​

Skills

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

• Le skills e i comandi vengono rilevati automaticamente quando il plugin viene installato
• Claude può invocarli automaticamente in base al contesto dell’attività
• Le skills possono includere file di supporto insieme a 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.

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

​

Hooks

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

• command: esegui comandi shell o script
• http: invia l’evento JSON come richiesta POST a un URL
• mcp_tool: chiama uno strumento su un server MCP configurato
• prompt: valuta un prompt con un LLM (usa il placeholder $ARGUMENTS per il contesto)
• agent: esegui un verificatore agentico con strumenti per attività di verifica complesse

​

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"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

• 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

​

LSP servers

• Diagnostica istantanea: Claude vede errori e avvisi immediatamente dopo ogni modifica
• Navigazione del codice: vai alla definizione, trova riferimenti e informazioni al passaggio del mouse
• Consapevolezza del linguaggio: informazioni sul tipo e documentazione per i simboli del codice

{
  "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 ${user_config.api_endpoint}",
    "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 del plugin

​

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"],
  "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"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

​

Campi obbligatori

​

Campi di metadati

​

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

​

Channels

{
  "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 del comportamento del percorso

• Sostituisce il valore predefinito: commands, agents, 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, elencalo esplicitamente: "commands": ["./commands/", "./extras/"]
• Aggiunge al valore predefinito: skills. La directory predefinita skills/ viene sempre scansionata e le directory elencate in skills vengono caricate insieme ad essa
• Regole di merge proprie: hooks, MCP servers e LSP servers. Vedi ogni sezione per come più fonti si combinano

• Tutti i percorsi devono essere relativi alla radice del plugin e iniziare con ./
• I componenti dai percorsi personalizzati utilizzano le stesse regole di denominazione e spazio dei nomi
• È possibile specificare più percorsi come array
• Quando un percorso di skill punta a una directory che contiene direttamente un SKILL.md, ad esempio "skills": ["./"] che punta alla radice del plugin, il campo frontmatter name in SKILL.md determina il nome di invocazione della skill. Questo fornisce un nome stabile indipendentemente dalla directory di installazione. Se name non è impostato nel frontmatter, il nome della directory viene utilizzato come fallback.

{
  "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 del 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.

​

Limitazioni dell’attraversamento dei percorsi

​

Condividere file all’interno di un marketplace con symlink

• All’interno della directory del plugin stesso: il symlink viene preservato come symlink relativo nella cache, quindi continua a risolversi al 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. Questo consente a un meta-plugin di collegare la sua directory skills/ alle skill definite da altri plugin nel marketplace.
• Al di fuori del marketplace: il symlink viene saltato per motivi di sicurezza. Questo impedisce ai plugin di estrarre file arbitrari dell’host come percorsi di sistema nella cache.

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

​

Struttura della directory del plugin

​

Layout standard del plugin

enterprise-plugin/
├── .claude-plugin/           # Directory dei metadati (opzionale)
│   └── plugin.json             # manifest del plugin
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills come file markdown flat
│   ├── status.md
│   └── logs.md
├── agents/                   # Definizioni dei subagent
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── output-styles/            # Definizioni dello stile di output
│   └── terse.md
├── themes/                   # Definizioni del tema 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 nello strumento Bash
├── settings.json            # Impostazioni predefinite per il plugin
├── .mcp.json                # Definizioni del server MCP
├── .lsp.json                # Configurazioni del server LSP
├── scripts/                 # Script degli hook e 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 install

claude plugin install <plugin> [options]

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

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

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

# Installa nell'ambito locale (gitignored)
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

​

plugin update

claude plugin update <plugin> [options]

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

​

plugin list

claude plugin list [options]

​

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 di skill, descrizioni di agent e nomi di 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.

security-guidance 1.2.0
  Real-time security analysis for Claude Code sessions
  Source: security-guidance@claude-code-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  (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 tag

claude plugin tag [options]

​

Strumenti di debug e sviluppo

​

Comandi di debug

• Quali plugin vengono caricati
• Eventuali errori nei manifest del 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: controlla la mancanza di virgole, virgole extra o stringhe non quotate
• Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required: un campo obbligatorio è mancante
• Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: errore di sintassi JSON

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

​

Risoluzione dei problemi degli hook

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

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

​

Risoluzione dei problemi del server MCP

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

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

​

Errori di struttura della directory

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← Solo manifest qui
├── commands/            ← A livello di radice
├── agents/              ← A livello di radice
└── hooks/               ← A livello di radice

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

​

Riferimento di distribuzione e versioning

​

Gestione della versione

1. Il campo version nel plugin.json del plugin
2. Il campo version nella voce del marketplace del plugin in marketplace.json
3. Lo SHA del commit git del plugin, per le fonti github, url, git-subdir e relative-path in un marketplace ospitato su git
4. unknown, per le fonti 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