Referensi Plugins

Referensi teknis lengkap untuk sistem plugin Claude Code, termasuk skema, perintah CLI, dan spesifikasi komponen.

Sebuah plugin adalah direktori yang mandiri berisi komponen-komponen yang memperluas Claude Code dengan fungsionalitas khusus. Komponen plugin mencakup skills, agents, hooks, MCP servers, LSP servers, dan monitors.

Referensi komponen plugin

Skills

Plugin menambahkan skills ke Claude Code, membuat pintasan /name yang dapat Anda atau Claude panggil.

Lokasi: Direktori skills/ atau commands/ di root plugin, atau file SKILL.md tunggal di root plugin

Format file: Skills adalah direktori dengan SKILL.md; commands adalah file markdown sederhana

Struktur skill:

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (opsional)
│   └── scripts/ (opsional)
└── code-reviewer/
    └── SKILL.md

Skills dan commands secara otomatis ditemukan ketika plugin diinstal.

Jika plugin tidak memiliki direktori skills/ dan tidak memiliki field manifest skills, file SKILL.md di root plugin dimuat sebagai skill tunggal. Atur field frontmatter name untuk mengontrol nama invokasi skill. Tanpanya, Claude Code kembali ke nama direktori instalasi. Untuk plugin yang disalin ke dalam cache, nama itu adalah string versi yang berubah pada setiap pembaruan. Untuk plugin yang mengirimkan lebih dari satu skill, gunakan tata letak direktori skills/ yang ditunjukkan di atas.

Dalam skills dan commands plugin, field frontmatter Boolean seperti disable-model-invocation menerima yes, no, on, off, 1, dan 0 dalam huruf apa pun, selain true dan false. Sebelum v2.1.218, Claude Code hanya mengenali true dan false.

Untuk detail lengkap, lihat Skills.

Agents

Plugin dapat menyediakan subagents khusus untuk tugas-tugas tertentu yang dapat Claude panggil secara otomatis jika sesuai.

Lokasi: Direktori agents/ di root plugin

Format file: File markdown yang menjelaskan kemampuan agent

Struktur agent:

---
name: agent-name
description: Apa yang agent ini spesialisasikan dan kapan Claude harus memanggilnya
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Prompt sistem terperinci untuk agent yang menjelaskan peran, keahlian, dan perilakunya.

Frontmatter agent plugin

File agent plugin menggunakan field frontmatter yang sama seperti file subagent, kecuali bahwa Claude Code hanya menghormati beberapa di antaranya ketika agent berasal dari plugin:

• Didukung: name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, omitClaudeMd, isolation, color, dan experimental. Satu-satunya nilai isolation yang valid adalah "worktree".
• Tidak didukung, untuk alasan keamanan: hooks, mcpServers, dan permissionMode. Claude Code mengabaikan ini ketika memuat agent dari plugin. Untuk menggunakannya, salin file agent ke .claude/agents/ atau ~/.claude/agents/.
• Tidak didukung: initialPrompt.

Anda dapat menempatkan file plugin agent dalam subfolder dari agents/. Claude Code memuatnya secara rekursif dan menggabungkan nama plugin, setiap nama subfolder, dan nama file dengan titik dua untuk membentuk nama scoped agent. Misalnya, agents/review/security.md dalam plugin bernama my-plugin dimuat sebagai my-plugin:review:security. Dua pengaturan mengubah nama itu:

• Frontmatter name: ini menggantikan hanya nama file, jadi name: audit dalam agents/review/security.md dimuat sebagai my-plugin:review:audit
• Field manifest agents: file yang Anda daftarkan di sana dimuat tanpa nama subfolder, jadi "agents": "./custom/review/security.md" dimuat sebagai my-plugin:security

Claude Code memuat agent plugin bahkan ketika frontmatternya tidak memiliki name atau tidak dapat diuraikan:

• Tidak ada name: Claude Code memberi nama agent sesuai file, jadi agents/reviewer.md dalam plugin bernama my-plugin dimuat sebagai my-plugin:reviewer
• Frontmatter yang tidak dapat diuraikan: Claude Code memberi nama agent sesuai file, menggunakan Agent from my-plugin plugin sebagai deskripsinya, dan mengabaikan setiap field dalam file

Sebaliknya, Claude Code melewati file project, user, atau managed agent yang frontmatternya tidak memiliki name atau tidak dapat diuraikan.

Untuk menemukan file dalam direktori agents/ default plugin yang frontmatternya tidak dapat diuraikan, jalankan claude plugin validate. Path yang Anda berikan tergantung pada apakah plugin memiliki manifest, dan kedua contoh menggunakan ./my-plugin sebagai direktori plugin:

• Plugin dengan manifest: claude plugin validate ./my-plugin
• Plugin tanpa manifest: claude plugin validate ./my-plugin/agents. Memerlukan Claude Code v2.1.233 atau lebih baru.

Agents muncul dalam @-mention typeahead di bawah nama scoped mereka, seperti my-plugin:code-reviewer, setelah plugin diaktifkan.

Untuk detail lengkap, lihat Subagents.

Hooks

Plugin dapat menyediakan event handlers yang merespons event Claude Code secara otomatis.

Lokasi: hooks/hooks.json di root plugin, atau inline dalam plugin.json

Format: Konfigurasi JSON dengan event matchers dan actions

hooks/hooks.json dapat membawa key $schema tingkat atas yang menamai URL JSON Schema untuk autocomplete dan validasi editor. Claude Code mengabaikan key saat waktu load.

Konfigurasi hook:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

Plugin hooks merespons event lifecycle yang sama seperti user-defined hooks:

Tipe hook:

• command: jalankan perintah shell atau script
• http: kirim event JSON sebagai POST request ke URL
• mcp_tool: panggil tool pada MCP server yang dikonfigurasi
• prompt: evaluasi prompt dengan LLM (menggunakan placeholder $ARGUMENTS untuk konteks)
• agent: jalankan verifier agentic dengan tools untuk tugas verifikasi kompleks

Hooks yang menargetkan bundled MCP server plugin sendiri harus menggunakan nama scopednya. Tool matchers dan field if mengambil nama tool scoped mcp__plugin_<plugin-name>_<server-name>__<tool>, dan field server hook mcp_tool mengambil plugin:<plugin-name>:<server-name>. Matcher yang ditulis terhadap bare server key tidak pernah aktif. Lihat Match MCP tools dan Plugin-provided MCP servers.

MCP servers

Plugin dapat membundel Model Context Protocol (MCP) servers untuk menghubungkan Claude Code dengan tools dan services eksternal.

Lokasi: .mcp.json di root plugin, atau inline dalam plugin.json

Format: Konfigurasi MCP server standar

Konfigurasi MCP server:

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"]
    }
  }
}

Perilaku integrasi:

• MCP servers plugin dimulai secara otomatis ketika plugin diaktifkan
• Servers muncul sebagai MCP tools standar dalam toolkit Claude
• Plugin servers dapat dikonfigurasi secara independen dari user MCP servers
• Jika Anda menjalankan /reload-plugins di tengah sesi, Claude Code mempertahankan koneksi live dari servers yang konfigurasinya tidak berubah

LSP servers

Plugin dapat menyediakan Language Server Protocol (LSP) servers untuk memberikan Claude real-time code intelligence saat bekerja pada codebase Anda.

Lokasi: .lsp.json di root plugin, atau inline dalam plugin.json

Format: Konfigurasi JSON yang memetakan nama language server ke konfigurasi mereka

Format file .lsp.json:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

Inline dalam plugin.json:

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

Field yang diperlukan:

Field opsional:

restartOnCrash dan shutdownTimeout memerlukan Claude Code v2.1.205 atau lebih baru. Sebelum v2.1.205, skema config menerima kedua opsi tetapi mengatur salah satu menyebabkan Claude Code melewati LSP server itu sepenuhnya pada startup, dengan alasan hanya terlihat dalam output claude --debug.

Multiple servers untuk ekstensi yang sama: ketika lebih dari satu LSP server yang diaktifkan mendeklarasikan ekstensi file yang sama dalam extensionToLanguage, apakah servers berasal dari satu plugin atau dari plugin berbeda, server pertama yang terdaftar menangani file dengan ekstensi itu dan yang lain tidak pernah dimulai. Interface /plugin menampilkan peringatan yang menamai plugin yang servernya aktif.

