Tambahkan komponen ke plugin

Tambahkan skills, hooks, server MCP, dan setiap jenis komponen lainnya ke plugin Claude Code, dengan contoh yang memvalidasi untuk masing-masing.

Plugin Claude Code dibangun dari komponen, seperti skills, agents, hooks, dan server MCP. Setiap komponen memiliki folder default di plugin, kunci manifest opsional di .claude-plugin/plugin.json yang menggantikan atau menambah folder tersebut, dan nama yang dilihat pengguna. Untuk tabel bidang lengkap setiap kunci, lihat referensi manifest.

Gunakan halaman ini untuk menambahkan komponen ke plugin yang sudah dimuat.

Setelah Anda menambahkan komponen, jalankan /reload-plugins dalam sesi yang sedang berjalan atau mulai sesi baru sehingga Claude Code memuatnya. Untuk memeriksa file komponen sebelum memuatnya, jalankan claude plugin validate . di shell Anda dari direktori plugin.

[!NOTE]

Kasus-kasus ini tercakup di halaman lain:

• Membangun plugin pertama Anda: mulai dengan Buat plugin
• Memasang plugin orang lain: lihat Pasang plugins
• Pengguna plugin Anda berada di claude.ai atau di Cowork: serangkaian komponen yang berbeda dimuat di sana. Lihat Struktur plugin dan pengujian dan tabel dukungan komponen

Jelajahi direktori plugin

Explorer menunjukkan plugin contoh, my-plugin, yang memiliki satu dari setiap jenis komponen di lokasi defaultnya:

• Skill review dan perintah about
• Subagent security-review
• Hook yang memformat file setelah Claude mengeditnya, dan folder scripts/ yang dipanggilnya
• Monitor log
• Gaya output dan tema warna
• Workflow route-audit
• Executable hello-plugin
• Pengaturan default
• Server MCP lokal dan language server Go

Setiap file adalah contoh valid terkecil dari formatnya, ada untuk menunjukkan bentuknya daripada untuk berguna: skill atau agent nyata membawa instruksi lengkap dan sering kali file pendukung, dan hook atau monitor nyata melakukan pekerjaan nyata. Bagian setelah explorer menggunakan file yang sama sebagai contoh mereka dan menautkan ke yang lebih lengkap. Pilih file atau folder untuk membaca tujuannya, lihat apa yang ada di dalamnya, dan temukan bagian yang mencakupnya.

What goes in a plugin

This example plugin, my-plugin, has one of every kind of component, each in its default location. Select a file or folder to read what it’s for and see what goes in it.

Plugin directory

my-plugin/

Selected piece

Manifest adalah file plugin.json di direktori .claude-plugin/ plugin. Ini berisi metadata plugin dan nilai userConfig yang diminta Claude Code kepada pengguna. Claude Code tetap memuat plugin tanpa file ini. Di dalam file, hanya name yang diperlukan. Di sini, description adalah teks yang dilihat pengguna untuk plugin di /plugin, dan version membuat pengguna tetap pada versi itu sampai Anda mengubahnya:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Review, formatting, and database tools for this team"
}

Skill adalah file SKILL.md. Simpan setiap skill di direktorinya sendiri di bawah skills/. Claude membaca description setiap skill, dan ketika apa yang diminta pengguna cocok dengannya, seperti meminta Claude untuk meninjau pull request di sini, Claude memuat instruksi skill dan mengikutinya. Pengguna juga dapat menjalankannya secara langsung sebagai /my-plugin:review:

---
description: Reviews a pull request for style and test coverage. Use when asked to review code.
---

Review the changed files. Report style problems first, then missing tests.

Perintah adalah file Markdown tunggal yang dijalankan pengguna berdasarkan nama. Perintah adalah format yang lebih lama: skill berjalan berdasarkan nama dengan cara yang sama dan juga dapat membawa file pendukung di direktorinya sendiri, jadi tulis yang baru sebagai skills dan simpan commands/ untuk file yang sudah Anda miliki. File ini menjadi /my-plugin:about dan mengambil frontmatter yang sama dengan skill:

---
description: Summarize the repository
---

Summarize what this repository does in three sentences.

