Claude Code Plugin vs Skill: Kapan Perlu Dibundel

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.

# A skill is a folder with one required file in it. There is no install
# step, because being on disk IS the installation.
.claude/skills/publishing-blog-posts/SKILL.md      # project, this repo
~/.claude/skills/summarise-changes/SKILL.md        # personal, everywhere

# The whole interface is the frontmatter. description is what Claude
# matches the task against, so it is the only field that decides whether
# the skill is ever loaded at all.
---
name: publishing-blog-posts
description: The staging and merge pipeline for a bilingual blog post.
  Use when adding, merging or debugging a post or the merge scripts.
disable-model-invocation: false   # default; true means only /name invokes it
allowed-tools: Read Grep          # pre-approved for the invoking turn only
---

# Project skills load from the starting directory AND every parent up to
# the repository root, so starting Claude in a subdirectory still finds
# the skills defined at the root.
#
# The trap: across levels, personal beats project. A stale copy in
# ~/.claude/skills wins over the one you committed, and nothing says so.

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.

# The same markdown, wrapped. Only plugin.json goes inside
# .claude-plugin/ — every component directory sits at the plugin root.
my-tool/
  .claude-plugin/plugin.json   # name, description, version, author
  skills/publishing-blog-posts/SKILL.md
  agents/blog-post-author.md
  hooks/hooks.json             # the same object you had in settings.json
  .mcp.json                    # MCP servers the bundle brings with it
  bin/                         # joins the Bash tool PATH while enabled
  settings.json                # its agent key can swap the main thread

# The manifest, in full. version is optional, and it is the field that
# decides whether your users ever cross a change you did not intend:
#   name         "my-tool"
#   description  "Blog publishing pipeline"
#   version      "1.0.0"

# Test it without installing anything and without a marketplace:
claude --plugin-dir ./my-tool      # also accepts ./my-tool.zip
claude plugin validate ./my-tool   # --strict fails on warnings too

# Or skip the marketplace permanently. A manifest dropped into a folder
# that is already in your skills directory loads as my-tool@skills-dir:
claude plugin init my-tool         # scaffolds it under ~/.claude/skills

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.

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.

# What changes under you, and how to stop it changing.

# Auto-update runs AFTER your session starts, with a random delay of up
# to ten minutes, so the running session keeps the versions it launched
# with and you get a line instead of a surprise:
#
#   Run /reload-plugins to activate.
#
# ON by default: claude-plugins-official and most official Anthropic
# marketplaces. OFF by default: third-party and local development ones.

# Stop Claude Code and its marketplace plugins updating themselves:
export DISABLE_AUTOUPDATER=1

# The combination most teams actually want — pin the CLI for a sprint,
# keep the plugins current:
export DISABLE_AUTOUPDATER=1
export FORCE_AUTOUPDATE_PLUGINS=1

# Pull an update on purpose rather than on a timer, and read what the
# new version installs before you reload it:
claude plugin marketplace update my-team-tools
claude plugin details my-tool

# If you are the author, ship a version in plugin.json. Without one your
# users track whatever you last pushed: in the community catalogue every
# plugin is pinned to a commit SHA, and CI bumps that pin as you push.

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.

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.

Aturan yang saya pakai sekarang

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

1. 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.
2. 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.
3. 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.