Servers yang gagal menginisialisasi: Claude Code melewati server yang konfigurasinya tidak valid, misalnya yang hilang command atau extensionToLanguage, dan server yang dikonfigurasi lainnya masih dimulai. Jalankan claude --debug untuk melihat mengapa server dilewati.

Server yang dilewati tidak mengklaim ekstensi filenya, jadi server valid lain yang mendeklarasikan ekstensi yang sama, dari plugin yang sama atau berbeda, masih menangani file tersebut.

Kirim output log ke stderr, bukan stdout: Claude Code membaca stdout server hanya sebagai pesan protokol, dan menerima header pesan hingga 64 KiB dan body pesan hingga 32 MiB. Claude Code memutuskan server yang melebihi batas apa pun atau menulis output non-protokol ke stdout, dan menghitung putus sebagai crash untuk restartOnCrash dan maxRestarts. Ketika Anda menjalankan dengan --debug, Claude Code menulis error yang menamai penyebabnya ke debug log.

Plugin LSP yang tersedia:

Instal language server terlebih dahulu, kemudian instal plugin dari marketplace.

Monitors

Plugin dapat mendeklarasikan background monitors yang Claude Code mulai secara otomatis ketika plugin aktif. Setiap monitor menjalankan perintah shell untuk seumur hidup sesi dan mengirimkan setiap baris stdout ke Claude sebagai notifikasi, sehingga Claude dapat bereaksi terhadap entri log, perubahan status, atau event yang dipolling tanpa diminta untuk memulai watch itu sendiri.

Plugin monitors menggunakan mekanisme yang sama seperti Monitor tool dan berbagi batasan ketersediaannya. Mereka hanya berjalan dalam sesi CLI interaktif, berjalan unsandboxed pada tingkat kepercayaan yang sama seperti hooks, dan dilewati pada host di mana Monitor tool tidak tersedia.

Lokasi: monitors/monitors.json di root plugin, atau inline dalam plugin.json

Format: Array JSON dari entri monitor

monitors/monitors.json berikut mengawasi endpoint status deployment dan log error lokal:

[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
    "description": "Deployment status changes"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log",
    "when": "on-skill-invoke:debug"
  }
]

Untuk mendeklarasikan monitors inline, atur experimental.monitors dalam plugin.json ke array yang sama. Untuk memuat dari path non-default, atur experimental.monitors ke string path relatif seperti "./config/monitors.json". Monitors adalah komponen eksperimental.

Field yang diperlukan:

Field opsional:

Nilai command mendukung substitusi path path substitutions ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}, dan ${CLAUDE_PROJECT_DIR}, ditambah ${ENV_VAR} apa pun dari environment. Awali perintah dengan cd "${CLAUDE_PLUGIN_ROOT}" && jika script perlu berjalan dari direktori plugin itu sendiri.

Monitor command tidak dapat mereferensikan nilai ${user_config.*}. Perintah berjalan melalui shell, jadi Claude Code menolak monitor dengan error daripada mensubstitusi nilai. Proses monitor tidak menerima variabel environment CLAUDE_PLUGIN_OPTION_<KEY>, jadi biarkan script monitor membaca nilai dari file config yang dimilikinya.

Jika Anda menonaktifkan plugin di tengah sesi, Claude Code tidak menghentikan monitors yang sudah berjalan; mereka berhenti ketika sesi berakhir.

Themes

Plugin dapat mengirimkan color themes yang muncul dalam /theme bersama preset built-in dan themes lokal pengguna. Theme adalah file JSON dalam themes/ dengan preset base dan map overrides sparse dari color tokens. Themes adalah komponen eksperimental.

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

Ketika pengguna memilih theme plugin, Claude Code menyimpan custom:<plugin-name>:<slug> dalam config mereka. Plugin themes adalah read-only: ketika pengguna menekan Ctrl+E pada satu dalam /theme, Claude Code menyalinnya ke ~/.claude/themes/ sehingga mereka dapat mengedit salinannya.

Cakupan instalasi plugin

Ketika Anda menginstal plugin, Anda memilih cakupan yang menentukan di mana plugin tersedia dan siapa lagi yang dapat menggunakannya:

Plugin menggunakan sistem cakupan yang sama dengan konfigurasi Claude Code lainnya. Untuk instruksi instalasi dan flag cakupan, lihat Install plugins. Untuk penjelasan lengkap tentang cakupan, lihat Configuration scopes.

Plugin direktori skills

Folder apa pun di bawah direktori skills yang berisi manifes .claude-plugin/plugin.json dimuat sebagai plugin bernama <name>@skills-dir pada sesi berikutnya, tanpa marketplace dan tanpa langkah instalasi. Buat satu dengan plugin init. Tidak seperti instalasi marketplace yang disalin, plugin ditemukan di tempat daripada disalin ke cache plugin.

Pohon direktori skills mendukung tiga hal yang berbeda:

Pilih tempat plugin dimuat dari

Plugin dengan cakupan proyek diperiksa ke dalam repositori dan menjangkau setiap kolaborator yang mengklonnya. Karena konten tersebut berasal dari repositori daripada dari Anda, konten tersebut dimuat hanya setelah gerbang kepercayaan yang sama yang mengatur aturan izin proyek di .claude/settings.json, jadi mempercayai folder induk atau menjalankan dengan -p tidak cukup, dan komponen yang menjalankan kode dibatasi lebih lanjut:

• Server MCP yang dideklarasikannya melalui persetujuan per-server yang sama sebagai .mcp.json proyek
• Server LSP dimulai hanya setelah Anda mempercayai workspace
• Monitor latar belakang tidak dimuat

Plugin dengan cakupan personal tidak memiliki pembatasan ini.

Edit, muat ulang, dan nonaktifkan plugin direktori skills

Perubahan yang Anda buat pada SKILL.md skill berlaku segera dalam sesi saat ini. Perubahan pada komponen lain plugin, seperti hooks/, .mcp.json, agents/, dan output-styles/, tidak. Jalankan /reload-plugins atau mulai ulang Claude Code untuk mengambilnya. Lihat Deteksi perubahan langsung.

Untuk menghentikan pemuatan plugin direktori skills, hapus foldernya atau nonaktifkan berdasarkan nama. Tidak ada langkah uninstall karena tidak ada yang diinstal dari marketplace.

claude plugin disable my-tool@skills-dir

Plugin yang disinkronkan dari claude.ai

Claude Code memuat plugin yang diaktifkan untuk akun claude.ai Anda, termasuk plugin yang organisasi Anda aktifkan untuk anggotanya, bersama dengan plugin yang Anda instal dari marketplace. Plugin ini diunduh ke dalam ~/.claude/plugins/synced/ dan dimuat sebagai <name>@synced, tanpa marketplace dan tanpa catatan instalasi. Plugin yang disinkronkan berjalan dengan kepercayaan yang sama seperti plugin marketplace yang Anda instal: skills, agents, hooks, server MCP, dan server LSP semuanya dimuat.

Tempat Claude Code menyinkronkan plugin ini tergantung pada sesi:

• Di Cowork dan sesi cloud, Claude Code mengunduh plugin ke dalam lingkungan sesi itu sendiri ketika sesi dimulai. Sebelum v2.1.239, Claude Code memuat plugin ini sebagai <name>@inline, identitas yang digunakan plugin --plugin-dir.
• Di sesi terminal tempat Anda masuk dengan akun claude.ai Anda, Claude Code memeriksa akun Anda sekali setiap kali dimulai, kemudian mengunduh plugin baru dan yang diperbarui serta menghapus plugin yang Anda atau organisasi Anda matikan, semuanya di latar belakang. Sinkronisasi di sesi terminal memerlukan Claude Code v2.1.273 atau lebih baru.

Pemeriksaan peluncuran berjalan di latar belakang, sehingga dapat selesai setelah sesi Anda dimulai. Ketika menambah, memperbarui, atau menghapus plugin yang disinkronkan di sesi interaktif, Claude Code menampilkan Plugins changed. Run /reload-plugins to activate. Jalankan /reload-plugins untuk memuat perubahan di sesi itu, atau biarkan untuk lain kali Anda memulai Claude Code. Jika Anda mengaktifkan plugin di claude.ai saat sesi sedang berjalan, Claude Code mengunduhnya lain kali dimulai.

