dotnet/skills 插件架构深度解析：plugin.json 与 version.json 如何协同多端分发
【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills
本仓库是 .NET 团队官方维护的 AI 编码代理技能库（.NET Agent Skills），通过每个插件目录下的三份 plugin.json 清单 + 一份 version.json 版本基座文件，实现了"一次编写、多客户端分发"的插件架构——Copilot CLI、Claude Code、Codex CLI、Cursor 都能直接从仓库读取并安装同一套 .NET 技能。下面带你快速看懂这套机制。
一分钟看懂插件目录结构
每个插件都是plugins/下的一个独立目录，内部同时为不同客户端准备了对应的清单文件：
| 文件 | 谁在读它 | 说明 |
|---|---|---|
| plugin.json | Copilot CLI / Claude Code | 主清单，是版本的权威来源 |
| .codex-plugin/plugin.json | Codex CLI | Codex 原生插件清单 |
| .claude-plugin/plugin.json | Claude Code | 由脚本生成的主清单逐字节副本 |
| version.json | 自动化版本脚本 | 声明版本基座（major.minor） |
💡 关键点：同一份技能内容，客户端各读各的清单。所以清单之间版本不一致时，脚本会主动修复漂移，而不是任其分叉。
plugin.json：一个文件描述完整插件
以 plugins/dotnet/plugin.json 为例，字段非常精简：
- name：插件标识（如
dotnet） - version：完整三段版本号（如
0.2.3），由脚本自动盖章，不要手改 - description：一句话描述，用于市场浏览
- skills：指向
./skills/目录，插件内所有技能都放这里 - 可选字段按需出现：
lspServers：plugins/dotnet/lsp.json 让dotnet插件附带 C# 语言服务器集成agents：plugins/dotnet-msbuild/plugin.json 声明了 3 个角色代理（如msbuild.agent.md）mcpServers：同一文件还内联声明了binlogMCP 服务器
📌 注意：如果一个插件捆绑了 MCP 服务器，它必须在每一份清单中都声明——Copilot 读plugin.json、Codex 读.codex-plugin/plugin.json、Claude 读.claude-plugin/plugin.json，只写一处就会在另两个客户端上"静默消失"。校验工具skill-validator check会强制执行这条规则。
version.json：版本号的真正"源头"
打开 plugins/dotnet/version.json 会看到它只有两个核心字段：
{ "version": "0.2", "pathFilters": [".", ":!plugin.json", ":!.codex-plugin/plugin.json", ":!.claude-plugin/plugin.json", ":!version.json"] }- version 是"基座"（只有 major.minor 两段），只有当你要发布一次有意的 minor/major 升级时才能改它（如
0.1→0.2），改基座会把 patch 重置为0 - pathFilters 是"排除清单"：三份清单文件和 version.json 自身都属于"版本输出物"，不算有效内容——只改元数据不会触发 patch 递增
于是版本号形成分工：
| 段位 | 谁决定 | 何时变化 |
|---|---|---|
| major.minor | 人类，改 version.json 基座 | 有意的功能升级 |
| patch | 脚本自动计算 | 插件"有效内容"相对上次发布点有净变化时 +1 |
协同机制：自动版本同步脚本如何工作
核心引擎是 eng/version/Sync-PluginVersions.ps1（配套自测在 eng/version/Test-Sync-PluginVersions.ps1），它支撑两个入口：
- PR 期间：维护者在 PR 下评论
/version-bump，脚本用-PredictMerge预测这个 PR 合并后插件的版本并直接盖章到分支 - 每周兜底：在主分支上跑一次，把所有"内容变了但版本没盖章"的插件全部对齐
它的几个设计细节很值得学：
- 发布检查点（checkpoint）：只有"与父提交相比版本恰好递增"的提交才算发布点，任意手动 patch 编辑不具备版本权威性
- 只看第一父提交历史：合并一个旧分支不会让版本被"图结构高度"误判为新版
- 写回只动 version 字段：用正则替换而非 JSON 重排，保证清单其余字节不变，diff 干净
也就是说：你只需要改技能内容，版本号会被自动推到三份清单里（plugin.json、.codex-plugin/plugin.json、.claude-plugin/plugin.json），Claude 那份还会被整体刷新为主清单副本。
质量门：版本发布前有自动化评测兜底
每个插件/技能都有对应的tests/<plugin>/<skill>/eval.yaml评测，变更会经历 baseline（无技能）、skilled、plugin 三种对照运行，只有"可信地优于基线"才算通过。评测结果以 PR 评论形式发布：
版本-only 的变更（仅清单元数据）不会触发技能评测，避免无谓消耗。
新手上手：多端安装与更新
# 克隆仓库（本地调试/私有使用） git clone https://gitcode.com/GitHub_Trending/skills17/skills各客户端安装方式（详见根 README.md）：
- Copilot CLI / Claude Code：
/plugin marketplace add dotnet/skills→/plugin install <plugin>@dotnet-agent-skills - VS Code：settings.json 中配置
"chat.plugins.marketplaces": ["dotnet/skills"] - Cursor：直接在插件市场面板搜索
.NET - Codex CLI：
codex plugin marketplace add dotnet/skills→/plugins浏览安装
更新插件时，各客户端读取的就是上面盖章过的清单版本号，/plugin update即可拉到最新发布点。
想自己加一个插件？最小清单
按 CONTRIBUTING.md 的要求：
- 新建
plugins/<name>/plugin.json及其.claude-plugin/、.codex-plugin/两份副本，版本从0.1.0起步 - 加一份 version.json（基座设为当前 major.minor），否则每周同步会直接报错——没有 version.json 的插件不允许存在
- 在 4 份市场清单（GitHub、Claude、Cursor、Codex 各自的 marketplace.json）中登记
- 补充 CODEOWNERS 与
tests/<name>/评测
小结
这套架构的精髓可以浓缩为一句话：plugin.json 管"插件长什么样"，version.json 管"版本从哪来"，同步脚本负责把两者缝合成多客户端一致的可发布产物。对使用者来说，它意味着四个客户端体验一致、版本永不漂移；对贡献者来说，唯一要手动管理的版本号只剩 version.json 里的基座一个。
【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
