Referensi Plugins

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

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

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

Referensi komponen plugin

Skills

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

Lokasi: Direktori skills/ atau commands/ 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

Perilaku integrasi:

• Skills dan commands secara otomatis ditemukan saat plugin dipasang
• Claude dapat memanggilnya secara otomatis berdasarkan konteks tugas
• Skills dapat menyertakan file pendukung di samping SKILL.md

Untuk detail lengkap, lihat Skills.

Agents

Plugins 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.

Plugin agents mendukung field frontmatter name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, dan isolation. Satu-satunya nilai isolation yang valid adalah "worktree". Untuk alasan keamanan, hooks, mcpServers, dan permissionMode tidak didukung untuk agents yang dikirim plugin.

Titik integrasi:

• Agents muncul di antarmuka /agents
• Claude dapat memanggil agents secara otomatis berdasarkan konteks tugas
• Agents dapat dipanggil secara manual oleh pengguna
• Plugin agents bekerja bersama agents Claude bawaan

Untuk detail lengkap, lihat Subagents.

Hooks

Plugins dapat menyediakan event handlers yang merespons peristiwa Claude Code secara otomatis.

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

Format: Konfigurasi JSON dengan event matchers dan actions

Konfigurasi hook:

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

Plugin hooks merespons peristiwa lifecycle yang sama seperti hooks yang ditentukan pengguna:

Tipe hook:

• command: jalankan perintah shell atau scripts
• http: kirim JSON event 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

MCP servers

Plugins dapat menggabungkan Model Context Protocol (MCP) servers untuk menghubungkan Claude Code dengan alat dan layanan eksternal.

Lokasi: .mcp.json di root plugin, atau inline di 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"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

Perilaku integrasi:

• Plugin MCP servers dimulai secara otomatis saat plugin diaktifkan
• Servers muncul sebagai alat MCP standar di toolkit Claude
• Kemampuan server terintegrasi dengan mulus dengan alat Claude yang ada
• Plugin servers dapat dikonfigurasi secara independen dari MCP servers pengguna

LSP servers

Plugins dapat menyediakan server Language Server Protocol (LSP) untuk memberikan Claude intelijen kode real-time saat bekerja pada codebase Anda.

Integrasi LSP menyediakan:

• Diagnostik instan: Claude melihat kesalahan dan peringatan segera setelah setiap edit
• Navigasi kode: buka definisi, temukan referensi, dan informasi hover
• Kesadaran bahasa: informasi tipe dan dokumentasi untuk simbol kode

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

Format: Konfigurasi JSON yang memetakan nama language server ke konfigurasinya

Format file .lsp.json:

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

Inline di plugin.json:

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

Field yang diperlukan:

Field opsional:

LSP plugins yang tersedia:

Pasang language server terlebih dahulu, kemudian pasang plugin dari marketplace.

Monitors

Plugins dapat mendeklarasikan monitors latar belakang yang Claude Code mulai secara otomatis saat 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 peristiwa 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 tanpa sandbox 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 di plugin.json

Format: Array JSON dari entri monitor

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

[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh ${user_config.api_endpoint}",
    "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 di plugin.json ke array yang sama. Untuk memuat dari jalur non-default, atur experimental.monitors ke string jalur relatif seperti "./config/monitors.json". Monitors adalah komponen eksperimental.

Field yang diperlukan:

Field opsional:

Nilai command mendukung substitusi variabel yang sama seperti konfigurasi MCP dan LSP server: ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}, ${CLAUDE_PROJECT_DIR}, ${user_config.*}, dan ${ENV_VAR} apa pun dari lingkungan. Awali perintah dengan cd "${CLAUDE_PLUGIN_ROOT}" && jika script perlu berjalan dari direktori plugin itu sendiri.

Menonaktifkan plugin di tengah sesi tidak menghentikan monitors yang sudah berjalan. Mereka berhenti saat sesi berakhir.

Themes

Plugins dapat mengirimkan color themes yang muncul di /theme bersama preset bawaan dan themes lokal pengguna. Sebuah theme adalah file JSON di themes/ dengan preset base dan peta overrides yang sparse dari color tokens. Themes adalah komponen eksperimental.

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

Memilih plugin theme menyimpan custom:<plugin-name>:<slug> di config pengguna. Plugin themes bersifat read-only; menekan Ctrl+E pada salah satu di /theme menyalinnya ke ~/.claude/themes/ sehingga pengguna dapat mengedit salinannya.

Cakupan instalasi plugin

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

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

Skema manifest plugin