Sinkronisasi plugin di sesi terminal berjalan di bawah kondisi masuk yang sama seperti skills yang disinkronkan dari claude.ai. Plugin ini juga memerlukan masuk yang memberikan Claude Code akses ke plugin akun Anda.

Masuk dari versi Claude Code yang lebih awal mengambil akses plugin lain kali Claude Code memperbarui masuk itu di latar belakang, dalam beberapa jam, atau segera jika Anda menjalankan /login lagi. Sinkronisasi plugin dimulai lain kali Anda memulai Claude Code setelah itu.

claude plugin list menampilkan plugin yang disinkronkan di bawah judul Synced from claude.ai, dan tab Installed /plugin mencantumkannya dengan synced sebagai sumber mereka. Kelola plugin yang disinkronkan dengan ID <name>@synced yang dicetak oleh claude plugin list:

• Matikan salah satu: jalankan claude plugin disable <name>@synced, atau matikan dari tab Installed /plugin. Claude Code menyimpan pilihan sebagai "<name>@synced": false di enabledPlugins tingkat pengguna Anda. Untuk menghidupkan kembali plugin, jalankan claude plugin enable <name>@synced.
• Jaga plugin tetap keluar di mana-mana: matikan plugin untuk akun claude.ai Anda. Untuk menjaganya tetap keluar dari satu proyek di setiap lingkungan, atur "<name>@synced": false di bawah enabledPlugins di .claude/settings.json proyek yang berkomitmen itu.
• Kelola plugin itu sendiri di claude.ai: claude plugin install, update, dan uninstall tidak berlaku untuk plugin yang disinkronkan. Claude Code mengunduh pembaruan plugin pada sinkronisasi berikutnya. Untuk menghapusnya, matikan plugin untuk akun claude.ai Anda, dan Claude Code menghapusnya pada sinkronisasi berikutnya.
• Hentikan sinkronisasi di mesin: atur syncClaudeAiPlugins ke false di pengaturan pengguna Anda. Claude Code berhenti mengunduh, dan lain kali dimulai, plugin yang sudah disinkronkan dipindahkan ke ~/.claude/plugins/.trash/ dan tidak lagi dimuat. Organisasi Anda dapat mengatur kunci yang sama di pengaturan terkelola, atau matikan Skills di claude.ai, yang juga menghentikan plugin dari sinkronisasi.

Anda tidak dapat mematikan plugin yang organisasi Anda tandai sebagai wajib di claude.ai. Claude Code memuat plugin bahkan jika Anda menonaktifkannya sebelumnya, dan claude plugin disable menolak dengan Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it. Di claude plugin list, plugin ini ditandai required by your org.

Ketika plugin yang diaktifkan dari sumber lain cocok dengan nama plugin yang disinkronkan, Claude Code memuat plugin itu dan melaporkan salinan yang disinkronkan sebagai tidak dimuat. Sumber lain termasuk instalasi marketplace, plugin skills-directory, plugin --plugin-dir, dan plugin yang tertanam di Claude Code. Untuk menggunakan salinan claude.ai sebagai gantinya, nonaktifkan salinan Anda sendiri. Sebelum v2.1.239, Claude Code memuat salinan yang disinkronkan alih-alih instalasi marketplace dengan nama yang sama.

Skema manifes plugin

File .claude-plugin/plugin.json mendefinisikan metadata dan konfigurasi plugin Anda.

Manifes bersifat opsional. Jika dihilangkan, Claude Code secara otomatis menemukan komponen di lokasi default dan menurunkan nama plugin dari nama direktori. Gunakan manifes ketika Anda perlu memberikan metadata atau jalur komponen kustom.

Skema lengkap

{
  "name": "plugin-name",
  "displayName": "Plugin Name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "metadata": { "catalogId": "cat-123", "tier": "pro" },
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json",
    "evals": "quality/evals"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Bidang yang diperlukan

Jika Anda menyertakan manifes, name adalah satu-satunya bidang yang diperlukan.

Nama ini digunakan untuk namespacing komponen. Misalnya, di UI, agent agent-creator untuk plugin dengan nama plugin-dev akan muncul sebagai plugin-dev:agent-creator.

Bidang yang tidak dikenali

Claude Code mengabaikan bidang tingkat atas yang tidak dikenalinya. Anda dapat menyimpan metadata dari ekosistem lain di plugin.json dan plugin masih dimuat. Ini membuat praktis untuk mempertahankan satu manifes yang berfungsi ganda sebagai manifes ekstensi VS Code atau Cursor, package.json npm, atau manifes bundle MCPB/DXT.

claude plugin validate melaporkan bidang yang tidak dikenali sebagai peringatan, bukan kesalahan. Jika bidang hanya berbeda satu atau dua karakter dari yang dikenali, peringatan menyarankan nama yang mungkin dimaksudkan. Plugin dengan hanya peringatan bidang yang tidak dikenali masih lulus validasi dan dimuat saat runtime.

Bagaimana Claude Code menangani bidang yang dikenali yang nilainya memiliki tipe yang salah tergantung pada bidangnya:

• Sebagian besar bidang: plugin gagal dimuat. Misalnya, nilai keywords yang berupa string bukan array adalah kesalahan pemuatan, dan claude plugin validate melaporkannya sebagai demikian.
• experimental dan metadata: Claude Code mengabaikan nilai non-object, dan claude plugin validate melaporkan peringatan.

Teruskan --strict untuk memperlakukan peringatan sebagai kesalahan. Gunakan di CI untuk menangkap nama bidang yang salah eja atau bidang yang tersisa dari manifes alat lain sebelum menerbitkan, meskipun plugin akan dimuat saat runtime.

claude plugin validate ./my-plugin --strict

Bidang metadata

Pengaktifan default

Atur defaultEnabled: false di plugin.json untuk mengirimkan plugin yang diinstal dalam keadaan dinonaktifkan. Pengguna menghidupkannya dengan claude plugin enable <plugin> atau antarmuka /plugin. Gunakan ini untuk plugin yang menambah biaya atau ruang lingkup yang harus dipilih pengguna, seperti yang menghubungkan ke layanan eksternal.

defaultEnabled adalah fallback ketika tidak ada yang lain telah memutuskan status plugin. Pengaturan pengguna dan persyaratan ketergantungan mengambil alih:

• Pengaturan pengguna: entri untuk plugin di enabledPlugins di ruang lingkup pengaturan apa pun. Setelah ditulis, itu bertahan di seluruh pembaruan dan penginstalan ulang plugin, jadi mengubah defaultEnabled dalam rilis yang lebih baru tidak membalik pengguna yang ada.
• Persyaratan ketergantungan: ketika plugin diperlukan oleh plugin lain yang aktif, Claude Code menulis true untuk itu pada waktu instalasi atau pengaktifan. Itu memberikannya pengaturan eksplisit, jadi default-nya sendiri tidak lagi berlaku. Lihat Aktifkan atau nonaktifkan plugin dengan ketergantungan.

Bidang yang sama dapat muncul di entri marketplace plugin, di mana itu mengambil alih nilai di plugin.json. Lihat Bidang plugin opsional.

Bidang jalur komponen

Komponen eksperimental

Komponen di bawah kunci experimental, themes dan monitors, memiliki skema manifes yang mungkin berubah antar rilis saat mereka stabil. Tempat Anda mendeklarasikannya adalah migrasi terpisah: tingkat atas masih berfungsi, claude plugin validate memperingatkan, dan rilis di masa depan akan memerlukan experimental.*.

Konfigurasi pengguna

Bidang userConfig mendeklarasikan nilai yang Claude Code minta dari pengguna ketika plugin diaktifkan. Gunakan ini alih-alih mengharuskan pengguna untuk mengedit settings.json secara manual.

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Your team's API endpoint"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "API authentication token",
      "sensitive": true
    }
  }
}

Kunci harus berupa pengidentifikasi yang valid. Setiap opsi mendukung bidang-bidang ini:

Kecuali bidang sensitive dan daftar multiple, setiap bidang dari setiap plugin yang diaktifkan juga muncul sebagai baris di panel /config. Baris memerlukan Claude Code v2.1.269 atau lebih baru.

Setiap nilai tersedia untuk substitusi sebagai ${user_config.KEY} dalam konfigurasi server MCP dan LSP serta perintah hook. Nilai non-sensitif juga dapat disubstitusi dalam konten skill dan agent. Semua nilai diekspor ke proses hook sebagai variabel lingkungan CLAUDE_PLUGIN_OPTION_<KEY>, di mana <KEY> adalah kunci opsi dengan huruf besar.

