一份 SKILL.md 兩邊用：Claude Code 與 Codex 的共用邊界
本篇是「Codex 和 Claude Code 雙修」系列的第 4 / 7 篇。你可以從系列總覽開始閱讀，也可以直接接著看本文。
上一篇把 repo 規則整理成一份共用核心。這一篇處理更適合封裝「做事方法」的東西：Skills。
Claude Code 與 Codex 都支援 Agent Skills 開放規格。因此，流程說明、參考資料與腳本可以共用；但兩個 client 的工具名稱、權限模型與載入路徑不同，不能只看到同樣叫 SKILL.md 就當成零成本搬移。
這是系列第 4 篇。上一篇是共用專案規則與設定檔。
先分清楚：規格相容與 runtime 相容
一個 Skill 通常是一個資料夾：
release-check/
├── SKILL.md
├── scripts/
│ └── verify.sh
└── references/
└── checklist.md其中 SKILL.md 的必要 frontmatter 很精簡：
---
name: release-check
description: Verify a release candidate before deployment.
---
# Release check
1. Read the repository release instructions.
2. Run the project check and build commands.
3. Inspect the generated diff and artifacts.
4. Report blockers before any deployment action.name 與 description 是規格核心；license、compatibility、metadata 等欄位可依需求補充。最保險的做法是把跨工具內容維持在標準欄位內，client 專屬欄位另外驗證。
這只代表兩邊能理解 Skill 的包裝方式。真正執行時還要確認：
SKILL.md提到的工具在兩邊是否存在；- script 需要的 binary 是否已安裝；
- 相對路徑是否從同一位置解析；
- 網路、寫檔與環境變數權限是否足夠；
- skill 是否依賴某一邊特有的 hook、subagent 或 plugin。
兩邊的 discovery 路徑
專案內最常見的目錄是：
| 範圍 | Claude Code | Codex |
|---|---|---|
| 專案 | .claude/skills/<name>/ | .agents/skills/<name>/ |
| 個人 | ~/.claude/skills/<name>/ | ~/.agents/skills/<name>/ |
Codex 另外有管理員與系統層級的 Skills；Claude Code 也能從 plugins 提供 Skills。這些適合組織政策或工具發佈，不適合拿來藏只有這個 repo 才懂的流程。
實際載入規則與優先順序可查 Claude Code Skills 和 Codex Skills。
共用方式一：Unix 環境用 symlink
如果團隊主要使用 macOS 或 Linux，可以選一邊當正本，再把另一邊的 discovery 路徑連過去。例如以 .agents/skills 為正本：
mkdir -p .agents/skills .claude
ln -s ../.agents/skills .claude/skills目錄會變成：
.agents/skills/release-check/SKILL.md
.claude/skills -> ../.agents/skills好處很直接：只有一份內容，不會改了 Codex 版卻忘記 Claude 版。Codex 官方文件也明確支援 symlinked skill folders。
但把 symlink commit 進 Git 前，先測試：
git status --short
readlink .claude/skillsWindows、某些解壓縮工具或 core.symlinks=false 的環境可能無法保留連結。跨平台團隊不應把「我電腦可用」當成驗證完成。
共用方式二：用同步腳本產生第二份
如果 Windows 支援是硬需求，可以把 .agents/skills 當 source of truth，透過 repo script 在安裝或檢查階段同步到 .claude/skills。
這種方式會產生兩份實體檔案，但責任很清楚：
- 只編輯 source 目錄；
- generated 目錄不接受手改；
- CI 檢查同步後是否有 diff；
- script 使用跨平台工具，並保留 executable 權限。
比起人工複製，這至少能偵測 drift。若 Skill 本來就要跨多個 repo 發佈，則應考慮獨立套件、plugin 或安裝流程，不要在每個 repo 各養一份。
哪些內容適合共用，哪些要拆 adapter
適合直接共用的內容：
- 任務目標與觸發情境；
- repo 內的固定檢查步驟；
- 一般 shell、Node 或 Python script；
- 輸出格式與驗收標準；
- 參考文件與範例。
容易需要 adapter 的內容：
- 指定 client 才有的 tool 名稱；
- Claude Code 專屬 frontmatter 或 hook；
- Codex 專屬 approval／sandbox 參數；
- 特定 plugin 或 MCP server 的呼叫方式；
- 依賴某種 subagent 編排的流程。
我會把共用核心寫成中性的步驟，再把 client 差異留在很薄的入口。例如核心只說「用唯讀權限檢查 diff」，Claude adapter 再指定 plan mode，Codex adapter 再指定 -s read-only -a never。
一份 Skill 的跨工具驗證清單
每次新增或修改共用 Skill，我會分別在兩邊做這些測試：
- 啟動新 session，確認 Skill 能被 discovery。
- 用自然語言觸發一次，再直接指定 Skill 觸發一次。
- 確認它只讀取需要的 references，不會一次塞進全部內容。
- 執行 scripts，檢查工作目錄、參數、exit code 與相依 binary。
- 以最小權限跑一次，找出偷偷依賴的寫入或網路。
- 模擬失敗，確認它會回報 blocker，而不是自動擴權或跳過檢查。
最後再看 git diff，避免同步工具或 script 意外改到 repo 其他檔案。
Skills 共用的是流程，不是信任
Skill 會影響 agent 的決策，也可能要求執行 script。從別人 repo 安裝前，至少要讀過 SKILL.md 和實際被呼叫的程式，確認沒有上傳 secrets、修改 shell profile 或執行未釘版本的遠端腳本。
同一份 Skill 被兩個工具讀取，不代表它在兩邊擁有相同權限。權限仍由各 client 設定、沙箱與外部環境決定。這個邊界留清楚，Skills 才會真的降低維護成本，而不是把風險也一起複製。
上一篇：共用專案規則與設定檔 · 下一篇：Claude Code 與 Codex 共用 MCP
