NNNNzs

Git Submodule 不好用：用 GitHub Actions 同步管理多个 Skills 仓库

2026年07月24日9 次阅读0 人喜欢
gitgithubCI/CDAgent Skillsnpx skillsskills青龙面板
所属合集
小破站建设

今天折腾了一下我那个 skills 仓库的管理方式，记录一下。

起因

我有两套 skills：

一开始的想法很简单：把 qinglong-skills 作为 git submodule 挂到 agent-skills 下面，这样既能独立维护，又能在一个仓库里看到所有 skills。

Git Submodule 的坑

Submodule 的机制其实不复杂——主仓库里存的只是一个指向子仓库某个 commit 的引用（gitlink），不是实际文件。

但这带来几个问题：

1. Clone 时必须加参数

别人 clone agent-skills 的时候，如果不加 --recurse-submodules，submodule 目录是空的：

bash 复制代码 
git clone https://github.com/NNNNzs/agent-skills.git
ls skills/qinglong-skills/   # 空的！

# 必须这样
git clone --recurse-submodules https://github.com/NNNNzs/agent-skills.git

2. 更新是两步操作

在 qinglong-skills 推了新代码后，别人已经 clone 过 agent-skills 的，光 git pull 不够：

bash 复制代码 
git pull                          # 只拿到引用变了
git submodule update --remote      # 还得手动拉子模块

3. npx skills add 不支持

这才是关键。npx skills 做的是普通 git clone，不会拉子模块。所以：

bash 复制代码 
npx skills add NNNNzs/agent-skills --skill qinglong-skills
# ❌ 找不到！因为 submodule 目录是空的

正确做法：GitHub Actions 自动同步

既想要独立仓库方便维护，又想在主仓库里有实际文件让 npx skills add 能用，最佳方案是 GitHub Actions 自动同步：

复制代码 
qinglong-skills（独立仓库，正常维护）
        │
        │ push / 定时触发
        ▼
agent-skills 的 GitHub Actions
  → 浅克隆 qinglong-skills
  → 复制文件到 skills/qinglong-skills/
  → 自动 commit & push
        │
        ▼
agent-skills（包含实际文件）
  → npx skills add NNNNzs/agent-skills --skill qinglong ✅

Workflow 配置

在 agent-skills 里加了 .github/workflows/sync-skills.yml：

yaml 复制代码 
name: Sync Skills from Independent Repos

on:
  workflow_dispatch:
  schedule:
    - cron: '0 2 * * *'  # 每天凌晨 2 点

permissions:
  contents: write

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Sync qinglong-skills
        run: |
          git clone --depth 1 https://github.com/NNNNzs/qinglong-skills.git /tmp/qinglong-skills
          rm -rf skills/qinglong-skills
          cp -r /tmp/qinglong-skills skills/qinglong-skills
          rm -rf skills/qinglong-skills/.git

      - name: Commit and push
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add -A
          if git diff --cached --quiet; then
            echo "No changes to commit"
          else
            git commit -m "sync: update skills from independent repos"
            git push
          fi

踩坑记录

  1. submodule 残留配置：删除 submodule 后，.git/config 里可能还残留 [submodule "xxx"] 配置。需要手动 git config --remove-section 清掉，否则 git add 会把目录当成 gitlink（mode 160000）而不是普通文件。

  2. 技能名 ≠ 目录名：npx skills add 用的是 SKILL.md 里 name 字段定义的名字，不是目录名。所以安装命令是 --skill qinglong 而不是 --skill qinglong-skills。

  3. 复制前要清 .git：从独立仓库复制文件时，如果忘了删 .git 目录，git 会把它识别为 embedded repository，各种奇怪的问题。

日常维护

操作 做什么
在 qinglong-skills 改代码 正常 push 到独立仓库
同步到 agent-skills 等每天凌晨自动同步，或去 GitHub Actions 手动触发
新增独立仓库 在 workflow 里加一个 sync step
安装技能 npx skills add NNNNzs/agent-skills --skill qinglong

总结

方案 独立维护 npx skills add Clone 体验
Git Submodule ✅ ❌ 差（要 --recurse-submodules）
Git Subtree ✅ ✅ 好（但历史乱）
GitHub Actions 同步 ✅ ✅ 好
直接复制 ❌ ✅ 好（但无法独立维护）

最终选了 GitHub Actions 同步——既能独立维护，又能无缝支持 npx skills add，代价只是同步有最多一天的延迟（也可以手动触发秒级同步）。

站长

加载评论中...