Plugin dalam SDK

Plugin memungkinkan Anda memperluas Claude Code dengan fungsionalitas khusus yang dapat dibagikan di seluruh proyek. Melalui Agent SDK, Anda dapat secara terprogram memuat plugin dari direktori lokal untuk menambahkan perintah garis miring khusus, agen, keterampilan, hook, dan server MCP ke sesi agen Anda.

Apa itu plugin?

Plugin adalah paket ekstensi Claude Code yang dapat mencakup:

• Perintah: Perintah garis miring khusus
• Agen: Subagen khusus untuk tugas-tugas tertentu
• Keterampilan: Kemampuan yang dipanggil model yang digunakan Claude secara otonom
• Hook: Penanganan peristiwa yang merespons penggunaan alat dan peristiwa lainnya
• Server MCP: Integrasi alat eksternal melalui Model Context Protocol

Untuk informasi lengkap tentang struktur plugin dan cara membuat plugin, lihat Plugin.

Memuat plugin

Muat plugin dengan menyediakan jalur sistem file lokal mereka dalam konfigurasi opsi Anda. SDK mendukung pemuatan beberapa plugin 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

async def main():
    async for message in 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
        pass

asyncio.run(main())

Spesifikasi jalur

Jalur plugin dapat berupa:

• Jalur relatif: Diselesaikan relatif terhadap direktori kerja saat ini Anda (misalnya, "./plugins/my-plugin")
• Jalur absolut: Jalur sistem file lengkap (misalnya, "/home/user/plugins/my-plugin")

Memverifikasi instalasi plugin

Ketika plugin dimuat dengan berhasil, mereka muncul dalam pesan inisialisasi sistem. Anda dapat memverifikasi bahwa plugin 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" }]

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

Menggunakan perintah plugin

Perintah dari plugin secara otomatis diberi namespace dengan nama plugin untuk menghindari konflik. Formatnya adalah plugin-name:command-name.

import { query } from "@anthropic-ai/claude-agent-sdk";

// Load a plugin with a custom /greet command
for await (const message of query({
  prompt: "/my-plugin:greet",  // Use plugin command with namespace
  options: {
    plugins: [{ type: "local", path: "./my-plugin" }]
  }
})) {
  // Claude executes the custom greeting command from the plugin
  if (message.type === "assistant") {
    console.log(message.content);
  }
}

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 commands:", message.slash_commands);
    }

    if (message.type === "assistant") {
      console.log("Assistant:", message.content);
    }
  }
}

runWithPlugin().catch(console.error);

Referensi struktur plugin

Direktori plugin harus berisi file manifes .claude-plugin/plugin.json. Secara opsional dapat mencakup:

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: plugin manifest
├── commands/                 # Custom slash commands
│   └── custom-cmd.md
├── agents/                   # Custom agents
│   └── specialist.md
├── skills/                   # Agent Skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/                    # Event handlers
│   └── hooks.json
└── .mcp.json                # MCP server definitions

Untuk informasi terperinci tentang membuat plugin, lihat:

• Plugin - Panduan pengembangan plugin lengkap
• Referensi Plugin - Spesifikasi teknis dan skema

Kasus penggunaan umum

Pengembangan dan pengujian

Muat plugin selama pengembangan tanpa memasangnya secara global:

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

Ekstensi khusus proyek

Sertakan plugin di repositori proyek Anda untuk konsistensi di seluruh tim:

plugins: [
  { type: "local", path: "./project-plugins/team-workflows" }
]

Sumber plugin ganda

Gabungkan plugin dari lokasi berbeda:

plugins: [
  { type: "local", path: "./local-plugin" },
  { type: "local", path: "~/.claude/custom-plugins/shared-plugin" }
]

Pemecahan masalah

Plugin tidak dimuat

Jika plugin Anda tidak muncul dalam pesan init:

1. Periksa jalurnya: Pastikan jalur menunjuk ke direktori root plugin (berisi .claude-plugin/)
2. Validasi plugin.json: Pastikan file manifes Anda memiliki sintaks JSON yang valid
3. Periksa izin file: Pastikan direktori plugin dapat dibaca

Perintah tidak tersedia

Jika perintah plugin tidak berfungsi:

1. Gunakan namespace: Perintah plugin memerlukan format plugin-name:command-name
2. Periksa pesan init: Verifikasi bahwa perintah muncul di slash_commands dengan namespace yang benar
3. Validasi file perintah: Pastikan file markdown perintah berada di direktori commands/

Masalah resolusi jalur

Jika jalur relatif tidak berfungsi:

1. Periksa direktori kerja: Jalur relatif diselesaikan dari direktori kerja saat ini Anda
2. Gunakan jalur absolut: Untuk keandalan, pertimbangkan menggunakan jalur absolut
3. Normalkan jalur: Gunakan utilitas jalur untuk membuat jalur dengan benar

Lihat juga

• Plugin - Panduan pengembangan plugin lengkap
• Referensi Plugin - Spesifikasi teknis
• Perintah Garis Miring - Menggunakan perintah garis miring di SDK
• Subagen - Bekerja dengan agen khusus
• Keterampilan - Menggunakan Agent Skills