Skip to main content
Plugin adalah direktori skills, agents, hooks, dan MCP servers, ditambah file plugin.json, yang disebut manifest, yang memberi nama pada plugin. Claude Code memuat direktori sebagai satu unit, sehingga Anda dapat membagikannya dengan rekan kerja, memasangnya di beberapa proyek, atau menerbitkannya ke marketplace. Halaman ini untuk orang-orang yang menulis plugin mereka sendiri.
Kasus-kasus ini tercakup di halaman lain:
Mulai dari bagian yang sesuai dengan apa yang sudah Anda miliki:

Tentukan kapan menggunakan plugin

Skills, agents, hooks, dan MCP servers semuanya bekerja standalone di proyek Anda atau direktori home. Pertahankan setup standalone itu selama melayani satu proyek atau hanya Anda. Buat plugin ketika Anda ingin berbagi setup dengan rekan kerja, memasangnya di beberapa proyek, atau menerbitkan rilis yang diversi. Ketika Anda memindahkan skills, agents, hooks, dan MCP config standalone ke plugin, lokasi dan nama mereka berubah:
  • Di mana file-file itu pergi: di bawah direktori plugin sendiri, yang disebut plugin root, sebagai skills/, agents/, hooks/hooks.json, dan .mcp.json.
  • Bagaimana mereka dinamai: plugin skills dan agents mendapatkan nama plugin sebagai prefix, seperti /my-plugin:hello, sehingga dua plugin dapat masing-masing menyediakan skill hello tanpa bertabrakan.
Untuk memindahkan setup yang sudah ada ke plugin, lihat Convert an existing .claude/ setup.

Buat plugin pertama Anda

Dalam walkthrough ini, Anda membuat plugin yang satu-satunya komponennya adalah satu skill, sebuah greeting, dan menjalankannya dengan --plugin-dir, yang memuat plugin untuk satu sesi tanpa memasangnya. Plugin dapat menampung campuran apa pun dari components, seperti skills, agents, hooks, dan MCP servers, dan tidak ada yang diperlukan; satu skill adalah contoh terkecil yang menunjukkan layout. Anda memerlukan Claude Code installed and signed in. Buka terminal di direktori tempat Anda ingin menyimpan plugin, seperti ~/projects, dan jalankan perintah dalam langkah-langkah ini darinya. Anda dapat menyimpan plugin di mana saja, karena Anda meneruskan jalurnya ke Claude Code ketika Anda memulai sesi.
1

Buat direktori plugin

Buat direktori plugin, dengan folder .claude-plugin/ di dalamnya untuk menampung manifest:
2

Tulis manifest

manifest adalah file JSON bernama plugin.json yang memberi tahu Claude Code nama plugin dan mendeskripsikannya. Simpan yang ini sebagai my-first-plugin/.claude-plugin/plugin.json:
my-first-plugin/.claude-plugin/plugin.json
Empat field melakukan ini:
  • name: diperlukan. Ini mengidentifikasi plugin dan menjadi prefix pada setiap skill dan agent yang disediakan plugin. Jangan masukkan spasi di dalamnya.
  • description: teks yang dilihat pengguna untuk plugin di /plugin.
  • version: opsional. Menetapkannya membuat pengguna tetap pada versi itu sampai Anda mengubahnya; Release a new version mengatakan kapan harus menetapkan atau menghilangkannya.
  • author: siapa yang dikreditkan. name diperlukan di dalamnya; email dan url opsional.
Setiap field lainnya ada di manifest reference.Hanya plugin.json yang masuk ke dalam .claude-plugin/. Skill yang Anda tambahkan selanjutnya langsung di bawah my-first-plugin/, di sebelah folder itu.
3

Tambahkan skill

Satu-satunya komponen plugin ini adalah skill. Setiap skill adalah direktori di bawah skills/ yang berisi file SKILL.md. Buat direktori skill:
Kemudian buat my-first-plugin/skills/hello/SKILL.md dengan konten ini:
my-first-plugin/skills/hello/SKILL.md
Baris disable-model-invocation: true berarti Claude tidak menjalankan skill sendiri, jadi hanya Anda yang memicunya. Hapus baris itu dari skill yang ingin Anda jalankan sendiri oleh Claude. Perintah skill menggabungkan nama plugin dan nama skill, jadi Anda menjalankan yang ini sebagai /my-first-plugin:hello. Untuk field frontmatter lainnya, lihat skill frontmatter reference.
4

