Adding vendor skills — 加入 vendor skill¶

Terminology rule (zh-TW pages)

技術名詞首次出現以「中文 (English original)」格式呈現，例：依賴注入 (dependency injection)。不自創翻譯——若無公認譯名直接保留英文（如 embedding、tokenizer）。代碼、API 名、CLI flag、套件名、檔名一律不翻。

Vendor skill 是從 upstream repo 精選 (cherry-picked) 進 skills/vendor/ 的第三方 skill。 vendor.yaml 這個 manifest 追蹤每個 upstream 來源、最後同步日期、commit SHA，讓重新同步可重現。

快速加入 (Quick add)¶

./scripts/add-vendor.sh owner/repo/path/to/skill

# Examples
./scripts/add-vendor.sh marimo-team/skills/skills/marimo-notebook
./scripts/add-vendor.sh vercel-labs/agent-skills/skills/next-js
./scripts/add-vendor.sh --name my-name --branch dev owner/repo/skills/some-skill

# 用 series 子目錄分組 (group)
./scripts/add-vendor.sh --series fullstack-nextjs vercel/vercel-plugin/skills/nextjs

# 或透過 Makefile
make add-vendor SOURCE=owner/repo/path/to/skill

# GitHub URL 也可以
./scripts/add-vendor.sh https://github.com/marimo-team/skills/tree/main/skills/marimo-notebook

這會驗證 upstream 路徑存在、把條目寫進 vendor.yaml、並立即同步該 skill。傳 --no-sync 可以只新增條目而不下載。

依賴項目 (Dependencies)： gh（已認證的 GitHub CLI）跟 yq （YAML processor）。

Series 分組 (grouping)¶

當你要 vendor 一組圍繞同一個技術組合 (stack) 的 skill（例如 Next.js + Supabase + shadcn），傳 --series <name>，這樣 skill 會落到 skills/vendor/<series>/<name>/ 而不是平鋪 (flat) 結構。series 欄位記錄在 vendor.yaml，sync-vendor.sh 會尊重它。

# vendor.yaml
- name: nextjs
  series: fullstack-nextjs              # ← 可選，省略代表平鋪佈局
  upstream:
    owner: vercel
    repo: vercel-plugin
    path: skills/nextjs
    branch: main
  last_sync: { date: "...", commit: "..." }

結果是 skills/vendor/fullstack-nextjs/nextjs/SKILL.md。 npx skills@latest add 的探索做 5 層 fallback 遞迴搜尋，所以 series 子目錄一樣會被找到。

既有的平鋪條目（沒有 series 欄位）行為不變。這個 repo 目前活躍的 series：

fullstack-nextjs —— 詳見 Skills 總覽 > Fullstack Next.js series

Repo 層級授權檔¶

若 skill subtree 本身沒有包含 upstream license，請在 manifest entry 加上 license_path：

- name: my-skill
  upstream:
    owner: org-name
    repo: project
    path: skills/my-skill
    branch: main
  license_path: LICENSE
  last_sync:
    date: ""
    commit: ""
    license_sha: ""

同步腳本會將它複製成 skills/vendor/<name>/LICENSE.txt，並獨立記錄 blob SHA，因此 make sync-check 也能偵測只有授權檔發生的更新。

手動 config¶

如果你比較想直接編輯 vendor.yaml：

- name: my-skill
  upstream:
    owner: org-name
    repo: skills-repo
    path: skills/my-skill
    branch: main
  last_sync:
    date: ""
    commit: ""

接著跑 make sync 下載並寫入 last_sync 戳記。

檢查 upstream 是否有更新¶

make sync-check

這會對每個條目記錄的 last_sync.commit 做 dry-run，並印出哪些 skill 有 upstream 新 commit。跑 make sync 套用更新。

定期自動 sync (GitHub Actions)¶

.github/workflows/vendor-sync.yml 每週一 03:00 UTC 跑 make sync（也可手動 workflow_dispatch，並可指定只 sync 單一 skill）。有 diff 時它會跑過發佈閘門，然後在固定分支 chore/vendor-sync 上開一個 PR — 已存在就更新同一個 PR。

之所以開 PR 而不是直接 commit 到 main：vendored 的 SKILL.md 內容會透過 npx skills update 直接進到下游 agent 的 context；而且 frontmatter 一旦壞掉，npx skills add 會靜默跳過而不是報錯。

兩個必知重點：

validate.yml 不會在這個 sync PR 上執行。 GitHub 不會為 GITHUB_TOKEN 建立的 PR 觸發其他 workflow，所以 sync job 自己跑完閘門（frontmatter lint、marketplace、kanban、native smoke），並把結果寫進 PR 內文。
job 紅燈通常代表 upstream 改名或刪除。 upstream.path 解析不到時 make sync 會直接失敗，這需要人來決定 renamed_from: 還是 frozen: （見慣例）。

Repo 需要先設定一次：Settings → Actions → General → Workflow permissions 設為 Read and write，並勾選 Allow GitHub Actions to create and approve pull requests。

為什麼不直接從 upstream 安裝？¶

npx skills add owner/repo/path/to/skill 一次只裝一個 skill，而且不留 manifest。把 skill vendor 進這個 repo 帶來：

整套精選集合的單一安裝指令 (npx skills@latest add daviddwlee84/agent-skills/skills)。
每個 skill 都鎖定 (pin) 某個 commit，避免上游粗糙更新時被打到。
重新同步時 repo 會出現 diff，那就是你閱讀這次變更、決定要不要接受的時機。

不要在原地編輯 vendored skill¶

skills/vendor/ 底下的修改會被 make sync 蓋掉。如果你需要客製化某個 vendored skill，把它 fork 到 skills/local/，然後從 vendor.yaml 拿掉那個 upstream 條目。詳見 Conventions。