Agent Skills：如何建立一份可供 Claude Code、Codex、Cursor、ChatGPT 與 Copilot 共用的 SKILL.md
One SKILL.md, Every Agent: How to Build a Single Agent Skill That Works in Claude Code, Codex, Cursor, ChatGPT & Copilot
指南説明如何讓一份 SKILL.md 跨 Claude Code、Codex、Cursor、ChatGPT 與 Copilot 使用，並透過共用目錄及各 Agent 的目錄連結或複製檔案。
文章將跨 Agent 共用 SKILL.md 拆成欄位規範、共用目錄與觸發測試，並附可複用範例，讀者可據此整理技能的跨平台部署方式。
簡短答案：可以——一份 SKILL.md 可供不同 Agent 使用。自 2026年10月22日 起，Agent Skills 已成為 Linux Foundation 旗下的廠商中立標準，並已獲 70+ 個平台採用。只要技能 (1) 只使用規格中的 frontmatter 欄位，(2) 存放在共用的 .agents/skills 資料夾，並且 (3) 複製或連結至每個 Agent 自己的資料夾，便可在各處使用。下文會介紹完整的資料夾配置、可攜性規則，以及一個經完整測試、可供複製的範例。
最後核實：2026年10月
2026年10月22日有何改變——Agent Skills 找到中立的歸屬
2026年10月22日，Anthropic 將 Agent Skills 規格——其名稱、格式、GitHub 組織及 agentskills.io 參考網站——捐贈予 Agentic AI Foundation (AAIF)。AAIF 是 Linux Foundation 負責制定 Agent 標準的組織。同日，AAIF 亦接納了 OpenAI 的 Open Responses、Hugging Face 的 OpenEnv 及 Alibaba 的 OpenSandbox，託管項目由 3 個增至 10 個。
這對你有何重要：這次捐贈消除了最後一個令人猶豫的理由。Agent Skills 不再是「Claude 的功能，其他工具只是照搬」，而是共用標準。移交時公佈的數據顯示，已有 70+ 個平台整合、超過 1 million 項技能已發佈，安裝次數約為 280 million。
現在由誰掌舵——接下來有何安排
AAIF 負責監管，而日常維護工作則由 Anthropic、Google、OpenAI 等公司的工程師以個人身份負責——David Soria Parra 和 Mahesh Murag 被列為首席維護者。Anthropic 提出了一份初步路線圖：推出有版本編號的版本、制定正式的變更提案流程，以及公開為編寫和安裝技能的人士提供的安全指引。最後一項正式承認了信任問題：技能已發佈約 1 million 項，安裝次數約為 280 million，安裝時的安全已不能再只靠圈內口耳相傳。（這次移交於 10月22日 在 San Jose 舉行的 AGNTCon + MCPCon North America 上公佈——Agent Skills 是 AAIF 新增的四個項目之一，也是 Anthropic 捐贈予該基金會的第二個項目，首個是 MCP。）
Anthropic 沒有捐出的東西：你的技能
格式的管理權易手了，但你的技能仍屬於你。你編寫的技能仍然是你的檔案，存放在你的儲存庫內，並受你的授權條款規管。你不需要加入 AAIF、擁有付費帳戶，或取得任何人的許可，便可發佈技能。
沒有改變的事：每個 Agent 仍會讀取不同的資料夾
規格是共用的，資料夾則不是。Claude Code、Codex、Cursor、Copilot 和 Gemini CLI 各自掃描自己的目錄。因此，可攜性是一個檔案組織方式的問題，而且完全可以解決；本指南接下來的內容會説明如何處理。
甚麼是 Agent Skill（60 秒版）
Agent Skill 是一個資料夾，內含 SKILL.md 檔案：YAML frontmatter（name 和 description 為必填欄位），以及通俗易明的指示；此外，亦可選擇加入 scripts/、references/ 和 assets/ 子資料夾，存放支援檔案。
令技能成本低廉的機制是漸進式揭露：Agent 啟動時，只會讀取每項技能的名稱和描述——合共只有幾十個 token。只有當你的要求符合描述時，才會載入完整指示。這帶來兩個結果：
- 描述就是產品本身。 它決定你的技能是否會觸發。請把描述寫成觸發條件，而非摘要：説明技能的功能 以及應在甚麼確切情況下啟動，並把觸發詞放在前面。有些 Agent 會限制可讀取的描述文字長度（例如 Codex 會為所有技能描述預留約 2% 的上下文視窗），因此應把關鍵詞放在最前。
- 安裝技能幾乎不會帶來成本。 數十個技能可以放在資料夾內，消耗的上下文只相當於一段文字——這與始終載入的系統提示詞恰恰相反。
跨平台資料夾對照表
從共用的 .agents/skills 資料夾保留一份標準副本——這是標準指定的位置，而且已有數個 Agent 會直接讀取——然後將它連結或複製到其他 Agent 會掃描的資料夾：
| Agent | 個人（所有專案） | 專案（此儲存庫） |
|---|---|---|
| 共用標準 | ~/.agents/skills |
.agents/skills |
| Claude Code | ~/.claude/skills |
.claude/skills |
| GitHub Copilot |
~/.copilot/skills 或 ~/.agents/skills
|
.github/skills、.claude/skills 或 .agents/skills
|
| OpenCode | 全域設定中的技能資料夾 |
.opencode/skills，亦會讀取 .claude/skills 和 .agents/skills
|
| Codex / Cursor / Gemini CLI |
~/.agents/skills（共用） |
.agents/skills（共用） |
路徑依照各廠商目前的文件而定——請查閲 Agent 的文件頁面；廠商正逐漸統一採用 .agents/skills，而舊有的個別工具資料夾則保留作相容性別名。
單一標準副本的設定方式（不要維護五份副本）
- 將每項技能的主副本保存在
.agents/skills/<skill-name>/（團隊技能放在儲存庫內，個人技能則放在~/.agents/skills/）。 - 在 macOS/Linux 上，將各 Agent 的資料夾建立符號連結，指向主副本：
ln -s ~/.agents/skills ~/.claude/skills（如果工具已有自己的技能資料夾，也可以只連結個別技能資料夾）。 - 在 Windows 上，建立符號連結需要開啟開發人員模式或管理員權限——請改用目錄接合：
mklink /J %USERPROFILE%\.claude\skills %USERPROFILE%\.agents\skills；或使用兩行 PowerShell 複製指令碼，並在編輯後執行。無論選擇哪種方式，都只編輯主副本。
一步步建立技能
步驟 1 — 選一個常用提示詞
任何你曾至少兩次為其撰寫可重用提示詞的任務，都可以變成技能。從一個已經有效的提示詞開始——如果你需要提示詞，可以先在 Prompt Generator 中撰寫，再將它轉換成技能。
步驟 2 — 只使用可跨平台的欄位撰寫 frontmatter
規格定義了一組精簡欄位，所有 Agent 都能理解。有些 Agent 會忽略工具專用的額外欄位，某些上載流程甚至會直接拒絕（claude.ai 的技能上載檢查相當嚴格），因此共用檔案只保留規格欄位，並將工具專用的額外內容放在各工具版本的副本或 metadata。
| 欄位 | 可移植？ | 規則 |
|---|---|---|
name |
✅ 必須 | 1–64 個字元，使用小寫字母、數字及單個連字號，並須與資料夾名稱一致 |
description |
✅ 必須 | 説明功能及觸發時機；關鍵詞置前 |
license |
✅ | 例如 MIT 或 Proprietary
|
compatibility |
✅ | 註明所需工具／環境 |
metadata |
✅ | 任意格式的鍵值（作者、版本……） |
allowed-tools |
⚠️ 部分支援 | 部分 Agent 會採用，其他 Agent 則會忽略——切勿只依賴此欄位 |
| 工具專用欄位（例如 Claude 專用選項） | ❌ | 不要放入共用檔案 |
步驟 3 — 撰寫指示
正文結構依次為：使用時機（以及不應使用的時機）→ 編號步驟 → 確切輸出格式 → 特殊情況。正文應少於 500 行／約 5,000 個 token；較長的參考資料則移至 references/ 檔案，讓 Agent 只在需要時開啟。
步驟 4 — 只在某個步驟只有一個正確答案時加入指令碼
確定性的步驟（日期計算、檔案重新命名、格式轉換）應寫成 scripts/。需要判斷的步驟則應以文字説明。每個額外指令碼也會擴大攻擊面——請參閲下方的安全檢查。
步驟 5 — 完整範例（直接複製）
一項完整、毋須編寫程式碼的技能——跟進未付款發票，這是專業人士每週都會重複處理的工作：
---
name: invoice-chaser
description: Draft a polite-but-firm payment reminder for an overdue invoice. Use when the user mentions an unpaid, overdue, or late invoice, a client who hasn't paid, or asks for a payment follow-up email. Not for quotes, receipts, or first invoices.
license: MIT
metadata:
author: PromptStaging
version: 1.0
---
# Invoice Chaser
## When to use
- An invoice is past its due date and the user wants a reminder drafted.
- Do NOT use for issuing a first invoice, quotes, or payment receipts.
## Steps
1. Ask for (or extract): invoice number, client name, amount + currency, due date, days overdue.
2. Choose tone by days overdue: 1–7 days = friendly nudge; 8–21 = firm, restate terms; 22+ = final notice, state next step.
3. Draft the email: subject `Payment reminder: Invoice #[number] — [amount]`, body under 120 words, include amount, due date, and a clear pay-by date 7 days out.
4. End with one line: what changes if they don't pay (late fee / pause of work), only if the user confirms one applies.
5. Output ONLY the email (subject + body) unless the user asks for explanation.
先在 Skill Builder 建立技能，再透過 Quality Check Builder 檢查，然後才安裝到任何地方。
在正式推出前，先在三個 Agent 中測試
5 個提示詞觸發測試
在每個 Agent 中各用五個全新提示詞：三個應觸發技能的提示詞（每次換一種措辭——正式、口語、帶有錯字），以及兩個不應觸發的提示詞（相近的任務：報價請求、收據）。評分：觸發 3/3 次，誤觸發 0/2 次，即可推出。如果觸發不足，表示描述範圍太窄——加入缺少的措辭。如果過度觸發，加入明確的「不適用於……」情況。
安全檢查——像檢查軟件套件一樣閲讀技能
技能中的指令碼會使用你的憑證執行。安裝其他人的技能前，請由頭到尾閲讀 SKILL.md，閲讀每個指令碼，而且只從你願意信任其程式碼的來源安裝——因為它本質上就是程式碼。固定版本；更新時重新閲讀。
技能、MCP 與 AGENTS.md——各自屬於哪一層
| 層級 | 包含內容 | 載入時機 | 例子 |
|---|---|---|---|
| SKILL.md | 知識：程序、格式、判斷 | 觸發時（漸進載入） | 「我們如何撰寫版本説明」 |
| MCP server | 能力：工具、資料存取、操作 | 預先載入工具結構描述（Agent 越來越常延後這項成本） | 查詢帳單資料庫 |
| AGENTS.md | 持續生效的專案規則 | 每個工作階段 | 「使用 pnpm；切勿編輯遷移檔」 |
2026 年 9 月新增：MCP 的 SEP-2640 擴充規格，讓 MCP 伺服器可以在工具旁邊發布技能——這些層級正在融合，而非互相競爭。需要能力這一層時，可在 MCP Studio 建立。
疑難排解——人人都會遇到的 6 種故障
| 症狀 | 可能原因 | 解決方法 |
|---|---|---|
| 技能從不觸發 | 描述含糊，或缺少用戶會使用的措辭 | 重寫描述，優先寫明觸發條件；加入用戶實際使用的措辭 |
| 技能遇到任何情況都會觸發 | 描述範圍太廣，沒有排除情況 | 在描述中加入「不適用於……」的情況 |
| 描述似乎被截斷 | Agent 為描述分配的上下文容量有限 | 將關鍵字放在前面；縮短描述；減少已安裝的技能 |
| 上載時檔案遭拒 | 工具專用的 frontmatter 欄位 | 共享檔案只保留規格指定的欄位（見上表） |
| Agent 忽略部分指示 | 內文過長／規則埋得太深 | 少於 500 行；將重要規則放在前面；大量內容移至 references/ |
| 在 Windows 上看不到修改 | 修改的是副本，而非主檔案（使用 junction／複製的設定） | 只修改 .agents/skills；重新執行複製指令碼 |
常見問題
一項技能可否同時用於 Claude Code、Codex 和 Cursor？
可以——Agent Skills 格式是共用標準，三者都會讀取 SKILL.md 檔案。不同之處在於各自掃描的資料夾；請將主檔案放在 .agents/skills，再連結或複製到各 Agent 的資料夾（見上表）。
SKILL.md 檔案應放在哪裏？
將檔案放在以技能名稱命名的資料夾內，並置於 skills 資料夾中：共用標準位置是 .agents/skills/<name>/SKILL.md，Claude Code 使用 .claude/skills/<name>/SKILL.md，Copilot 專案使用 .github/skills/<name>/SKILL.md——個人技能則放在主目錄下相應的資料夾。
SKILL.md 應有多長？
內文應少於 500 行（約 5,000 個 token）。較長的內容應放在技能資料夾內的 references/ 檔案中，Agent 只會在任務需要時才開啟這些檔案。
我需要編寫程式碼才能撰寫技能嗎？
不需要。技能是一個帶有簡短 YAML 標頭的 Markdown 檔案。腳本並非必要，只有當某個步驟只有一個正確答案時，才值得加入。上面的發票催收範例只有文字説明。
SKILL.md 和 AGENTS.md 是一樣的嗎？
不一樣。AGENTS.md 存放始終生效的專案規則，並會在每個工作階段載入。SKILL.md 只會在請求符合其描述時載入——它是按需提供的知識，而非常設規則。大多數設定會同時使用兩者。
Claude Skills 和 Agent Skills 是同一回事嗎？
Agent Skills 是 Anthropic 建立的開放標準，並於 2026 年 10 月捐贈予 Linux Foundation 的 Agentic AI Foundation。「Claude Skills」是 Anthropic 在 Claude 產品中對同一標準的實作——按此標準撰寫的技能亦可在其他 Agent 中使用。
立即開始
選取一個你每週都會重用的提示詞，並將它製作成技能：在 Skill Builder 中起草，使用 5 個提示詞的觸發測試進行驗證，然後從同一個主資料夾安裝。想找現成的起點？Skills Directory 收集了可用於正式環境的技能，包括供開發人員使用的版本説明，以及供專業人士使用的商品刊登文案、發票和人力資源技能。你可以複製、修改，並在將它們交由 Agent 使用前，先用同一項測試進行測試。
來源：DEV Community · dev.to