File .claude-plugin/plugin.json mendefinisikan metadata dan konfigurasi plugin Anda. Bagian ini mendokumentasikan semua field dan opsi yang didukung.

Manifest bersifat opsional. Jika dihilangkan, Claude Code secara otomatis menemukan komponen di lokasi default dan menurunkan nama plugin dari nama direktori. Gunakan manifest saat Anda perlu memberikan metadata atau jalur komponen khusus.

Skema lengkap

{
  "name": "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"],
  "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"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Field yang diperlukan

Jika Anda menyertakan manifest, name adalah satu-satunya field 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.

Field metadata

Field jalur komponen

Komponen eksperimental

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

User configuration

Field userConfig mendeklarasikan nilai yang Claude Code minta dari pengguna saat plugin diaktifkan. Gunakan ini daripada memerlukan pengguna untuk mengedit settings.json secara manual.

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Endpoint API tim Anda"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token autentikasi API",
      "sensitive": true
    }
  }
}

Kunci harus berupa pengenal yang valid. Setiap opsi mendukung field berikut:

Setiap nilai tersedia untuk substitusi sebagai ${user_config.KEY} di konfigurasi MCP dan LSP server, perintah hook, dan perintah monitor. Nilai non-sensitif juga dapat disubstitusi dalam konten skill dan agent. Semua nilai diekspor ke subprocess plugin sebagai variabel lingkungan CLAUDE_PLUGIN_OPTION_<KEY>.

Nilai non-sensitif disimpan di settings.json di bawah pluginConfigs[<plugin-id>].options. Nilai sensitif masuk ke keychain sistem (atau ~/.claude/.credentials.json di mana keychain tidak tersedia). Penyimpanan keychain dibagikan dengan token OAuth dan memiliki batas total sekitar 2 KB, jadi jaga nilai sensitif tetap kecil.

Channels

Field channels memungkinkan plugin mendeklarasikan satu atau lebih message channels yang menyuntikkan konten ke dalam percakapan. Setiap channel mengikat ke MCP server yang disediakan plugin.

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

Field server diperlukan dan harus cocok dengan kunci di mcpServers plugin. Field userConfig per-channel opsional menggunakan skema yang sama dengan field tingkat atas, memungkinkan plugin meminta token bot atau ID pemilik saat plugin diaktifkan.

Aturan perilaku jalur

Apakah jalur khusus menggantikan atau memperluas direktori default plugin tergantung pada field:

• Menggantikan default: commands, agents, outputStyles, experimental.themes, experimental.monitors. Misalnya, saat manifest menentukan commands, direktori default commands/ tidak dipindai. Untuk menyimpan default dan menambahkan lebih banyak, sertakan secara eksplisit: "commands": ["./commands/", "./extras/"]
• Menambah default: skills. Direktori default skills/ selalu dipindai, dan direktori yang tercantum di skills dimuat bersama dengannya
• Aturan penggabungan sendiri: hooks, MCP servers, dan LSP servers. Lihat setiap bagian untuk cara beberapa sumber digabungkan

Saat plugin memiliki folder default dan kunci manifest yang cocok, Claude Code v2.1.140 dan yang lebih baru menandai folder yang diabaikan di /doctor, claude plugin list, dan tampilan detail /plugin. Plugin masih dimuat menggunakan jalur manifest. Tidak ada peringatan yang ditampilkan saat kunci manifest menunjuk ke folder default, misalnya "commands": ["./commands/deploy.md"], karena folder ditangani secara eksplisit dalam hal itu.

Untuk semua field jalur:

• Semua jalur harus relatif terhadap root plugin dan dimulai dengan ./
• Komponen dari jalur khusus menggunakan aturan penamaan dan namespacing yang sama
• Beberapa jalur dapat ditentukan sebagai array
• Saat jalur skill menunjuk ke direktori yang berisi SKILL.md secara langsung, misalnya "skills": ["./"] menunjuk ke root plugin, field frontmatter name di SKILL.md menentukan nama invokasi skill. Ini memberikan nama stabil terlepas dari direktori instalasi. Jika name tidak diatur di frontmatter, basename direktori digunakan sebagai fallback.

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. Semuanya disubstitusi inline di mana pun mereka muncul dalam konten skill, konten agent, perintah hook, perintah monitor, dan konfigurasi MCP atau LSP server. Semuanya juga diekspor sebagai variabel lingkungan ke proses hook dan subprocess MCP atau LSP server.