Subagent adalah asisten terpisah, dengan instruksinya sendiri dan jendela konteksnya sendiri, yang dapat didelegasikan Claude untuk menyelesaikan tugas dan mendapatkan hasil kembali. Setiap file Markdown di bawah agents/ mendefinisikan satu: frontmatter menamainya dan mengatakan kapan menggunakannya, dan body adalah system prompt-nya. Yang ini dinamai my-plugin:security-reviewer, dan pengguna dapat memanggilnya dengan @agent-my-plugin:security-reviewer:

---
name: security-reviewer
description: Reviews code changes for security issues. Use after edits to authentication or input handling.
model: sonnet
---

You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

Hook menjalankan sesuatu secara otomatis pada titik dalam siklus hidup Claude Code, seperti setelah setiap pengeditan file: perintah shell, permintaan HTTP, panggilan tool MCP, prompt ke model, atau subagent. Simpan hooks plugin di hooks/hooks.json di root plugin. Yang ini menjalankan scripts/format.sh plugin setelah Claude menulis atau mengedit file:

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

Monitor adalah perintah shell yang dimulai Claude Code di latar belakang ketika sesi dimulai dan terus berjalan sampai sesi berakhir. Apa yang dicetak mencapai Claude sebagai notifikasi. Field when dapat malah memulainya pertama kali skill bernama berjalan. Yang ini mengekor log kesalahan:

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

Plugin dapat menyertakan output styles, yang mengubah cara Claude memformat dan merumuskan balasannya. Simpan setiap output style sebagai output-styles/<name>.md. Yang ini muncul di /output-style sebagai my-plugin:terse:

---
name: terse
description: Answer in as few words as possible
keep-coding-instructions: true
---

Keep every reply short. Skip preambles and summaries.

Plugin dapat menyertakan color themes untuk antarmuka Claude Code. Simpan setiap tema sebagai themes/<slug>.json. Yang ini muncul di /theme sebagai Dracula, ditandai sebagai dari my-plugin:

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

Folder workflows/ menyimpan file .js workflow: blok meta, kemudian body script yang mengorkestra beberapa subagent. Yang ini berjalan sebagai /my-plugin:audit-routes:

export const meta = {
  name: 'audit-routes',
  description: 'Audit every route handler for missing auth checks',
}

const found = await agent('List every .ts file under src/routes/.', {
  schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },
})

const audits = await pipeline(found.files, file =>
  agent(`Audit ${file} for missing authentication checks.`, { label: file }),
)

return audits.filter(Boolean)

bin/ adalah cara plugin mengirimkan alat command-line. Sementara plugin diaktifkan, Claude Code menempatkan folder ini di PATH shell tempat ia menjalankan perintah, sehingga Claude, atau instruksi skill, dapat menjalankan alat berdasarkan nama tanpa pengguna memasangnya. Dengan executable ini di tempat, hello-plugin adalah perintah yang dapat dijalankan Claude:

#!/bin/bash
echo "hello from my-plugin"

Hook di hooks/hooks.json menjalankan script, dan folder ini adalah tempat contoh menyimpannya. Nama scripts/ adalah konvensi, bukan sesuatu yang dicari Claude Code: hook menunjuk ke file berdasarkan jalurnya, ${CLAUDE_PLUGIN_ROOT}/scripts/format.sh. Script formatter mungkin terlihat seperti ini:

#!/bin/bash
npx prettier --write .

settings.json di root plugin menyimpan settings yang berlaku sementara plugin diaktifkan, sehingga plugin dapat mengubah cara sesi berperilaku dan tidak hanya menambahkan komponen. Hanya dua kunci yang berlaku dari plugin, agent dan subagentStatusLine; setiap kunci lain dijatuhkan. Lihat Default settings.

Yang ini menetapkan agent, yang menjalankan thread utama sesi sebagai agent security-reviewer plugin sendiri, sehingga system prompt, pembatasan tool, dan model agent itu berlaku untuk seluruh sesi:

{
  "agent": "security-reviewer"
}

Server MCP memberikan Claude tools dari sistem eksternal. Deklarasikan di .mcp.json di root plugin. Yang ini memulai server lokal dari script di dalam plugin, dan muncul di /mcp sebagai plugin:my-plugin:db:

