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 kemampuan ke sesi agen Anda. Sebuah plugin dapat mencakup:

• Skills: kemampuan yang Claude panggil secara otonom ketika relevan. Anda juga dapat menjalankan plugin skill secara langsung dengan /plugin-name: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 plugin

Muat plugin dengan memberikan path sistem file lokalnya dalam konfigurasi opsi Anda. Field type harus bernilai "local", satu-satunya nilai yang diterima SDK. SDK mendukung pemuatan beberapa plugin dari lokasi yang berbeda.

Untuk menggunakan plugin yang didistribusikan melalui marketplace atau repositori jarak jauh, unduh plugin tersebut terlebih dahulu dan berikan path direktori lokalnya. Untuk tata letak direktori yang dibutuhkan plugin, lihat Referensi struktur plugin di bawah.

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 path

Path plugin dapat berupa:

• Path relatif: di-resolve relatif terhadap opsi cwd (misalnya, "./plugins/my-plugin")
• Path absolut: path sistem file lengkap (misalnya, "/home/user/plugins/my-plugin")

[!NOTE]

Path harus mengarah ke direktori root plugin: induk dari skills/, agents/, hooks/, commands/, atau .claude-plugin/.

Memuat ulang plugin dalam sesi yang sedang berjalan

Untuk menerapkan perubahan pada skill, perintah, agent, atau hook milik plugin tanpa memulai sesi baru, panggil reloadPlugins() pada objek Query milik TypeScript SDK. Python SDK tidak menyediakan metode yang setara; sebagai gantinya, kirim /reload-plugins sebagai prompt dalam sesi tersebut.

Menambahkan plugin ke sesi yang sedang berjalan

Di TypeScript SDK, panggil reloadPlugins() pada objek Query yang dikembalikan oleh query(), dan cantumkan direktori plugin dalam opsi addPlugins pada panggilan tersebut. Setiap entri addPlugins adalah objek { type: "local", path } dengan path absolut. Memerlukan TypeScript Agent SDK v0.3.301 atau yang lebih baru.

Dalam contoh ini, q adalah objek Query yang dikembalikan oleh query(). Contoh ini menambahkan satu direktori plugin ke sesi yang sedang berjalan dan, setelah reloadPlugins() selesai, mencetak path setiap plugin dalam sesi tersebut:

const result = await q.reloadPlugins({
  addPlugins: [{ type: "local", path: "/home/user/plugins/another-plugin" }]
});

console.log(result.plugins.map((plugin) => plugin.path));

Jika plugin berhasil dimuat, daftar yang dicetak mencakup /home/user/plugins/another-plugin. Jika path tersebut tidak ada dalam daftar, atau reloadPlugins() ditolak (reject), lihat Ketika reloadPlugins() tidak memuat folder addPlugins untuk mengetahui penyebabnya.

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: "/absolute/path/to/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": "/absolute/path/to/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="/my-plugin:greet",  # Use plugin skill with namespace
        options=ClaudeAgentOptions(
            plugins=[{"type": "local", "path": "./my-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())

[!NOTE]

Jika Anda menginstal plugin melalui CLI (misalnya, /plugin install my-plugin@marketplace), Anda masih dapat menggunakannya di SDK dengan menyediakan jalur instalasinya. Periksa ~/.claude/plugins/ untuk plugins yang diinstal CLI.

Contoh lengkap

Berikut adalah contoh lengkap yang mendemonstrasikan pemuatan dan penggunaan plugin:

import { query } from "@anthropic-ai/claude-agent-sdk";
import { fileURLToPath } from "node:url";

async function runWithPlugin() {
  const pluginPath = fileURLToPath(new URL("./plugins/my-plugin", import.meta.url));

  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."""

import asyncio
from pathlib import Path

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" / "my-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__":
    asyncio.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 /plugin-name:skill-name)
│   └── my-skill/
│       └── SKILL.md
├── commands/                 # Skills sebagai file .md datar
│   └── custom-cmd.md
├── agents/                   # Custom agents
│   └── specialist.md
├── hooks/                    # Event handlers
│   └── hooks.json
└── .mcp.json                # Definisi server MCP

[!NOTE]

Direktori commands/ menyimpan skills sebagai file Markdown datar. Gunakan skills/ untuk plugin baru. Claude Code mendukung kedua lokasi.

Sumber plugin ganda

Gabungkan plugins dari lokasi berbeda:

import * as os from "node:os";
import * as path from "node:path";

plugins: [
  { type: "local", path: "./local-plugin" },
  {
    type: "local",
    path: path.join(os.homedir(), ".claude", "custom-plugins", "shared-plugin")
  }
];

[!NOTE]

SDK tidak memperluas jalur tilde seperti ~/plugins. Jika jalur plugin tidak ada, SDK melewati plugin tersebut dan sesi berlanjut, jadi periksa daftar plugins dalam pesan init untuk mengonfirmasi setiap plugin dimuat.

Troubleshooting

Plugin tidak dimuat

Jika plugin Anda tidak muncul dalam daftar plugins pesan init, periksa bidang plugin_errors untuk alasannya, kemudian lakukan pemeriksaan berikut:

1. Periksa jalurnya: pastikan jalur menunjuk ke direktori root plugin, induk dari skills/, agents/, hooks/, commands/, atau .claude-plugin/
2. Validasi plugin.json: jika plugin Anda menyertakan manifest, pastikan memiliki sintaks JSON yang valid
3. Periksa izin file: pastikan direktori plugin dapat dibaca
4. Konfirmasi direktori ada: SDK melewati jalur yang tidak ada, dan plugin tidak muncul dalam daftar plugins pesan init

Skills tidak muncul

Jika plugin skills tidak berfungsi:

1. Gunakan namespace: panggil plugin skills sebagai /plugin-name:skill-name
2. Periksa pesan init: verifikasi bahwa skill muncul di daftar skills dengan namespace yang benar
3. Validasi file skill: pastikan setiap skill memiliki file SKILL.md di subdirektorinya sendiri di bawah skills/, misalnya skills/my-skill/SKILL.md

Lihat juga

• Plugins - Panduan pengembangan plugin lengkap
• Plugins reference - Spesifikasi teknis
• Commands - Mengirimkan commands di SDK
• Subagents - Bekerja dengan agen khusus
• Skills - Menggunakan Agent Skills