| name | maintain-claude-plugins |
| description | My personal, authoritative spec for building, developing, versioning, releasing, and wiring dependencies for my own Claude Code plugins through a split-repo plus central-marketplace setup. Use when creating a new plugin repo, laying out a plugin's .claude/skills/<name>/ folder, writing plugin.json or marketplace.json, tagging a plugin release, wiring plugin-to-plugin dependencies, authenticating private repos, or when I ask how to structure, release, or publish my Claude Code plugin. |
维护我自己的 Claude Code 插件
这是我维护自己 Claude Code 插件的终极规范. 完整内容在 reference/personal-plugin-marketplace-best-practices.md —— 需要具体做法或想回看某条决策的理由时读它.
架构一句话
三类 GitHub 仓库各司其职:
- 每个插件一个独立 repo, 插件代码放在
.claude/skills/<插件名>/ 下 (开发时靠 @skills-dir 自动加载, 发布时用 git-subdir 引用).
- 一个中央 marketplace repo, 只有一个
.claude-plugin/marketplace.json catalog, 用 git-subdir source + ref 指向各插件 repo 的发布 tag.
- 使用者的 workspace repo, 在
.claude/settings.json 里用 extraKnownMarketplaces + enabledPlugins 声明式装插件.
什么时候读 reference 的哪一节
| 我要做的事 | 读哪节 |
|---|
| 建新插件 repo / 摆放插件目录 / 写 plugin.json | 1, 2.1 |
| 写中央 marketplace.json | 2.2 |
| 让使用者 clone 即用 (settings.json) | 2.3 |
| 开发时加载测试, 搞懂作用域限制 | 3 |
| 搞清 skill / agent 的命名空间前缀 | 4 |
| 一个插件依赖另一个插件 | 5 |
| 插件内 / 跨插件 skill 互相调用 | 6 |
| 私有 repo 认证 (手动 / 后台更新) | 7 |
| 发新版本的完整流程 | 8 |
| 使用者怎么装 | 9 |
| 命令速查 / 决策速查 | 10 |
发布一个新版本 (最常用)
在插件 repo 里: 改代码 → bump plugin.json 的 version → git commit → mise run tag-plugin (扫描 .claude/skills/ 批量打 {插件名}--v{版本} tag 并推送) → 去 marketplace repo 把对应 source.ref 改成新 tag 并 push → 用户 /plugin marketplace update. 细节和为什么这么做见 reference 第 8 节.
底层脚本: scripts/plugin_release.py
mise run tag-plugin 和 mise run list-plugins 背后都是这一个 0 依赖纯标准库 CLI: scripts/plugin_release.py. 它从当前目录往上找到 .git 定位 git repo 根, 扫描 <repo根>/.claude/skills/ 下每个目录, 对含 .claude-plugin/plugin.json 的做校验 (必须有 name/description/version, 且 version 是 x.y.z; 有文件但格式不对就报错), 没有 manifest 的当 standalone skill 忽略.
| 命令 | 作用 |
|---|
python3 scripts/plugin_release.py list | 列出并校验所有插件 (加 --json 输出机器可读) |
python3 scripts/plugin_release.py tag | 先整体校验 (任一 manifest 非法则中止), 再逐个 cd 进插件目录跑 claude plugin tag --push, 已存在的 tag 跳过 (--no-push 只本地打, --force 移动已存在 tag) |
因为靠 git-root 自动发现, 这个脚本在任何插件 repo 里都能直接跑, 不只这个 repo. 在别的插件 repo 里复用时, 把这个 skill 带过去, 再在那个 repo 的 mise.toml 里加一行指向本脚本的 tag-plugin 任务即可.