{
  "mcpServers": {
    "db": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}

Server LSP memberikan Claude diagnostics dan code navigation untuk bahasa. Deklarasikan server di .lsp.json di root plugin. Yang ini menghubungkan language server Go untuk file .go:

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

Tambahkan setiap jenis komponen

Setiap bagian di bawah mencakup satu jenis komponen: di mana file-filenya berada di plugin, contoh yang memvalidasi, apa yang dilihat pengguna setelah plugin dimuat, dan kunci manifest yang mengubah lokasi default. Tambahkan yang dibutuhkan plugin Anda; tidak ada yang diperlukan.

Skills

Skill adalah file SKILL.md yang dapat dimuat Claude ketika deskripsinya cocok dengan tugas. Pengguna juga dapat menjalankannya sebagai perintah. Simpan setiap skill di direktorinya sendiri di bawah skills/:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── review/
        └── SKILL.md

Berikan SKILL.md description sehingga Claude tahu kapan menggunakannya:

---
description: Reviews a pull request for style and test coverage. Use when asked to review code.
---

Review the changed files. Report style problems first, then missing tests.

Setelah Anda memuat plugin, /my-plugin:review menjalankan skill. Nama perintah dan siapa yang dapat memanggilnya mengikuti aturan ini:

• Nama perintah: /<plugin>:<directory>, jadi skills/review/SKILL.md di my-plugin adalah /my-plugin:review. Jika Anda menetapkan name di frontmatter, itu menggantikan segmen terakhir dan awalan plugin tetap. Lihat bagaimana skill mendapatkan nama perintahnya
• Siapa yang memanggilnya: Claude, pengguna, atau keduanya, dikendalikan oleh frontmatter. Lihat Kontrol siapa yang memanggilnya skill

Anda juga dapat menempatkan skills di luar direktori default skills/:

• Direktori tambahan: daftarkan di kunci manifest skills. Mereka menambah pemindaian default skills/ daripada menggantinya, tidak seperti commands dan agents
• Skill tunggal di root plugin: tanpa direktori skills/ dan tanpa kunci manifest skills, SKILL.md di root plugin dimuat sebagai satu skill. Tetapkan name di frontmatter-nya, karena jika tidak, instalasi marketplace menamakan skill setelah cache directory-nya daripada plugin Anda

Untuk menyertakan instruksi dalam plugin, tulislah sebagai skill. Claude Code tidak memuat CLAUDE.md di root plugin, dan claude plugin validate memperingatkan CLAUDE.md at the plugin root is not loaded as project context.

Jika aturan harus berlaku setiap saat, seperti memblokir pengeditan ke file yang dilindungi, tambahkan ke plugin sebagai hook daripada skill. Untuk memilih di antara keduanya, lihat tab Hook vs Skill di bawah Bandingkan fitur serupa.

Untuk field frontmatter dan file pendukung, lihat Skills.

Commands

Perintah adalah file Markdown tunggal yang dijalankan pengguna berdasarkan nama, seperti /my-plugin:about.

[!NOTE]

Perintah adalah format yang lebih lama, dan skills menggantikannya untuk pekerjaan baru. Skill berjalan berdasarkan nama dengan cara yang sama, dan itu juga dapat membawa file pendukung di direktorinya. Simpan commands/ untuk file yang Anda pindahkan dari .claude/commands/.

Simpan perintah di commands/<file>.md dan itu menjadi /<plugin>:<file>. Subdirektori menambah segmen, jadi commands/db/migrate.md adalah /my-plugin:db:migrate.

File perintah mengambil frontmatter yang sama dengan skills.

Tentukan perintah di manifest

Anda hanya membutuhkan ini jika Anda ingin menyimpan file perintah di tempat lain selain commands/, atau untuk mendefinisikan perintah pendek di dalam plugin.json tanpa file Markdown terpisah. Tetapkan kunci manifest commands, dan Claude Code membacanya daripada memindai commands/. Kunci mengambil jalur, array jalur, atau objek yang memetakan setiap nama perintah ke file source atau content inline.

Manifest ini mendefinisikan /my-plugin:about inline, tanpa file Markdown:

{
  "name": "my-plugin",
  "commands": {
    "about": {
      "content": "Summarize what this repository does in three sentences.",
      "description": "Summarize the repository"
    }
  }
}

Muat plugin dan jalankan /my-plugin:about dalam sesi untuk mengonfirmasi itu dimuat.

Untuk sintaks kunci lengkap, lihat commands.

Agents

Subagent adalah asisten terpisah, dengan instruksinya sendiri dan jendela konteks, yang dapat didelegasikan Claude untuk menyelesaikan tugas. Setiap file Markdown di bawah agents/ mendefinisikan satu:

---
name: security-reviewer
description: Reviews code changes for security issues. Use after edits to authentication or input handling.
model: sonnet
---

You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

Agent ini dinamai my-plugin:security-reviewer, dan pengguna dapat memanggilnya secara eksplisit dengan @agent-my-plugin:security-reviewer. Bentuk nama adalah <plugin>:<name>, di mana <name> berasal dari field name di frontmatter, atau dari nama file ketika field itu tidak ada.

Kunci manifest agents menggantikan pemindaian agents/.

Atur agents dalam subfolder

Anda dapat menempatkan file agent plugin dalam subfolder 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: itu menggantikan hanya nama file, jadi name: audit di 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

Field frontmatter dalam agent plugin

Frontmatter agent plugin mengikuti aturan ini:

• Field yang didukung: name, description, model, effort, maxTurns, autoCompactWindow, tools, disallowedTools, skills, memory, background, omitClaudeMd, isolation, color, dan kunci cacheTtl dari experimental. Satu-satunya nilai isolation yang valid adalah "worktree". Lihat field frontmatter yang didukung untuk apa yang dilakukan masing-masing
• Field yang diabaikan: permissionMode, hooks, mcpServers, dan initialPrompt. File agent tidak dapat menambahkan hooks atau server MCP sendiri, jadi tambahkan itu sebagai plugin hooks dan server MCP sebagai gantinya
• Frontmatter yang tidak diuraikan: agent masih dimuat dengan setiap field diabaikan. Itu dinamai setelah file, dan deskripsinya berbunyi Agent from my-plugin plugin. Jalankan claude plugin validate di shell Anda untuk menemukan file-file ini

Untuk apa yang dilakukan setiap field dan aturan prioritas, lihat Subagents.

Hooks

Hook menjalankan sesuatu secara otomatis pada titik dalam siklus hidup Claude Code, seperti setelah setiap pengeditan file: perintah shell, permintaan HTTP, panggilan tool MCP, prompt ke model, atau subagent. Simpan hooks plugin di hooks/hooks.json di root plugin, di bawah kunci top-level "hooks", dalam bentuk yang sama dengan objek hooks di settings.json. Itu memungkinkan Anda menyalin hook pengaturan yang ada tanpa perubahan.

Hook ini menjalankan script bundled setelah setiap Write atau Edit:

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

Simpan script di scripts/format.sh dan buat dapat dieksekusi.

Muat plugin dan minta Claude untuk mengedit file. Hook PostToolUse yang keluar 0 tidak menunjukkan apa pun dalam transkrip, jadi konfirmasi itu berjalan dengan debug logging atau dengan apa yang diubah script itu sendiri.

Hooks di hooks/hooks.json dan di kunci manifest hooks keduanya dimuat. Untuk setiap event dan payload-nya, lihat Hook events.

Ketika plugin lain yang diaktifkan memiliki nama yang sama, salah satu dari keduanya mendaftarkan hook hooks/hooks.json-nya dan hook milik yang lain tidak disertakan. Lihat Hooks ketika dua plugin yang diaktifkan memiliki nama yang sama untuk mengetahui yang mana, serta catatan di /plugin yang memberi tahu Anda.

Untuk menulis hooks sebagai fungsi JavaScript yang berjalan di dalam Claude Code dan dapat menggambar di antarmukanya, daftarkan file modul di bawah kunci modules dalam hooks/hooks.json yang sama. Plugin dengan satu adalah mod. Lihat Create a mod.

Kapan hook plugin dipecat

Hook plugin tidak menunggu salah satu skill atau perintah plugin digunakan. Claude Code mendaftarkannya ketika sesi memuat plugin, dan mereka dipecat pada event mereka sejak saat itu. Untuk membatasi kapan hook berjalan, persempit matcher-nya.

Jika hook tidak pernah dipecat, lihat hooks yang tidak dipecat.

Lingkungan, quoting, dan pencocokan tool MCP

Lingkungan hook, quoting ${CLAUDE_PLUGIN_ROOT}, dan matcher untuk tool MCP plugin sendiri bekerja sebagai berikut:

• Lingkungan: setiap proses hook menerima CLAUDE_PLUGIN_ROOT dan CLAUDE_PLUGIN_DATA di lingkungannya, ditambah CLAUDE_PLUGIN_OPTION_<KEY> untuk setiap nilai konfigurasi pengguna, sehingga script Anda dapat membacanya dari sana
• Quoting: ketika command tidak memiliki args, itu berjalan melalui shell, jadi bungkus jalur ${CLAUDE_PLUGIN_ROOT} dalam tanda kutip ganda, seperti contoh hooks/hooks.json di bawah Hooks, untuk menjaga jalur yang diperluas sebagai satu kata shell. Ketika Anda melewatkan args sebagai gantinya, setiap elemen dilewatkan sebagai satu argumen tanpa shell dan tidak memerlukan quoting. Lihat exec form dan shell form
• Pencocokan tool MCP plugin sendiri: tool dari server MCP yang dideklarasikan plugin ini dinamai mcp__plugin_<plugin>_<server>__<tool>, jadi tulis nama lengkap itu di matcher. Matcher pada nama server saja tidak pernah dipecat. Lihat Match MCP tools

Server MCP

Server MCP memberikan Claude tools dari sistem eksternal. Deklarasikan di .mcp.json di root plugin, dalam bentuk yang sama dengan project .mcp.json. .mcp.json ini mendeklarasikan satu server bernama db:

{
  "mcpServers": {
    "db": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}

Anda juga dapat menghilangkan wrapper mcpServers dan menempatkan db di level atas file.

Muat plugin dan jalankan /mcp untuk mengonfirmasi server muncul sebagai plugin:my-plugin:db.

claude plugin validate memeriksa .mcp.json dan melaporkan entri server yang akan dijatuhkan Claude Code pada waktu muat sebagai kesalahan. Memerlukan Claude Code v2.1.281 atau lebih baru.

Untuk di mana entri buruk muncul pada waktu muat, lihat Server MCP yang tidak dimulai.

Kunci manifest mcpServers mengambil peta server inline, jalur ke file JSON, atau array dari itu. Ketika server manifest memiliki nama yang sama dengan yang di .mcp.json, server manifest menggantinya.

Jangkau pengguna di claude.ai dan Cowork

Server stdio lokal, seperti server db di bawah Server MCP, berjalan di Claude Code dan dalam sesi Cowork yang berjalan di mesin Anda di aplikasi Claude Desktop, tetapi bukan di claude.ai. Untuk menjangkau pengguna di sana juga, referensikan server jarak jauh dengan URL https://-nya, yang claude.ai dan Cowork tawarkan kepada pengguna sebagai konektor, seperti yang ditunjukkan Bundle an MCP connector with its skill.

Nama server, nama tool, dan reload

Nama server, substitusi variabel, dan perilaku reload mengikuti aturan ini:

• Nama server: plugin:<plugin>:<server>, jadi server db di my-plugin adalah plugin:my-plugin:db di /mcp. Gunakan bentuk yang sama untuk menamakan server dalam hook mcp_tool
• Nama tool: mcp__plugin_<plugin>_<server>__<tool>, jadi tool query pada server db itu adalah mcp__plugin_my-plugin_db__query. Itu adalah nama yang digunakan dalam aturan izin dan matcher hook
• Substitusi: ${CLAUDE_PLUGIN_ROOT} dan variabel jalur lainnya disubstitusikan dalam command, args, dan env. Tidak ada quoting yang diperlukan dalam args, karena setiap elemen dilewatkan sebagai satu argumen
• Reload: ketika pengguna menjalankan /reload-plugins dan reload berlaku, server yang konfigurasinya tidak berubah menjaga koneksinya. Server yang konfigurasinya berubah terhubung kembali, dan yang Anda hapus terputus

Sertakan server MCPB yang dikemas

Kunci mcpServers juga menerima server yang dikemas sebagai file MCPB, yang ekstensinya adalah .mcpb atau .dxt yang lebih lama. Arahkan kunci ke file, sebagai jalur di dalam plugin atau URL https://:

{
  "name": "my-plugin",
  "mcpServers": "./servers/db.mcpb"
}

Server mengambil namanya dari name dalam manifest bundle.

Bundle manifest sendiri dapat mendeklarasikan pengaturan yang dibutuhkan server dari pengguna dalam blok user_config. Server bundled dengan pengaturan yang diperlukan yang tidak memiliki nilai yang disimpan tidak dimulai. Tab Errors /plugin menunjukkan Bundled MCP server "<name>" was not started: it needs configuration.

Pengguna menyediakan nilai dengan salah satu dari dua cara:

• Di /plugin: pilih plugin di tab Installed dan pilih Configure
• Saat instalasi, dari shell: lewatkan --config <server>.<key>=<value> ke claude plugin install. Memerlukan Claude Code v2.1.285 atau lebih baru, dan hanya berfungsi untuk bundle yang dikemas di dalam plugin.

Untuk transport dan autentikasi, lihat MCP.

Server LSP

Server LSP memberikan Claude diagnostics dan code navigation untuk bahasa. Jika plugin code intelligence resmi sudah mencakup bahasa Anda, pasang itu daripada menulis satu. Jika tidak, deklarasikan server di .lsp.json di root plugin:

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

File memetakan setiap nama server langsung ke konfigurasinya, tanpa objek wrapper di sekitar peta. command adalah nama binary, dengan argumennya di args. extensionToLanguage memerlukan setidaknya satu ekstensi, masing-masing dimulai dengan ..

claude plugin validate tidak membaca file ini. Ketika entri apa pun tidak valid, seluruh file dilewati pada waktu muat dan Invalid LSP server config for ".lsp.json" muncul di tab Errors /plugin.

Plugin Anda mengonfigurasi koneksi tetapi tidak memasang binary server, dan setiap ekstensi file mendapat satu server:

• Binary yang hilang: Claude Code memulai command berdasarkan nama dari PATH pengguna. Ketika binary tidak ada, server gagal dimulai dan claude --debug mencatat LSP server <name> failed to start
• Konflik ekstensi: ketika dua server yang diaktifkan mengklaim ekstensi yang sama, yang pertama terdaftar menangani file-file itu dan yang lain tidak digunakan untuk mereka, apakah server berasal dari satu plugin atau dua. Tab Errors /plugin menunjukkan peringatan LSP server "<name>" is not used for <ext> files

Kunci manifest lspServers mengambil peta yang sama inline, jalur ke file JSON, atau array dari itu, dan server-nya menambah yang di .lsp.json. Ketika server manifest memiliki nama yang sama dengan yang di .lsp.json, server manifest menggantinya.

Untuk transport, timeout, restart, dan field lainnya, lihat lspServers.

Kirim output log ke stderr, bukan stdout. Claude Code membaca stdout server sebagai pesan protokol saja, 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 kesalahan yang menamai penyebabnya ke log debug.

Executables

File di bin/ di root plugin berada di PATH shell tool Bash sementara plugin diaktifkan, sehingga Claude dapat menjalankannya sebagai perintah bare. Perintah yang dijalankan Claude dengan tool PowerShell di luar sandbox juga menemukannya di PATH-nya, sedangkan perintah PowerShell yang berjalan di dalam sandbox tidak. Tambahkan script yang dapat dieksekusi:

#!/bin/bash
echo "hello from my-plugin"

Buat dapat dieksekusi dengan chmod +x bin/hello-plugin dan muat plugin. Ketika Anda meminta Claude untuk menjalankan hello-plugin, hasil tool Bash menunjukkan output script.

Direktori bin/ plugin datang setelah entri PATH pengguna sendiri, jadi plugin tidak dapat menaungi git, ls, atau perintah sistem lainnya.

claude.ai dan Cowork tidak memasang plugin yang memiliki direktori bin/ level atas, termasuk yang Anda distribusikan melalui pengaturan organisasi claude.ai.

Pengaturan default

Untuk menetapkan default yang berlaku sementara plugin diaktifkan, tambahkan settings.json di root plugin, atau letakkan objek yang sama inline di kunci manifest settings. Dua kunci berlaku, agent dan subagentStatusLine, dan setiap kunci lain dijatuhkan.

Tetapkan agent untuk menjalankan salah satu agent plugin sendiri sebagai thread utama:

{
  "agent": "security-reviewer"
}

Muat plugin dan mulai sesi. Claude kemudian menjawab dalam percakapan utama dengan system prompt dan model agent security-reviewer.

Untuk semua yang dikontrol kunci, lihat pengaturan agent.

Ketika kunci yang sama ditetapkan di lebih dari satu tempat, aturan ini memutuskan nilai mana yang berlaku:

• File atas manifest: ketika keduanya ada dan settings.json menetapkan setidaknya satu kunci yang didukung, settings.json berlaku dan settings manifest diabaikan
• Pengaturan pengguna atas default plugin: di seluruh sumber pengaturan, default plugin adalah layer terendah, jadi agent pengguna sendiri di ~/.claude/settings.json menggantikan milik Anda
• Dua plugin menetapkan kunci yang sama: nilai dari plugin yang dimuat terakhir berlaku, dan claude --debug mencatat overrides setting

Untuk bentuk subagentStatusLine, lihat subagent status lines.

Tema dan output styles

Plugin dapat menyertakan color themes dan output styles. Keduanya muncul di picker yang sama dengan pengguna sendiri. Untuk salah satu, menetapkan kunci manifest menggantikan pemindaian folder.

Tema plugin adalah read-only, jadi ketika pengguna mengedit satu di /theme, edit disimpan sebagai salinan di direktori tema mereka sendiri.

Tema ini mengubah warna prompt accent dan error text pada preset dark:

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

Channels

Channel memungkinkan sistem luar seperti aplikasi chat mengirim pesan ke sesi. Dalam plugin, channel adalah salah satu server MCP ditambah entri channels yang mengikat ke itu dan dapat meminta konfigurasinya sendiri. Manifest ini mengikat channel ke server telegram dan meminta token bot:

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

server harus cocok dengan kunci di mcpServers. Per-channel userConfig mengambil bentuk yang sama dengan kunci userConfig level atas.

Untuk apa yang harus diimplementasikan server dan bagaimana pengguna mengaktifkan plugin channel, lihat Package as a plugin dalam referensi channels. Untuk tabel field, lihat channels.

Monitors

Monitor adalah perintah shell yang berjalan di latar belakang untuk seluruh sesi. Apa yang dicetak mencapai Claude sebagai notifikasi, sehingga Claude dapat bereaksi terhadap log atau perubahan status tanpa diminta untuk menontonnya. Simpan entri di monitors/monitors.json:

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

Perintah berjalan dalam shell, di direktori kerja saat ini dari sesi. Perintah ini berjalan dengan izin pengguna penuh Anda dan di luar sandbox.

Perintah monitor dibatasi di mana itu dimulai dan apa yang dapat direferensikan:

• Sesi interaktif saja: monitor plugin dimulai dalam sesi interaktif dan tidak pernah dalam mode non-interaktif dengan flag -p. Mereka juga tidak dimulai dalam sesi di mana penyedia API atau pengaturan telemetri membuat Monitor tool tidak tersedia
• Tidak ada konfigurasi pengguna: command mendapat variabel jalur dan ${ENV_VAR} dari lingkungan, tetapi tidak pernah ${user_config.*}. Monitor yang mereferensikan satu tidak dimulai, dan proses monitor tidak menerima CLAUDE_PLUGIN_OPTION_<KEY> juga
• Menonaktifkan mid-session: jika Anda menonaktifkan plugin mid-session, Claude Code tidak menghentikan monitor yang sudah berjalan. Mereka berhenti ketika sesi berakhir

Kunci manifest experimental.monitors mengambil array yang sama inline atau jalur ke file JSON, dan dibaca daripada monitors/monitors.json.

Untuk trigger when dan field lainnya, lihat monitors.

Minta pengguna untuk nilai konfigurasi

Deklarasikan nilai yang dibutuhkan plugin Anda dari pengguna di kunci manifest userConfig, sehingga pengguna tidak mengedit settings.json sendiri. Setiap opsi muncul dalam dialog dengan title-nya sebagai label dan description-nya di bawahnya.

Tetapkan "sensitive": true untuk token atau password. Dialog kemudian menutupi input, dan nilai disimpan dalam penyimpanan aman daripada settings.json.

Manifest ini meminta endpoint dan token:

{
  "name": "my-plugin",
  "userConfig": {
    "api_url": {
      "type": "string",
      "title": "API URL",
      "description": "Base URL of your team's API"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for your team's API",
      "sensitive": true
    }
  }
}

Kapan dialog konfigurasi muncul

Dialog adalah bagian dari antarmuka /plugin interaktif. Ketika pengguna melakukan salah satu dari berikut, dialog terbuka untuk opsi apa pun yang belum ditetapkan:

• Memasang plugin di /plugin
• Menjalankan /plugin install <plugin>@<marketplace> di dalam sesi
• Mengaktifkan plugin dari tab Installed di /plugin

Untuk membuka dialog yang sama kapan saja, pengguna menjalankan /plugin configure <plugin>@<marketplace>.

Dialog Manage plugins di ekstensi VS Code Manage plugins dialog meminta opsi yang tidak ditetapkan sebagai formulir setelah instalasi, dan ikon gear pada baris plugin membuka formulir lagi dengan setiap opsi.

Perintah shell claude plugin install tidak pernah meminta nilai userConfig. Untuk menetapkan nilai dari shell, lewatkan masing-masing sebagai --config KEY=VALUE saat Anda memasang, atau pipa objek JSON ke claude plugin configure --values-stdin setelahnya.

Ketika opsi tetap tidak ditetapkan, claude plugin install mencetak baris userConfig options not yet set. Untuk teks pasti baris tersebut, lihat The userConfig dialog never appears.

Untuk field opsi, di mana setiap nilai disimpan, bagaimana komponen mereferensikan nilai yang disimpan, dan field mana yang menolak ${user_config.*}, lihat User configuration.

Referensikan jalur plugin dan simpan data

Anda tidak tahu di mana plugin Anda akan dipasang, jadi referensikan file dan data-nya melalui variabel ini daripada jalur tetap. Mereka disubstitusikan dalam skill, command, dan agent content, dalam hook dan monitor commands, dan dalam konfigurasi server MCP dan LSP. Mereka juga diekspor ke hook, MCP, dan proses LSP:

• ${CLAUDE_PLUGIN_ROOT}: direktori instalasi plugin. Setiap versi memiliki cache directory-nya sendiri, jadi jalur berubah ketika plugin diperbarui. Jangan tulis state di sana
• ${CLAUDE_PLUGIN_DATA}: direktori yang bertahan dari update, untuk node_modules, virtual environments, dan caches. Itu diselesaikan ke ~/.claude/plugins/data/<id>/ dan dibuat ketika pertama kali direferensikan
• ${CLAUDE_PROJECT_DIR}: root proyek, nilai yang sama yang diterima hooks

Dalam jalur direktori data, <id> adalah identifier plugin dengan setiap karakter selain huruf, digit, _, dan - diganti dengan -, jadi my-plugin@my-marketplace menjadi my-plugin-my-marketplace.

Di Windows, jalur yang disubstitusikan menggunakan forward slashes sehingga shell tidak membaca backslashes sebagai escapes.

Pasang dependensi ke direktori data

Untuk plugin yang dipasang marketplace, Claude Code memasang dependensi paket Node.js yang memenuhi syarat secara otomatis ketika itu cache plugin, jadi Anda mungkin tidak perlu memasangnya sendiri. Ketika Anda melakukannya, hook SessionStart ini memasang node_modules ke ${CLAUDE_PLUGIN_DATA} pada run pertama dan lagi setelah update mengubah package.json:

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

Setelah sesi pertama, ~/.claude/plugins/data/<id>/node_modules ada. Server MCP kemudian dapat menetapkan NODE_PATH ke ${CLAUDE_PLUGIN_DATA}/node_modules di env-nya. Untuk field mana yang mensubstitusikan variabel mana, lihat Environment variables.

Langkah berikutnya

• Referensi manifest plugin: field plugin.json, aturan jalur, dan layout standar
• Test plugins dengan evals: periksa bahwa komponen yang Anda tambahkan mengubah perilaku Claude dengan cara yang Anda maksudkan
• Publikasikan dan distribusikan plugin: versi plugin dan letakkan di marketplace
• Troubleshoot plugins: apa yang harus dilakukan ketika komponen tidak dimuat atau hook tidak dipecat