Validasi plugin

Periksa manifest dan frontmatter skill sebelum Anda menjalankan apa pun:
Perintah mencetak jalur manifest yang diperiksa dan ✔ Validation passed. Jika mencetak ✘ Validation failed sebagai gantinya, setiap baris di atas baris hasil itu memberi nama field yang harus diperbaiki. Cari setiap pesan di bawah claude plugin validate reports errors.
5

Jalankan Claude Code dengan plugin

Mulai sesi dengan plugin dimuat:
Setelah Claude Code dimulai, jalankan skill:
Claude membalas dengan greeting.
Plugin dimuat hanya dalam sesi yang Anda mulai dengan --plugin-dir. Untuk terus bekerja padanya tanpa flag, atau untuk menguji build .zip, lihat Develop without a marketplace.

Bagikan plugin Anda

Plugin yang Anda bangun dengan Create your first plugin hanya ada di mesin Anda. Ketika sudah siap untuk orang lain, ada tiga cara untuk mendapatkannya kepada mereka:
  • Kirimkan langsung ke beberapa orang: berikan mereka direktori plugin atau .zip darinya, dan tidak ada yang perlu dipublikasikan. Lihat Share a plugin without a marketplace.
  • Daftarkan di marketplace Anda sendiri: rekan kerja menambahkan marketplace Anda sekali dan memasang plugin berdasarkan nama, dan mereka menerima update Anda. Lihat Publish through your own marketplace.
  • Kirimkan ke community marketplace Anthropic: setelah terdaftar, siapa pun yang menambahkan marketplace itu dapat memasangnya. Lihat Submit to the community marketplace.

Plugin layout

Setiap jenis component, seperti skills, agents, hooks, dan MCP servers, masuk ke direktori tetap di bawah plugin root, yang merupakan direktori yang Anda teruskan ke --plugin-dir. Tambahkan hanya direktori yang Anda gunakan. Untuk mengklik melalui direktori plugin lengkap dan membaca apa yang dilakukan setiap file, buka plugin explorer. Tabel mencantumkan direktori yang paling banyak digunakan plugin untuk memulai, dan full layout mencantumkan sisanya.
Hanya plugin.json yang masuk ke dalam .claude-plugin/. Komponen yang disimpan di sana tidak dimuat.Plugin root adalah direktori plugin sendiri, bukan ~/.claude/ itu sendiri. .mcp.json yang disimpan di ~/.claude/.mcp.json tidak dimuat.

Kembangkan tanpa marketplace

Anda tidak memerlukan marketplace untuk menjalankan plugin yang Anda tulis. Muat langsung dari disk atau URL sebagai gantinya:
  • --plugin-dir: memuat direktori atau arsip .zip untuk satu sesi.
  • --plugin-url: mengambil arsip .zip dari URL untuk satu sesi.
  • claude plugin init: membuat scaffold plugin di bawah ~/.claude/skills/ yang dimuat setiap sesi.
Jika dua plugin yang dimuat dengan cara berbeda berbagi nama, lihat Name conflicts untuk mengetahui mana yang Claude Code pertahankan.

Muat plugin untuk satu sesi

Anda dapat memuat plugin untuk satu sesi dengan tiga cara: dari direktori atau arsip .zip di disk dengan --plugin-dir, dari URL dengan --plugin-url, atau dari variabel lingkungan ketika Anda tidak dapat menambahkan flag. Setiap plugin dimuat hanya untuk sesi itu, dan tidak ada yang ditulis ke settings Anda untuk itu. Ketika Anda mengedit file plugin selama sesi, jalankan /reload-plugins untuk memuat perubahan.

Dari direktori atau .zip

Ketika Anda memulai claude dari shell Anda, teruskan --plugin-dir dengan direktori root plugin atau arsip .zip darinya. Ulangi flag untuk memuat beberapa plugin:

