Plugin nell'SDK
Carica plugin personalizzati per estendere Claude Code con skills, agenti, hooks e server MCP tramite l'Agent 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 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
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
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
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 esempio,
"./plugins/my-plugin") - Percorsi assoluti: Percorsi completi del file system (ad esempio,
"/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" }]
// 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"]
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage
async def main():
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
plugins=[{"type": "local", "path": "./my-plugin"}]
),
):
if isinstance(message, SystemMessage) and message.subtype == "init":
# Check loaded plugins
print("Plugins:", message.data.get("plugins"))
# Example: [{"name": "my-plugin", "path": "./my-plugin"}]
# Plugin skills appear with the plugin name as a prefix
print("Skills:", message.data.get("skills"))
# Example: ["my-plugin:greet"]
# Plugin commands use the same prefix, and skills appear here too
print("Commands:", message.data.get("slash_commands"))
# Example: ["compact", "context", "my-plugin:custom-command", "my-plugin:greet"]
asyncio.run(main())
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);
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock
async def main():
# Load a plugin with a custom /greet skill
async for message in query(
prompt="/demo-plugin:greet", # Use plugin skill with namespace
options=ClaudeAgentOptions(
plugins=[{"type": "local", "path": "./plugins/demo-plugin"}]
),
):
# Claude executes the custom greeting skill from the plugin
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(f"Claude: {block.text}")
asyncio.run(main())
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);
#!/usr/bin/env python3
"""Example demonstrating how to use plugins with the Agent SDK."""
from pathlib import Path
import anyio
from claude_agent_sdk import (
AssistantMessage,
ClaudeAgentOptions,
SystemMessage,
TextBlock,
query,
)
async def run_with_plugin():
"""Example using a custom plugin."""
plugin_path = Path(__file__).parent / "plugins" / "demo-plugin"
print(f"Loading plugin from: {plugin_path}")
options = ClaudeAgentOptions(
plugins=[{"type": "local", "path": str(plugin_path)}],
max_turns=3,
)
async for message in query(
prompt="What custom commands do you have available?", options=options
):
if isinstance(message, SystemMessage) and message.subtype == "init":
print(f"Loaded plugins: {message.data.get('plugins')}")
print(f"Available skills: {message.data.get('skills')}")
print(f"Available commands: {message.data.get('slash_commands')}")
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(f"Assistant: {block.text}")
if __name__ == "__main__":
anyio.run(run_with_plugin)
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:
- Plugins - Guida completa allo sviluppo dei plugin
- Plugins reference - 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 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:
- 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/ - Valida plugin.json: se il tuo plugin include un manifest, assicurati che abbia una sintassi JSON valida
- Controlla i permessi dei file: assicurati che la directory del plugin sia leggibile
Skills non appaiono
Se le skills dei plugin non funzionano:
- Usa lo spazio dei nomi: richiama le skills dei plugin come
/plugin-name:skill-name - Controlla il messaggio di init: verifica che la skill appaia nell'elenco
skillscon lo spazio dei nomi corretto - Valida i file delle skills: assicurati che ogni skill abbia un file
SKILL.mdnella sua sottodirectory sottoskills/, ad esempioskills/my-skill/SKILL.md
Problemi di risoluzione dei percorsi
Se i percorsi relativi non funzionano:
- Controlla la directory di lavoro: i percorsi relativi vengono risolti dalla tua directory di lavoro corrente
- Usa percorsi assoluti: per l'affidabilità, considera l'utilizzo di percorsi assoluti
- Normalizza i percorsi: usa le utility dei percorsi per costruire i percorsi correttamente
Vedi anche
- Plugins - Guida completa allo sviluppo dei plugin
- Plugins reference - Specifiche tecniche
- Commands - Utilizzo dei comandi nell'SDK
- Subagents - Lavoro con agenti specializzati
- Skills - Utilizzo delle Agent Skills