Production-Quality Standards
The quality bar for a plugin you tuck into your personal dotfiles and one you publish to a public marketplace are worlds apart. The former just needs to work in your own environment; the latter must account for diverse operating systems, Node.js versions, shells, coexistence with existing settings, onboarding experience, and upgrade strategy.
As of April 2026, Anthropic's official plugin marketplace hosts over 1,800 plugins, but fewer than 100 crack 1,000 weekly active installs. The gap isn't driven by flashy features — it comes down to the unglamorous fundamentals: manifest quality, documentation, versioning discipline, and clean settings-merge behavior.
Standard Repository Structure
A well-structured plugin repository looks like this:
``` 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 configuration │ └── hooks.json ├── mcp/ # Bundled MCP server │ ├── server.ts │ └── package.json ├── scripts/ # Install / migration scripts │ └── postinstall.sh ├── README.md ├── CHANGELOG.md └── LICENSE ```
Popular repos like gsd-build/get-shit-done and wshobson/agents have converged on essentially this layout. Placing `.claude-plugin/plugin.json` at the top is especially non-negotiable: the Anthropic CLI's `plugin add` command hard-codes that path.
Writing the plugin.json Manifest
At minimum, plugin.json needs these fields:
```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" } } ```
Update `claudeCode.minVersion` every time you introduce a breaking change — the worst UX is a silent malfunction on an older CLI. `configSchema` uses JSON Schema to validate user settings and surface helpful error messages when something is misconfigured.
Semantic Versioning in Practice
Semver is the baseline, but deciding what counts as a breaking change takes judgment. Renaming a slash command, changing an existing hook's matcher, or adding a required field to an MCP tool's `inputSchema` are all breaking changes. Adding a new command, making an argument optional, or introducing a new MCP tool are minor-version bumps.
Keep a Changelog format is strongly recommended for CHANGELOG.md. The marketplace UI auto-parses it for the update screen, so formatting consistency has a direct impact. At KGA IT we enforce this format across all client-facing and internal plugins.
Marketplace Distribution
As of April 2026, there are three main distribution channels. First, Anthropic's official marketplace (claude.ai/plugins): reviewed, but highest discoverability. Second, direct installation from a GitHub repo (`claude plugin add github.com/user/repo`): no review, instant, popular with OSS authors. Third, private marketplaces: organizations host their own `claude-plugin-registry` for internal distribution.
The official marketplace review checks shell command legitimacy, explicit declaration of outbound network destinations, privacy handling, and — for paid plugins — payment flow security. Since February 2026, an "audit badge" is awarded to plugins that pass static analysis. Data shows adoption rates more than double for badged plugins, so pursuing it is strongly advised.
Telemetry and Observability
Knowing how your plugin is actually being used is essential for operations. That said, Claude Code users are privacy-conscious — opaque telemetry triggers immediate uninstalls. The recommended approach follows three principles: opt-in, anonymous, aggregates only.
Concretely: on first launch, ask "Do you consent to sending anonymous usage statistics?" Send only an installation ID and per-command invocation counts on a daily basis — only if the user said yes. Never transmit prompt content or file paths. wshobson/agents uses this approach to compile a popularity ranking of Subagent definitions and publishes it monthly in the README. That transparency also signals responsible stewardship.
Keeping Up with Breaking API Changes
Claude Code's pace of development has accelerated since late 2025, and even minor releases occasionally break existing plugins. When Claude Code 3.0 changed the hook contract in January 2026 — making JSON-via-stdin mandatory — 1,200 plugins needed updates within two weeks.
The defense is two-layered. First, pin `claudeCode.minVersion` strictly so the plugin refuses to start on unsupported CLI versions. Second, run integration tests against `claude-code-nightly` in GitHub Actions to catch regressions automatically. Anthropic started publishing a `plugin-compat-matrix` in February that shows compatibility status across CLI versions for official plugins; third-party plugins are following suit.
User Settings Merge Strategy
Plugins write to `.claude/settings.json`, but they must never clobber the user's existing configuration. The recommended approach is JSON Pointer-based patching: save the diff as `.claude/plugins/<name>/applied-patch.json` at install time so it can be precisely reversed on uninstall.
Pay special attention to the `permissions` array. To avoid conflicts with the user's existing allow/deny rules, it's becoming standard practice to namespace plugin-specific rules with a prefix (e.g., `"gsd:*"`). get-shit-done pioneered this pattern and has become a reference implementation for many plugins that followed.
Life After Launch
Publishing isn't the finish line. Response time on GitHub Issues, prompt patches when semver is violated, security advisory procedures, and notifying users of deprecations — all of this operational quality determines long-term adoption. The more popular a plugin, the heavier the maintenance burden; some maintainers end up expanding their team or forming a legal entity.
At KGA IT, when we deliver internal plugins to clients we package the runbook, on-call setup, and quarterly review meetings as part of the engagement. A plugin is a product, not a deliverable — the moment it goes live, you own the operational responsibility. That mindset is the line between professional-grade plugins and hobby projects.