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

npm 比喻已經不只是比喻了

2025 年 12 月，Anthropic 將 Agent Skills 規範以開放標準釋出。2026 年 1 月，OpenAI 為 Codex CLI 採用了同一格式。Google 在 Gemini CLI 中加入原生支援。GitHub 將它整合進 Copilot。到 2026 年 3 月，生態系跨三大市場突破 351,000 個已發布的 skills，而 skillpm 和 skills-npm 等工具直接將 agent skills 橋接進 npm registry。

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

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

一個格式，六個 Agent

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

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

以下相容性矩陣總結了各 agent 讀取的目錄慣例及支援的 frontmatter 欄位。

這張表的關鍵結論： 每個 agent 都會讀取 .agents/skills/ 作為備援。那個目錄就是通用匯流排。如果你為跨 agent 使用來撰寫 skills，放在那裡。

Claude Code 的功能集最豐富，allowed-tools 做沙箱、disable-model-invocation 做手動觸發、多層級 skill 載入（個人、專案、市場）。Codex CLI 部分支援 allowed-tools。其餘只讀取 name、description 和 Markdown 本文。對跨 agent skills 而言，最低公約數就夠了。

目錄慣例：碎片化問題

每個 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

一個格式七個目錄。如果你想讓一個 skill 被團隊使用的每個工具都發現，你有三個選擇：

選項一：符號連結（簡單，現在就能用）

把 skills 放在一個標準位置，再對每個 agent 預期的路徑建 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 完全指南中建議的做法。能用、簡單，在你的專案設定腳本中只佔四行。缺點：symlinks 在 Windows 上很脆弱（需要開發者模式或管理員權限），某些 CI 環境不會追蹤它們。

選項二：只用 .agents/skills/

如果你接受不是每個 agent 都會從其主要路徑找到你的 skills，.agents/skills/ 是最強的單一選擇。上方相容性矩陣中的每個 agent 都會把它當備援來讀。Codex CLI 更把它當主要路徑。Claude Code 和 Gemini CLI 都能發現它。一個目錄、不需要 symlinks、每個作業系統都能用。

代價是：Claude Code 使用者執行 claude skill list 時不會在預設輸出中看到 .agents/skills/ 裡的 skills。它們存在而且會載入，但探索體驗不如直接用 .claude/skills/。

選項三：agent-skill-creator 做法

FrancyJGLisboa 的 agent-skill-creator 工具讀取你的 skill 定義一次，然後自動寫入 14+ 個 agent 目錄。這是「寫一次、到處部署」的做法。缺點：它引入了建置步驟，而你的 skill 現在對一個散佈工具產生了依賴。

我的建議：用 .agents/skills/ 作為主要目錄。如果你的團隊重度使用 Claude Code，加一個從 .claude/skills/ 來的 symlink。其餘除非有團隊成員明確需要透過主要路徑讓 Gemini CLI 或 Copilot 發現，否則跳過。

撰寫真正的跨 Agent Skills

在一個 agent 上能用、在另一個上壞掉的，不叫跨 agent skill。以下是寫出到處都能用的 skills 的規則。

規則一：只用核心 Frontmatter

跨 agent 安全的 frontmatter 欄位是：

---
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 都讀取它們。跨 agent skills 到這裡就夠了。不要用 allowed-tools（僅 Claude Code / OpenCode）、disable-model-invocation（僅 Claude Code），或任何其他 agent 特定的擴充欄位。如果你需要存取控制，把它寫在 Markdown 本文中作為慣例，而非透過 frontmatter 強制。

規則二：不要用 Agent 特定的工具名稱

Claude Code 的工具叫 Bash、Read、Edit、Write。Codex CLI 用不同的內部工具名。Gemini CLI 有自己的一套。如果你的 skill 本文寫「使用 Edit 工具修改檔案」，這個指令對 Claude Code 有意義，對 Gemini CLI 完全無意義。

