Vai al contenuto principale
I plugin ti permettono di estendere Claude Code con funzionalità personalizzate che possono essere condivise tra i progetti. Attraverso l’Agent SDK, puoi caricare programmaticamente i plugin da directory locali per aggiungere skills, agenti, hooks e server MCP alle tue sessioni di agente.

​
Cosa sono i plugin?

I plugin sono pacchetti di estensioni di Claude Code che possono includere:
  • Skills: Capacità richiamate dal modello che Claude utilizza autonomamente (possono anche essere richiamate con /skill-name)
  • Agents: Subagenti specializzati per compiti specifici
  • Hooks: Gestori di eventi che rispondono all’uso degli strumenti e ad altri eventi
  • MCP servers: Integrazioni di strumenti esterni tramite Model Context Protocol
La directory commands/ è un formato legacy. Usa skills/ per i nuovi plugin. Claude Code continua a supportare entrambi i formati per la compatibilità con le versioni precedenti.
Per informazioni complete sulla struttura dei plugin e su come creare plugin, vedi Plugins.

​
Caricamento dei plugin

Carica i plugin fornendo i loro percorsi del file system locale nella configurazione delle opzioni. Il campo type deve essere "local", l’unico valore che l’SDK accetta. Per utilizzare un plugin distribuito tramite un marketplace o un repository remoto, scaricalo prima e fornisci il percorso della directory locale. L’SDK supporta il caricamento di più plugin da posizioni diverse. 
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Hello",
  options: {
    plugins: [
      { type: "local", path: "./my-plugin" },
      { type: "local", path: "/absolute/path/to/another-plugin" }
    ]
  }
})) {
  // Plugin commands, agents, and other features are now available
}

​
Specifiche dei percorsi

I percorsi dei plugin possono essere:
  • Percorsi relativi: Risolti rispetto alla tua directory di lavoro corrente (ad esempio, "./plugins/my-plugin")
  • Percorsi assoluti: Percorsi completi del file system (ad esempio, "/home/user/plugins/my-plugin")
Il percorso deve puntare alla directory radice del plugin: la directory padre di skills/, agents/, hooks/, commands/ (legacy), o .claude-plugin/, non una sottodirectory.

​
Verifica dell’installazione del plugin

Quando i plugin si caricano correttamente, appaiono nel messaggio di inizializzazione del sistema. Puoi verificare che i tuoi plugin siano disponibili: 
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Hello",
  options: {
    plugins: [{ type: "local", path: "./my-plugin" }]
  }
})) {
  if (message.type === "system" && message.subtype === "init") {
    // Check loaded plugins
    console.log("Plugins:", message.plugins);
    // Example: [{ name: "my-plugin", path: "./my-plugin" }]

    // Plugin skills appear with the plugin name as a prefix
    console.log("Skills:", message.skills);
    // Example: ["my-plugin:greet"]

    // Plugin commands use the same prefix, and skills appear here too
    console.log("Commands:", message.slash_commands);
    // Example: ["compact", "context", "my-plugin:custom-command", "my-plugin:greet"]
  }
}

​
Utilizzo delle skills dei plugin

Le skills dai plugin vengono automaticamente associate allo spazio dei nomi del plugin per evitare conflitti. Per richiamare una direttamente, invia /plugin-name:skill-name come prompt. 
import { query } from "@anthropic-ai/claude-agent-sdk";

// Load a plugin with a custom /greet skill
for await (const message of query({
  prompt: "/my-plugin:greet", // Use plugin skill with namespace
  options: {
    plugins: [{ type: "local", path: "./my-plugin" }]
  }
})) {
  // Claude executes the custom greeting skill from the plugin
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}
Se hai installato un plugin tramite la CLI (ad esempio, /plugin install my-plugin@marketplace), puoi comunque utilizzarlo nell’SDK fornendo il suo percorso di installazione. Controlla ~/.claude/plugins/ per i plugin installati tramite CLI.

​
Esempio completo

Ecco un esempio completo che dimostra il caricamento e l’utilizzo dei plugin: 
import { query } from "@anthropic-ai/claude-agent-sdk";
import * as path from "path";

async function runWithPlugin() {
  const pluginPath = path.join(__dirname, "plugins", "my-plugin");

  console.log("Loading plugin from:", pluginPath);

  for await (const message of query({
    prompt: "What custom commands do you have available?",
    options: {
      plugins: [{ type: "local", path: pluginPath }],
      maxTurns: 3
    }
  })) {
    if (message.type === "system" && message.subtype === "init") {
      console.log("Loaded plugins:", message.plugins);
      console.log("Available skills:", message.skills);
      console.log("Available commands:", message.slash_commands);
    }

    if (message.type === "assistant") {
      console.log("Assistant:", message.message.content);
    }
  }
}

runWithPlugin().catch(console.error);

​
Riferimento della struttura del plugin

Una directory di plugin contiene tipicamente un file manifest .claude-plugin/plugin.json. Il manifest è facoltativo. Quando omesso, Claude Code scopre automaticamente i componenti dal layout della directory. La directory può includere: 
my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Plugin manifest (facoltativo, componenti auto-scoperti senza di esso)
├── skills/                   # Agent Skills (invocati autonomamente o via /skill-name)
│   └── my-skill/
│       └── SKILL.md
├── commands/                 # Legacy: usa skills/ invece
│   └── custom-cmd.md
├── agents/                   # Agenti personalizzati
│   └── specialist.md
├── hooks/                    # Gestori di eventi
│   └── hooks.json
└── .mcp.json                # Definizioni del server MCP
Per informazioni dettagliate sulla creazione di plugin, vedi:

​
Casi d’uso comuni

​
Sviluppo e test

Carica i plugin durante lo sviluppo senza installarli globalmente: 
plugins: [{ type: "local", path: "./dev-plugins/my-plugin" }];

​
Estensioni specifiche del progetto

Includi i plugin nel tuo repository di progetto per la coerenza a livello di team: 
plugins: [{ type: "local", path: "./project-plugins/team-workflows" }];

​
Più fonti di plugin

Combina i plugin da posizioni diverse: 
plugins: [
  { type: "local", path: "./local-plugin" },
  { type: "local", path: "~/.claude/custom-plugins/shared-plugin" }
];

​
Troubleshooting

​
Plugin non caricato

Se il tuo plugin non appare nel messaggio di init:
  1. Controlla il percorso: assicurati che il percorso punti alla directory radice del plugin, la directory padre di skills/, agents/, hooks/, commands/ (legacy), o .claude-plugin/
  2. Valida plugin.json: se il tuo plugin include un manifest, assicurati che abbia una sintassi JSON valida
  3. Controlla i permessi dei file: assicurati che la directory del plugin sia leggibile

​
Skills non appaiono

Se le skills dei plugin non funzionano:
  1. Usa lo spazio dei nomi: richiama le skills dei plugin come /plugin-name:skill-name
  2. Controlla il messaggio di init: verifica che la skill appaia nell’elenco skills con lo spazio dei nomi corretto
  3. Valida i file delle skills: assicurati che ogni skill abbia un file SKILL.md nella sua sottodirectory sotto skills/, ad esempio skills/my-skill/SKILL.md

​
Problemi di risoluzione dei percorsi

Se i percorsi relativi non funzionano:
  1. Controlla la directory di lavoro: i percorsi relativi vengono risolti dalla tua directory di lavoro corrente
  2. Usa percorsi assoluti: per l’affidabilità, considera l’utilizzo di percorsi assoluti
  3. Normalizza i percorsi: usa le utility dei percorsi per costruire i percorsi correttamente

​
Vedi anche