Kualiti yang Diperlukan untuk Plugin Produksi
Kualiti yang diperlukan antara plugin yang disimpan dalam dotfiles peribadi dan plugin yang diterbitkan di marketplace awam berbeza jauh. Yang pertama boleh beroperasi selagi berfungsi dalam persekitaran sendiri, tetapi yang kedua perlu mengambil kira pelbagai OS, versi Node.js, shell, kewujudan bersama tetapan sedia ada, pengalaman onboarding, dan strategi peningkatan versi.
Sehingga April 2026, lebih 1,800 plugin telah diterbitkan di marketplace plugin rasmi Anthropic, tetapi hanya kira-kira 100 teratas yang melebihi 1,000 pemasangan aktif mingguan. Perbezaan ini bukan disebabkan oleh kecanggihan ciri, tetapi oleh "asas yang tidak mencolok" seperti kualiti manifes, dokumentasi, disiplin penomboran versi, dan tatacara penggabungan konfigurasi.
Struktur Repositori Standard
Struktur repositori plugin standard adalah seperti berikut.
``` my-claude-plugin/ ├── .claude-plugin/ │ └── plugin.json # Manifes (wajib) ├── commands/ # Perintah slash │ ├── review.md │ └── deploy.md ├── skills/ # Kemahiran │ └── security-audit/ │ └── SKILL.md ├── agents/ # Definisi sub-ejen │ └── researcher.md ├── hooks/ # Konfigurasi hook │ └── hooks.json ├── mcp/ # Pelayan MCP yang disertakan │ ├── server.ts │ └── package.json ├── scripts/ # Skrip pemasangan dan migrasi │ └── postinstall.sh ├── README.md ├── CHANGELOG.md └── LICENSE ```
Repositori popular seperti gsd-build/get-shit-done dan wshobson/agents hampir semua menumpu kepada struktur ini. Khususnya, konvensyen meletakkan `.claude-plugin/plugin.json` di bahagian atas adalah peraturan yang wajib dipatuhi kerana perintah `plugin add` Anthropic CLI mencari laluan ini secara langsung.
Cara Menulis Manifes plugin.json
plugin.json mesti mempunyai sekurang-kurangnya medan berikut.
```json { "name": "gsd-build", "displayName": "Get Shit Done", "version": "2.4.1", "description": "Stop-hook driven task persistence for Claude Code", "author": { "name": "GSD Team", "url": "https://github.com/gsd-build" }, "license": "MIT", "homepage": "https://github.com/gsd-build/get-shit-done", "repository": "https://github.com/gsd-build/get-shit-done.git", "claudeCode": { "minVersion": "2.8.0" }, "commands": ["commands/"], "skills": ["skills/"], "agents": ["agents/"], "hooks": "hooks/hooks.json", "mcpServers": { "gsd-db": { "command": "node", "args": ["mcp/server.js"] } }, "configSchema": "config.schema.json", "telemetry": { "endpoint": "https://telemetry.gsd.dev/v1" } } ```
`claudeCode.minVersion` mesti dikemas kini setiap kali ada perubahan yang memecah keserasian. Ini kerana pemasangan pada CLI lama pengguna yang menyebabkan kegagalan fungsi tersembunyi adalah pengalaman pengguna yang paling buruk. `configSchema` menyediakan pengesahan konfigurasi pengguna dalam format JSON Schema dan memastikan mesej ralat yang mesra dipaparkan apabila konfigurasi salah.
Amalan Penomboran Versi Semantik
Penomboran versi plugin pada asasnya mengikuti semver, tetapi pertimbangan "apa yang dianggap perubahan yang memecah keserasian" mempunyai kesukaran tersendiri. Perubahan nama perintah slash, perubahan matcher pada hook sedia ada, dan penambahan medan wajib dalam inputSchema alat MCP semuanya adalah perubahan yang memecah keserasian. Sebaliknya, penambahan perintah baru, penambahan argumen pilihan pada perintah sedia ada, dan penambahan alat MCP baharu boleh dilakukan dengan versi minor.
CHANGELOG.md sangat disyorkan menggunakan format Keep a Changelog. Ini kerana UI marketplace akan menghurai CHANGELOG.md secara automatik dan memaparkannya di skrin kemas kini, jadi penyeragaman format membawa manfaat praktikal secara langsung. Di KGA IT kami, format ini dikuatkuasakan untuk semua projek termasuk plugin dalaman.
Pengedaran Marketplace
Sehingga April 2026, terdapat tiga saluran pengedaran utama. Pertama ialah marketplace rasmi Anthropic (claude.ai/plugins), yang mempunyai semakan tetapi menawarkan kebolehcarian tertinggi. Kedua ialah pemasangan langsung dari repositori GitHub (`claude plugin add github.com/user/repo`), yang popular di kalangan penulis OSS kerana tiada semakan dan pengesahan segera. Ketiga ialah marketplace peribadi, di mana syarikat menghoskan `claude-plugin-registry` sendiri untuk pengedaran dalaman.
Semakan marketplace rasmi memeriksa kesahihan pelaksanaan perintah shell, penzahiran destinasi penghantaran rangkaian, pengisytiharan pengendalian maklumat peribadi, dan keselamatan aliran pembayaran untuk plugin berbayar. Mulai Februari 2026, sistem "audit badge" telah diperkenalkan, dan plugin yang lulus analisis statik mendapat lencana hijau. Data yang diterbitkan menunjukkan kadar penerimaan lebih daripada dua kali ganda dengan kehadiran lencana ini, jadi mendapatkannya sangat disyorkan.
Telemetri dan Kebolehmerhatian
Pemahaman tentang "siapa yang menggunakan dan bagaimana" adalah penting untuk operasi plugin. Walau bagaimanapun, pengguna Claude Code sangat sedar privasi, dan telemetri yang tidak telus akan menyebabkan penyahpasangan segera. Pendekatan yang disyorkan adalah tiga prinsip: "opt-in, tanpa nama, hantar nilai agregat sahaja".
Secara khusus, pada permulaan pertama, paparkan gesaan "Adakah anda bersetuju untuk menghantar statistik penggunaan tanpa nama?", dan hanya jika Ya, hantar ID pemasangan dan bilangan panggilan setiap perintah secara harian. Kandungan gesaan individu atau laluan fail tidak sekali-kali dihantar. wshobson/agents mengumpulkan ranking definisi Subagent popular menggunakan kaedah ini dan menerbitkannya di README setiap bulan. Ini juga berfungsi sebagai isyarat bahawa "plugin ini dikendalikan dengan sihat".
Mengikuti API yang Memecah Keserasian
Claude Code itu sendiri telah mempercepatkan kadar penambahan ciri sejak separuh kedua 2025, dan terdapat kes-kes jarang di mana plugin sedia ada tidak berfungsi walaupun dengan versi minor. Apabila kontrak Hook berubah dalam Claude Code 3.0 pada Januari 2026 dan penyerahan JSON melalui stdin menjadi wajib, 1,200 plugin terpaksa mengemaskini dalam masa dua minggu.
Terdapat dua lapisan langkah balas. Pertama, tentukan `claudeCode.minVersion` dalam plugin.json secara ketat dan pastikan ia tidak bermula pada CLI yang tidak disokong. Kemudian, automatikkan pengesahan operasi pada versi baharu menggunakan ujian integrasi yang menjalankan `claude-code-nightly` dalam GitHub Actions. Anthropic telah menerbitkan `plugin-compat-matrix` sejak Februari, yang menunjukkan status operasi plugin rasmi pada setiap versi CLI. Pihak ketiga juga mengikuti skema ini.
Strategi Penggabungan Konfigurasi Pengguna
Plugin menulis ke `.claude/settings.json`, tetapi tidak boleh merosakkan tetapan pengguna yang sedia ada. Pelaksanaan yang disyorkan adalah "penerapan tampalan berasaskan JSON Pointer". Simpan tampalan perbezaan ke `.claude/plugins/<name>/applied-patch.json` semasa pemasangan plugin dan pastikan ia boleh diterbalikkan dengan tepat semasa penyahpasangan.
Perkara yang perlu diberi perhatian khusus ialah penggabungan tatasusunan permissions. Untuk mengelakkan konflik dengan peraturan allow/deny sedia ada pengguna, konvensyen untuk mengasingkan peraturan khusus plugin dengan awalan namespace (contoh: `"gsd:*"`) semakin mantap. get-shit-done telah mengamalkan pendekatan ini secara perintis dan menjadi pelaksanaan rujukan bagi banyak plugin kemudiannya.
Operasi Selepas Penerbitan
Ini bukan sekadar diterbitkan dan selesai. Kelajuan tindak balas awal isu GitHub, tampalan segera apabila ada pelanggaran semver, prosedur pengeluaran nasihat keselamatan, dan pemberitahuan pengguna tentang notis tamat penggunaan — kualiti operasi ini menentukan kadar penerimaan jangka panjang. Semakin popular sesuatu plugin, semakin tinggi beban operasinya, dan terdapat kes-kes di mana penambahan ahli penyelenggara atau pemerbadanan diperlukan.
Di KGA IT kami, apabila menyerahkan plugin dalaman kepada pelanggan, kami membungkuskan runbook operasi, sistem bertugas, dan mesyuarat semakan suku tahunan sebagai satu pakej. Plugin adalah produk, bukan hasil kerja, dan tanggungjawab operasi bermula saat ia diterbitkan untuk produksi — kesedaran ini adalah garis sempadan yang membezakan plugin berkualiti profesional daripada plugin hobi.