Bidang yang berjalan dalam shell menolak ${user_config.*}: mensubstitusi nilai yang dikonfigurasi ke dalam perintah shell akan membiarkan shell menjalankan apa pun yang berisi nilai itu, jadi komponen gagal dengan kesalahan sebagai gantinya. Setiap bidang yang ditolak memiliki cara alternatif untuk melewatkan nilai:

Sebelum v2.1.207, bidang-bidang ini mensubstitusi nilai ${user_config.KEY}; perbarui plugin yang mengandalkan ini.

Nilai non-sensitif disimpan di bawah kunci pluginConfigs di settings.json pengguna Anda sebagai pluginConfigs[<plugin-id>].options.

Di macOS, Claude Code menyimpan nilai sensitif di macOS Keychain, kembali ke ~/.claude/.credentials.json ketika Keychain menolak penulisan. Di platform tanpa keychain yang didukung, itu menyimpannya di ~/.claude/.credentials.json. Penyimpanan Keychain dibagikan dengan token OAuth dan memiliki batas total sekitar 2 KB, jadi simpan nilai sensitif tetap kecil.

Claude Code membaca semua nilai pluginConfigs dari hanya tiga sumber pengaturan:

• Pengaturan pengguna: ~/.claude/settings.json, file yang ditulis prompt waktu pengaktifan
• --settings: bendera CLI atau pengaturan inline SDK
• Pengaturan terkelola: kebijakan yang dikendalikan organisasi

Ketika lebih dari satu sumber menetapkan kunci yang sama, pengaturan terkelola mengambil alih, kemudian --settings, kemudian pengaturan pengguna. Satu-satunya sumber yang dapat Anda hapus dari daftar ini adalah pengaturan pengguna: teruskan --setting-sources tanpa user dan Claude Code melewatinya. Pengaturan terkelola dan --settings tetap apa pun yang Anda teruskan. Opsi settingSources SDK menetapkan daftar yang sama.

Entri di .claude/settings.json atau .claude/settings.local.json proyek diabaikan. Kedua file berada di workspace, jadi repositori yang dikloning dapat menyediakan nilai di sana, dan nilai-nilai itu akan mengalir ke perintah hook plugin, konfigurasi server MCP, perintah LSP, dan perintah monitor. Sebelum v2.1.207, entri-entri ini dibaca. Pembatasan khusus untuk pluginConfigs: enabledPlugins masih menghormati pengaturan proyek dan lokal.

Batasi bidang ke opsi tetap

Atur options pada bidang userConfig untuk membuat pengguna memilih nilainya dari daftar tetap.

Untuk membatasi bidang tone ke tiga opsi, cantumkan dalam options dan atur default ke salah satunya:

{
  "userConfig": {
    "tone": {
      "type": "string",
      "title": "Tone",
      "description": "Voice for generated replies",
      "options": ["neutral", "warm", "formal"],
      "default": "neutral"
    }
  }
}

Jika Anda mendeklarasikan options pada bidang apa pun, pengguna pada versi Claude Code sebelum v2.1.271 tidak dapat memuat plugin.

Ketika Anda menetapkan options pada bidang, ikuti aturan-aturan ini:

• Atur type ke string
• Jangan atur multiple atau sensitive ke true
• Atur default ke salah satu opsi
• Jika Anda membiarkan default tidak diatur, atur required ke true
• Cantumkan setidaknya satu opsi, masing-masing 1 hingga 64 karakter panjang
• Jangan mulai atau akhiri opsi dengan spasi
• Jangan gunakan karakter kontrol, karakter tak terlihat, karakter yang mengubah arah teks, atau spasi selain spasi biasa dalam opsi
• Jangan cantumkan opsi yang sama dua kali, bahkan dalam huruf case yang berbeda

Jika Anda melanggar salah satu aturan ini, plugin gagal dimuat. Jalankan claude plugin validate untuk melihat bidang mana yang melanggar aturan mana.

Channels

Bidang channels memungkinkan plugin mendeklarasikan satu atau lebih saluran pesan yang menyuntikkan konten ke dalam percakapan. Setiap saluran mengikat ke server MCP yang disediakan plugin.

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Your Telegram user ID"
        }
      }
    }
  ]
}

Bidang server diperlukan dan harus cocok dengan kunci di mcpServers plugin. userConfig per-saluran opsional menggunakan skema yang sama dengan bidang tingkat atas, memungkinkan plugin untuk meminta token bot atau ID pemilik ketika plugin diaktifkan.

Aturan perilaku jalur

Apakah jalur kustom menggantikan atau memperluas direktori default plugin tergantung pada bidangnya:

• Menggantikan default: commands, agents, workflows, outputStyles, experimental.themes, experimental.monitors. Misalnya, ketika manifes menentukan commands, direktori commands/ default tidak dipindai. Untuk menyimpan default dan menambah lebih banyak, cantumkan secara eksplisit: "commands": ["./commands/", "./extras/"]
• Menambah default: skills. Direktori skills/ default selalu dipindai, dan direktori yang tercantum di skills dimuat bersama. Pengecualian: untuk entri marketplace yang source-nya diselesaikan ke akar marketplace, mendeklarasikan subdirektori spesifik menggantikan pemindaian skills/ default
• Aturan penggabungan sendiri: hooks, server MCP, dan server LSP. Lihat setiap bagian untuk cara beberapa sumber menggabungkan

Ketika plugin memiliki folder default dan kunci manifes yang cocok, Claude Code memperingatkan tentang folder yang diabaikan di claude plugin list dan tampilan detail /plugin. Plugin masih dimuat menggunakan jalur manifes. Claude Code tidak memperingatkan ketika kunci manifes menunjuk ke folder default, misalnya "commands": ["./commands/deploy.md"], karena jalur itu menamai folder secara eksplisit.

Untuk semua bidang jalur:

• Semua jalur harus relatif terhadap akar plugin dan dimulai dengan ./, kecuali bidang skills juga menerima "."
  • Baik "." maupun "./" menunjukkan akar plugin itu sendiri
  • Sebelum v2.1.221, "." gagal validasi manifes dan plugin tidak dimuat, jadi gunakan "./" untuk mendukung versi sebelumnya
• Komponen dari jalur kustom menggunakan aturan penamaan dan namespacing yang sama, kecuali file agent. Lihat Agents untuk cara kerja nama agent
• Beberapa jalur dapat ditentukan sebagai array
• Jalur skill dapat menunjuk ke direktori yang berisi SKILL.md secara langsung, misalnya "skills": ["."] untuk akar plugin
  • Claude Code mengambil nama invokasi skill dari bidang frontmatter name di SKILL.md, jadi nama tetap stabil apa pun nama direktori instalasi
  • Jika name tidak diatur di frontmatter, Claude Code kembali ke nama dasar direktori

Plugin yang memiliki SKILL.md di akarnya, tidak ada subdirektori skills/, dan tidak ada bidang manifes skills secara otomatis dimuat sebagai plugin skill tunggal. Anda tidak perlu menetapkan "skills": ["./"] di plugin.json untuk tata letak ini.

Contoh jalur:

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

Variabel lingkungan

Claude Code menyediakan tiga variabel untuk mereferensikan jalur:

Ketiga-tiganya diekspor sebagai variabel lingkungan ke proses hook dan ke subproses server MCP dan LSP. Mereka tidak ada di lingkungan perintah yang Claude jalankan melalui alat Bash, di sesi utama atau di subagent. Dalam konten plugin, tulis placeholder sebagai gantinya, dan Claude Code mensubstitusi jalur inline ketika memuat konten. Bidang mana yang mensubstitusi mereka inline tergantung pada komponen plugin:

Dalam perintah hook, gunakan bentuk exec dengan args sehingga setiap jalur dilewatkan sebagai satu argumen tanpa tanda kutip. Dalam hook bentuk shell dan perintah monitor, bungkus variabel dalam tanda kutip ganda, seperti "${CLAUDE_PROJECT_DIR}/scripts/server.sh". Hook bentuk shell ini menjalankan skrip yang disertakan dengan plugin:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

