SpyBara
Go Premium

plugins/manifest-reference.md 2026-11-09 23:02 UTC to 2026-11-10 21:57 UTC

This page contains 56 additions and 56 deletions.

2026
Wed 4 23:59 Tue 10 21:57 Wed 11 22:59

Referensi manifest plugin

Referensi lengkap untuk plugin.json: setiap field dengan tipenya dan default, bentuk path yang diterima, dan skema userConfig serta variabel lingkungan.

Manifest plugin adalah file plugin.json di direktori .claude-plugin/ plugin. File ini membawa metadata plugin dan nilai userConfig yang diminta Claude Code kepada pengguna. File ini juga mendeklarasikan komponen apa pun yang Anda tentukan secara inline atau simpan di luar lokasi defaultnya.

Referensi ini untuk pembuat plugin, dan untuk pemilik marketplace yang menempatkan field komponen dalam entri marketplace.

[!NOTE]

Kasus-kasus ini tercakup di halaman lain:

Mulai dari bagian yang sesuai dengan apa yang Anda cari:

  • Sebuah field: tabel Fields memberikan tipe setiap field, apakah diperlukan, defaultnya, dan apa yang diterima. Path rules mencakup awalan ./ dan containment untuk setiap path komponen
  • Opsi userConfig atau entri channels: skema User configuration dan Channels
  • ${CLAUDE_PLUGIN_ROOT} atau variabel lain yang dapat direferensikan plugin: Environment variables
  • Di mana file setiap komponen berada: Standard layout
  • Pesan dari claude plugin validate: halaman troubleshooting mencantumkan setiap pesan dengan perbaikannya dan tautan ke bagian relevan di halaman ini

Manifest file

Manifest bersifat opsional. Tanpanya, Claude Code memuat komponen yang ditemukannya di standard layout. Nama plugin kemudian berasal dari entri marketplace, atau dari nama direktori saat Anda memuat plugin dengan --plugin-dir.

Tulis manifest saat Anda menginginkan metadata, komponen di luar direktori defaultnya, userConfig, atau definisi komponen inline.

Simpan manifest di .claude-plugin/plugin.json di bawah root plugin. Letakkan setiap file plugin lainnya di root plugin, bukan di dalam .claude-plugin/. Ini termasuk skills/, commands/, dan hooks/.

Contoh berikut menetapkan sebagian besar kunci dalam tabel Fields. Ini melewati validasi di direktori plugin yang berisi setiap path yang direferensikan.

{
  "name": "deploy-tools",
  "displayName": "Deploy Tools",
  "version": "1.2.0",
  "description": "Deployment commands, a review agent, and a status monitor",
  "author": {
    "name": "Example Team",
    "email": "dev@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/docs/deploy-tools",
  "repository": "https://github.com/example/deploy-tools",
  "license": "MIT",
  "keywords": ["deployment", "ci"],
  "defaultEnabled": true,
  "dependencies": ["secrets-vault"],
  "metadata": { "catalogId": "cat-123" },
  "skills": ["./extra-skills/"],
  "commands": {
    "status": {
      "source": "./commands/status.md",
      "description": "Show the current deployment status"
    },
    "about": {
      "content": "Explain what the deploy-tools plugin provides.",
      "description": "Describe this plugin"
    }
  },
  "agents": ["./agents/reviewer.md"],
  "hooks": "./config/extra-hooks.json",
  "mcpServers": {
    "deploy-api": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  },
  "lspServers": "./.lsp.json",
  "outputStyles": "./styles/",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./config/monitors.json"
  },
  "userConfig": {
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for the deployment API",
      "sensitive": true
    }
  }
}

Unrecognized fields

Kunci tingkat atas yang tidak dikenali akan dihapus, dan kunci yang tidak dikenali di dalam opsi userConfig, entri channels, config lspServers, atau entri monitors akan ditolak:

  • Top-level fields: field dihapus dan plugin dimuat. claude plugin validate melaporkan setiap field tingkat atas yang tidak dikenali sebagai peringatan
  • Strict objects: opsi userConfig, entri channels, config lspServers, dan entri monitors bersifat ketat. Kunci yang tidak diketahui di dalamnya adalah kesalahan, dan plugin tidak dimuat

Validate the manifest

claude plugin validate adalah pemeriksaan otoritatif untuk manifest. Jalankan dari shell Anda terhadap direktori plugin:

claude plugin validate ./my-plugin

Perintah melaporkan salah satu hasil berikut:

  • Validation passed: manifest dimuat
  • Validation passed with warnings: manifest dimuat, tetapi validator menemukan sesuatu untuk diperbaiki, seperti field tingkat atas yang tidak diketahui yang Claude Code hapus, name yang bukan kebab-case, atau version, description, atau author yang hilang. Lewatkan --strict untuk mengubah peringatan menjadi kegagalan di CI
  • Validation failed: manifest memiliki ketidakcocokan tipe, path yang hilang atau keluar dari root plugin, atau kunci yang tidak diketahui di dalam opsi userConfig, entri channels, config lspServers, atau entri monitors. Claude Code melaporkan masalah yang sama saat memuat plugin