Dari folder plugin

Untuk memuat beberapa plugin dari satu tempat, teruskan folder yang menampungnya, seperti --plugin-dir ./plugins. Memuat folder plugin memerlukan Claude Code v2.1.265 atau lebih baru. Jika folder tidak memiliki direktori .claude-plugin/ dan tidak memiliki komponen plugin di tingkat atasnya, Claude Code memperlakukannya sebagai folder plugin. Setiap subfolder langsung yang memiliki manifest .claude-plugin/plugin.json kemudian dimuat sebagai plugin terpisah. Semua yang lain di folder dilewati tanpa kesalahan, termasuk subfolder yang tidak memiliki manifest. Jika plugin di folder tidak dimuat, periksa bahwa subfoldernya memiliki .claude-plugin/plugin.json. Dalam sesi interaktif, Anda juga dapat menambah dan menghapus plugin di folder setelah startup:
  • Subfolder yang Anda tambahkan dimuat sebagai plugin baru setelah manifestnya ada.
  • Ketika Anda menghapus subfolder, pluginnya dibongkar.
Pesan muncul dalam sesi untuk setiap perubahan ini. Jika memuat atau membongkar plugin di tengah percakapan akan invalidate the prompt cache, perubahan ditahan sebagai gantinya, dan pesan memberi tahu Anda untuk menjalankan /reload-plugins untuk menerapkannya.

Dari URL

Ketika Anda memulai claude dari shell Anda, teruskan --plugin-url dengan alamat arsip .zip, seperti artefak build yang CI Anda publikasikan:
Claude Code mengunduh arsip saat startup. Untuk memuat beberapa, ulangi flag atau teruskan URL yang dipisahkan spasi dalam satu argumen yang dikutip. Arahkan flag hanya ke arsip yang Anda kontrol atau percayai. Jika Claude Code tidak dapat mengambil arsip, atau arsip tidak valid, itu dimulai tanpa plugin dan mencatat kesalahan beban plugin yang dapat Anda tinjau di tab Errors manajer /plugin.

Dari variabel lingkungan

Untuk memuat plugin dalam sesi di mana Anda tidak dapat menambahkan flag --plugin-dir, daftarkan jalur absolutnya dalam variabel lingkungan CLAUDE_CODE_PLUGIN_DIRS sebagai gantinya. Claude Code memuat setiap jalur saat memuat jalur --plugin-dir. Plugin ini dimuat sebagai tambahan untuk yang Anda teruskan dengan --plugin-dir. Project and local settings can’t set this variable. CLAUDE_CODE_PLUGIN_DIRS memerlukan Claude Code v2.1.280 atau lebih baru. Managed settings dapat mematikan --plugin-dir dan CLAUDE_CODE_PLUGIN_DIRS. Lihat Flags that load a plugin for one session. Untuk menguji plugin bersama dengan plugin yang bergantung padanya, lihat Test a plugin and its dependency locally.

Buat plugin dimuat di setiap sesi

Direktori skills pribadi Anda adalah ~/.claude/skills/. Claude Code memuat folder apa pun di sana yang berisi .claude-plugin/plugin.json sebagai plugin di setiap sesi, tanpa flag dan tanpa langkah install. claude plugin init membuat scaffold satu dari plugin ini untuk Anda.

Buat scaffold plugin dengan claude plugin init

claude plugin init menulis plugin starter di bawah ~/.claude/skills/. Memerlukan Claude Code v2.1.157 atau lebih baru. Buat scaffold satu dari shell Anda:
Perintah membuat ~/.claude/skills/my-tool/ dengan .claude-plugin/plugin.json dan root SKILL.md. Ini mencetak ✔ Created plugin "my-tool" at ~/.claude/skills/my-tool diikuti oleh It will auto-load next session as my-tool@skills-dir. Run /reload-plugins to load it now. Teruskan --with skills untuk membuat scaffold claude plugin init skill di bawah skills/ untuk Anda. Nilai --with lainnya ada di plugin commands reference.

Beri nama skills plugin

