用Gitea自建Claude Code内部插件市场，团队Skill统一分发

有些 skill 只适合在团队内部使用，但如果想让同事也能方便地安装和更新，就需要搭建一个统一的平台。

本文主要记录如何用自架的 Gitea 建立一个内部专用的 Claude Code plugin marketplace，让团队里每个人写的 skill 不再散落在各自电脑上，而是集中在同一个地方统一发布、安装和更新。

其他同事只需安装一次就能共用，后续改版也能同步拿到最新版本。

本文整理了实作过程中每一个能正确跑通的步骤，让大家避免在这个过程中踩坑。

支持 GitHub、GitLab、Gitea，主要是项目能有版本控制即可。

本文演示在自架的 Gitea 上实作。

在 Gitea 上新建一个 repo（例如 claude-plugins），本地目录结构如下：

claude-plugins/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── your-plugin-name/
        ├── .claude-plugin/
        │   └── plugin.json
        └── skills/
            └── your-skill/
                └── SKILL.md

让 Claude Code 直接生成 SKILL.md、plugin.json、marketplace.json

看到上面的架构，有一堆文件要建立时，不用感到惊慌或害怕。

因为我们只需要把上面的架构提供给 Claude Code，让它读取之前已经写好的 skill 内容，依照结构把 SKILL.md、plugin.json、marketplace.json 都建出来即可。

底下附上完整的 marketplace.json 示例，供对照参考：

{
  "name": "claude-plugins",
  "owner": { "name": "August" },
  "plugins": [
    { "name": "ai-tools", "source": "./plugins/ai-tools" },
    { "name": "ai-tools2", "source": "./plugins/ai-tools2" }
  ]
}

必要字段：name（kebab-case，公开可见）、owner、plugins。

每个 plugin entry 至少要有 name 和 source。

若 source 是同一 repo 内的相对路径，必须以 ./ 开头，不可用 ../ 跳出去。

一个 plugin 可以装多个 skill：skills/ 文件夹下每个子文件夹都是独立的 skill，不需要每个 skill 各自开一个 plugin。

不限 GitHub，GitLab、Bitbucket、自架服务器都支持。把整个 claude-plugins repo push 到 Gitea 即可，不需要额外设置。

在 claude-plugins 项目打开终端机，输入：

claude plugin validate .

会检查 JSON schema、重复的 plugin 名称、路径穿越等问题。

文件写得有问题，就会看到哪里写错、哪里建议要改，再照着回应让 Claude 继续做修改即可。

/plugin marketplace add ./claude-plugins
/plugin install ai-tools@claude-plugins

安装语法格式固定是 plugin名称@marketplace名称，分别对应 plugin.json 的 name 和 marketplace.json 的 name。

有几个 plugin 就要执行几次安装指令。

要注意的是，这步可以跳过吗？技术上可以，因为下一步的远程安装跟这步没有依赖关系，直接对 Gitea 网址下指令一样装得起来。但跳过等于少了一层"出包前先在本机拦下来"的保护。

/plugin marketplace add https://gitea.你们公司.internal/team/claude-plugins.git

同事不需要碰任何配置文件，两行指令就能装好：

/plugin marketplace add https://gitea.你们公司.internal/team/claude-plugins.git
/plugin install ai-tools@claude-plugins
/plugin install ai-tools2@claude-plugins

装完就能直接用，缺点是每次换电脑、换项目，或新同事加入，都要重新打一次这几行。

如果不想让同事记指令、手动输入，才需要往下看配置文件自动化这条路。

进阶：让同事 trust 项目文件夹就自动装好。

以下内容要放在每一个开发中项目的 .claude/settings.json 里：

{
  "extraKnownMarketplaces": {
    "claude-plugins": {
      "source": {
        "source": "url",
        "url": "https://gitea.你们公司.internal/team/claude-plugins.git"
      }
    }
  },
  "enabledPlugins": {
    "ai-tools@claude-plugins": true,
    "ai-tools2@claude-plugins": true
  }
}

extraKnownMarketplaces 只负责自动注册 marketplace 来源。

enabledPlugins 才是真正让 plugin 自动装上并启用的关键，两者要同时写，同事 trust 项目文件夹后才会完全不用手动 /plugin install。

如果目前还没有同事需要同步使用，这一步可以先跳过，不影响前面步骤的成果，等有需要再回头补上即可。

如果有发布新版本，记得 plugin.json 里的 version 要往上加一版，没改版本号的话，其他同事那边不会判断成有更新。

/plugin marketplace update claude-plugins
/plugin update ai-tools@claude-plugins

第一行只是刷新 marketplace 目录，让 Claude Code 知道有新版本存在。

第二行才是真正把新内容拉下来、覆盖本地缓存。

也可以用交互面板 /plugin → 选到该 plugin → Update now 达到同样效果。

Create and distribute a plugin marketplace — Claude Code Docs

Discover and install prebuilt plugins — Claude Code Docs

Plugins reference — Claude Code Docs

本文记录的是目前版本观察到的行为，Claude Code 的 plugin 系统仍在快速迭代中，实际行为可能随版本更新而改变，建议操作前对照当下的官方文件再确认一次。