Perintah juga memeriksa setiap entri server MCP yang dideklarasikan plugin dalam .mcp.json, dalam file .json yang dinamai mcpServers, atau inline dalam plugin.json. Pemeriksaan MCP ini memerlukan Claude Code v2.1.281 atau lebih baru dan mencakup:

  • Errors: entri yang Claude Code akan hapus saat memuat plugin, referensi ${user_config.KEY} ke opsi yang tidak dideklarasikan manifest, dan url jarak jauh yang bukan URL absolut yang valid
  • Warnings: http:// atau ws:// URL ke host non-loopback, dan nilai header yang terlihat seperti kredensial literal

Field

Tabel berikut mencantumkan kunci tingkat atas dalam plugin.json. name adalah satu-satunya kunci yang wajib. Jika nama field berupa tautan, bagian yang ditautkan memuat aturan lengkapnya.

Untuk kunci komponen seperti commands dan hooks, Bentuk path komponen menunjukkan setiap bentuk yang diterima beserta contohnya, dan setiap path mengikuti aturan path untuk prefiks ./, ekstensi, dan batasan cakupan.

Field Tipe Deskripsi
$schema String URL JSON Schema untuk pelengkapan otomatis editor. Claude Code mengabaikannya saat pemuatan
name String Pengenal plugin, wajib. Gunakan kebab-case. Setiap komponen diberi namespace di bawahnya
displayName String Nama yang ditampilkan di UI sebagai pengganti name
version String String versi. Menetapkannya membuat pengguna tetap pada versi tersebut hingga Anda mengubahnya
description String Penjelasan singkat tentang apa yang disediakan plugin
author Object name, yang wajib, ditambah email dan url opsional
homepage String URL dokumentasi. Harus dapat diurai sebagai URL, jika tidak plugin gagal dimuat
repository String URL repositori sumber. Tidak divalidasi
license String Pengenal SPDX seperti MIT atau Apache-2.0
keywords Array of strings Tag penemuan
metadata Object Objek bebas untuk data Anda sendiri. Claude Code tidak membacanya
icon String Ikon untuk listing plugin di direktori Anthropic. Claude Code tidak membacanya
documentationUrl String Tautan dokumentasi untuk listing plugin di direktori Anthropic. Claude Code tidak membacanya
supportUrl String Tautan dukungan untuk listing plugin di direktori Anthropic. Claude Code tidak membacanya
privacyPolicyUrl String Tautan kebijakan privasi untuk listing plugin di direktori Anthropic. Claude Code tidak membacanya
termsOfServiceUrl String Tautan ketentuan layanan untuk listing plugin di direktori Anthropic. Claude Code tidak membacanya
defaultEnabled Boolean Apakah plugin dimulai dalam keadaan aktif ketika pengguna belum mengaturnya. Default-nya true
dependencies Array of strings or objects Plugin yang harus diaktifkan agar plugin ini berfungsi
settings Object Pengaturan yang diterapkan Claude Code selama plugin aktif. Hanya agent dan subagentStatusLine yang berlaku
userConfig Object Nilai yang diminta Claude Code dari pengguna ketika plugin diaktifkan
types Path File .d.ts yang mendeklarasikan nilai $.state dan nomina $ dari sebuah mod
channels Array of objects Channel pesan yang disediakan plugin, masing-masing terikat ke salah satu server MCP-nya
skills Path, or array of paths Direktori yang dipindai untuk skill, masing-masing berupa direktori berisi folder <name>/SKILL.md atau satu folder yang langsung memuat SKILL.md. "." menunjuk root plugin. Menambah pemindaian default skills/
commands Path, array of paths, or object File perintah .md datar, direktori yang berisi file tersebut, atau peta objek dari nama perintah ke source atau content. Menggantikan pemindaian default commands/
agents Path, or array of paths File agent .md. Direktori tidak diterima. Menggantikan pemindaian default agents/
hooks Path, object, or array of either File hook .json atau konfigurasi hook inline. Dimuat bersama hooks/hooks.json
mcpServers Path, object, or array of either File konfigurasi MCP .json, bundel .mcpb atau .dxt, atau konfigurasi server inline yang dikunci berdasarkan nama. Dimuat bersama .mcp.json; nama server yang dideklarasikan belakangan menggantikan yang lebih awal
lspServers Path, object, or array of either File konfigurasi LSP .json atau konfigurasi server inline yang dikunci berdasarkan nama. Dimuat bersama .lsp.json
outputStyles Path, or array of paths File atau direktori gaya output. Menggantikan pemindaian default output-styles/
workflows Path, or array of paths File atau direktori workflow .js. Menggantikan pemindaian default workflows/
experimental Object Wadah untuk themes, monitors, dan evals, yang bentuk manifesnya masih dapat berubah
experimental.themes Path, or array of paths File atau direktori tema. Menggantikan pemindaian default themes/. Kunci themes tingkat atas tetap dimuat, dengan peringatan claude plugin validate
experimental.monitors Path, or inline array File .json yang memuat array monitor, atau array itu sendiri. Default-nya monitors/monitors.json. Kunci monitors tingkat atas tetap dimuat, dengan peringatan claude plugin validate. Monitor tidak dimulai dengan flag -p
experimental.evals Path, or array of paths Direktori yang memuat kasus eval plugin ketika bukan default evals/. claude plugin eval --eval-dir menimpanya

