一份 SKILL.md 兩邊用：Claude Code 與 Codex 的共用邊界

本篇是「Codex 和 Claude Code 雙修」系列的第 4 / 7 篇。你可以從系列總覽開始閱讀，也可以直接接著看本文。

上一篇把兩邊的專案規則放在一起維護。這篇接著處理 Skills：那些常用步驟、腳本和參考文件，能不能也只留一份？

Claude Code 與 Codex 都支援 Agent Skills 開放規格。因此，流程說明、參考資料與腳本可以共用；但兩個 client 的工具名稱、權限模型與載入路徑不同，搬過去之後，還是要實際跑一次才知道能不能用。

這是系列第 4 篇。上一篇是共用專案規則與設定檔。

讀得懂同一份檔案，還要確認能不能執行

一個 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。

Skill 要放在哪裡，兩邊才找得到？

專案內最常見的目錄是：

範圍	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/skills

Windows、某些解壓縮工具或 core.symlinks=false 的環境可能無法保留連結。跨平台團隊不應把「我電腦可用」當成驗證完成。

共用方式二：用同步腳本產生第二份

如果 Windows 支援是硬需求，可以把 .agents/skills 當正本，透過 repo script 在安裝或檢查階段同步到 .claude/skills。

這種方式會產生兩份實體檔案，但責任很清楚：

只編輯 source 目錄；
generated 目錄不接受手改；
CI 檢查同步後是否有 diff；
script 使用跨平台工具，並保留 executable 權限。

這樣至少能檢查出兩份內容有沒有不同，不必靠自己記得複製。若 Skill 本來就要跨多個 repo 發佈，則應考慮獨立套件、plugin 或安裝流程，不要在每個 repo 各養一份。

哪些直接共用，哪些另外寫設定？

適合直接共用的內容：

任務目標與觸發情境；
repo 內的固定檢查步驟；
一般 shell、Node 或 Python script；
輸出格式與驗收標準；
參考文件與範例。

容易需要 adapter 的內容：

指定 client 才有的 tool 名稱；
Claude Code 專屬 frontmatter 或 hook；
Codex 專屬 approval／sandbox 參數；
特定 plugin 或 MCP server 的呼叫方式；
依賴某種 subagent 編排的流程。

我會先寫兩邊都能照做的步驟，工具專用的設定再分開補上。例如核心只說「用唯讀權限檢查 diff」，Claude adapter 再指定 plan mode，Codex adapter 再指定 -s read-only -a never。

共用內容和工具專用設定，可以這樣分：

flowchart TD
    SRC["一份正本資料夾<br/>本文以 .agents/skills 為例<br/>共用核心寫成中性步驟"]
    SRC --> CA["Claude adapter<br/>指定 plan mode"]
    SRC --> XA["Codex adapter<br/>指定 -s read-only -a never"]
    CA -->|"symlink 或同步腳本"| CC["Claude Code<br/>從 .claude/skills 載入"]
    XA -->|"直接讀正本"| CX["Codex<br/>從 .agents/skills 載入"]
    CC --> PC["權限由 Claude Code 自己的<br/>設定、沙箱與外部環境決定"]
    CX --> PX["權限由 Codex 自己的<br/>設定、沙箱與外部環境決定"]

例如共用步驟寫「用唯讀權限檢查 diff」，兩邊再各自設定怎麼執行。symlink 或同步腳本只負責讓另一邊讀到同一份檔案，權限仍要另外設。