用結果來寫指令，而非工具：

## 不好（agent 特定）
使用 `Bash` 工具執行測試套件。
使用 `Edit` 工具更新設定檔。

## 好（agent 無關）
執行測試套件：`pnpm test`
用新的值更新 `src/config.ts` 設定檔。

Agent 知道怎麼跑 shell 命令和編輯檔案。它不需要你指名內部工具。描述你要完成什麼，而非呼叫哪個 API。

規則三：使用相對於專案根目錄的路徑

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

讀取部署檢查清單：`./references/deploy-checklist.md`

或相對於專案根目錄：

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

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

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

抓跨 agent 問題最快的方法是在 Claude Code 加上另一個 agent 上測試。Claude Code 功能最多，如果在那裡能用，通常到處都能用。但像 allowed-tools 這樣的功能在其他 agent 上會靜默降級，你不會發現，直到 Codex CLI 使用者回報 skill 執行了不該執行的 shell 命令。

雙 agent 測試只要五分鐘：在兩個 agent 上用斜線命令呼叫 skill，驗證行為一致，完成。

市場生態系

三個市場服務 skills 生態系。它們的差異在理念，不在格式。

以下市場比較呈現各平台的規模與定位。

SkillsMP 是數量霸主。它爬取 GitHub 上的 SKILL.md 檔案並用 AI 語意搜尋建立索引。分類涵蓋 89K 工具類、70K 開發類、60K 商業類 skills。數字很漂亮；信噪比不怎麼樣。沒有安全掃描、沒有安裝機制。它是探索平台，找到 skill、在 GitHub 上讀 SKILL.md、手動複製。

Skills.sh 是 Vercel 的答卷。2026 年 1 月 20 日上線，六小時內達到 20,000 次安裝。Stripe、Prisma、Supabase、Coinbase、Remotion 都在 Q1 結束前發布了官方 skills。Skills.sh 的差異化在於 CLI 原生安裝體驗、整合 Snyk 安全掃描，以及真實的安裝次數追蹤。當 vercel-react-best-practices 等熱門 skill 顯示 10 萬+次安裝，那個數字是有意義的。

ClawHub 是反面教材變成的翻身故事。它遭受了 ClawHavoc 惡意軟體攻擊（341 個惡意 skills 散播 Atomic macOS Stealer）但以強制掃描回應，成為最具策展品質的市場。~3,200 個 skills 搭配適當的版本控制和回滾支援，它最小但訊號最強。

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

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

npm 在 2012 年用 semver、package-lock.json 和集中式 registry 解決了版本控制。Skills 生態系正在從頭重新解決這些問題，晚了十四年。

現況

Skills 沒有內建的版本控制。SKILL.md 就是一個目錄裡的文字檔。核心規範中沒有 version 欄位。當 SkillsMP 爬取你的 GitHub 倉庫，它拿到的是 default branch 上的內容。當 Skills.sh 安裝一個 skill，它複製當前版本。沒有 lock file。沒有辦法 pin 版本。沒有辦法回滾。

社群方案正在浮現：

skill-semver 為 Claude Code skills 加入自動版本控制，MAJOR.MINOR.PATCH 格式、每次編輯自動備份、變更日誌追蹤。它是一個管理其他 skills 的 skill。聰明，但在錯的層級解決問題。版本控制應該在 registry 裡，不是在 userspace。