Di kolom Tipe, path adalah string yang relatif terhadap root plugin, seperti "./custom/commands".

name

Pengenal plugin. Nilainya tidak boleh kosong, tanpa spasi, @, :, pemisah path, karakter kontrol, atau karakter pemformatan dua arah; gunakan kebab-case.

Claude Code memberi namespace pada setiap komponen di bawahnya, sehingga agent reviewer di plugin deploy-tools muncul sebagai deploy-tools:reviewer.

claude plugin validate juga memeriksa bahwa nama tersebut tidak menyamar sebagai salah satu plugin milik Anthropic sendiri. Pemeriksaan ini mengabaikan huruf besar/kecil dan memperlakukan rangkaian pemisah apa pun sebagai satu:

Nama Hasil
Diawali dengan claude-, anthropic-, anthropics-, atau cc-plugin- Error
Berupa claude, anthropic, anthropics, claude-code, atau claude-mods Error
Menempatkan official di samping claude atau anthropic, seperti official-claude-tools Error
Memuat claude, anthropic, atau anthropics sebagai kata utuh di tempat lain, seperti mcp-for-claude Peringatan

Pesan error-nya berbunyi Plugin name "<name>" is reserved: it passes as one of Anthropic's own, dan peringatannya berbunyi Plugin name "<name>" reads as one of Anthropic's own. claude plugin init dan claude plugin tag menolak nama yang memicu error tersebut. Claude Code tetap menginstal dan memuat plugin yang namanya ditolak oleh keduanya.

displayName

Nama yang ditampilkan di UI sebagai pengganti name. Nama ini boleh memuat spasi dan huruf besar/kecil apa pun, dan tidak digunakan untuk namespace atau pencarian.

Untuk plugin yang diinstal dari marketplace, displayName pada entri marketplace diutamakan daripada nilai ini.

version

String versi, tidak diperiksa terhadap semver. Menetapkannya akan mengunci plugin pada versi tersebut hingga Anda mengubahnya; lihat Versi dan pembaruan. Plugin dengan sumber command, plugin dari marketplace yang di-host di claude.ai, dan plugin yang dimuat di tempat dari marketplace yang ditambahkan dari path lokal tidak dikunci oleh field ini.

metadata

Objek bebas untuk data Anda sendiri, seperti field katalog atau hak akses. Claude Code tidak membacanya.

Field listing direktori

Direktori Anthropic membaca field icon, documentationUrl, supportUrl, privacyPolicyUrl, dan termsOfServiceUrl dari plugin.json untuk listing plugin Anda ketika Anda mengirimkan plugin. Claude Code mengabaikannya saat pemuatan. Tetapkan field tersebut hanya di plugin.json. Dalam entri marketplace, claude plugin validate melaporkan masing-masing sebagai field yang tidak dikenal.

Tetapkan icon ke path file gambar di dalam plugin, seperti ./logo.png, dan masing-masing dari keempat field URL ke URL https://.

[!NOTE]

claude plugin validate tidak melaporkan field-field ini di plugin.json sebagai tidak dikenal pada Claude Code v2.1.281 atau yang lebih baru. Versi sebelumnya mencetak peringatan Unknown field untuk masing-masing field, sehingga eksekusi --strict gagal pada versi tersebut.

defaultEnabled

Apakah plugin dimulai dalam keadaan aktif ketika pengguna belum mengaturnya di enabledPlugins. Default-nya true. Plugin yang menjadi dependensi dari plugin yang aktif tetap dimulai dalam keadaan aktif apa pun nilainya. Field yang sama di entri marketplace menimpa field ini.

Setelah entri enabledPlugins pengguna ditulis, entri tersebut tetap bertahan di seluruh pembaruan plugin, sehingga mengubah defaultEnabled di rilis berikutnya tidak mengubah pengaturan untuk pengguna yang sudah ada.

dependencies

