生产级插件的质量要求
放在个人 dotfiles 中的插件与发布到公开市场的插件，所要求的质量相差悬殊。前者「能在自己的环境中运行即可」，而后者则必须考虑多样的操作系统、Node.js 版本、Shell 环境、与现有配置的兼容性、用户引导体验以及升级策略。
截至 2026 年 4 月，Anthropic 官方插件市场已发布超过 1,800 个插件，但周活跃安装量超过 1,000 的仅有约 100 个。拉开差距的并非功能的华丽程度，而是 manifest 质量、文档、版本控制规范、配置合并规范等「看似平凡的基础」。
标准仓库结构
插件仓库的标准结构如下。
``` my-claude-plugin/ ├── .claude-plugin/ │ └── plugin.json # manifest（必须） ├── commands/ # 斜杠命令 │ ├── review.md │ └── deploy.md ├── skills/ # 技能 │ └── security-audit/ │ └── SKILL.md ├── agents/ # 子 Agent 定义 │ └── researcher.md ├── hooks/ # Hook 配置 │ └── hooks.json ├── mcp/ # 内置 MCP 服务器 │ ├── server.ts │ └── package.json ├── scripts/ # 安装/迁移脚本 │ └── postinstall.sh ├── README.md ├── CHANGELOG.md └── LICENSE ```
gsd-build/get-shit-done、wshobson/agents 等热门仓库几乎都收敛到了这一结构。尤其是将 `.claude-plugin/plugin.json` 放在顶层的惯例，是因为 Anthropic CLI 的 `plugin add` 命令会硬编码查找此路径，实际上已成为必须遵守的规范。
plugin.json manifest 的写法
plugin.json 至少需要包含以下字段。
```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`。若用户以旧版 CLI 安装后发生隐性故障，是最糟糕的用户体验。`configSchema` 以 JSON Schema 格式为用户配置提供校验，确保配置出错时能显示友好的错误信息。
语义化版本控制的实践
插件版本控制遵循 semver 是基本原则，但「何为破坏性变更」的判断有其独特难度。斜杠命令名称变更、现有 Hook 的 matcher 变更、MCP 工具 inputSchema 中新增必填字段，均属破坏性变更。反之，新增命令、为现有命令增加可选参数、新增 MCP 工具，则可在次版本号中处理。
CHANGELOG.md 强烈推荐采用 Keep a Changelog 格式。市场 UI 会自动解析 CHANGELOG.md 并在更新页面展示，因此格式统一直接关系到实际效益。KGA IT 对所有项目（包括内部插件）均强制执行该格式。
市场分发
截至 2026 年 4 月，主要分发渠道有三种。第一是 Anthropic 官方市场（claude.ai/plugins），虽有审核但可见度最高。第二是从 GitHub 仓库直接安装（`claude plugin add github.com/user/repo`），无需审核、即时生效，深受开源作者欢迎。第三是私有市场，即企业内部托管 claude-plugin-registry 进行内部分发。
官方市场审核会检查：Shell 命令执行的合理性、网络传输目标的明示、个人信息处理声明，以及付费插件的支付流程安全性。2026 年 2 月引入了「audit badge」制度，通过静态分析的插件将获得绿色徽章。公开数据显示，有无该徽章导致采用率相差两倍以上，强烈建议申请。
遥测与可观测性
插件运营中，了解「谁在如何使用」不可或缺。但 Claude Code 用户隐私意识较强，不透明的遥测会导致插件被立即卸载。推荐的方法是遵循「选择加入、匿名、仅发送聚合值」三项原则。
具体而言，首次启动时询问「是否同意发送匿名使用统计？」，仅在用户同意的情况下，每日发送安装 ID 和各命令调用次数。绝不发送单次提示内容或文件路径。wshobson/agents 采用此方式统计热门 Subagent 定义排行，并每月在 README 中公开，这也起到了「该插件运营健全」的信号作用。
跟进破坏性 API 变更
Claude Code 本体自 2025 年下半年起加快了功能迭代节奏，偶尔出现次版本更新也导致现有插件无法运行的情况。2026 年 1 月 Claude Code 3.0 变更了 Hook 约定，强制要求通过 stdin 传递 JSON，导致约 1,200 个插件在两周内被迫更新。
应对措施分两层。首先在 plugin.json 中严格指定 `claudeCode.minVersion`，确保在不兼容的 CLI 上不启动。其次通过 GitHub Actions 使用 claude-code-nightly 运行集成测试，自动化验证在新版本上的运行情况。Anthropic 自 2 月起公开了 plugin-compat-matrix，可视化各 CLI 版本下官方插件的运行状态，第三方也逐渐跟进该规范。
用户配置的合并策略
插件会向 `.claude/settings.json` 写入内容，但绝不能破坏用户的现有配置。推荐的实现方式是「基于 JSON Pointer 的补丁应用」。在 `plugin install` 时将差量补丁保存到 `.claude/plugins/<name>/applied-patch.json`，确保卸载时能精确逆向应用。
需要特别注意的是 `permissions` 数组的合并。为避免与用户现有的 allow/deny 规则冲突，为插件专属规则加上命名空间前缀（如 `"gsd:*"`）进行隔离，正逐渐成为惯例。get-shit-done 率先采用了此方式，并成为众多后续插件的参考实现。
发布后的运营
发布之后并非终点。GitHub Issues 的初步响应速度、semver 违规时的即时 patch、安全公告的发布流程、deprecation notice 的用户通知——这些运营质量决定了长期的采用率。越热门的插件，运营负担越重，有时甚至需要增加维护者或法人化。
KGA IT 在向客户交付内部插件时，会将运营手册、随叫随到体制、季度审查会议一并打包提供。插件不是交付物，而是产品；正式上线的那一刻起，运营责任便已产生——正是这种认识，划定了专业级插件与业余插件之间的分界线。