Plugin nell'SDK

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 comandi slash personalizzati, agenti, competenze, hook e server MCP alle tue sessioni di agente.

Cosa sono i plugin?

I plugin sono pacchetti di estensioni di Claude Code che possono includere:

• Comandi: Comandi slash personalizzati
• Agenti: Sottoagenti specializzati per attività specifiche
• Competenze: Capacità richiamate dal modello che Claude utilizza autonomamente
• Hook: Gestori di eventi che rispondono all'uso di strumenti e altri eventi
• Server MCP: Integrazioni di strumenti esterni tramite Model Context Protocol

Per informazioni complete sulla struttura dei plugin e su come creare plugin, vedi Plugin.

Caricamento dei plugin

Carica i plugin fornendo i percorsi del file system locale nella configurazione delle opzioni. 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
}

import asyncio
from claude_agent_sdk import query

async def main():
    async for message in 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
        pass

asyncio.run(main())

Specifiche dei percorsi

I percorsi dei plugin possono essere:

• Percorsi relativi: Risolti rispetto alla tua directory di lavoro corrente (ad es., "./plugins/my-plugin")
• Percorsi assoluti: Percorsi completi del file system (ad es., "/home/user/plugins/my-plugin")

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

    // Check available commands from plugins
    console.log("Commands:", message.slash_commands);
    // Example: ["/help", "/compact", "my-plugin:custom-command"]
  }
}

Utilizzo dei comandi dei plugin

I comandi dai plugin sono automaticamente nello spazio dei nomi con il nome del plugin per evitare conflitti. Il formato è plugin-name:command-name.

import { query } from "@anthropic-ai/claude-agent-sdk";

// Load a plugin with a custom /greet command
for await (const message of query({
  prompt: "/my-plugin:greet",  // Use plugin command with namespace
  options: {
    plugins: [{ type: "local", path: "./my-plugin" }]
  }
})) {
  // Claude executes the custom greeting command from the plugin
  if (message.type === "assistant") {
    console.log(message.content);
  }
}

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 commands:", message.slash_commands);
    }

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

runWithPlugin().catch(console.error);

Riferimento della struttura del plugin

Una directory di plugin deve contenere un file manifest .claude-plugin/plugin.json. Può facoltativamente includere:

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: plugin manifest
├── commands/                 # Custom slash commands
│   └── custom-cmd.md
├── agents/                   # Custom agents
│   └── specialist.md
├── skills/                   # Agent Skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/                    # Event handlers
│   └── hooks.json
└── .mcp.json                # MCP server definitions

Per informazioni dettagliate sulla creazione di plugin, vedi:

• Plugin - Guida completa allo sviluppo dei plugin
• Riferimento dei plugin - Specifiche tecniche e schemi

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 in tutto il 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" }
]

Risoluzione dei problemi

Plugin non caricato

Se il tuo plugin non appare nel messaggio di inizializzazione:

1. Controlla il percorso: Assicurati che il percorso punti alla directory radice del plugin (contenente .claude-plugin/)
2. Convalida plugin.json: Assicurati che il tuo file manifest abbia una sintassi JSON valida
3. Controlla i permessi dei file: Assicurati che la directory del plugin sia leggibile

Comandi non disponibili

Se i comandi dei plugin non funzionano:

1. Usa lo spazio dei nomi: I comandi dei plugin richiedono il formato plugin-name:command-name
2. Controlla il messaggio di inizializzazione: Verifica che il comando appaia in slash_commands con lo spazio dei nomi corretto
3. Convalida i file di comando: Assicurati che i file markdown dei comandi siano nella directory commands/

Problemi di risoluzione del percorso

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 affidabilità, considera l'utilizzo di percorsi assoluti
3. Normalizza i percorsi: Usa le utilità di percorso per costruire i percorsi correttamente

Vedi anche

• Plugin - Guida completa allo sviluppo dei plugin
• Riferimento dei plugin - Specifiche tecniche
• Comandi slash - Utilizzo dei comandi slash nell'SDK
• Sottoagenti - Lavoro con agenti specializzati
• Competenze - Utilizzo delle competenze dell'agente