Untuk plugin yang disalin, ${CLAUDE_PLUGIN_ROOT} berubah ketika plugin diperbarui. Direktori versi sebelumnya tetap di disk untuk periode tenggang setelah pembaruan, tetapi perlakukan sebagai ephemeral dan jangan tulis status di sana. Untuk plugin yang dimuat di tempat dari marketplace direktori lokal, variabel menunjuk ke direktori sumber yang stabil. Lihat plugin caching untuk plugin mana yang disalin dan untuk semantik pembersihan.

Ketika plugin yang disalin diperbarui di tengah sesi, perintah hook, monitor, server MCP, dan server LSP terus menggunakan jalur versi sebelumnya. Jalankan /reload-plugins untuk mengganti hook, server MCP, dan server LSP ke jalur baru; monitor memerlukan restart sesi. Dalam sesi tanpa terminal interaktif, reload meninggalkan server MCP plugin di jalur lama sampai sesi berikutnya.

Untuk plugin dengan sumber command, Claude Code dapat memuat ulang plugin itu sendiri.

Server MCP juga dapat memanggil permintaan roots/list untuk membaca direktori kerja sesi saat runtime. Lihat apa yang dikembalikan roots/list dan kapan Claude Code memberi tahu server tentang perubahan.

Direktori data persisten

Direktori ${CLAUDE_PLUGIN_DATA} diselesaikan ke ~/.claude/plugins/data/{id}/, di mana {id} adalah pengidentifikasi plugin dengan karakter di luar a-z, A-Z, 0-9, _, dan - diganti dengan -. Untuk plugin yang diinstal sebagai formatter@my-marketplace, direktorinya adalah ~/.claude/plugins/data/formatter-my-marketplace/.

Penggunaan umum adalah menginstal ketergantungan bahasa sekali dan menggunakannya kembali di seluruh sesi dan pembaruan plugin. Gunakan untuk ketergantungan Python, ketergantungan yang dikunci dengan Yarn atau pnpm, dan paket yang skrip siklus hidupnya harus berjalan. Untuk plugin yang diinstal marketplace, Anda mungkin tidak membutuhkannya sama sekali: Claude Code secara otomatis menginstal ketergantungan paket Node.js yang memenuhi syarat ketika cache plugin.

Karena direktori data melampaui versi plugin tunggal, pemeriksaan keberadaan direktori saja tidak dapat mendeteksi ketika pembaruan mengubah manifes ketergantungan plugin. Pola yang direkomendasikan membandingkan manifes bundel terhadap salinan di direktori data dan menginstal ulang ketika berbeda.

Hook SessionStart ini menginstal node_modules pada run pertama dan lagi kapan pun pembaruan plugin menyertakan package.json yang berubah:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

diff keluar nonzero ketika salinan yang disimpan hilang atau berbeda dari yang bundel, mencakup run pertama dan pembaruan yang mengubah ketergantungan. Jika npm install gagal, rm trailing menghapus manifes yang disalin sehingga sesi berikutnya mencoba lagi.

Skrip yang disertakan dalam ${CLAUDE_PLUGIN_ROOT} kemudian dapat berjalan terhadap node_modules yang bertahan:

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

Direktori data dihapus secara otomatis ketika Anda mencopot plugin dari ruang lingkup terakhir tempat itu diinstal. Antarmuka /plugin menampilkan ukuran direktori dan meminta sebelum menghapus. CLI menghapus secara default; teruskan --keep-data untuk mempertahankannya.

Plugin caching dan resolusi file

Plugin ditentukan dalam salah satu dari tiga cara:

• Melalui claude --plugin-dir atau claude --plugin-url, untuk durasi sesi.
• Melalui marketplace, diinstal untuk sesi mendatang.
• Melalui akun claude.ai Anda, disinkronkan ke dalam ~/.claude/plugins/synced/.

Untuk tujuan keamanan dan verifikasi, Claude Code menyalin plugin marketplace ke plugin cache lokal pengguna (~/.claude/plugins/cache), kecuali plugin dimuat di tempat. Sebuah command source dalam link mode dimuat di tempat melalui link dalam entri cache. Sebuah relative path source dalam marketplace yang ditambahkan dari direktori lokal dimuat di tempat dari folder marketplace.

Untuk plugin yang dimuat di tempat dari marketplace direktori-lokal, edit Anda ke direktori sumber berlaku pada awal sesi berikutnya atau /reload-plugins. Anda tidak perlu bump versi. Proses hook plugin dan server MCP dan LSP menerima CLAUDE_PLUGIN_ROOT yang menunjuk ke direktori sumber. Claude Code tidak menginstal dependensi paket Node.js plugin ke dalam direktori sumber. Instal mereka di sana sendiri, atau dari hook ke direktori data persisten.

Untuk plugin yang disalin, setiap versi yang diinstal adalah direktori terpisah dalam cache, dikelompokkan berdasarkan marketplace dan plugin serta dinamai untuk versi yang diselesaikan, dengan salinannya sendiri dari file plugin dan dependensi paket Node.js. Dependensi yang diselesaikan dari release tag mendapatkan nama direktori dengan akhiran commit-SHA.

Ketika Anda memperbarui atau mencopot plugin, Claude Code menandai direktori versi sebelumnya sebagai orphaned dan menghapusnya dalam sweep latar belakang kira-kira 14 hari kemudian. Periode grace memungkinkan sesi Claude Code bersamaan yang sudah memuat versi lama untuk terus berjalan tanpa kesalahan. Claude Code menjalankan sweep hanya saat setidaknya satu plugin diinstal; setelah Anda mencopot plugin terakhir Anda, direktori orphaned tetap di disk sampai Anda menginstal plugin lagi.

Claude Code menghapus folder plugin atau marketplace dari cache hanya ketika tidak lagi berisi direktori atau symlink apa pun. Jika Anda membuat symlink dari checkout pengembangan ke dalam cache sebagai entri versi plugin, Claude Code tidak pernah menandai link sebagai orphaned dan tidak pernah menghapusnya atau folder yang menahannya. Claude Code juga tidak pernah menulis file pelacakan versinya di dalam checkout yang ditautkan.

Tools Glob dan Grep Claude melewati direktori versi orphaned selama pencarian, sehingga hasil file tidak menyertakan kode plugin yang sudah ketinggalan zaman.

Dependensi paket Node.js

Ketika Claude Code menyalin plugin ke dalam cache, Claude Code juga menginstal dependensi paket Node.js plugin di sana, sehingga hooks dan MCP servers plugin dapat memuatnya. Bagian ini mencakup paket npm dan Bun yang dideklarasikan plugin dalam package.json miliknya sendiri. Untuk plugin yang bergantung pada plugin lain, lihat versi dependensi plugin.

Claude Code menjalankan install di dalam direktori versi yang disalin setiap kali membuat satu: ketika Anda menginstal plugin, ketika Claude Code memperbarui plugin ke versi baru, dan pada awal sesi ketika plugin yang diaktifkan belum di-cache, seperti pada mesin baru. Install hanya berjalan ketika direktori root plugin berisi package.json dan lockfile yang didukung:

Jika plugin berisi lebih dari satu lockfile ini, Claude Code menggunakan kecocokan pertama, memeriksa secara berurutan: bun.lock, bun.lockb, npm-shrinkwrap.json, package-lock.json.

Claude Code melewati install dalam dua kasus, masing-masing dengan perbaikannya sendiri:

• Jika plugin Anda hanya mengirimkan yarn.lock atau pnpm-lock.yaml, gantikan dengan lockfile npm.
• Jika bunfig.toml berada di samping lockfile bun, hapus bunfig.toml, atau gantikan lockfile bun dengan lockfile npm.

Kirimkan lockfile npm untuk jangkauan terluas. Claude Code menjalankan package manager lockfile yang cocok dari PATH pengguna dan tidak kembali ke lockfile lain jika hilang. Untuk plugin yang didistribusikan melalui sumber npm, gunakan npm-shrinkwrap.json; npm mengecualikan package-lock.json dari paket yang dipublikasikan.

Claude Code membatasi install dependensi ini sehingga tidak ada kode dari plugin atau paketnya yang dieksekusi selama install, dan membatasi berapa lama install dapat berjalan:

• Frozen resolution: Bun dan npm menginstal dengan tepat apa yang dikunci lockfile, dan gagal daripada re-resolve versi ketika package.json dan lockfile tidak setuju.
• No lifecycle scripts: --ignore-scripts menjaga agar script preinstall, install, dan postinstall tidak berjalan, sehingga dependensi yang membangun modul native dalam script tersebut diunduh tetapi tidak dikompilasi selama install ini.
• 60-second timeout: Claude Code menghentikan install yang berjalan lebih lama dan memperlakukannya sebagai gagal.

