跨 Agent Skill 開發：為什麼 Agent Skills 是新一代 npm

npm 比喻已經不只是比喻了

2025 年 12 月，Anthropic 將 Agent Skills 規範以開放標準釋出。2026 年 1 月 OpenAI 為 Codex CLI 採用。Google 在 Gemini CLI 加入原生支援。GitHub 整合進 Copilot。到 2026 年 3 月，生態系跨三大 marketplace 突破 351,000 個，skillpm 和 skills-npm 等工具直接把 agent skill 橋接進 npm registry。

「skill 就是新一代 npm」一開始只是順口比喻。SKILL.md 給 AI agent 可複用知識，像 npm 套件給應用程式可複用程式碼。但比喻已變成真實基礎設施。Anthony Fu 的 skills-npm 發現打包在 npm 套件內的 agent skill，為 coding agent 建 symlink。skillpm 更進一步 -- 把 Agent Skills 映射到 npm 的 package.json、node_modules、registry、semver 解析。Skill 現在就是 npm 套件。你可以發布、安裝、版本管理、宣告依賴。

本文涵蓋跨 agent 相容性的完整故事：一個 SKILL.md 如何在每個主流 coding agent 運作、各工具預期在哪找 skill、跨 agent 切換時什麼會壞、生態系跟真正 npm 比還差在哪。對 agent skill 完全陌生的話先從 Agent Skills 完全指南開始。想直接動手建第一個 skill，逐步教學更快。

一個格式，六個 Agent

SKILL.md 格式刻意簡單：YAML frontmatter 含 name 和 description，接著 Markdown body 指令。這份簡單是跨 agent 運作的原因。沒有 agent 專屬 API、沒有編譯後二進位、沒有 runtime 依賴。一個目錄加一個文字檔。任何能讀 Markdown 的 agent 都能消化。

截至 2026 年 3 月，六個主流 coding agent 原生支援 SKILL.md：

相容性矩陣：

關鍵結論： 每個 agent 都讀 .agents/skills/ 作為備援。那個目錄就是通用匯流排。為跨 agent 寫 skill 就放那裡。

Claude Code 功能最豐富 -- allowed-tools 沙箱、disable-model-invocation 手動觸發、多層級載入。Codex CLI 部分支援 allowed-tools。其餘只讀 name、description 和 body。跨 agent skill 用最低公約數就夠。

目錄慣例：碎片化問題

每個 agent 建了自己的 dotfile 目錄。「開放標準」故事唯一失敗的地方。

.claude/skills/       # Claude Code
.agents/skills/       # Codex CLI、通用備援
.github/skills/       # GitHub Copilot
.gemini/skills/       # Gemini CLI
.codex/skills/        # Codex CLI（替代）
.opencode/skills/     # OpenCode
.cursor/skills/       # Cursor

一個格式七個目錄。三個選項：

選項一：Symlink（簡單，現在能用）

標準位置加 symlink：

# 標準位置
mkdir -p .skills/code-review

# 各 agent symlink
ln -s ../.skills .claude/skills
ln -s ../.skills .agents/skills
ln -s ../.skills .github/skills
ln -s ../.skills .gemini/skills

Agent Skills 完全指南建議的做法。能用、簡單、設定腳本四行。缺點：Windows 上 symlink 脆弱，某些 CI 不追蹤。

選項二：只用 .agents/skills/

接受不是每個 agent 都從主要路徑找到的話，.agents/skills/ 是最強單一選擇。每個 agent 當備援讀。Codex CLI 當主要。Claude Code 和 Gemini CLI 都能發現。一個目錄、不用 symlink、每個 OS。

代價：Claude Code 使用者 claude skill list 預設輸出不會顯示 .agents/skills/ 裡的 skill。存在且會載入，但探索體驗不如 .claude/skills/。

選項三：agent-skill-creator

FrancyJGLisboa 的 agent-skill-creator 讀 skill 定義一次，自動寫入 14+ agent 目錄。寫一次到處部署。缺點：引入 build 步驟和工具依賴。

建議：.agents/skills/ 作主要。團隊重度 Claude Code 就加 .claude/skills/ symlink。其餘除非明確需要就跳過。