${CLAUDE_PLUGIN_ROOT}: jalur absolut ke direktori instalasi plugin Anda. Gunakan ini untuk mereferensikan scripts, binaries, dan file konfigurasi yang disertakan dengan plugin. Dalam perintah hook, gunakan exec form dengan args sehingga jalur dilewatkan sebagai satu argumen tanpa quoting. Dalam hook bentuk shell dan perintah monitor, bungkus dalam tanda kutip ganda, seperti "${CLAUDE_PLUGIN_ROOT}". Jalur ini berubah saat plugin diperbarui. Direktori versi sebelumnya tetap berada di disk selama sekitar tujuh hari setelah update sebelum pembersihan, tetapi perlakukan sebagai ephemeral dan jangan tulis state di sini.

Saat plugin diperbarui di tengah sesi, perintah hook, monitor, MCP server, dan LSP server terus menggunakan jalur versi sebelumnya. Jalankan /reload-plugins untuk mengalihkan hooks, MCP server, dan LSP server ke jalur baru; monitor memerlukan restart sesi.

${CLAUDE_PLUGIN_DATA}: direktori persisten untuk state plugin yang bertahan setelah updates. Gunakan ini untuk dependensi yang dipasang seperti node_modules atau Python virtual environments, kode yang dihasilkan, caches, dan file lainnya yang harus bertahan di seluruh versi plugin. Direktori dibuat secara otomatis pertama kali variabel ini direferensikan.

${CLAUDE_PROJECT_DIR}: root proyek. Ini adalah direktori yang sama yang diterima hooks di variabel CLAUDE_PROJECT_DIR mereka. Gunakan ini untuk mereferensikan scripts atau file konfigurasi lokal proyek. Bungkus dalam tanda kutip untuk menangani jalur dengan spasi, misalnya "${CLAUDE_PROJECT_DIR}/scripts/server.sh". MCP server juga dapat memanggil permintaan MCP roots/list, yang mengembalikan direktori tempat Claude Code diluncurkan.

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

Direktori data persisten

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

Penggunaan umum adalah memasang dependensi bahasa sekali dan menggunakannya kembali di seluruh sesi dan update plugin. Karena direktori data bertahan lebih lama dari versi plugin tunggal, pemeriksaan keberadaan direktori saja tidak dapat mendeteksi saat update mengubah manifest dependensi plugin. Pola yang direkomendasikan membandingkan manifest yang disertakan terhadap salinan di direktori data dan memasang ulang saat mereka berbeda.

Hook SessionStart ini memasang node_modules pada run pertama dan lagi kapan pun update 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 saat salinan yang disimpan hilang atau berbeda dari yang disertakan, mencakup run pertama dan updates yang mengubah dependensi. Jika npm install gagal, trailing rm menghapus manifest yang disalin sehingga sesi berikutnya mencoba lagi.

Scripts yang disertakan di ${CLAUDE_PLUGIN_ROOT} kemudian dapat berjalan terhadap node_modules yang persisten:

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

Direktori data dihapus secara otomatis saat Anda menghapus plugin dari cakupan terakhir di mana itu dipasang. Antarmuka /plugin menunjukkan ukuran direktori dan meminta sebelum menghapus. CLI menghapus secara default; teruskan --keep-data untuk mempertahankannya.

Plugin caching dan resolusi file

Plugins ditentukan dalam salah satu dari dua cara:

• Melalui claude --plugin-dir atau claude --plugin-url, untuk durasi sesi.
• Melalui marketplace, dipasang untuk sesi mendatang.

Untuk tujuan keamanan dan verifikasi, Claude Code menyalin plugin marketplace ke plugin cache lokal pengguna (~/.claude/plugins/cache) daripada menggunakannya di tempat. Memahami perilaku ini penting saat mengembangkan plugins yang mereferensikan file eksternal.

Setiap versi yang dipasang adalah direktori terpisah dalam cache. Saat Anda memperbarui atau menghapus plugin, direktori versi sebelumnya ditandai sebagai orphaned dan dihapus secara otomatis 7 hari kemudian. Periode grace memungkinkan sesi Claude Code bersamaan yang sudah memuat versi lama untuk terus berjalan tanpa kesalahan.

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

Batasan path traversal

Plugin yang dipasang tidak dapat mereferensikan file di luar direktorinya. Jalur yang melintasi di luar root plugin (seperti ../shared-utils) tidak akan berfungsi setelah instalasi karena file eksternal tersebut tidak disalin ke cache.

Bagikan file dalam marketplace dengan symlinks

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

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