Claude Code mengambil plugin sumber npm sebelum install dependensi ini, dan tidak ada script install paket sendiri yang berjalan selama pengambilan. Lihat npm packages.

Install yang gagal atau dilewati tidak pernah memblokir plugin. Ketika install gagal, atau Claude Code melewati karena lockfile yarn atau pnpm atau bunfig.toml di samping lockfile bun, Claude Code mencatat alasannya sebagai peringatan dalam debug output. Plugin dengan package.json dan tidak ada lockfile dilewati tanpa entri log. Install yang time-out dapat meninggalkan pohon node_modules parsial dalam salinan cache.

Anda tidak dapat mematikan install otomatis; tidak ada pengaturan atau variabel lingkungan yang menonaktifkannya. Di jaringan terbatas, lihat persyaratan akses jaringan untuk host yang diizinkan.

Untuk dependensi yang install otomatis tidak dapat sediakan, seperti paket yang memerlukan lifecycle scripts mereka untuk membangun, dependensi Python, atau plugin yang dikunci dengan Yarn atau pnpm, instal dari hook ke direktori data persisten.

Batasan path traversal

Claude Code tidak membiarkan plugin mereferensikan file di luar direktorinya sendiri. Claude Code menolak path komponen yang diselesaikan di luar root plugin, apakah path dideklarasikan dalam plugin.json atau dalam entri marketplace. Itu mencakup path yang menunjuk di luar plugin seperti yang ditulis, seperti ../shared-utils, dan symlink yang mengarah di luar plugin, selain link dalam satu marketplace.

Di macOS dan Linux, Claude Code juga menolak path komponen yang berisi backslash di mana pun dalam path, bahkan ketika path tetap berada di dalam plugin. Komponen yang dideklarasikan dengan path backslash oleh karena itu hanya dimuat di Windows. Tulis path komponen dengan forward slash, seperti ./commands/deploy.md.

Ketika Claude Code menolak path, Claude Code melaporkan error path escapes plugin directory dan memuat plugin tanpa komponen tersebut.

Claude Code juga tidak menyalin file di luar direktori plugin ke dalam cache ketika menginstal plugin, jadi ketika script di dalam plugin yang disalin membaca path di atas root plugin, script tidak menemukan file tersebut juga.

Bagikan file dalam marketplace dengan symlink

Jika plugin Anda perlu berbagi file dengan bagian lain dari marketplace yang sama, Anda dapat membuat symbolic link di dalam direktori plugin Anda. Bagaimana symlink ditangani ketika plugin disalin ke dalam cache tergantung pada di mana targetnya diselesaikan:

• Dalam direktori plugin sendiri: symlink dipertahankan sebagai symlink relatif dalam cache, sehingga tetap diselesaikan ke target yang disalin saat runtime.
• Di tempat lain dalam marketplace yang sama: symlink didereferensikan. Konten target disalin ke dalam cache di tempatnya. Ini memungkinkan direktori skills/ meta-plugin untuk menautkan ke skill yang ditentukan oleh plugin lain dalam marketplace.
• Di luar marketplace: symlink dilewati untuk keamanan. Ini mencegah plugin dari menarik file host arbitrer seperti path sistem ke dalam cache.

Untuk plugin yang diinstal dengan --plugin-dir, dari path lokal, atau dari command source dalam copy mode, hanya symlink yang diselesaikan dalam direktori plugin sendiri yang dipertahankan. Semua yang lain dilewati.

Perintah berikut membuat link dari dalam plugin marketplace ke skill bersama yang ditentukan oleh plugin sibling. Di Windows, gunakan mklink /D dari Command Prompt yang ditingkatkan atau aktifkan Developer Mode:

ln -s ../../shared-plugin/skills/foo ./skills/foo

Struktur direktori plugin

Tata letak plugin standar

Plugin lengkap mengikuti struktur ini:

enterprise-plugin/
├── .claude-plugin/           # Direktori metadata (opsional)
│   └── plugin.json             # manifes plugin
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills sebagai file .md datar
│   ├── status.md
│   └── logs.md
├── agents/                   # Definisi subagent
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   ├── compliance-checker.md
│   └── review/               # Agents di sini dimuat sebagai enterprise-plugin:review:<name>
│       └── accessibility.md
├── workflows/                # Skrip workflow
│   └── release-audit.js
├── output-styles/            # Definisi gaya output
│   └── terse.md
├── themes/                   # Definisi tema warna
│   └── dracula.json
├── monitors/                 # Konfigurasi monitor latar belakang
│   └── monitors.json
├── hooks/                    # Konfigurasi hooks
│   ├── hooks.json           # Konfigurasi hook utama
│   └── security-hooks.json  # Hooks tambahan
├── bin/                      # Plugin yang dapat dijalankan ditambahkan ke PATH
│   └── my-tool               # Dapat dipanggil sebagai perintah bare di Bash tool
├── settings.json            # Pengaturan default untuk plugin
├── .mcp.json                # Definisi server MCP
├── .lsp.json                # Konfigurasi server LSP
├── scripts/                 # Skrip hook dan utilitas
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # File lisensi
└── CHANGELOG.md             # Riwayat versi

File CLAUDE.md di root plugin tidak dimuat sebagai konteks proyek. Plugin berkontribusi konteks melalui skills, agents, dan hooks daripada CLAUDE.md. Untuk mengirimkan instruksi yang dimuat ke dalam konteks Claude, letakkan di skill.

Referensi lokasi file

Referensi perintah CLI

Claude Code menyediakan perintah CLI untuk manajemen plugin non-interaktif, berguna untuk skrip dan otomasi.

plugin init

Membuat perancah plugin baru di ~/.claude/skills/<name>/. Pada sesi Claude Code berikutnya, plugin akan dimuat secara otomatis sebagai <name>@skills-dir dan muncul di /plugin dan claude plugin list tanpa langkah instalasi.

Lihat Skills-directory plugins untuk persyaratan cakupan dan kepercayaan.

claude plugin init <name> [options]

Perintah ini mengambil argumen-argumen berikut:

• <name>: Nama plugin. Menjadi namespace skill dan nama direktori di bawah ~/.claude/skills/, jadi tidak boleh mengandung spasi atau pemisah jalur.

Perintah ini menerima opsi-opsi berikut:

claude plugin new adalah alias untuk perintah ini.

Setiap nilai --with menambahkan file pemula untuk komponen tersebut, siap untuk diedit:

Plugin yang dibuat perancah menggunakan sumber @skills-dir daripada marketplace. Admin dapat memblokir sumber ini dengan strictKnownMarketplaces atau dengan menambahkan {"source": "skills-dir"} ke blockedMarketplaces dalam managed settings. Ketika diblokir, plugin init gagal sebelum menulis.

Contoh-contoh ini menunjukkan invokasi umum:

# Membuat perancah plugin minimal
claude plugin init my-helper

# Membuat perancah dengan folder skill dan hook
claude plugin init my-helper --with skills hooks

# Timpa perancah yang ada
claude plugin init my-helper --force

plugin install

Instal plugin dari marketplace yang tersedia.

claude plugin install <plugin> [options]

Perintah ini mengambil argumen-argumen berikut:

• <plugin>: Nama plugin atau plugin-name@marketplace-name untuk marketplace tertentu

Perintah ini menerima opsi-opsi berikut:

Cakupan menentukan file pengaturan mana yang ditambahkan plugin yang diinstal. Misalnya, --scope project menulis ke enabledPlugins dalam .claude/settings.json, membuat plugin tersedia untuk semua orang yang mengkloning repositori proyek.

Dengan --json, baris terakhir stdout adalah satu objek JSON. Parsing hanya baris itu, karena Claude Code mencetak perintah apa pun yang dideklarasikan marketplace sebelumnya. Tiga field selalu ada:

• command: subperintah yang dijalankan, seperti install
• outcome: ok atau failed
• message: deskripsi hasil yang dapat dibaca manusia

Field lain, seperti pluginId, scope, dan failureCode, muncul hanya ketika berlaku. Opsi --json pada plugin uninstall, plugin update, plugin enable, dan plugin disable mencetak objek yang sama dengan field subperintah tersebut. Kesalahan penggunaan, seperti --scope yang tidak valid, tidak mencetak baris hasil dan keluar 1 dengan alasan di stderr.

