Plugins nell'SDK

Carica plugin personalizzati per estendere Claude Code con comandi, agenti, skills e hooks 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 comandi slash personalizzati, agenti, skills, 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" }]

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

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

# Check available commands from plugins
print("Commands:", message.data.get("slash_commands"))
# Example: ["/help", "/compact", "my-plugin:custom-command"]


asyncio.run(main())

Utilizzo delle skills dei plugin

Le skills dai plugin vengono automaticamente associate allo spazio dei nomi del plugin per evitare conflitti. Quando richiamate come comandi slash, il formato è plugin-name:skill-name.

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 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 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 deve contenere un file manifest .claude-plugin/plugin.json. Può facoltativamente includere:

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: plugin manifest
├── skills/                   # Agent Skills (invoked autonomously or via /skill-name)
│   └── my-skill/
│       └── SKILL.md
├── commands/                 # Legacy: use skills/ instead
│   └── custom-cmd.md
├── agents/                   # Custom agents
│   └── specialist.md
├── hooks/                    # Event handlers
│   └── hooks.json
└── .mcp.json                # MCP server definitions

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 (contenente .claude-plugin/)
Valida plugin.json: Assicurati che il tuo file manifest 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: Le skills dei plugin richiedono il formato plugin-name:skill-name quando richiamate come comandi slash
Controlla il messaggio di init: Verifica che la skill appaia in slash_commands con lo spazio dei nomi corretto
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:

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
Slash Commands - Utilizzo dei comandi slash nell'SDK
Subagents - Lavoro con agenti specializzati
Skills - Utilizzo delle Agent Skills

agent-sdk/plugins.md +16 −10

46 46

47 ```python Python theme={null}47 ```python Python theme={null}

48 import asyncio48 import asyncio

~~49 from claude_agent_sdk import query~~49 from claude_agent_sdk import query, ClaudeAgentOptions

50 50

51 51

52 async def main():52 async def main():

53 async for message in query(53 async for message in query(

54 prompt="Hello",54 prompt="Hello",

~~55 options={~~55 options=ClaudeAgentOptions(

~~56 "plugins": [~~56 plugins=[

57 {"type": "local", "path": "./my-plugin"},57 {"type": "local", "path": "./my-plugin"},

58 {"type": "local", "path": "/absolute/path/to/another-plugin"},58 {"type": "local", "path": "/absolute/path/to/another-plugin"},

59 ]59 ]

~~60 },~~60 ),

61 ):61 ):

62 # Plugin commands, agents, and other features are now available62 # Plugin commands, agents, and other features are now available

63 pass63 pass

106 106

107 ```python Python theme={null}107 ```python Python theme={null}

108 import asyncio108 import asyncio

109 from claude_agent_sdk import query109 from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage

110 110

111 111

112 async def main():112 async def main():

113 async for message in query(113 async for message in query(

114 prompt="Hello", options={"plugins": [{"type": "local", "path": "./my-plugin"}]}114 prompt="Hello",

115 options=ClaudeAgentOptions(

116 plugins=[{"type": "local", "path": "./my-plugin"}]

117 ),

115 ):118 ):

116 if message.type == "system" and message.subtype == "init":119 if isinstance(message, SystemMessage) and message.subtype == "init":

117 # Check loaded plugins120 # Check loaded plugins

118 print("Plugins:", message.data.get("plugins"))121 print("Plugins:", message.data.get("plugins"))

119 # Example: [{"name": "my-plugin", "path": "./my-plugin"}]122 # Example: [{"name": "my-plugin", "path": "./my-plugin"}]

151 154

152 ```python Python theme={null}155 ```python Python theme={null}

153 import asyncio156 import asyncio

154 from claude_agent_sdk import query, AssistantMessage, TextBlock157 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock

155 158

156 159

157 async def main():160 async def main():

158 # Load a plugin with a custom /greet skill161 # Load a plugin with a custom /greet skill

159 async for message in query(162 async for message in query(

160 prompt="/demo-plugin:greet", # Use plugin skill with namespace163 prompt="/demo-plugin:greet", # Use plugin skill with namespace

161 options={"plugins": [{"type": "local", "path": "./plugins/demo-plugin"}]},164 options=ClaudeAgentOptions(

165 plugins=[{"type": "local", "path": "./plugins/demo-plugin"}]

166 ),

162 ):167 ):

163 # Claude executes the custom greeting skill from the plugin168 # Claude executes the custom greeting skill from the plugin

164 if isinstance(message, AssistantMessage):169 if isinstance(message, AssistantMessage):

219 from claude_agent_sdk import (224 from claude_agent_sdk import (

220 AssistantMessage,225 AssistantMessage,

221 ClaudeAgentOptions,226 ClaudeAgentOptions,

227 SystemMessage,

222 TextBlock,228 TextBlock,

223 query,229 query,

224 )230 )

238 async for message in query(244 async for message in query(

239 prompt="What custom commands do you have available?", options=options245 prompt="What custom commands do you have available?", options=options

240 ):246 ):

241 if message.type == "system" and message.subtype == "init":247 if isinstance(message, SystemMessage) and message.subtype == "init":

242 print(f"Loaded plugins: {message.data.get('plugins')}")248 print(f"Loaded plugins: {message.data.get('plugins')}")

243 print(f"Available commands: {message.data.get('slash_commands')}")249 print(f"Available commands: {message.data.get('slash_commands')}")

244 250

agent-sdk/plugins.md 2026-05-14 17:02 UTC to 2026-05-15 22:58 UTC

Plugins nell'SDK

Cosa sono i plugin?

Caricamento dei plugin

Specifiche dei percorsi

Verifica dell'installazione del plugin

Utilizzo delle skills dei plugin

Esempio completo

Riferimento della struttura del plugin

Casi d'uso comuni

Sviluppo e test

Estensioni specifiche del progetto

Più fonti di plugin

Troubleshooting

Plugin non caricato

Skills non appaiono

Problemi di risoluzione dei percorsi

Vedi anche