skillpm 是最有前途的做法。它把 Agent Skills 映射到 npm 的 package.json 和 node_modules。Skills 變成帶有 semver、依賴解析、lockfiles 和 audit 的 npm 套件，全由 npm 本身處理。skillpm 只加入 npm 做不到的事：掃描 node_modules 中包含 skills/*/SKILL.md 的套件，並將它們接入 agent 目錄。

skills-npm（Anthony Fu）採取更輕量的做法。它發現打包在 npm 套件內的 agent skills，並為 coding agent 建立 symlink。在 package.json 中加入 prepare 腳本，skills 就會在你執行 npm install 時自動 symlink。不需要新的套件管理器、不需要新的 registry，只是 npm 之上的一層發現機制。

依賴問題

npm 套件可以互相依賴。Skills 不行，至少原生不行。一個「部署到 AWS」的 skill 如果需要「跑測試」的 skill 和「更新 changelog」的 skill，就必須把三個的指令全部內嵌進去。這就是 skillpm 解決的 prompt 膨脹問題：因為 skills 變成 npm 套件，它們可以宣告依賴，agent 只載入需要的東西。

沒有依賴解析，skills 生態系就是在鼓勵巨石 skills。一個 SKILL.md 試圖處理部署、測試和 changelog 生成，因為沒有辦法組合較小的 skills。這正是 JavaScript 的 pre-npm 時代：因為沒有依賴管理器，所以把函式庫原始碼複製進你的專案。

和真正的 npm 相比還缺什麼

「skills 是新一代 npm」的敘事很有說服力，但不完整。以下是 skills 生態系和 npm 功能集的誠實比較。

以下差距分析比較 skills 生態系成熟度與 npm 的功能集。

嚴重差距在 registry 碎片化和安全性。npm 有一個 registry。Skills 有三個，而且 SkillsMP 上的 skill 可能在 Skills.sh 或 ClawHub 上不存在。npm 有 npm audit，背後有多個漏洞資料庫。Skills 在 Snyk ToxicSkills 研究中的重大問題率是 13.4%，而那只是在 351K 中他們設法掃描到的 3,984 個 skills 上。

中等差距（命名空間、發布流程、棄用機制）可解決且正在積極開發。嚴重差距將決定「skills 是新一代 npm」到底是會成為現實，還是停留在行銷文案。

跨 Agent Skill 撰寫清單

如果你正在發布一個要多 agent 使用的 skill，發布前跑完這份清單：

1. 用 .agents/skills/ 作為主要目錄。 需要時對 .claude/skills/ 建 symlink。
2. Frontmatter 只放 name 和 description。 除非你記錄了在其他 agent 上的降級行為，否則不用 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 本文中簡單寫一行「Tested on: Claude Code, Codex CLI, Gemini CLI」就設定了預期。
9. 避免基於 agent 偵測的條件邏輯。 如果你發現自己在寫「如果是 Claude Code 就做 X；如果是 Codex 就做 Y」，你在對抗抽象。寫一個到處都能用的指令。
10. Pin 你的市場版本。 如果發布到 Skills.sh，用內建的版本控制。如果透過 skillpm 以 npm 散佈，用 semver。

關於撰寫有效 skills 的設計原則（描述優化、漸進式揭露、eval 迴圈）skill 設計原則指南涵蓋了工藝面。這份清單涵蓋的是散佈面。

這一切的走向

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

三個預測：

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

npm 匯流。 skillpm 和 skills-npm 指出了方向。Skills 會變成帶有 agent 特定 metadata 的 npm 套件。獨立的 skill registry 要嘛和 npm 整合，要嘛輸給直接發布到 npm 的套件。JavaScript 生態系已經解決了套件散佈問題。為了一個和 JavaScript 程式碼放在同一個倉庫的文字格式重新解決一次，是浪費所有人的時間。

Agent 端標準化。 目錄碎片化不可持續。Agent 們會收斂到 .agents/skills/ 作為主要路徑，不只是備援。OpenAI 和 Google 將這個慣例作為主要路徑（不只是備援）的採用使這很可能發生。Claude Code 已經在讀取它了。唯一的問題是它何時從腳註變成文件中的預設值。

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

理解 SKILL.md、CLAUDE.md 和 AGENTS.md 的差異是正確分層的基礎。一旦掌握了這一點，建立跨 agent skills 就很直觀，格式到處都一樣，而目錄問題今天已有可行的解決方案。