Plugin yang harus diaktifkan agar plugin ini berfungsi. Setiap entri berupa "name", "name@marketplace", atau { "name": "...", "marketplace": "...", "version": "..." }. Nama tanpa kualifikasi di-resolve ke marketplace milik plugin ini sendiri. Lihat batasan dependensi.

settings

Pengaturan yang diterapkan Claude Code selama plugin aktif. Hanya agent dan subagentStatusLine yang berlaku; kunci lainnya dibuang saat pemuatan. settings.json di root plugin diutamakan daripada kunci ini. Lihat Pengaturan default.

Component path forms

Setiap kunci komponen menerima path relatif terhadap root plugin. hooks, mcpServers, lspServers, dan experimental.monitors juga menerima config inline, commands juga menerima peta objek, dan mcpServers juga menerima path bundle MCP dan URL. Contoh-contoh berikut menunjukkan setiap bentuk yang diterima sekali. Untuk apa yang dilakukan setiap komponen saat runtime, lihat Plugin components.

Path-only fields

agents, skills, outputStyles, workflows, dan experimental.themes mengambil satu path atau array path. Entri agents harus file .md, dan entri skills harus direktori. Tiga lainnya menerima direktori atau file.

{
  "agents": ["./custom-agents/reviewer.md", "./custom-agents/tester.md"],
  "skills": ["./extra-skills/", "."],
  "outputStyles": "./styles/"
}

commands

commands mengambil path, array path, atau peta objek. Path menamai file perintah .md datar atau direktori. Dalam peta objek, setiap kunci menjadi nama perintah setelah awalan plugin. Misalnya, "about" dalam plugin deploy-tools berjalan sebagai /deploy-tools:about.

Setiap nilai menetapkan tepat satu dari source atau content, dan entri yang menetapkan keduanya atau tidak ada gagal validasi. Field lain dalam tabel ini opsional:

Field Type Description
source string Path ke file Markdown perintah, relatif terhadap root plugin
content string Markdown inline untuk badan perintah, sebagai pengganti source
description string Deskripsi yang ditampilkan untuk perintah
argumentHint string Hint argumen yang ditampilkan setelah nama perintah, seperti [file]
model string Model default untuk perintah
allowedTools array of strings Tools yang dapat digunakan perintah tanpa prompt

Peta ini mendeklarasikan satu perintah dari file dan satu dari konten inline:

{
  "commands": {
    "status": { "source": "./commands/status.md", "argumentHint": "[env]" },
    "about": { "content": "Explain what this plugin provides." }
  }
}

hooks

hooks mengambil path file .json, objek hooks inline dalam bentuk yang sama seperti hooks dalam settings.json, atau array yang mencampur keduanya. Untuk event hook dan field handler, lihat hooks reference.

File hooks membungkus peta event dalam kunci "hooks" tingkat atas, yaitu bentuk yang digunakan hooks/hooks.json. File yang hanya berisi peta event, tanpa pembungkus tersebut, gagal dimuat. Objek inline adalah peta event itu sendiri, tanpa pembungkus.

Claude Code menggabungkan apa pun yang Anda deklarasikan dengan hooks/hooks.json saat file itu ada. Array ini memuat satu file hooks dan mendeklarasikan satu hook PostToolUse inline:

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

File yang dinamai oleh array tersebut membawa pembungkus "hooks" di sekitar peta event miliknya sendiri:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/check-command.sh" }
        ]
      }
    ]
  }
}

mcpServers

mcpServers mengambil path file .json, path bundle MCP atau URL, peta inline, atau array yang mencampur mereka. Untuk field config server, lihat plugin-provided MCP servers.

Claude Code memuat .mcp.json di root plugin terlebih dahulu, kemudian setiap bentuk yang dideklarasikan secara berurutan. Nama server yang dideklarasikan kemudian menggantikan yang sebelumnya.

Nilai mcpServers mengambil salah satu bentuk berikut:

Shape Example value What Claude Code does
.json file path "./mcp/servers.json" Membaca file sebagai peta mcpServers
MCP bundle path "./bundle.mcpb" Mengekstrak bundle .mcpb atau .dxt ke .mcpb-cache/ di bawah root plugin dan membaca config servernya
MCP bundle URL "https://example.com/server.mcpb" Mengunduh bundle ke .mcpb-cache/, kemudian membacanya
Inline map { "deploy-api": { "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"] } } Menggunakan peta sebagai config server yang di-key berdasarkan nama

Path bundle atau URL harus berakhir dengan .mcpb atau .dxt. Ekstensi lain apa pun gagal validasi.

lspServers

lspServers mengambil path file .json, peta inline nama server ke config, atau array keduanya.

Claude Code memuat .lsp.json di root plugin terlebih dahulu, kemudian setiap config yang dideklarasikan secara berurutan. Nama server yang dideklarasikan kemudian menggantikan yang sebelumnya.

Setiap config server adalah objek ketat dengan field berikut. Kunci yang tidak diketahui gagal validasi.

