Riferimento dei plugin

​

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

​

Ambiti di installazione del plugin

​

Schema del manifest del plugin

​

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/",
  "skills": "./custom/skills/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json"
}

​

Campi obbligatori

​

Campi di metadati

​

Campi del percorso del componente

​

Configurazione utente

{
  "userConfig": {
    "api_endpoint": {
      "description": "L'endpoint API del tuo team",
      "sensitive": false
    },
    "api_token": {
      "description": "Token di autenticazione API",
      "sensitive": true
    }
  }
}

​

Canali

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": { "description": "Token bot Telegram", "sensitive": true },
        "owner_id": { "description": "Il tuo ID utente Telegram", "sensitive": false }
      }
    }
  ]
}

​

Regole del comportamento del percorso

• Se commands/ esiste, viene caricato in aggiunta ai percorsi di 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 spazio dei nomi
• È possibile specificare più percorsi come array per flessibilità

{
  "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, per la durata di una sessione.
• Tramite un marketplace, installato per sessioni future.

​

Limitazioni dell’attraversamento dei percorsi

​

Lavorare con dipendenze esterne

# All'interno della directory del tuo plugin
ln -s /path/to/shared-utils ./shared-utils

​

Struttura della directory del plugin

​

Layout standard del plugin

enterprise-plugin/
├── .claude-plugin/           # Directory dei metadati (opzionale)
│   └── plugin.json             # manifest del plugin
├── commands/                 # Posizione predefinita del comando
│   ├── status.md
│   └── logs.md
├── agents/                   # Posizione predefinita dell'agent
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── skills/                   # Skills dell'agent
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── hooks/                    # Configurazioni degli hook
│   ├── hooks.json           # Configurazione principale degli hook
│   └── security-hooks.json  # Hook aggiuntivi
├── 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 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

​

Strumenti di debug e sviluppo

​

Comandi di debug

• Quali plugin vengono caricati
• Eventuali errori nei manifest del plugin
• Registrazione di comandi, agents 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, 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

{
  "name": "my-plugin",
  "version": "2.1.0"
}

• MAJOR: Modifiche di rilievo (modifiche API incompatibili)
• MINOR: Nuove funzionalità (aggiunte compatibili con le versioni precedenti)
• PATCH: Correzioni di bug (correzioni compatibili con le versioni precedenti)

• Inizia con 1.0.0 per il tuo primo rilascio stabile
• Aggiorna la versione in plugin.json prima di distribuire le modifiche
• Documenta le modifiche in un file CHANGELOG.md
• Usa versioni pre-release come 2.0.0-beta.1 per i test

​

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