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 plugins

Muat plugins dengan menyediakan jalur sistem file lokal mereka dalam konfigurasi opsi Anda. Bidang type harus "local", satu-satunya nilai yang diterima SDK. SDK mendukung pemuatan beberapa plugins dari lokasi berbeda.

Untuk menggunakan plugin yang didistribusikan melalui marketplace atau repositori jarak jauh, unduh terlebih dahulu dan sediakan jalur direktori lokal. 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 jalur

Jalur plugin dapat berupa:

• Jalur relatif: diselesaikan relatif terhadap opsi cwd (misalnya, "./plugins/my-plugin")
• Jalur absolut: jalur sistem file lengkap (misalnya, "/home/user/plugins/my-plugin")

[!NOTE]

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

Menambahkan plugins 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 jalur setiap plugin dalam sesi:

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 jalur tersebut tidak ada dalam daftar, atau reloadPlugins() ditolak, lihat Saat 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