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:
- Memasang plugin orang lain: lihat Install plugins
- Tidak yakin Anda memerlukan plugin: lihat Decide whether you need a plugin di overview
- Pengguna plugin Anda berada di claude.ai atau di Cowork: folder yang sama dipasang di sana dengan subset komponen yang berbeda. Lihat Plugins on claude.ai and in Cowork
- Belum ada apa-apa: ikuti Create your first plugin, kemudian Develop without a marketplace dan Test and debug.
- File di bawah
.claude/sudah ada: lakukan walkthrough first-plugin sekali untuk mempelajari layoutnya, kemudian ikuti Convert an existing.claude/setup.
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 skillhellotanpa bertabrakan.
.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 Empat field melakukan ini:
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
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.namediperlukan di dalamnya;emaildanurlopsional.
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 Kemudian buat Baris
skills/ yang berisi file SKILL.md. Buat direktori skill:my-first-plugin/skills/hello/SKILL.md dengan konten ini:my-first-plugin/skills/hello/SKILL.md
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-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
.zipdarinya, 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.
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.zipuntuk satu sesi.--plugin-url: mengambil arsip.zipdari URL untuk satu sesi.claude plugin init: membuat scaffold plugin di bawah~/.claude/skills/yang dimuat setiap sesi.
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.
/reload-plugins untuk menerapkannya.
Dari URL
Ketika Anda memulaiclaude dari shell Anda, teruskan --plugin-url dengan alamat arsip .zip, seperti artefak build yang CI Anda publikasikan:
/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:
~/.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 jalankanclaude 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:- Di shell Anda, jalankan
claude plugin validate <path>. Ini memeriksa manifest dan frontmatter setiap file skill, agent, dan command, dan keluar0padaValidation passed. Tambahkan--strictuntuk gagal pada peringatan juga. Exit codes dan penanganan direktori ada di plugin commands reference. - Dalam sesi yang berjalan, jalankan
/reload-pluginsuntuk menerapkan edit yang Anda buat di disk. Ini mencetak satu barisReloaded:dengan hitungan. Kemudian konfirmasi skill dimuat dengan mengetik perintah/plugin-name:skillatau dengan menemukan plugin di tab Installed/plugin. - 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. - Kembali di shell Anda, jalankan
claude plugin list. Ini mencetak plugin sesi-saja dan direktori-skills dalam bagian mereka sendiri denganStatus: ✔ loadedatau kesalahan beban. Untuk menyertakan plugin yang Anda kembangkan, teruskan--plugin-dirdengan jalurnya sebelumplugin list.
/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
Direktoriskills/ 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 Buat
.claude-plugin/ di sebelah .claude/. Anda dapat memindahkan plugin ke mana saja setelahnya.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 Buat
.claude/settings.json atau .claude/settings.local.json, buat direktori hooks: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:deployuntuk skill yang sebelumnya/deploy. - Subagents: minta Claude untuk menggunakan agent
my-plugin:revieweruntuk agent yang sebelumnyareviewer. - Hooks: picu event yang cocok dengan setiap hook.
.claude/, mereka tetap dimuat bersama salinan plugin:
- Skills dan agents: dua set tidak bertabrakan, karena skills dan agents plugin membawa prefix
my-plugin:./deploydan/my-plugin:deploykeduanya bekerja, dan Claude melihatreviewerdanmy-plugin:reviewersebagai dua subagent. - Hooks: hooks tidak memiliki prefix, jadi hook yang ada di file settings Anda dan
hooks/hooks.jsonberjalan dua kali setiap kali event-nya terjadi.
.claude/ dan hapus objek hooks dari file settings Anda.
Langkah berikutnya
- Plugin components: tambahkan agents, hooks, MCP servers, LSP servers, dan user configuration ke plugin Anda
- Test plugins with evals: tulis kasus eval dan jalankan dengan
claude plugin evaluntuk memeriksa seberapa andal plugin memandu perilaku Claude - Publish a plugin: versi itu, masukkan ke marketplace, dan kirimkan ke community marketplace
- Plugins on claude.ai and in Cowork: folder plugin yang sama dipasang di claude.ai dan di Cowork. Beberapa komponen hanya Claude Code
- Plugin manifest reference: setiap field
plugin.json, aturan path, dan direktori - Skills: tulis skills yang disediakan plugin Anda
- Anthropic’s plugins in the claude-code repository: contoh lengkap yang dikerjakan dari layout di halaman ini, seperti
feature-devdancode-review