Root skill di ~/.claude/skills/my-tool/SKILL.md juga merupakan personal skill, jadi Anda memanggilnya sebagai /my-tool, bukan /my-tool:my-tool. Skills yang Anda tambahkan di bawah skills/ di dalam plugin mendapatkan prefix nama plugin, seperti /my-tool:example.

Hentikan pemuatan plugin

Untuk menghentikan pemuatan plugin yang dibuat scaffold, hapus direktorinya, atau jalankan claude plugin disable my-tool@skills-dir di shell Anda dengan nama my-tool@skills-dir yang dicetak claude plugin init. Dalam ID my-tool@skills-dir, skills-dir berdiri di mana nama marketplace akan berada, karena plugin dimuat dari direktori skills Anda daripada dari marketplace.

Bagikan plugin melalui repository

claude plugin init menulis plugin ke direktori skills pribadi Anda di ~/.claude/skills/, sehingga dimuat untuk Anda di setiap proyek. Untuk membuat plugin dimuat untuk semua orang di satu repository, buat layout yang sama sendiri di <project>/.claude/skills/<name>/, termasuk .claude-plugin/plugin.json. Lihat Plugins shared through a repository untuk kondisi di mana Claude Code memuat itu.

Uji dan debug

Ketika perubahan pada plugin Anda tidak muncul, kerjakan pemeriksaan ini secara berurutan. Masing-masing memberi tahu Anda apa yang dilakukan Claude Code dengan plugin:
  1. Di shell Anda, jalankan claude plugin validate <path>. Ini memeriksa manifest dan frontmatter setiap file skill, agent, dan command, dan keluar 0 pada Validation passed. Tambahkan --strict untuk gagal pada peringatan juga. Exit codes dan penanganan direktori ada di plugin commands reference.
  2. Dalam sesi yang berjalan, jalankan /reload-plugins untuk menerapkan edit yang Anda buat di disk. Ini mencetak satu baris Reloaded: dengan hitungan. Kemudian konfirmasi skill dimuat dengan mengetik perintah /plugin-name:skill atau dengan menemukan plugin di tab Installed /plugin.
  3. Dalam sesi yang sama, jalankan /plugin. Tab Installed mencantumkan plugin Anda dan, dalam detail plugin, komponen yang ditemukan Claude Code. Tab Errors mencantumkan apa yang gagal dimuat dan mengapa, seperti jalur dalam manifest Anda yang tidak ada.
  4. Kembali di shell Anda, jalankan claude plugin list. Ini mencetak plugin sesi-saja dan direktori-skills dalam bagian mereka sendiri dengan Status: ✔ loaded atau kesalahan beban. Untuk menyertakan plugin yang Anda kembangkan, teruskan --plugin-dir dengan jalurnya sebelum plugin list.
Untuk memeriksa MCP server, jalankan /mcp dalam sesi untuk melihat status server. Ketika server sehat, /mcp mencantumkannya sebagai terhubung. Jika tidak, lihat MCP servers that don’t start. Untuk memeriksa hook, picu event yang cocok. Misalnya, minta Claude untuk mengedit file untuk memicu hook PostToolUse. Kemudian baca debug log, yang menunjukkan hook mana yang cocok, exit codes mereka, dan output mereka. Bagian berikutnya mencakup kegagalan yang paling mungkin Anda alami saat mengembangkan, dan troubleshooting page memiliki entri lengkap untuk masing-masing.

Jalur komponen tidak ditemukan

Tab Errors dari /plugin menunjukkan <component> path not found: <path>, misalnya commands path not found. Jalur komponen dalam manifest Anda, seperti commands, skills, agents, atau hooks, menunjuk ke tidak ada. Perbaiki jalur atau buat direktori, kemudian jalankan /reload-plugins dalam sesi. Lihat commands path not found.

--plugin-dir di root marketplace tidak memuat plugin di bawah plugins/

--plugin-dir mengambil direktori root plugin, yang berisi .claude-plugin/plugin.json dan direktori komponen seperti skills/. Jika Anda mengarahkannya ke root marketplace sebagai gantinya, Claude Code tidak membaca marketplace.json, jadi plugin di bawah plugins/ tidak dimuat, dan Anda tidak melihat kesalahan. Arahkan flag ke folder satu plugin, atau tambahkan marketplace. Lihat entri troubleshooting.