寫真正的跨 Agent Skill

在一個 agent 能用另一個壞掉的不叫跨 agent skill。規則：

規則一：只用核心 Frontmatter

跨 agent 安全的欄位：

---
name: deploy-staging
description: >
  Deploy the current branch to the staging environment.
  Use when the user asks to deploy, push to staging, or
  test changes in a staging environment.
---

name 和 description 通用。跨 agent skill 到這就夠。不用 allowed-tools（僅 Claude Code/OpenCode）、disable-model-invocation（僅 Claude Code）。需要存取控制就寫在 body 作為慣例，非透過 frontmatter 強制。

規則二：不要用 Agent 專屬工具名

Claude Code 工具叫 Bash、Read、Edit、Write。Codex CLI 不同名。Gemini CLI 另一套。「使用 Edit 工具修改檔案」對 Claude Code 有意義，對 Gemini CLI 無意義。

用結果寫指令，非工具：

## 不好（agent 專屬）
使用 `Bash` 工具跑測試。
使用 `Edit` 工具更新設定檔。

## 好（agent 無關）
跑測試：`pnpm test`
用新值更新 `src/config.ts`。

Agent 知道怎麼跑命令和改檔案。描述要完成什麼，非呼叫哪個 API。

規則三：用相對路徑

引用 ~/.claude/skills/my-skill/references/guide.md 的 skill 在 Codex CLI 壞掉，因為那裡放在 .agents/skills/。相對於 skill 目錄引用：

讀 deploy checklist：`./references/deploy-checklist.md`

或相對於專案根目錄：

讀 API schema：`src/schemas/api.yaml`

絕不用絕對路徑。絕不引用 agent 設定目錄。

規則四：至少在兩個 Agent 上測

抓跨 agent 問題最快的方法：Claude Code 加另一個。Claude Code 功能最多，能用通常到處能用。但 allowed-tools 在其他 agent 靜默降級。你不會發現直到 Codex CLI 使用者回報非預期 shell 執行。

雙 agent 測試五分鐘：兩邊 slash command，驗證行為一致，完成。

Marketplace 生態系

三個 marketplace，理念不同，格式一樣。

SkillsMP 數量霸主。爬 GitHub SKILL.md 用語意搜尋索引。89K 工具、70K 開發、60K 商業。數字漂亮，信噪比不怎樣。沒安全掃描、沒安裝機制。探索平台而已。

Skills.sh 是 Vercel 答卷。2026/1/20 上線，六小時 20,000 安裝。Stripe、Prisma、Supabase、Coinbase、Remotion 都在 Q1 前發官方 skill。差異化在 CLI 安裝、Snyk 掃描、真實安裝追蹤。vercel-react-best-practices 顯示 10 萬+安裝，那數字有意義。

ClawHub 反面教材變翻身。ClawHavoc 惡意攻擊（341 個惡意 skill、Atomic macOS Stealer）但以強制掃描回應。~3,200 個 skill 搭版控和 rollback，最小但訊號最強。

三個 marketplace 碎片化是生態系未達 npm 成熟度的最明顯信號。npm 一個 registry。Skill 有三個，沒一個能獨自提供完整 npm install 體驗。

版本控制與散佈：真正見真章

npm 2012 年用 semver、package-lock.json、集中 registry 解決版本控制。Skill 生態系從頭重新解決，晚了十四年。

現況

沒有內建版本控制。SKILL.md 就是目錄裡的文字檔。核心規範沒 version 欄位。SkillsMP 爬 default branch。Skills.sh 複製當前版本。沒 lock file、沒辦法 pin、沒辦法 rollback。

社群方案浮現：

skill-semver 為 Claude Code skill 加自動版控 -- MAJOR.MINOR.PATCH、每次編輯自動備份、changelog。管理其他 skill 的 skill。聰明但錯的層級。版控該在 registry 裡。

