Panduan

Plugin dalam SDK

Muat plugin khusus untuk memperluas Claude Code dengan perintah, agen, keterampilan, dan hook melalui Agent 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
}

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

Jalur harus menunjuk ke direktori root plugin (direktori yang berisi .claude-plugin/plugin.json).

Memverifikasi instalasi plugin

Ketika plugin dimuat dengan berhasil, mereka muncul dalam pesan inisialisasi sistem. Anda dapat memverifikasi bahwa plugin Anda tersedia:

Menggunakan perintah plugin

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

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

Contoh lengkap

Berikut adalah contoh lengkap yang mendemonstrasikan pemuatan dan penggunaan plugin:

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:

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

Perintah tidak tersedia

Jika perintah plugin tidak berfungsi:

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

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

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

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 { 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);
  }
}

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);