Field Required Description
command Yes Binary language server. Tanpa spasi kecuali nilai dimulai dengan /; letakkan argumen di args
extensionToLanguage Yes Peta ekstensi file ke LSP language ID, setidaknya satu entri. Kunci dimulai dengan titik, seperti ".go"
args No Argumen yang dilewatkan ke server
transport No Transport komunikasi: stdio (default) atau socket. Claude Code menerima socket tetapi menjalankan setiap server melalui stdio, jadi aturan protokol stdout berlaku untuk semua server
env No Variabel lingkungan untuk proses server
initializationOptions No Opsi yang dikirim dalam permintaan initialize
settings No Pengaturan yang dikirim oleh workspace/didChangeConfiguration
workspaceFolder No Path folder workspace untuk server
startupTimeout No Milidetik untuk menunggu startup, integer positif
shutdownTimeout No Milidetik untuk menunggu shutdown yang elegan, integer positif. Saat timeout berlalu, Claude Code menghentikan proses server. Saat tidak diatur, tidak ada timeout yang berlaku
requestTimeout No Milidetik untuk menunggu server menjawab permintaan, integer positif. Default ke 60000, sehingga permintaan yang tidak pernah dijawab server gagal setelah 60 detik. Memerlukan v2.1.288 atau lebih baru
restartOnCrash No Apakah memulai ulang server setelah crash. Default ke true. Atur ke false untuk membiarkan server yang crash tetap berhenti daripada memulai ulang
maxRestarts No Upaya restart sebelum menyerah, nol atau lebih
diagnostics No Apakah mendorong diagnostik ke konteks setelah edit. Default ke true

Config inline ini menjalankan gopls untuk file .go:

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

Untuk language server yang Anthropic terbitkan sebagai plugin dan bagaimana server berperilaku saat runtime, lihat Code intelligence.

monitors

experimental.monitors mengambil path file .json atau array inline. Saat Anda menghilangkan kunci, Claude Code memuat monitors/monitors.json jika ada.

Setiap entri adalah objek ketat dengan field berikut.

Field Required Description
name Yes Identifier unik dalam plugin
command Yes Perintah shell yang Claude Code jalankan sebagai proses latar belakang persisten dalam direktori kerja sesi
description Yes Ringkasan singkat yang ditampilkan di panel tugas dan ringkasan notifikasi
when No Dengan "always", default, monitor dimulai saat awal sesi dan pada reload plugin. Dengan "on-skill-invoke:<skill>", dimulai pertama kali skill itu berjalan

Array inline ini mendeklarasikan satu monitor yang dimulai pertama kali skill deploy berjalan:

{
  "experimental": {
    "monitors": [
      {
        "name": "deploy-status",
        "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
        "description": "Deployment status changes",
        "when": "on-skill-invoke:deploy"
      }
    ]
  }
}

Perintah monitor command tidak dapat mereferensikan ${user_config.*}. Lihat Fields that run through a shell.

Path rules

Setiap path komponen dalam manifest relatif terhadap root plugin dan harus dimulai dengan ./. Path seperti commands/foo.md gagal validasi. skills dan mcpServers masing-masing menerima satu bentuk di luar aturan itu:

  • skills: juga menerima ".". Baik "." maupun "./" menunjukkan root plugin
  • mcpServers: juga menerima URL bundle https://

experimental.evals bukan path komponen, sehingga aturan di bagian ini tidak mencakupnya, dan claude plugin eval memeriksa nilainya saat dijalankan. Nilai ini menamai direktori di bawah root plugin, seperti "quality/evals", dengan atau tanpa awalan ./. Dengan array, hanya entri pertama yang digunakan. Untuk nilai apa yang diterima dan apa yang terjadi dengan nilai yang tidak dapat digunakan, lihat Use a different eval directory.

Containment and existence

Setiap path komponen harus diselesaikan di dalam root plugin dan harus ada. claude plugin validate memeriksa path di bawah setiap kunci komponen:

  • Containment: path yang diselesaikan di luar root plugin tidak dimuat, dan tab Errors /plugin menampilkan <component> path escapes plugin directory: <path>. Path yang berisi .. adalah kasus biasa, dan claude plugin validate melaporkan kesalahan Path contains ".." which could be a path traversal attempt. Untuk file mcpServers atau lspServers, pesan path not read berarti path tersebut absolut atau berisi ..
  • Existence: path yang tidak ada tidak dimuat, dan tab Errors /plugin menampilkan <component> path not found: <path>. claude plugin validate melaporkan kesalahan Path not found

Untuk path outputStyles, lspServers, monitors, dan themes, pemeriksaan claude plugin validate memerlukan Claude Code v2.1.283 atau lebih baru.

How each key combines with its default location