Plugin dimuat tetapi skillnya hilang

Direktori skills/ ada di dalam .claude-plugin/, atau entri skills dalam manifest menunjuk ke file. Pindahkan skills/ ke plugin root, arahkan setiap entri skills ke direktori yang berisi SKILL.md, dan jalankan /reload-plugins dalam sesi. Lihat Plugin loads but its skills are missing.

Dialog userConfig tidak pernah muncul

Dialog untuk opsi userConfig plugin Anda adalah bagian dari pemasangan melalui /plugin dalam sesi. Memuat dengan --plugin-dir tidak menampilkannya, begitu juga claude plugin install di shell. Dengan plugin dimuat, jalankan /plugin configure <plugin-name> dalam sesi untuk membukanya. Lihat The userConfig dialog never appears.

Periksa bahwa plugin mengubah perilaku Claude

Plugin yang dimuat tanpa kesalahan masih dapat gagal mengarahkan Claude dengan cara yang Anda maksudkan. claude plugin eval, yang Anda jalankan di shell Anda, menjalankan kasus uji Anda dengan dan tanpa plugin dan mencetak perbedaannya. Lihat Test plugins with evals, dimulai dengan Create your first eval suite.

Konversi setup .claude/ yang sudah ada

Jika Anda sudah memiliki skills, agents, atau hooks di bawah direktori .claude/ proyek, Anda dapat memindahkannya ke plugin tanpa menulis ulang. Jalankan perintah dalam langkah-langkah ini dari root proyek, yang merupakan direktori yang berisi .claude/, karena jalur cp relatif terhadapnya.
1

Buat struktur plugin

Buat direktori plugin dan folder .claude-plugin/ di sebelah .claude/. Anda dapat memindahkan plugin ke mana saja setelahnya.
Buat my-plugin/.claude-plugin/plugin.json:
my-plugin/.claude-plugin/plugin.json
2

Salin file yang sudah ada

Salin setiap direktori konfigurasi yang Anda miliki ke plugin root, dan lewati perintah untuk direktori apa pun yang tidak Anda miliki.
Jalankan ls -a my-plugin untuk mengonfirmasi bahwa setiap direktori yang Anda salin muncul di sebelah .claude-plugin.
3

Pindahkan hooks Anda

Jika Anda memiliki hooks di .claude/settings.json atau .claude/settings.local.json, buat direktori hooks:
Buat my-plugin/hooks/hooks.json dan salin objek hooks dari file settings Anda ke dalamnya. Formatnya sama.Contoh ini menunjukkan bentuk dengan satu hook yang menjalankan linter pada setiap file yang ditulis atau diedit Claude. Ganti contoh dengan objek hooks Anda sendiri.
my-plugin/hooks/hooks.json
4

Uji plugin yang dimigrasikan

Muat plugin untuk sesi:
Periksa setiap komponen di bawah nama barunya:
  • Skills: jalankan /my-plugin:deploy untuk skill yang sebelumnya /deploy.
  • Subagents: minta Claude untuk menggunakan agent my-plugin:reviewer untuk agent yang sebelumnya reviewer.
  • Hooks: picu event yang cocok dengan setiap hook.
Jika ada yang hilang, kerjakan Test and debug.
Sementara yang asli masih di bawah .claude/, mereka tetap dimuat bersama salinan plugin:
  • Skills dan agents: dua set tidak bertabrakan, karena skills dan agents plugin membawa prefix my-plugin:. /deploy dan /my-plugin:deploy keduanya bekerja, dan Claude melihat reviewer dan my-plugin:reviewer sebagai dua subagent.
  • Hooks: hooks tidak memiliki prefix, jadi hook yang ada di file settings Anda dan hooks/hooks.json berjalan dua kali setiap kali event-nya terjadi.
Setelah Anda mengonfirmasi plugin bekerja, hapus yang asli dari .claude/ dan hapus objek hooks dari file settings Anda.

Langkah berikutnya