Plugins dalam SDK
Muat plugin kustom untuk memperluas Claude Code dengan skills, agen, hooks, dan server MCP melalui Agent SDK
Plugins memungkinkan Anda memperluas Claude Code dengan fungsionalitas kustom yang dapat dibagikan di seluruh proyek. Melalui Agent SDK, Anda dapat secara terprogram memuat plugins dari direktori lokal untuk menambahkan skills, agen, hooks, dan server MCP ke sesi agen Anda.
Apa itu plugins?
Plugins adalah paket ekstensi Claude Code yang dapat mencakup:
- Skills: Kemampuan yang dipanggil model yang digunakan Claude secara otonom (juga dapat dipanggil dengan
/skill-name) - Agents: Subagen khusus untuk tugas-tugas tertentu
- Hooks: Penanganan peristiwa yang merespons penggunaan alat dan peristiwa lainnya
- MCP servers: Integrasi alat eksternal melalui Model Context Protocol
Untuk informasi lengkap tentang struktur plugin dan cara membuat plugins, lihat Plugins.
Memuat plugins
Muat plugins dengan menyediakan jalur sistem file lokal mereka dalam konfigurasi opsi Anda. Bidang type harus "local", satu-satunya nilai yang diterima SDK. Untuk menggunakan plugin yang didistribusikan melalui marketplace atau repositori jarak jauh, unduh terlebih dahulu dan sediakan jalur direktori lokal. SDK mendukung pemuatan beberapa plugins dari lokasi berbeda.
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())
Spesifikasi jalur
Jalur plugin dapat berupa:
- Jalur relatif: Diselesaikan relatif terhadap direktori kerja saat ini (misalnya,
"./plugins/my-plugin") - Jalur absolut: Jalur sistem file lengkap (misalnya,
"/home/user/plugins/my-plugin")
Memverifikasi instalasi plugin
Ketika plugins dimuat dengan berhasil, mereka muncul dalam pesan inisialisasi sistem. Anda dapat memverifikasi bahwa plugins Anda tersedia:
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())
Menggunakan plugin skills
Skills dari plugins secara otomatis diberi namespace dengan nama plugin untuk menghindari konflik. Untuk menjalankan satu secara langsung, kirimkan /plugin-name:skill-name sebagai 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())
Contoh lengkap
Berikut adalah contoh lengkap yang mendemonstrasikan pemuatan dan penggunaan 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)
Referensi struktur plugin
Direktori plugin biasanya berisi file manifest .claude-plugin/plugin.json. Manifest bersifat opsional. Ketika dihilangkan, Claude Code secara otomatis menemukan komponen dari tata letak direktori. Direktori dapat mencakup:
my-plugin/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest (opsional, komponen ditemukan secara otomatis tanpanya)
├── skills/ # Agent Skills (dipanggil secara otonom atau melalui /skill-name)
│ └── my-skill/
│ └── SKILL.md
├── commands/ # Legacy: gunakan skills/ sebagai gantinya
│ └── custom-cmd.md
├── agents/ # Custom agents
│ └── specialist.md
├── hooks/ # Event handlers
│ └── hooks.json
└── .mcp.json # Definisi server MCP
Untuk informasi terperinci tentang membuat plugins, lihat:
- Plugins - Panduan pengembangan plugin lengkap
- Plugins reference - Spesifikasi teknis dan skema
Kasus penggunaan umum
Pengembangan dan pengujian
Muat plugins selama pengembangan tanpa menginstalnya secara global:
plugins: [{ type: "local", path: "./dev-plugins/my-plugin" }];
Ekstensi khusus proyek
Sertakan plugins di repositori proyek Anda untuk konsistensi di seluruh tim:
plugins: [{ type: "local", path: "./project-plugins/team-workflows" }];
Sumber plugin ganda
Gabungkan plugins dari lokasi berbeda:
plugins: [
{ type: "local", path: "./local-plugin" },
{ type: "local", path: "~/.claude/custom-plugins/shared-plugin" }
];
Troubleshooting
Plugin tidak dimuat
Jika plugin Anda tidak muncul dalam pesan init:
- Periksa jalurnya: pastikan jalur menunjuk ke direktori root plugin, induk dari
skills/,agents/,hooks/,commands/(legacy), atau.claude-plugin/ - Validasi plugin.json: jika plugin Anda menyertakan manifest, pastikan memiliki sintaks JSON yang valid
- Periksa izin file: pastikan direktori plugin dapat dibaca
Skills tidak muncul
Jika plugin skills tidak berfungsi:
- Gunakan namespace: panggil plugin skills sebagai
/plugin-name:skill-name - Periksa pesan init: verifikasi bahwa skill muncul di daftar
skillsdengan namespace yang benar - Validasi file skill: pastikan setiap skill memiliki file
SKILL.mddi subdirektorinya sendiri di bawahskills/, misalnyaskills/my-skill/SKILL.md
Masalah resolusi jalur
Jika jalur relatif tidak berfungsi:
- Periksa direktori kerja: jalur relatif diselesaikan dari direktori kerja saat ini Anda
- Gunakan jalur absolut: untuk keandalan, pertimbangkan menggunakan jalur absolut
- Normalkan jalur: gunakan utilitas jalur untuk membuat jalur dengan benar
Lihat juga
- Plugins - Panduan pengembangan plugin lengkap
- Plugins reference - Spesifikasi teknis
- Commands - Menggunakan commands di SDK
- Subagents - Bekerja dengan agen khusus
- Skills - Menggunakan Agent Skills