Ketika run menampilkan perintah yang dideklarasikan marketplace dan tidak menjalankannya, hasil failed juga membawa objek shownCommand yang field-nya mencakup perintah seperti yang ditampilkan, plugin yang dimilikinya, dan sha256 perintah. Untuk menerima perintah yang tepat, jalankan kembali dengan sha256 itu sebagai --accept-command. Memerlukan Claude Code v2.1.271 atau lebih baru.

Jika shownCommand.acceptCommandMatched adalah false, digest yang Anda lewatkan tidak cocok dengan perintah yang sekarang ditampilkan. Tampilkan perintah itu kepada seseorang sebelum melewatkan sha256-nya.

Contoh-contoh ini menunjukkan invokasi umum:

# Instal ke cakupan pengguna (default)
claude plugin install formatter@my-marketplace

# Instal ke cakupan proyek (dibagikan dengan tim)
claude plugin install formatter@my-marketplace --scope project

# Instal ke cakupan lokal (tidak dibagikan dengan tim)
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

Hapus plugin yang diinstal.

claude plugin uninstall <plugin> [options]

Perintah ini mengambil argumen-argumen berikut:

• <plugin>: Nama plugin atau plugin-name@marketplace-name

Perintah ini menerima opsi-opsi berikut:

claude plugin remove dan claude plugin rm adalah alias untuk perintah ini.

Secara default, mencopot instalasi dari cakupan terakhir yang tersisa juga menghapus direktori ${CLAUDE_PLUGIN_DATA} plugin. Gunakan --keep-data untuk mempertahankannya, misalnya saat menginstal ulang setelah menguji versi baru.

plugin prune

Hapus dependensi plugin yang diinstal otomatis yang tidak lagi diperlukan oleh plugin yang diinstal. Dependensi yang Claude Code tarik untuk memenuhi field dependencies plugin lain dihapus; plugin yang Anda instal secara langsung tidak pernah disentuh.

claude plugin prune [options]

Perintah ini menerima opsi-opsi berikut:

claude plugin autoremove adalah alias untuk perintah ini.

Perintah mencantumkan dependensi yatim piatu dan meminta konfirmasi sebelum menghapusnya. Untuk menghapus plugin dan membersihkan dependensinya dalam satu langkah, jalankan claude plugin uninstall <plugin> --prune.

plugin enable

Aktifkan plugin yang dinonaktifkan. Ketika target diinstal dari marketplace dan mendeklarasikan dependencies, Claude Code mengaktifkannya secara transitif pada cakupan yang sama. Perintah gagal dalam kondisi yang Enable or disable a plugin with dependencies daftar.

claude plugin enable <plugin> [options]

Perintah ini mengambil argumen-argumen berikut:

• <plugin>: Nama plugin, plugin-name@marketplace-name, atau plugin-name@synced untuk plugin yang disinkronkan dari claude.ai

Perintah ini menerima opsi-opsi berikut:

plugin disable

Nonaktifkan plugin tanpa mencopot instalasinya.

Ketika target diinstal dari marketplace, perintah gagal jika plugin yang diaktifkan lain bergantung pada itu. Pesan kesalahan mencakup perintah berantai yang menonaktifkan setiap plugin yang bergantung padanya terlebih dahulu.

Untuk plugin yang disinkronkan yang organisasi Anda perlukan, perintah gagal dan tidak menyimpan apa pun.

claude plugin disable [plugin] [options]

Perintah ini mengambil argumen-argumen berikut:

• [plugin]: Nama plugin, plugin-name@marketplace-name, atau plugin-name@synced untuk plugin yang disinkronkan dari claude.ai. Opsional saat menggunakan --all

Perintah ini menerima opsi-opsi berikut:

plugin update

Perbarui plugin ke versi terbaru.

claude plugin update <plugin> [options]

Perintah ini mengambil argumen-argumen berikut:

• <plugin>: Nama plugin atau plugin-name@marketplace-name

Perintah ini menerima opsi-opsi berikut:

plugin list

Daftar plugin yang diinstal dengan versi, marketplace sumber, dan status pengaktifan mereka.

claude plugin list [options]

Perintah ini menerima opsi-opsi berikut:

Dalam sesi interaktif, /plugin list mencetak daftar serupa secara inline, tetapi mencakup hanya plugin yang diinstal marketplace:

• Plugin yang dimuat dari direktori skills muncul di antarmuka /plugin dan dalam claude plugin list, tetapi tidak dalam output /plugin list inline.
• Plugin yang disinkronkan dari claude.ai muncul dalam claude plugin list pada Claude Code v2.1.239 atau lebih baru dan di antarmuka /plugin, tetapi tidak dalam output /plugin list inline.
• Plugin yang dimuat untuk sesi dengan --plugin-dir atau --plugin-url muncul di antarmuka /plugin, dan dalam claude plugin list hanya ketika flag yang sama mendahului subperintah, seperti dalam claude --plugin-dir <dir> plugin list. Hanya nama flag lokasi mereka, jadi claude plugin list tanpa kualifikasi tidak dapat menemukannya, tidak seperti plugin yang disinkronkan dan plugin direktori skills, yang direktorinya tetap Claude Code pindai.

Bentuk interaktif menerima --enabled atau --disabled untuk menampilkan hanya plugin dalam status itu, dan ls sebagai singkatan untuk list.

plugin details

Tampilkan inventaris komponen plugin dan biaya token yang diproyeksikan. Output mencantumkan semua komponen yang disumbangkan plugin, dikelompokkan sebagai Skills, Agents, Hooks, server MCP, dan server LSP, bersama dengan perkiraan berapa banyak token yang ditambahkannya ke setiap sesi. Grup Skills mencakup entri skills/ dan commands/.

claude plugin details <name>

Perintah ini mengambil argumen-argumen berikut:

• <name>: Nama plugin atau plugin-name@marketplace-name

Perintah ini menerima opsi-opsi berikut:

Output menampilkan dua angka biaya untuk setiap komponen:

• Always-on: token yang ditambahkan ke setiap sesi oleh teks daftar plugin, seperti deskripsi skill, deskripsi agent, dan nama perintah, terlepas dari apakah komponen apa pun diaktifkan.
• On-invoke: token yang dihabiskan komponen saat diaktifkan. Ditampilkan per komponen, bukan sebagai total plugin, karena sesi khas hanya mengaktifkan subset komponen.

Contoh ini menunjukkan seperti apa output untuk plugin dengan dua skill:

dependency-guard 1.2.0
  Dependency analysis for Claude Code sessions
  Source: dependency-guard@example-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  SessionStart  (harness-only — no model context cost)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~180 tok   added to every session

Per-component (rounded)
  component            always-on  on-invoke
  scan-dependencies        ~100      ~2400
  review-changes            ~80      ~1800

  On-invoke cost is paid each time a skill or agent fires.
  Token counts are estimates and may differ from actual usage.

Total always-on dihitung melalui API count_tokens untuk model aktif Anda. Angka per-komponen diskalakan secara proporsional dari total itu. Jika API tidak dapat dijangkau, perintah kembali ke perkiraan berbasis karakter.

plugin validate

Periksa plugin atau marketplace untuk kesalahan sintaks dan skema sebelum menerbitkan.

Perintah keluar 0 ketika validasi lulus, 1 ketika gagal, dan 2 ketika validasi itu sendiri gagal, seperti ketika jalur yang Anda berikan tidak dapat dibaca.

claude plugin validate <path> [options]

Perintah ini mengambil argumen-argumen berikut:

• <path>: Jalur ke direktori plugin atau direktori marketplace. Lihat Validate a plugin or a directory without a manifest untuk file mana yang dicakup plugin run.

Perintah ini menerima opsi-opsi berikut:

Dengan --json, Claude Code menulis laporan ke stdout sebagai satu objek JSON dengan field tingkat atas ini:

• success: versi yang sama yang diberikan kode keluar
• strict: apakah run memperlakukan peringatan sebagai kesalahan
• target: jalur yang diselesaikan Claude Code divalidasi
• manifest: hasil manifest itu sendiri, atau null untuk run tanpa manifest
• contents: hasil per-file, masing-masing menamai file-nya dan membawa array errors, warnings, dan notes