Setiap kunci komponen baik menggantikan lokasi defaultnya, menambahnya, atau menggabungkannya:

  • Menggantikan default: commands, agents, outputStyles, workflows, experimental.themes, experimental.monitors. Saat Anda menetapkan commands, direktori default commands/ tidak dipindai. Untuk menyimpan default dan menambah lebih banyak, daftarkan secara eksplisit: "commands": ["./commands/", "./extras/"]
  • Menambah default: skills. Direktori skills/ masih dipindai, dan direktori yang terdaftar dimuat bersama dengannya
  • Menggabungkan: hooks, mcpServers, lspServers. File default dimuat terlebih dahulu, dan apa yang manifest deklarasikan digabungkan ke dalamnya, seperti dijelaskan di bawah Component path forms

Jika plugin memiliki folder default seperti commands/ dan juga menetapkan kunci manifest yang menggantinya, Claude Code memuat path manifest dan bukan folder. claude plugin list dan antarmuka /plugin kemudian menampilkan peringatan Default <folder>/ folder is ignored because the manifest sets "<key>".

Untuk menghindari peringatan, atur kunci ke path di dalam folder itu: "commands": ["./commands/deploy.md"] menamai file di folder default dan tidak menghasilkan peringatan.

User configuration

userConfig mendeklarasikan nilai yang Claude Code minta kepada pengguna saat plugin diaktifkan, sehingga pengguna tidak mengedit settings.json sendiri.

Kunci adalah identifier yang terdiri dari huruf, digit, dan garis bawah, dan tidak dapat dimulai dengan digit.

Setiap nilai adalah objek ketat dengan field berikut. Kunci yang tidak diketahui gagal validasi.

Field Required Description
type Yes Salah satu dari string, number, boolean, directory, atau file
title Yes Label yang ditampilkan dalam dialog konfigurasi
description Yes Teks bantuan yang ditampilkan di bawah field
required No Jika true, dialog konfigurasi tidak menerima nilai kosong
default No Nilai yang digunakan saat pengguna tidak memberikan apa pun: string, number, boolean, atau array string
options No Untuk string, nilai yang diterima field, ditampilkan sebagai picker di /config. Lihat Limit a field to fixed options. Memerlukan Claude Code v2.1.271 atau lebih baru
multiple No Untuk string, memungkinkan array string
sensitive No Jika true, menyembunyikan input dan menyimpan nilai di penyimpanan aman daripada settings.json
min / max No Batas untuk number

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

userConfig ini mendeklarasikan endpoint dan token yang disembunyikan:

{
  "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
    }
  }
}

Limit a field to fixed options

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

Untuk membatasi field tone ke tiga opsi, daftarkan di 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 field apa pun, pengguna di versi Claude Code sebelum v2.1.271 tidak dapat memuat plugin.

options berlaku untuk field string yang bukan multiple atau sensitive. Atur default ke salah satu nilai yang terdaftar, atau atur required: true sehingga pengguna harus memilih satu. Setiap opsi adalah label polos 1 hingga 64 karakter, dan claude plugin validate, yang Anda jalankan di shell Anda, melaporkan apa pun yang ditolaknya. Plugin yang options-nya melanggar aturan ini gagal dimuat.

Where values are stored

Nilai non-sensitif disimpan di bawah pluginConfigs dalam settings.json pengguna. Nilai sensitif masuk ke penyimpanan kredensial aman platform sebagai gantinya. Halaman pengaturan mencantumkan file pengaturan mana yang pluginConfigs dibaca.

Reference a saved value

Referensikan nilai yang disimpan di mana plugin membutuhkannya, dalam salah satu dari dua bentuk:

  • ${user_config.KEY}: disubstitusi dalam config server MCP, config server LSP, exec-form hook args, dan konten skill dan agent. Dalam konten skill dan agent, hanya nilai non-sensitif yang disubstitusi, dan nilai sensitif di sana menjadi placeholder
  • CLAUDE_PLUGIN_OPTION_<KEY>: diekspor ke proses hook untuk setiap opsi, dengan <KEY> huruf besar. Hook bentuk shell membaca $CLAUDE_PLUGIN_OPTION_API_TOKEN untuk api_token

Fields that run through a shell

Perintah hook bentuk shell, perintah monitor, dan MCP headersHelper menolak ${user_config.*}. Komponen yang mereferensikannya di salah satu field ini gagal dengan error daripada berjalan, karena nilai field dilewatkan ke shell yang akan mem-parse ulang nilai yang disubstitusi.

Tabel menunjukkan bagaimana nilai dapat mencapai setiap field ini sebagai gantinya.