skillpm 最有前途。把 Agent Skills 映射到 npm package.json 和 node_modules。Skill 變成帶 semver、依賴解析、lockfile、audit 的 npm 套件 -- 全由 npm 處理。skillpm 只加 npm 做不到的：掃描 node_modules 中 skills/*/SKILL.md 並接入 agent 目錄。

skills-npm（Anthony Fu）更輕量。發現 npm 套件內的 agent skill，建 symlink。Package.json 加 prepare script，npm install 時自動 symlink。不需新套件管理器、不需新 registry。npm 上的發現層。

依賴問題

npm 套件能互相依賴。Skill 不行 -- 至少原生不行。「deploy 到 AWS」skill 需要「跑測試」和「更新 changelog」就必須全部內嵌。這就是 skillpm 解決的 prompt 膨脹：skill 變 npm 套件可宣告依賴，agent 只載需要的。

沒依賴解析就鼓勵巨石 skill。一個 SKILL.md 處理 deploy、測試和 changelog 因為沒辦法組合小的。pre-npm JavaScript：因為沒依賴管理器所以把函式庫原始碼複製進專案。

跟真正 npm 比還缺什麼

「skill 是新一代 npm」有說服力但不完整。誠實比較：

嚴重差距在 registry 碎片化和安全。npm 一個 registry。Skill 三個 -- SkillsMP 上的可能在 Skills.sh 不存在。npm 有 npm audit。Skill 在 ToxicSkills 研究的 critical 率 13.4% -- 而且只掃了 351K 中的 3,984 個。

中等差距（命名空間、發布、棄用）可解正在開發。嚴重差距決定「skill 是新一代 npm」會成為現實還是停留行銷。

跨 Agent Skill 撰寫 Checklist

發布多 agent 用的 skill 前：

1. 用 .agents/skills/ 作主要目錄。 需要時 symlink 到 .claude/skills/。
2. Frontmatter 只放 name 和 description。 除非記錄降級行為否則不用 agent 專屬欄位。
3. 用結果寫指令非工具呼叫。 「跑 pnpm test」非「用 Bash 工具跑測試」。
4. 只用相對路徑。 相對 skill 目錄或專案根。
5. 在 Claude Code + 另一個 agent 測。 Codex CLI 最容易。
6. SKILL.md 500 行以內。 長內容放 references/。
7. 確定性任務包含 scripts/。 每個 agent 都能跑 bash。
8. 記錄測過的 agent。 SKILL.md body 寫「Tested on: Claude Code, Codex CLI, Gemini CLI」設期待。
9. 避免 agent 偵測條件邏輯。 在寫「如果 Claude Code 做 X、Codex 做 Y」就是對抗抽象。寫一個到處能用的指令。
10. Pin marketplace 版本。 Skills.sh 用內建版控。npm 透過 skillpm 用 semver。

設計原則（description 最佳化、漸進式揭露、eval loop）看 skill 設計原則。這份 checklist 涵蓋散佈面。

走向

Skill 生態系約在 npm 2011 年的位置。格式標準化。多 registry 競爭。散佈碎片化但堪用。社群量產品質還沒跟上。安全是公開傷口。

三個預測：

Registry 整合。 一個 marketplace 會勝出。Skills.sh 位置最有利 -- Vercel 撐腰、Snyk 整合、真實安裝指標。SkillsMP 有量沒安裝機制。ClawHub 有策展但信任損傷。12 個月內預期一個主導 registry，其他變鏡像或利基。

npm 匯流。 skillpm 和 skills-npm 指方向。Skill 會變帶 agent metadata 的 npm 套件。獨立 registry 要嘛和 npm 整合，要嘛輸給直接發到 npm 的。JavaScript 已經解決套件散佈。為同一 repo 裡的文字格式重新解決一次是浪費時間。

Agent 端標準化。 目錄碎片化不可持續。Agent 會收斂到 .agents/skills/ 作主要路徑非備援。OpenAI 和 Google 當主要路徑的採用讓這很可能。Claude Code 已在讀。問題是何時從腳註變預設。

今天建跨 agent skill 的開發者等同 2012 年 npm 套件作者。生態系混亂、工具不完整、慣例仍在形成。這正是參與塑造標準比等待穩定更值得的時候。

理解 SKILL.md、CLAUDE.md、AGENTS.md 差異是正確分層的基礎。掌握了就很直觀 -- 格式到處一樣，目錄問題今天已有可行解法。