Pada keluar 2, perintah tidak menulis apa pun ke stdout; pesan kesalahan masuk ke stderr.

Dalam sesi interaktif, /plugin validate <path> menjalankan pemeriksaan yang sama secara inline.

plugin eval

Jalankan eval cases plugin dan laporkan hasil yang diskor. Memerlukan Claude Code v2.1.269 atau lebih baru. Setiap case adalah prompt plus graders; Claude Code menjalankannya beberapa kali dalam sesi terisolasi dengan hanya plugin target yang dimuat, dan secara default juga tanpa plugin sehingga laporan menunjukkan perbedaannya. Lihat Test plugins with evals untuk format case, graders, hasil, dan penggunaan CI.

claude plugin eval [target] [options]

Target opsional adalah direktori plugin, file prompt.md atau case.yaml tunggal, plugin yang diinstal sebagai name atau name@marketplace, atau name@skills-dir, dan default ke direktori saat ini. Letakkan sebelum --tag, --allow-tools, dan --json.

Tabel ini mencantumkan opsi yang paling banyak digunakan run. Jalankan claude plugin eval --help untuk set lengkap, termasuk --case, --tag, --output-dir, --report, --allow-real-servers, --keep-temp, dan --verbose.

Perintah keluar 0 ketika setiap case memenuhi threshold, 1 pada case yang gagal, kesalahan load, atau direktori plugin yang tidak dipercaya, 2 pada run parsial, 130 ketika terputus, dan 143 ketika dihentikan. Lihat Run evals in CI.

plugin eval init

Buat suite eval untuk plugin di direktori saat ini. Memerlukan Claude Code v2.1.269 atau lebih baru. Di terminal ini memulai wawancara penulisan yang membaca plugin, mengusulkan cases dan graders, pilot mereka, dan menulis file. Dengan --bare, atau tanpa terminal, itu menulis template single-case kosong sebagai gantinya. Jalankan dari dalam sesi Claude Code interaktif, itu mencetak instruksi wawancara untuk sesi itu ikuti daripada menulis template. Lihat Create your first eval suite.

claude plugin eval init [name] [options]

Name opsional adalah case name: wawancara tidak memerlukan satu, sementara --bare dan path template no-terminal memerlukan satu. Itu menerima opsi ini:

plugin tag

Buat tag git rilis untuk plugin. Secara default perintah menandai plugin di direktori saat ini; berikan jalur untuk menandai plugin di tempat lain. Lihat Tag plugin releases.

claude plugin tag [path] [options]

Perintah ini mengambil argumen-argumen berikut:

• [path]: Jalur ke direktori plugin. Default ke direktori saat ini.

Perintah ini menerima opsi-opsi berikut:

Alat debugging dan pengembangan

Perintah debugging

Gunakan claude --debug untuk melihat detail pemuatan plugin:

Ini menampilkan:

• Plugin mana yang sedang dimuat
• Kesalahan apa pun dalam manifes plugin
• Pendaftaran skill, agent, dan hook
• Inisialisasi server MCP

Masalah umum

Contoh pesan kesalahan

Kesalahan validasi manifes:

• Invalid JSON syntax: Unexpected token } in JSON at position 142: periksa koma yang hilang, koma berlebih, atau string yang tidak dikutip
• Plugin <name> has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Invalid input: expected string, received undefined: field yang diperlukan hilang
• Plugin <name> has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: kesalahan sintaks JSON. Sebelum v2.1.246, Claude Code juga menghasilkan kesalahan ini untuk plugin.json yang disimpan sebagai UTF-8 dengan byte-order mark (BOM) di awal, bahkan ketika JSON sebaliknya valid.

Kesalahan pemuatan plugin:

• Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.: path command ada tetapi tidak berisi file command yang valid
• Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.: path source di marketplace.json menunjuk ke direktori yang tidak ada
• Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.: hapus definisi komponen duplikat atau hapus strict: false di entri marketplace

Hook troubleshooting

Hook script tidak dieksekusi:

1. Periksa script dapat dieksekusi: chmod +x ./scripts/your-script.sh
2. Verifikasi baris shebang: Baris pertama harus #!/bin/bash atau #!/usr/bin/env bash
3. Periksa path menggunakan ${CLAUDE_PLUGIN_ROOT}: "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"
4. Uji script secara manual: ./scripts/your-script.sh

Hook tidak dipicu pada event yang diharapkan:

1. Verifikasi nama event benar (case-sensitive): PostToolUse, bukan postToolUse
2. Periksa pola matcher cocok dengan tools Anda: "matcher": "Write|Edit" untuk operasi file
3. Konfirmasi tipe hook valid: command, http, mcp_tool, prompt, atau agent

MCP server troubleshooting

Server tidak memulai:

1. Periksa command ada dan dapat dieksekusi
2. Verifikasi semua path menggunakan variabel ${CLAUDE_PLUGIN_ROOT}
3. Periksa log server MCP: claude --debug menampilkan kesalahan inisialisasi
4. Uji server secara manual di luar Claude Code

Tool server tidak muncul:

1. Pastikan server dikonfigurasi dengan benar di .mcp.json atau plugin.json
2. Verifikasi server mengimplementasikan protokol MCP dengan benar
3. Periksa timeout koneksi di output debug

Kesalahan struktur direktori

Gejala: Plugin dimuat tetapi komponen (skills, agents, hooks) hilang.

Struktur yang benar: Komponen harus berada di root plugin, bukan di dalam .claude-plugin/. Hanya plugin.json yang termasuk dalam .claude-plugin/.

Daftar periksa debug:

1. Jalankan claude --debug dan cari pesan "loading plugin"
2. Periksa bahwa setiap direktori komponen terdaftar di output debug
3. Verifikasi izin file memungkinkan membaca file plugin

Referensi distribusi dan versioning

Manajemen versi

Claude Code menggunakan versi plugin sebagai cache key yang menentukan apakah update tersedia. Ketika Anda menjalankan /plugin update atau auto-update aktif, Claude Code menghitung versi saat ini dan melewati update jika cocok dengan yang sudah terinstal. Plugin yang dimuat di tempat dari marketplace direktori lokal memuat file sumber saat ini di setiap awal sesi, apa pun yang dikatakan string versinya.

Untuk setiap tipe sumber kecuali command, Claude Code menyelesaikan versi dari yang pertama dari ini yang diatur:

1. Field version dalam plugin.json plugin
2. Field version dalam entri marketplace plugin dalam marketplace.json
3. SHA commit git dari sumber plugin, untuk sumber github, url, git-subdir, dan relative-path dalam marketplace yang di-host git
4. Digest SHA-256, untuk sumber archive: pin sha256 dalam entri marketplace, atau digest dari file yang diunduh ketika Anda tidak menetapkan pin. Claude Code mempersingkatnya menjadi 12 karakter pertama
5. unknown, untuk sumber npm atau direktori lokal yang tidak berada dalam repositori git. Claude Code tidak mengambil versi dari repositori yang menutup path instalasi, seperti ~/.claude yang dikelola git

Untuk sumber command, Claude Code selalu menurunkan versi dari apa yang dihasilkan perintah: hash konten 12-karakter sendiri, atau ditambahkan ke versi plugin.json sebagai <version>-<hash> ketika satu diatur. Claude Code mengabaikan field version entri marketplace untuk sumber command. Perintah yang output hash-nya berubah oleh karena itu menghasilkan versi baru, bahkan ketika string versi yang ditulis tetap sama. Dalam link mode, hash mencakup path nyata direktori yang dicetak dan entri tingkat atasnya daripada konten file.

Untuk tipe sumber tersebut, ini memberi Anda tiga cara untuk membuat versi plugin:

Jika Anda menggunakan versi eksplisit, ikuti semantic versioning (MAJOR.MINOR.PATCH): naikkan MAJOR untuk perubahan breaking, MINOR untuk fitur baru, PATCH untuk perbaikan bug. Dokumentasikan perubahan dalam CHANGELOG.md.

Lihat juga

• Plugins - Tutorial dan penggunaan praktis
• Plugin marketplaces - Membuat dan mengelola marketplace
• Skills - Detail pengembangan skill
• Subagents - Konfigurasi dan kemampuan agent
• Hooks - Penanganan event dan otomasi
• MCP - Integrasi alat eksternal
• Settings - Opsi konfigurasi untuk plugins