Field How the value can reach it
Shell-form hook commands Gunakan exec form dengan args, atau baca CLAUDE_PLUGIN_OPTION_<KEY> dari lingkungan hook
Monitor commands Bukan melalui Claude Code. Proses monitor tidak menerima CLAUDE_PLUGIN_OPTION_<KEY>, jadi skrip monitor harus mendapatkan nilai sendiri
MCP headersHelper Bukan melalui Claude Code. Lingkungan helper membawa CLAUDE_PLUGIN_ROOT, CLAUDE_CODE_MCP_SERVER_NAME, dan CLAUDE_CODE_MCP_SERVER_URL tetapi tidak ada nilai opsi, jadi skrip helper harus mendapatkan nilai sendiri

Channels

channels mendeklarasikan saluran pesan yang disediakan plugin, seperti jembatan ke aplikasi chat. Saat Anda mendeklarasikan satu, Claude Code dapat meminta konfigurasi saluran saat plugin diaktifkan. Untuk bagaimana server menyuntikkan pesan, lihat channels reference.

Setiap entri adalah objek ketat yang terikat ke salah satu server MCP plugin, dengan field berikut:

Field Required Description
server Yes Kunci server MCP dalam mcpServers plugin ini yang saluran ikat ke
displayName No Nama yang ditampilkan dalam judul dialog konfigurasi. Default ke nama server
userConfig No Opsi untuk diminta, dalam bentuk yang sama seperti userConfig tingkat atas. Nilai yang disimpan disubstitusi ke referensi ${user_config.KEY} dalam env server

Manifest ini mengikat saluran ke server MCP telegram plugin dan meminta token bot yang disubstitusi ke dalam env server:

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [
    {
      "server": "telegram",
      "displayName": "Telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        }
      }
    }
  ]
}

Variabel lingkungan

Claude Code menyediakan tiga variabel path ke komponen plugin. Referensikan sebagai ${NAME} di field yang tercantum di bawah Where each variable resolves, dan bacanya sebagai variabel lingkungan dalam proses yang menerimanya.

Variable Resolves to Use it for
${CLAUDE_PLUGIN_ROOT} Path absolut dari versi plugin yang diinstal Skrip, binary, dan file config yang dikemas dengan plugin
${CLAUDE_PLUGIN_DATA} ~/.claude/plugins/data/<id>/, dibuat pada referensi pertama dan disimpan di seluruh pembaruan plugin. <id> adalah identifier plugin dengan setiap karakter selain huruf, digit, _, atau - diganti dengan - Dependensi yang diinstal seperti node_modules, kode yang dihasilkan, dan cache
${CLAUDE_PROJECT_DIR} Root proyek Skrip dan file config lokal proyek

${CLAUDE_PLUGIN_ROOT} berubah saat plugin diperbarui, jadi jangan tulis state di sana. Untuk di mana root bergerak dan kapan direktori lama dibersihkan, lihat halaman loading.

Secara default, Claude Code menghapus direktori ${CLAUDE_PLUGIN_DATA} saat Anda mencopot plugin dari tempat terakhir diinstal. Untuk --keep-data dan kasus lain di mana direktori tetap ada, lihat plugin uninstall.

Where each variable resolves

Di setiap komponen plugin, referensi ${...} diselesaikan inline di field tertentu, dan beberapa komponen juga menerima variabel di lingkungan proses mereka:

Plugin component Fields where ${...} resolves Exported to the process
Hook commands Di mana saja dalam command dan args CLAUDE_PLUGIN_ROOT, CLAUDE_PLUGIN_DATA, CLAUDE_PROJECT_DIR, dan CLAUDE_PLUGIN_OPTION_<KEY>
Monitor commands Di mana saja dalam command Tidak diekspor
MCP stdio servers command, args, env CLAUDE_PLUGIN_ROOT, CLAUDE_PLUGIN_DATA, CLAUDE_PROJECT_DIR
MCP http, sse, ws servers url, headers, headersHelper Tidak berlaku
LSP servers command, args, env, workspaceFolder CLAUDE_PLUGIN_ROOT, CLAUDE_PLUGIN_DATA, CLAUDE_PROJECT_DIR
Skill, command, and agent content Di mana saja dalam badan Markdown Tidak berlaku

Variabel tidak ada dalam lingkungan perintah yang Claude jalankan melalui tool Bash, dalam sesi utama atau dalam subagent. Dalam konten skill, command, dan agent, tulis referensi ${...} dalam badan Markdown sebagai gantinya, dan Claude Code mensubstitusi path inline saat memuat konten.

Quoting and path separators

Simpan setiap path yang disubstitusi sebagai argumen tunggal:

  • Hook commands: gunakan exec form dengan args sehingga setiap path adalah satu argumen tanpa quoting
  • Shell-form hooks dan monitor commands: bungkus variabel dalam tanda kutip ganda sehingga path dengan spasi tetap satu kata

Jika Anda meninggalkan salah satu variabel ini di luar tanda kutip dalam perintah bentuk shell dalam file hooks, claude plugin validate akan memperingatkan tentang hal itu kecuali hook menetapkan shell ke "powershell".