Untuk plugins yang dipasang dengan --plugin-dir atau dari jalur lokal, hanya symlinks yang diselesaikan dalam direktori plugin itu 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

Ini memberikan fleksibilitas sambil mempertahankan manfaat keamanan dari sistem caching.

Struktur direktori plugin

Tata letak plugin standar

Plugin lengkap mengikuti struktur ini:

enterprise-plugin/
├── .claude-plugin/           # Direktori metadata (opsional)
│   └── plugin.json             # plugin manifest
├── 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
├── 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  # Hook tambahan
├── bin/                      # Plugin executables ditambahkan ke PATH
│   └── my-tool               # Dapat dipanggil sebagai perintah bare di Bash tool
├── settings.json            # Pengaturan default untuk plugin
├── .mcp.json                # Definisi MCP server
├── .lsp.json                # Konfigurasi LSP server
├── scripts/                 # Hook dan utility scripts
│   ├── 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 mereka dalam sebuah skill.

Referensi lokasi file

Referensi perintah CLI

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

plugin install

Pasang plugin dari marketplace yang tersedia.

claude plugin install <plugin> [options]

Argumen:

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

Opsi:

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

Contoh:

# Pasang ke cakupan user (default)
claude plugin install formatter@my-marketplace

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

# Pasang ke cakupan local (gitignored)
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

Hapus plugin yang dipasang.

claude plugin uninstall <plugin> [options]

Argumen:

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

Opsi:

Alias: remove, rm

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

plugin prune

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

claude plugin prune [options]

Opsi:

Alias: autoremove

Perintah ini 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.

claude plugin enable <plugin> [options]

Argumen:

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

Opsi:

plugin disable

Nonaktifkan plugin tanpa menghapusnya.

claude plugin disable <plugin> [options]

Argumen:

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

Opsi:

plugin update

Perbarui plugin ke versi terbaru.

claude plugin update <plugin> [options]

Argumen:

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

Opsi:

plugin list

Daftar plugin yang dipasang dengan versi, marketplace sumber, dan status enable mereka.

claude plugin list [options]

Opsi:

plugin details

Tampilkan inventaris komponen plugin dan perkiraan biaya token. Output mencantumkan semua komponen yang disumbangkan plugin, dikelompokkan sebagai Skills (skills dan commands), Agents, Hooks, dan MCP servers, bersama dengan perkiraan berapa banyak token yang ditambahkannya ke setiap sesi.

claude plugin details <name>

Argumen:

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

Opsi:

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 ada komponen yang 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:

security-guidance 1.2.0
  Real-time security analysis for Claude Code sessions
  Source: security-guidance@claude-code-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  (harness-only — no model context cost)
  MCP 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 tersebut. Jika API tidak dapat dijangkau, perintah kembali ke perkiraan berbasis karakter.

plugin tag

Buat tag rilis git untuk plugin di direktori saat ini. Jalankan dari dalam folder plugin. Lihat Tag plugin releases.

claude plugin tag [options]

Opsi:

Alat debugging dan pengembangan

Perintah debugging

Gunakan claude --debug untuk melihat detail loading plugin:

Ini menunjukkan:

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

Masalah umum

Contoh pesan kesalahan

Kesalahan validasi manifest:

• Invalid JSON syntax: Unexpected token } in JSON at position 142: periksa koma yang hilang, koma ekstra, atau string yang tidak dikutip
• Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required: field yang diperlukan hilang
• Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: kesalahan sintaks JSON

Kesalahan loading plugin:

• Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.: jalur 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.: jalur 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

Troubleshooting hook

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 jalur 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 alat Anda: "matcher": "Write|Edit" untuk operasi file
3. Konfirmkan tipe hook valid: command, http, mcp_tool, prompt, atau agent

Troubleshooting MCP server

Server tidak dimulai:

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

Alat 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 di .claude-plugin/.

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← Hanya manifest di sini
├── commands/            ← Di level root
├── agents/              ← Di level root
└── hooks/               ← Di level root

Jika komponen Anda berada di dalam .claude-plugin/, pindahkan ke root 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 pembaruan tersedia. Ketika Anda menjalankan /plugin update atau auto-update dipicu, Claude Code menghitung versi saat ini dan melewati pembaruan jika cocok dengan apa yang sudah terpasang.

Versi diselesaikan 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. Git commit SHA dari sumber plugin, untuk sumber github, url, git-subdir, dan relative-path dalam marketplace yang dihosting git
4. unknown, untuk sumber npm atau direktori lokal yang tidak berada dalam repositori git

Ini memberi Anda dua cara untuk memberi versi pada 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