Kalidad na Kailangan para sa Production Plugin
Malaki ang pagkakaiba ng kalidad na kailangan sa pagitan ng plugin na nakalagay sa personal na dotfiles at plugin na ilalabas sa pampublikong marketplace. Sa una, sapat na ang "gumagana sa sariling environment" — pero sa huli, kailangang isaalang-alang ang iba't ibang OS, bersyon ng Node.js, shell, pakikipagsabay sa mga kasalukuyang settings, onboarding experience, at upgrade strategy.
Sa Abril 2026, mahigit 1,800 plugin na ang naka-publish sa opisyal na plugin marketplace ng Anthropic, pero tanging mga 100 lang sa itaas ang may weekly active install na higit sa 1,000. Hindi kagulat-gulat na ang nagdudulot ng pagkakaibang ito ay hindi ang ganda ng features, kundi ang "ordinaryong pundasyon" — kalidad ng manifest, dokumentasyon, disiplina sa versioning, at tamang paraan ng pag-merge ng settings.
Standard na Istruktura ng Repository
Ganito ang standard na istruktura ng plugin repository:
``` my-claude-plugin/ ├── .claude-plugin/ │ └── plugin.json # manifest (required) ├── commands/ # slash commands │ ├── review.md │ └── deploy.md ├── skills/ # skills │ └── security-audit/ │ └── SKILL.md ├── agents/ # sub-agent definitions │ └── researcher.md ├── hooks/ # hook settings │ └── hooks.json ├── mcp/ # bundled MCP server │ ├── server.ts │ └── package.json ├── scripts/ # install / migration scripts │ └── postinstall.sh ├── README.md ├── CHANGELOG.md └── LICENSE ```
Halos lahat ng sikat na repo tulad ng gsd-build/get-shit-done at wshobson/agents ay nagtutungo sa istrukturang ito. Lalo na ang paglalagay ng .claude-plugin/plugin.json sa tuktok — ito ay de-facto na required convention dahil ang `plugin add` command ng Anthropic CLI ay hinahanap ito sa eksaktong path na iyon.
Paano Isulat ang plugin.json Manifest
Ang plugin.json ay kailangang may hindi bababa sa mga sumusunod na field:
```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" } } ```
I-update ang `claudeCode.minVersion` tuwing may breaking change. Ang pinakamasamang UX ay ang plugin na naka-install sa lumang CLI ng user na tahimik na hindi gumagana. Ang `configSchema` ay nagbibigay ng JSON Schema validation para sa settings ng user, kaya may friendly error message kapag may mali sa configuration.
Praktikal na Semantic Versioning
Ang versioning ng plugin ay sumusunod sa semver, pero may sariling kahirapan sa pagtukoy kung ano ang "breaking change." Ang pagbabago ng pangalan ng slash command, pagbabago ng matcher ng kasalukuyang hook, at pagdaragdag ng required field sa inputSchema ng MCP tool — lahat ito ay breaking changes. Sa kabaligtaran, pagdaragdag ng bagong command, pagdaragdag ng optional argument sa kasalukuyang command, at pagdaragdag ng bagong MCP tool ay minor version lang.
Malakas na inirerekomenda ang CHANGELOG.md sa Keep a Changelog format. Awtomatikong ino-parse ng marketplace UI ang CHANGELOG.md para ipakita ito sa update screen, kaya direktang epekto ang consistent na format. Sa KGA IT, ipinapatupad namin ang format na ito sa lahat ng proyekto, kasama ang mga internal plugin.
Pamamahagi sa Marketplace
Sa Abril 2026, may tatlong pangunahing channel ng pamamahagi. Una ang opisyal na Anthropic marketplace (claude.ai/plugins), na may pinakamataas na discoverability kahit may review process. Pangalawa ang direktang install mula sa GitHub repository (`claude plugin add github.com/user/repo`), na paboritong paraan ng mga OSS author dahil walang review at agad na available. Pangatlo ang private marketplace, kung saan hinahosta ng mga kumpanya ang kanilang sariling `claude-plugin-registry` para sa internal distribution.
Sa official marketplace review, sinusuri ang bisa ng shell command execution, malinaw na deklarasyon ng mga network destination, patakaran sa paghawak ng personal data, at seguridad ng payment flow para sa mga paid plugin. Simula Pebrero 2026, ipinakilala ang sistema ng "audit badge" — ang mga plugin na nakapasa sa static analysis ay may berdeng badge. Ayon sa nailabas na data, ang presensya ng badge na ito ay nagdodoble o higit pa ng adoption rate, kaya lubos na inirerekumenda ang pagkuha nito.
Telemetry at Observability
Kailangan sa pag-operate ng plugin na malaman kung paano ginagamit ito ng mga user. Pero ang mga gumagamit ng Claude Code ay may mataas na kamalayan sa privacy, at ang hindi malinaw na telemetry ay agad na magdudulot ng uninstall. Ang inirerekomendang approach ay "opt-in, anonymous, aggregate values lang" ang tatlong prinsipyo.
Sa practice, mag-prompt ng "Pumayag ka bang magpadala ng anonymous na usage statistics?" sa unang startup, at kapag Yes, magpadala lang ng install ID at bilang ng bawat command call nang daily. Huwag kailanman magpadala ng nilalaman ng prompt o file path. Ginagamit ng wshobson/agents ang pamamaraang ito para mag-rank ng mga popular na Subagent definition at ini-publish ito monthly sa README. Gumagana rin ito bilang signal na "naaalagaan ang plugin na ito."
Pagsunod sa Breaking API Changes
Mula noong huling bahagi ng 2025, pabilis nang pabilis ang bilis ng pagdaragdag ng feature sa Claude Code mismo, at minsan ay hindi na gumagana ang mga kasalukuyang plugin kahit sa minor versions. Nang binago ang Hook contract sa Claude Code 3.0 noong Enero 2026 at naging required ang JSON passing sa pamamagitan ng stdin, mahigit 1,200 plugin ang napilitang mag-update sa loob ng dalawang linggo.
May dalawang layer ng countermeasure. Una, mahigpit na tukuyin ang `claudeCode.minVersion` sa plugin.json para hindi ito magsimula sa mga hindi compatible na CLI. Pangalawa, mag-run ng integration tests gamit ang `claude-code-nightly` sa GitHub Actions para i-automate ang compatibility verification sa mga bagong bersyon. Simula Pebrero, nag-publish ang Anthropic ng `plugin-compat-matrix`, na nivi-visualize ang status ng mga official plugin sa bawat CLI version. Ang third-party ay sumusunod na rin sa schema na ito.
Merge Strategy para sa User Settings
Sumusulat ang plugin sa .claude/settings.json, pero hindi dapat sirain ang mga kasalukuyang settings ng user. Ang inirerekomendang implementation ay "JSON Pointer-based patch application." I-save ang diff patch sa .claude/plugins/<name>/applied-patch.json sa oras ng plugin install, at tiyaking maaaring i-reverse apply ito nang tama sa oras ng uninstall.
Lalo na dapat mag-ingat sa pag-merge ng `permissions` array. Upang maiwasan ang conflict sa mga kasalukuyang allow/deny rules ng user, nagiging custom na ang paglalagay ng namespace prefix (hal.: "gsd:*") sa mga plugin-specific rule para ma-isolate ang mga ito. Nanguna ang get-shit-done sa pamamaraang ito at naging reference implementation para sa maraming susunod na plugin.
Operations Pagkatapos ng Pag-publish
Hindi natatapos sa pag-publish. Ang bilis ng initial response sa GitHub Issues, agarang patch kapag may semver violation, proseso ng pag-issue ng security advisory, at notification sa user ng deprecation notice — ang kalidad ng operasyong ito ang nagtatakda ng pangmatagalang adoption rate. Mas sikat ang plugin, mas mataas ang operational burden, at maaaring kailanganin ang dagdag na maintainer o pagbubuo ng korporasyon.
Sa KGA IT, kapag naghahatid ng internal plugin sa mga kliyente, isinasama namin ang operations runbook, on-call setup, at quarterly review meeting sa isang package. Ang plugin ay hindi deliverable — ito ay isang produkto, at responsibilidad sa operasyon ang nagsisimula sa sandaling ma-publish sa production. Ito ang hangganan na naghihiwalay sa professional-quality na plugin sa hobbyist na plugin.