Hook bentuk shell ini menjalankan skrip yang dikemas dengan plugin:

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

Di Windows, sebagian besar path yang disubstitusi menggunakan garis miring ke depan, seperti dalam C:/Users/you/.... Path tersebut mempertahankan garis miring terbalik aslinya dalam hook bentuk exec dan dalam hook yang berjalan melalui PowerShell, yang merupakan shell default di Windows saat Git Bash tidak diinstal.

Standard layout

Setiap tipe komponen memiliki lokasi default di bawah root plugin, digunakan saat manifest tidak menunjuk ke tempat lain.

Component Default location Contents
Manifest .claude-plugin/plugin.json Metadata dan konfigurasi plugin. Opsional
Skills skills/ Satu <name>/SKILL.md per skill. Plugin dengan SKILL.md di rootnya, tidak ada skills/, dan tidak ada kunci skills dimuat sebagai skill tunggal
Commands commands/ File perintah Markdown datar. Lebih suka skills/ untuk plugin baru
Agents agents/ File Markdown agent. Subfolder adalah bagian dari nama agent
Hooks hooks/hooks.json Konfigurasi hook
MCP servers .mcp.json Definisi server MCP
LSP servers .lsp.json Konfigurasi server LSP
Output styles output-styles/ File gaya output Markdown
Workflows workflows/ File workflow .js
Themes themes/ File tema JSON
Monitors monitors/monitors.json Array monitors
Executables bin/ File di sini ada di PATH tool Bash saat plugin diaktifkan, jadi Claude menjalankannya sebagai perintah bare. claude.ai dan Cowork tidak menginstal plugin yang memiliki direktori ini, termasuk yang Anda distribusikan melalui pengaturan organisasi claude.ai
Settings settings.json Default agent dan subagentStatusLine diterapkan saat plugin diaktifkan

Plugin yang menggunakan setiap lokasi default, ditambah folder scripts/ yang dipanggil hook-nya, diatur seperti ini:

deploy-tools/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── deploy/
│       └── SKILL.md
├── commands/
│   └── status.md
├── agents/
│   └── reviewer.md
├── hooks/
│   └── hooks.json
├── monitors/
│   └── monitors.json
├── output-styles/
│   └── terse.md
├── themes/
│   └── dracula.json
├── workflows/
│   └── release-audit.js
├── bin/
│   └── deploy-tool
├── scripts/
│   └── format.sh
├── settings.json
├── .mcp.json
└── .lsp.json

Untuk mengklik melalui tata letak ini dan membaca apa yang dilakukan setiap file, buka plugin explorer.

CLAUDE.md di root plugin tidak dimuat sebagai konteks, dan claude plugin validate memperingatkan saat menemukannya. Untuk menyertakan instruksi yang dimuat ke dalam konteks Claude, letakkan di skill.

Marketplace entries and the manifest

Entri marketplace menerima field-nya sendiri, termasuk strict, serta setiap field di halaman ini kecuali field daftar direktori.

Field strict memutuskan apakah entri dapat menambahkan komponen ke plugin yang memiliki plugin.json-nya sendiri. Default ke true.

How entry fields combine with plugin.json

Entri baik berfungsi sebagai manifest, menambahkan komponen ke dalamnya, atau berkonflik dengannya:

  • Tidak ada plugin.json: entri adalah manifest, terlepas dari strict. Entry hooks dimuat hanya dalam bentuk objek inline. Untuk path file atau array di sana, tab Errors /plugin menampilkan error not yet supported in a marketplace entry
  • plugin.json ada, strict tidak diatur atau true: Claude Code memuat manifest dan menambahkan commands, agents, skills, outputStyles, dan themes entri ke dalamnya. Untuk hooks, matcher entri untuk event menggantikan matcher manifest untuk event yang sama, dan event hanya manifest yang mendeklarasikan tetap miliknya
  • plugin.json ada, strict: false: entri yang mendeklarasikan salah satu dari commands, agents, skills, hooks, outputStyles, atau themes adalah konflik, dan plugin gagal dimuat dengan Plugin <name> has conflicting manifests

Saat entri marketplace yang source-nya adalah root marketplace mencantumkan subdirektori skills tertentu, hanya subdirektori tersebut yang dimuat, dan direktori default skills/ plugin tidak dipindai. Kunci skills dalam manifest sebagai gantinya menambah default.

Metadata precedence

Beberapa field metadata memiliki preseden tetap terlepas dari strict:

  • defaultEnabled dan display fields: defaultEnabled entri dan display fields-nya seperti displayName menimpakan manifest
  • version: version manifest menimpakan entri
  • name: saat entri mencantumkan plugin di bawah name berbeda dari manifest, enabledPlugins menggunakan nama entri, dan komponen di-namespace di bawah nama manifest

Untuk tabel preseden lengkap, lihat Strict mode.

Next steps