Codex 裡的 AGENTS.md 和 SKILL.md 差在哪？
- 小步
- 7月4日
- 讀畢需時 7 分鐘
最近在整理 Codex 的使用方式時，我一直想弄清楚一件事：
AGENTS.md 和 SKILL.md 到底差在哪裡？
一開始我會覺得，它們好像都是「寫給 Codex 看的說明文件」。
那為什麼需要兩種？什麼時候該寫 AGENTS.md？什麼時候又應該整理成 SKILL.md？
後來我用比較白話的方式理解：
AGENTS.md 是「這個專案的工作規則」；SKILL.md 是「某一種任務的標準流程」。
也就是說：
AGENTS.md = 專案規則
SKILL.md = 任務 SOP這樣理解之後，就清楚很多。
AGENTS.md 是什麼？
AGENTS.md 可以想成 Codex 進到某個專案時，要先看的「專案說明書」 。
它適合放這個專案長期都要遵守的規則，例如：
這個專案使用 Next.js + Supabase
UI 文字一律使用繁體中文
不要自行修改資料庫 schema
修改畫面時，要維持既有版型風格
日期格式要依照既有系統邏輯處理如果是程式專案，這裡可能會寫技術架構、開發規範、測試方式、命名規則。
但我後來發現，Codex 不一定只能拿來寫程式。
我自己也可能會把 Codex 用在：
影片腳本專案
合作信件整理專案
生圖提示詞專案
課程企劃專案
網站開發專案
所以與其說 AGENTS.md 是放在 repo 裡，我會覺得更適合我的說法是：
AGENTS.md 通常放在專案目錄裡。
如果這個專案剛好是程式專案，而且有 Git 管理，工程師才會稱它為 repo。
但對一般使用者來說，可以先這樣理解：
專案目錄 = 交給 Codex 處理的一整包資料夾
repo = 有 Git 管理的程式專案目錄OpenAI 的 Codex 文件也提到，Codex 會在開始工作前讀取 AGENTS.md，並且可以把全域規則與專案規則分層套用。
什麼是「長期的專案指引」？
在 Codex 的說明中，會看到類似 durable project guidance 這樣的說法。
這個詞一開始看起來有點抽象，但其實可以拆開理解。
durable 是「持久的、耐用的、不容易消失的」意思。
所以 durable project guidance 可以理解成：
寫在專案裡、可以長期保存、之後 Codex 再進來也能讀到的專案指引。
例如你只是這次聊天跟 Codex 說：
這個專案的畫面文字要用繁體中文
不要亂改資料庫結構
日期要用民國年這些規則可能只在這次對話比較有效。
但如果你把它寫進 AGENTS.md，它就會變成這個專案可以長期保存的工作規則。
下次 Codex 再進到這個專案時，就比較容易延續一致的做法。
AGENTS.md 可以有很多個嗎？
可以。
一開始我也以為，一個專案裡是不是只會有一個 AGENTS.md。
後來比較清楚的理解是：
同一個資料夾通常只會有一個 AGENTS.md，但整個專案裡可以有多個 AGENTS.md，分別放在不同層級的資料夾。
例如：
my-codex-project/
├─ AGENTS.md
├─ mail/
│ └─ AGENTS.md
├─ image-prompts/
│ └─ AGENTS.md
└─ scripts/
└─ AGENTS.md這樣可以理解成：
my-codex-project/AGENTS.md
整個專案的共通規則
mail/AGENTS.md
整理信件時的專用規則
image-prompts/AGENTS.md
撰寫生圖提示詞時的專用規則
scripts/AGENTS.md
撰寫腳本時的專用規則
也就是說，最外層的 AGENTS.md 可以放整個專案共用的規則；子資料夾裡的 AGENTS.md，則可以放更細的任務規則。
什麼叫「越靠近目前工作目錄」？
這句話一開始也容易讓人卡住。
簡單說，就是看 Codex 目前正在處理哪個資料夾或檔案。
假設專案長這樣：
abc-webapp/
├─ AGENTS.md
├─ src/
│ ├─ app/
│ │ ├─ customers/
│ │ │ ├─ AGENTS.md
│ │ │ └─ page.tsx
│ │ ├─ contracts/
│ │ │ └─ page.tsx如果 Codex 現在正在修改：
src/app/customers/page.tsx那麼這個檔案就比較「靠近」：
src/app/customers/AGENTS.md而這個比較「遠」：
abc-webapp/AGENTS.md所以可以這樣理解：
越靠近正在處理檔案的 AGENTS.md，規則越具體，優先度也越高。
根目錄的 AGENTS.md 像是「全站規則」；子資料夾的 AGENTS.md 則像是「這個模組的專用規則」。
OpenAI 文件中也提到，Codex 會從專案根目錄一路讀到目前工作目錄，越靠近目前目錄的檔案會出現在後面，因此可以覆蓋前面的規則。
不過剛開始不用搞太複雜。
我會建議先在專案根目錄放一個：
等到專案真的變大，或是不同資料夾有明顯不同的工作方式，再考慮在子資料夾裡放更細的 AGENTS.md。
SKILL.md 是什麼？
如果 AGENTS.md 是「專案規則」，那 SKILL.md 就比較像是「任務 SOP」。
它適合放某一種會重複執行的工作流程。
例如我常常可能會請 Codex 做這些事情：
整理合作邀約信
撰寫商業合作回覆
產生生圖提示詞
檢查 UI 一致性
新增 Excel 匯出功能
依照既有模組複製 CRUD 結構
這些事情不一定只屬於某一個專案，而是一種可以重複使用的方法。
這時候就適合整理成 Skill。
也就是說：
AGENTS.md：這個專案要怎麼做事
SKILL.md：遇到這類任務時，要怎麼做OpenAI 的 Codex Skills 文件也說明，Skill 是用來包裝可重複工作流程的格式，裡面一定會有 SKILL.md，也可以包含 scripts、references、assets 等輔助資料。
SKILL.md 通常放在哪裡？
SKILL.md 不是直接丟在專案根目錄，而是放在某個 skill 資料夾裡。
常見結構會像這樣：
my-skill/
├─ SKILL.md
├─ scripts/
├─ references/
└─ assets/如果只想讓某個專案使用，可以放在專案裡：
專案目錄/
├─ .agents/
│ └─ skills/
│ └─ mail-reply/
│ └─ SKILL.md如果想讓不同專案都可以共用，可以放在使用者層級：
$HOME/.agents/skills/在 Windows 上，可能會像這樣：
C:\Users\你的使用者名稱\.agents\skills\所以之後如果要建立 Skill，最好明確告訴 Codex 要放哪裡。
例如：
請在目前專案根目錄建立：
.agents/skills/mail-reply/SKILL.md或是：
請建立成個人共用 skill，放在：
$HOME/.agents/skills/mail-reply/SKILL.md這樣之後比較不會發生「我好像有建立過，但不知道它在哪裡」的狀況。
如果已經建立 SKILL.md，要怎麼找？
如果之前沒有特別指定位置，可以直接搜尋 SKILL.md。
在 Windows PowerShell 裡，可以先到目前專案根目錄，執行：
Get-ChildItem -Recurse -Force -Filter SKILL.md如果想連使用者資料夾一起找，可以執行：
Get-ChildItem $HOME -Recurse -Force -Filter SKILL.md -ErrorAction SilentlyContinue也可以直接請 Codex 幫你找：
請幫我搜尋目前專案裡所有 SKILL.md，列出完整路徑。或更明確一點：
請幫我檢查目前專案目錄、上層目錄，以及使用者層級的 .agents/skills 裡有哪些 SKILL.md，列出完整路徑與 skill name。AGENTS.md 和 SKILL.md 的差異整理
項目 | AGENTS.md | SKILL.md |
核心用途 | 專案規則 | 任務 SOP |
適合放什麼 | 專案背景、固定規範、工作偏好、限制事項 | 可重複任務流程、檢查清單、範例、腳本、參考資料 |
套用範圍 | 某個專案或資料夾 | 某一類任務 |
常見位置 | 專案根目錄或子目錄 | .agents/skills/某個技能/SKILL.md |
白話比喻 | 這個專案的工作守則 | 這種任務的操作手冊 |
最簡單的判斷方式是：
只跟這個專案有關 → AGENTS.md
很多專案都可能重複用 → SKILL.md我會怎麼使用？
以我的使用方式來說，我不會只把 Codex 當成寫程式工具，而是會用「專案」的方式拆分不同工作。
例如：
影片腳本專案
合作信件專案
生圖工作流專案
網站開發專案
課程企劃專案
所以我會這樣安排：
影片腳本專案 → AGENTS.md
合作信件專案 → AGENTS.md
生圖提示詞流程 → SKILL.md
合作邀約回覆流程 → SKILL.md
網站系統開發規則 → AGENTS.md
Excel 匯出功能流程 → SKILL.md如果是某個專案本身的背景、風格、限制、命名規則，就放 AGENTS.md。
如果是我之後很多專案都可能重複使用的流程，就整理成 SKILL.md。
總結
AGENTS.md 和 SKILL.md 都是讓 Codex 更懂你工作方式的檔案，但它們的定位不一樣。
一句話總結：
AGENTS.md 管「這個專案怎麼做」；SKILL.md 管「這類任務怎麼做」。
如果剛開始還不知道怎麼分，我會建議先從 AGENTS.md 開始。
先把專案的基本規則寫清楚，讓 Codex 不要每次都從零理解。
等到你發現某些任務一直重複出現，例如整理信件、產生提示詞、檢查 UI、匯出 Excel，再把這些流程整理成 SKILL.md。
這樣 Codex 不只會比較懂你的專案，也會慢慢變成更符合你工作習慣的 AI 助手。
資料參考：OpenAI Codex 的 AGENTS.md 與 Agent Skills 官方文件。
想把 AI 工具真正用進工作流程？
如果你也正在學習 ChatGPT、AI 工具、影片剪輯與數位應用，歡迎免費加入小步學習會員。
小步學習不只介紹工具有哪些功能，也會持續分享如何將這些工具實際運用在內容創作、工作流程與個人專案中。
加入會員後，可以：
使用會員專屬的「我的學習」空間
集中查看已取得的課程與學習內容
使用網站上的會員及數位商城功能
在活動期間完成會員資料，領取開業早鳥優惠券
從 Chat、Work 到 Codex，AI 工具還會持續改變。
希望小步學習可以陪你一起慢慢學習、實際操作，再把學到的內容真正運用在自己的工作中。
開業早鳥優惠券數量有限，實際面額、使用期限與適用範圍，以會員帳戶顯示內容為準。
留言