# Claude Code Plugin vs Skill: Kapan Perlu Dibundel

> Skill itu dokumen, plugin itu dependency. Kapan satu file SKILL.md sudah cukup, kapan drift antar copy menandakan waktunya membundel, dan apa biayanya.

URL: https://www.matthewswong.com/id/blog/claude-code-plugin-vs-skill-bundling/

- Author: Matthews Wong (https://www.matthewswong.com/id/about/)
- Published: 2026-09-07
- Updated: 2026-09-07
- Category: Software Development

> **Key takeaway:** Skill di Claude Code adalah dokumen; plugin adalah dependency. Simpan sebuah workflow sebagai satu file SKILL.md selama Anda satu-satunya pembacanya, dan bundel jadi plugin ber-version hanya ketika dua orang atau lebih harus menjalankan configuration yang identik dan Anda tidak bisa memastikan copy mereka belum menyimpang.

Ada tiga skill di repository ini, di bawah .claude/skills — satu untuk menulis konten blog, satu untuk menerbitkannya, satu untuk menggambar figure. Tidak ada satu pun yang berbentuk plugin. Tidak ada manifest, tidak ada entri marketplace, dan tidak ada version yang perlu di-pin. Setelah berbulan-bulan dipakai setiap hari, itu belum pernah merugikan saya dalam bentuk apa pun yang bisa saya sebutkan.

Tulisan ini adalah aturan keputusan di belakangnya, diargumentasikan alih-alih didaftar: skill adalah dokumen dan plugin adalah dependency. Mekanismenya diambil dari dokumentasi Claude Code, yang menarik garis serupa di tabelnya sendiri — standalone configuration untuk workflow pribadi, penyesuaian per project dan eksperimen cepat, sedangkan plugin untuk berbagi dengan rekan satu tim, versioned release, dan pemakaian ulang lintas project.

## Skill adalah dokumen, plugin adalah dependency

Keduanya mengirim markdown yang sama. Skill adalah file SKILL.md dengan YAML frontmatter yang dimuat Claude ketika tugasnya cocok dengan description-nya, dan direktori skills di sebuah plugin berisi file yang persis sama, tanpa perubahan. Bedanya bukan kemampuan, melainkan satuan distribusinya: dokumen yang Anda baca dan sunting, atau dependency yang Anda install, pin, dan upgrade.

Dokumentasinya membuat pembedaan itu terlihat lewat nama perintah. Skill standalone di .claude/skills/hello dipanggil dengan slash hello. Folder yang sama di dalam plugin dipanggil dengan slash nama-plugin titik dua hello, karena skill milik plugin selalu diberi namespace supaya dua plugin tidak bertabrakan di satu nama. Prefix itu sinyal yang jujur: prosedurnya sekarang milik sebuah package, bukan lagi milik project Anda.

## Berapa biaya satu file skill

Tidak ada, selain file itu sendiri. Skill personal tinggal di ~/.claude/skills/nama/SKILL.md dan tersedia di setiap project yang Anda buka; skill project tinggal di .claude/skills/nama/SKILL.md dan dimuat dari direktori tempat Anda memulai sesi plus setiap direktori induk sampai root repository. Tidak ada langkah install, karena keberadaan file di disk itulah instalasinya.

Dua sifat membuatnya sulit dikalahkan selama Anda satu-satunya pembaca. Claude Code mengawasi direktori skill, jadi menambah, menyunting, atau menghapus SKILL.md langsung terbaca di sesi yang sedang berjalan tanpa restart — loop sunting-lalu-uji sepanjang satu kali simpan. Lalu isi badan skill hanya dimuat ketika skill itu dipakai, jadi dokumen referensi yang panjang hampir tidak berbiaya sampai ada yang membutuhkannya. Itu sebabnya tiga skill di repository ini bisa sangat rinci tanpa jadi mahal.

## Apa yang ditambahkan pembungkus plugin

Sebuah manifest dan sebuah kontrak direktori. Plugin mendeklarasikan dirinya di .claude-plugin/plugin.json dengan name, description, version opsional, dan author opsional, lalu semua komponen lain duduk di root plugin: skills, agents, hooks/hooks.json, .mcp.json untuk MCP server, .lsp.json untuk language server, monitors, direktori bin, dan sebuah settings.json. Hanya manifest yang boleh berada di dalam .claude-plugin, dan dokumentasinya menyebut memasukkan direktori komponen ke sana sebagai kesalahan yang paling sering terjadi.

> Ada tangga yang lebih murah daripada marketplace, dan itulah yang sebaiknya dicoba lebih dulu oleh sebagian besar tim. Taruh .claude-plugin/plugin.json di folder yang sudah ada di direktori skills Anda, dan folder itu akan dimuat pada sesi berikutnya sebagai nama at skills-dir, tanpa marketplace dan tanpa langkah install — persis yang di-scaffold oleh claude plugin init. Ia bisa membawa agents, hooks, dan MCP server sambil tetap berupa folder yang Anda sunting di tempat.

Tangga itu juga titik di mana Anda merasakan satuannya berubah. Suntingan pada SKILL.md tetap langsung berlaku, tetapi perubahan pada hooks, .mcp.json, agents, atau output style tidak berlaku sampai Anda menjalankan slash reload-plugins atau restart. Begitu sebuah prosedur menumbuhkan bagian yang harus di-reload, ia berhenti menjadi dokumen.

## Ambangnya adalah drift, bukan jumlah orang

Menyalin folder skill ke mesin kedua bukan masalahnya. Masalahnya, kedua copy itu lalu menyimpang dan tidak ada yang memberi tahu Anda. Claude Code menyelesaikan skill bernama sama antar level dengan urutan prioritas yang tetap — enterprise mengalahkan personal, personal mengalahkan project — jadi rekan yang pernah menyalin prosedur itu ke ~/.claude/skills miliknya akan menjalankan copy lamanya, bukan yang Anda commit, dan tidak ada diff, review, atau pesan startup yang menyebutkannya.

Copy kedua biasanya datang lebih dulu daripada orang kedua. Skill tidak bisa membawa hook: blok hooks tinggal di .claude/settings.json, jadi begitu sebuah prosedur butuh langkah yang deterministik, ia hidup di dua file yang harus disalin bersama dan bisa tersalin terpisah. Migrasi ke plugin memindahkan objek yang sama itu ke hooks/hooks.json dengan format yang sama, dan itu pernyataan paling jelas tentang untuk apa sebuah bundle sebenarnya ada.

Jadi pemicunya bukan ukuran tim. Pemicunya adalah saat pertama Anda tidak bisa menjawab pertanyaan versi mana dari prosedur ini yang sedang dijalankan orang itu. Install pada project scope menjawabnya, karena plugin dituliskan ke .claude/settings.json sehingga repository yang menyebutkan version untuk semua orang. Satu catatan perlu diketahui sebelum Anda bergantung pada itu: plugin yang hanya diaktifkan oleh project dan berasal dari sumber eksternal tidak memasang dirinya sendiri, dan Claude Code melaporkannya sebagai belum terpasang sampai kolaborator menjalankan claude plugin install.

*Band yang perlu diperhatikan adalah yang ketiga, bukan yang keempat: sebuah prosedur terpecah menjadi dua file begitu ia butuh hook, dan itu biasanya terjadi jauh sebelum orang kedua muncul.*

## Upgrade yang tidak Anda jadwalkan

Plugin adalah dependency, artinya ia bisa berubah karena orang lain melakukan push. Claude Code memeriksa marketplace dan plugin terpasang untuk update setelah sesi Anda dimulai, dengan jeda acak sampai sepuluh menit, sehingga sesi yang sedang berjalan tetap memakai version yang dimuat saat launch dan Anda menerima ajakan untuk menjalankan slash reload-plugins atau version baru masuk pada launch berikutnya. Auto-update aktif secara default untuk claude-plugins-official dan sebagian besar marketplace resmi Anthropic lainnya, dan nonaktif secara default untuk marketplace pihak ketiga serta marketplace pengembangan lokal.

Community marketplace melangkah lebih jauh, dan bagian ini layak dibaca dua kali: setiap plugin yang disetujui di-pin ke commit SHA tertentu di katalognya, dan CI menaikkan pin itu secara otomatis saat penulisnya melakukan push commit baru, sementara katalog publiknya melakukan sync setiap malam. Pinning memang ada, tetapi ia milik penulis plugin. Version di plugin.json berarti pengguna hanya menerima update ketika field itu dinaikkan, dan nilainya mengalahkan version di entri marketplace.

> File skill berubah ketika seseorang melakukan commit ke repository Anda. Plugin bisa berubah karena penulisnya melakukan push, dan perubahannya mendarat di tengah pekerjaan yang sedang Anda jalankan. Reload pun tidak gratis: ia berbiaya token pada request berikutnya, dan plugin yang menyediakan MCP server membatalkan prompt cache, sehingga request itu membaca ulang seluruh percakapan kecuali tool search sudah menunda tool-tool tersebut.

## Delapan sumbu yang benar-benar berbeda

Sebagian besar perbandingan keduanya menyusut jadi satu sumbu, yaitu berbagi, lalu mengulanginya dalam empat kolom. Sumbu di bawah ini mengubah perilaku, bukan hanya kosakata, dan hanya tiga yang terakhir yang pernah mengubah keputusan saya.

| Sumbu | Satu file skill | Plugin bundle ber-version |
| --- | --- | --- |
| Distribusi | Commit foldernya, atau salin manual | Tambah marketplace, lalu install per nama dan scope |
| Versioning | Apa pun yang tercatat di git history Anda | Field version di plugin.json yang menggerbangi update |
| Friksi install | Nol — file di disk itulah instalasinya | Marketplace, install, scope, lalu reload atau restart |
| Loop umpan balik | Disunting di tempat, terbaca di tengah sesi | SKILL.md tetap live; hooks dan MCP butuh reload |
| Permukaan review | Satu file markdown, terlihat di diff | Manifest, hooks, MCP, LSP, monitors, bin, settings |
| Radius dampak | Teks yang mungkin dibaca model | Kode sembarang dengan hak akses user Anda |
| Siapa yang merawat | Anda, di repository yang dilayaninya | Penulisnya, dengan ritme rilis yang bukan Anda atur |
| Ketika salah | Hapus foldernya; sesi langsung melepasnya | Disable atau uninstall, lalu reload agar terlepas |

Baca paruh bawahnya lebih dulu. Distribusi dan friksi install sifatnya kosmetik — tim yang kompeten menyelesaikan keduanya dalam satu sore. Permukaan review, radius dampak, dan siapa yang merawat bersifat struktural, karena ketiganya menentukan apa yang harus Anda baca sebelum memercayai sesuatu dan siapa yang boleh mengubahnya setelah Anda memercayainya.

## Apa yang harus dibaca sebelum mengadopsinya

Untuk skill, review-nya adalah file itu sendiri. Buka markdown-nya, baca frontmatter dan prosanya, dan Anda sudah melihat semua yang bisa dilakukannya, karena semua yang bisa dilakukannya adalah meminta model mengerjakan sesuatu. Untuk plugin, review-nya adalah seluruh bundle: manifest, setiap skill dan agent, hooks/hooks.json, .mcp.json, .lsp.json, monitors, direktori bin yang isinya bergabung ke PATH milik tool Bash selama plugin aktif, dan settings.json di root plugin yang lewat key agent bisa mengaktifkan salah satu agent milik plugin itu sebagai main thread dan mengubah perilaku default Claude Code.

Dokumentasinya terus terang soal alasannya: plugin dan marketplace adalah komponen yang sangat dipercaya dan bisa menjalankan kode sembarang di mesin Anda dengan hak akses user Anda, dan Anthropic tidak mengontrol MCP server, file, atau perangkat lunak lain yang dibawa sebuah plugin. Tiga hal membuat review itu masih bisa dikerjakan. Panel detail plugin menampilkan daftar apa yang akan terpasang — commands, agents, skills, hooks, MCP dan LSP server — berdampingan dengan estimasi context cost dan tanggal terakhir diperbarui, sebelum Anda memasang apa pun. Perintah claude plugin validate memeriksa bundle Anda sendiri, dan flag strict-nya mengubah warning menjadi error. Lalu daftar terpasang menandai plugin yang tidak Anda pakai setidaknya dua minggu di sepanjang minimal sepuluh sesi, cara termurah menemukan bundle yang masih menagih context untuk workflow yang sudah Anda tinggalkan.

> Baca daftar will-install dan estimasi context cost pada setiap install, bukan hanya yang tampak berisiko. Context cost sebuah plugin dibayar pada setiap turn di setiap sesi tempat ia aktif, dan estimasinya berada di layar yang sama dengan tombol install.

*Setiap panel adalah superset panel sebelumnya, dan itulah harga sebenarnya dari membundel: pertanyaan yang harus Anda jawab sebelum mengadopsi sebuah workflow tumbuh lebih cepat daripada workflow itu sendiri.*

## Aturan yang saya pakai sekarang

Tiga langkah, berurutan, dan sebagian besar workflow berhenti di langkah pertama.

- Tulis sebagai satu SKILL.md di bawah .claude/skills dan biarkan di sana selama Anda satu-satunya pembacanya. Menyunting di tempat tanpa langkah install lebih bernilai daripada versioning yang belum Anda pakai.
- Naikkan statusnya ketika orang kedua membutuhkan configuration yang identik dan Anda tidak bisa memverifikasi bahwa dia memilikinya. Naikkan dulu menjadi plugin skills-dir, yang memberi Anda hooks, agents, dan MCP server tanpa marketplace.
- Terbitkan marketplace hanya ketika install manual justru menjadi sumber drift-nya, dan tetapkan version di plugin.json sebelum Anda menyuruh siapa pun memasangnya, karena alternatifnya adalah pengguna Anda mengikuti commit terakhir Anda.

Kasus sebaliknya nyata dan saya tidak ingin menyanggahnya. Tiga orang yang menyalin folder skill secara manual lalu menempelkan blok hooks ke tiga file settings terpisah adalah tepat drift yang membuat plugin perlu ada, dan pada titik itu version, marketplace, serta permukaan review yang lebih luas hanyalah harga dari workflow yang sama untuk semua orang. Yang saya tolak adalah membayar harga itu ketika pembacanya baru satu.

Jadi pertanyaannya bukan apakah sebuah workflow cukup penting untuk jadi plugin. Pertanyaannya adalah apakah copy-nya sudah lebih dari satu, dan apakah Anda bisa tahu kalau copy-copy itu menyimpang. Kalau jawabannya tidak, yang Anda punya adalah dokumen, dan dokumen tempatnya di file yang bisa Anda sunting sambil ia berjalan.

## Sumber

- Dokumentasi Claude Code — Create plugins: perbandingan standalone versus plugin, field manifest, dan kontrak direktori plugin
- Dokumentasi Claude Code — Extend Claude with skills: tempat skill hidup, prioritas antar level, field frontmatter, dan live change detection
- Dokumentasi Claude Code — Discover and install plugins: install scope, perilaku auto-update, panel will-install, dan peringatan keamanan
- Dokumentasi Claude Code — Plugins reference: version management, plugin skills-directory, serta perintah validate dan reload
- Dokumentasi Claude Code — Prompt caching: biaya mengaktifkan, menonaktifkan, atau me-reload plugin terhadap prompt cache

## Source links

- https://code.claude.com/docs/en/plugins
- https://code.claude.com/docs/en/skills
- https://code.claude.com/docs/en/discover-plugins
- https://code.claude.com/docs/en/plugins-reference
- https://code.claude.com/docs/en/prompt-caching

## FAQ

### Sebaiknya workflow Claude Code saya jadi skill atau plugin?

Mulailah sebagai skill dan biarkan begitu selama Anda satu-satunya pembacanya. Dokumentasi Claude Code membaginya dengan cara yang sama: standalone configuration di bawah .claude/ untuk workflow pribadi, penyesuaian project, dan eksperimen cepat, sedangkan plugin untuk berbagi dengan rekan tim, versioned release, dan pemakaian ulang lintas project. Naikkan jadi plugin ketika lebih dari satu orang harus menjalankan configuration yang identik dan Anda tidak bisa memverifikasi bahwa copy mereka sama.

### Apakah skill Claude Code bisa memuat hooks atau MCP server?

Tidak, kalau berdiri sendiri. Skill biasa hanyalah file SKILL.md, sementara blok hooks tinggal di .claude/settings.json dan MCP server dikonfigurasi terpisah, jadi prosedur yang membutuhkan salah satunya sudah tersebar di dua file. Menambahkan .claude-plugin/plugin.json ke folder skill mengubahnya menjadi plugin yang bisa membawa hooks, agents, dan MCP server, dan proses migrasi memindahkan objek hooks yang sama ke hooks/hooks.json dengan format yang sama.

### Apa itu plugin skills-dir di Claude Code?

Itu plugin yang tidak butuh marketplace. Folder mana pun di direktori skills Anda yang berisi manifest .claude-plugin/plugin.json akan dimuat pada sesi berikutnya sebagai nama at skills-dir, tanpa langkah install, dan claude plugin init men-scaffold tata letak itu. Versi project scope baru dimuat setelah Anda menerima dialog workspace trust, dan suntingan SKILL.md tetap langsung berlaku sementara perubahan hooks, agents, dan MCP butuh slash reload-plugins.

### Apakah plugin Claude Code bisa update sendiri di tengah sesi?

Version yang Anda pakai saat launch tetap dimuat, tetapi update-nya sudah diambil. Claude Code memeriksa marketplace dan plugin terpasang setelah sesi dimulai, dengan jeda acak sampai sepuluh menit, lalu mengajak Anda menjalankan slash reload-plugins atau menyimpan version baru untuk launch berikutnya. Auto-update aktif secara default untuk claude-plugins-official dan sebagian besar marketplace resmi Anthropic lainnya, dan bisa dimatikan lewat environment variable DISABLE_AUTOUPDATER.

### Apa yang perlu diperiksa sebelum memasang plugin Claude Code?

Baca daftar will-install dan estimasi context cost di panel detail plugin sebelum Anda mengonfirmasi, karena keduanya muncul di layar yang sama dengan tombol install. Setelah itu lihat isi bundle-nya: hooks/hooks.json menjalankan perintah shell, direktori bin bergabung ke PATH milik tool Bash selama plugin aktif, dan settings.json di root plugin bisa mengaktifkan salah satu agent milik plugin itu sebagai main thread. Dokumentasi Anthropic sendiri memperingatkan bahwa plugin dan marketplace bisa menjalankan kode sembarang dengan hak akses user Anda.

---

- HTML version: https://www.matthewswong.com/id/blog/claude-code-plugin-vs-skill-bundling/
- English: https://www.matthewswong.com/en/blog/claude-code-plugin-vs-skill-bundling/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json