Codex Skill 四種載入來源
2026-08-14
Aibasil
25
Codex 的 Skill 會從 REPO、USER、ADMIN 與 SYSTEM 四種來源載入，但它們並非單純的覆寫優先層級。本文依 OpenAI 官方文件，說明各層掃描路徑、共享範圍、同名技能行為、內建技能限制，以及 Skill 的觸發與漸進式載入機制，協助個人與團隊正確建立可重複使用的 AI 工作流程。
如果你正在使用 Codex 建立自動化工作流程，可能會發現 Skill 可以放在不同目錄。常見的說法是，Codex 會從 REPO、USER、ADMIN 與 SYSTEM 四個層級掃描技能。
這個架構方向大致正確，但其中有幾個容易造成誤解的地方：四種來源不等於覆寫優先順序；SYSTEM 沒有官方承諾的固定實體路徑；不同 Codex 介面所顯示的來源標籤，也可能有所差異。
本文依據截至 2026 年 8 月 13 日的 OpenAI 官方文件，說明這四種 Skill 來源的用途、共享範圍及使用時應注意的限制。
一分鐘先看結論
- 只和某個專案相關的工作流程，放在 REPO。
- 個人希望跨專案使用的工作流程，放在 USER。
- 同一台機器或容器中的使用者都要使用，放在 ADMIN。
- OpenAI 隨 Codex 提供的內建技能，屬於 SYSTEM。
- 這四種分類代表技能的來源範圍，不是固定的覆寫優先順序。
- 同名 Skill 不會自動合併，可能同時出現在技能選擇器中。
- Codex 啟動時不會立刻載入所有 Skill 的全文，而是先讀取名稱、說明與路徑，確定需要時才讀取完整內容。
什麼是 Codex Skill？
Skill 可以理解成提供給 ChatGPT 或 Codex 的「專門工作手冊」。
它把特定任務需要的步驟、規範、參考資料、程式與模板包裝在一起，讓 Codex 遇到相同類型的工作時，可以依照一致的方法執行，不必每次重新貼上完整提示詞。
一個 Skill 資料夾至少需要包含 SKILL.md，也可以加入其他選用資源：
my-skill/
├── SKILL.md
├── scripts/
├── references/
├── assets/
└── agents/
└── openai.yaml
各項內容的用途如下：
SKILL.md：記錄技能名稱、用途、觸發條件與完整操作指示。scripts/：存放需要穩定、可重複執行的程式。references/：存放 API 文件、公司規範、資料結構或領域知識。assets/：存放簡報模板、圖片、字型或其他輸出素材。agents/openai.yaml：設定介面名稱、圖示、預設提示、觸發政策或工具相依性。
最精簡的 SKILL.md 可以寫成：
--- name: my-skill description: 說明這項技能能做什麼，以及什麼情況下應該使用它 --- 在這裡撰寫完整操作指示。
其中 description 特別重要，因為 Codex 會根據這段說明判斷目前任務是否適合使用該技能。
REPO：跟著專案移動的團隊技能
REPO 是專案範圍的 Skill，也是團隊協作時最常使用的形式。
Codex 會從目前工作目錄的 $CWD/.agents/skills 開始尋找技能。如果目前位置位於 Git repository 的子目錄，Codex 還會向上檢查每一層的 .agents/skills，直到 repository root。
例如，專案可能有以下結構：
my-project/
├── .agents/
│ └── skills/
│ └── team-conventions/
└── services/
├── .agents/
│ └── skills/
│ └── service-deployment/
└── payment/
如果從 payment 目錄啟動 Codex，它可以發現 services 層級的技能，也可以發現專案根目錄的技能。這種設計讓大型 repository 可以同時擁有全專案共用規範，以及只適用於某個模組的工作流程。
REPO Skill 適合用來管理：
- 專案程式碼規範
- 測試與部署流程
- 特定模組的操作方式
- 團隊共同使用的審查標準
- 專案專屬的文件產生流程
不過，把 Skill 放進 repository 不代表其他成員立刻就能使用。它仍須被版本控制追蹤並分享出去，其他成員取得最新版專案後，才能真正完成團隊共用。
USER：個人跨專案使用的技能
USER Skill 的官方位置是 $HOME/.agents/skills，也就是常見的 ~/.agents/skills。
這類技能屬於目前使用者，適合在同一執行環境的不同專案之間重複使用，例如：
- 個人偏好的程式碼審查方式
- 固定使用的文章或文件格式
- 個人的資料分析流程
- 跨專案通用的開發習慣
- 經常使用的自動化工作
需要注意的是，「跨專案」不等於「跨電腦自動同步」。如果換到另一台電腦、另一個容器或不同的開發環境，仍須另外安裝或同步這些技能。
ADMIN：機器或容器共用的管理技能
ADMIN Skill 的官方位置是 /etc/codex/skills。
這是機器或容器層級的共用位置，適合由系統管理者放置預設工具、SDK 操作程序及組織要求的規範，例如：
- 公司統一的安全檢查
- 內部 SDK 使用方式
- 預設建置與部署程序
- 共用基礎設施操作
- 組織要求的品質檢查
放在 ADMIN 位置的 Skill，通常可供同一台機器或同一容器環境中的使用者使用。
但它不會天然成為「全公司共用」。如果公司有多台開發機、不同容器或多個雲端環境，管理者仍須透過映像檔、部署腳本或組態管理，把相同技能配置到每個執行環境。
SYSTEM：OpenAI 隨 Codex 提供的內建技能
SYSTEM Skill 是由 OpenAI 隨 Codex 提供的內建能力，通常面向廣泛使用者與常見工作。例如，某些環境可能包含協助建立 Skill 的 skill-creator，以及安裝精選技能的 skill-installer。
需要特別釐清的是，OpenAI 官方文件只把 SYSTEM 定義為「由 OpenAI 隨 Codex 內建」，並沒有承諾它一定存放在 ~/.codex/skills/.system/。
部分目前的 Codex 執行環境確實使用這個路徑，但這屬於實作細節，未來可能改變，不應視為穩定的公開介面。
因此，不建議把自行建立的 Skill 直接放進 SYSTEM 的內部位置。個人技能應使用 USER，專案技能應使用 REPO，需要機器共用時再由管理者配置至 ADMIN。
四種來源不是覆寫優先順序
REPO、USER、ADMIN、SYSTEM 的命名，很容易讓人聯想到設定檔優先級，例如專案設定覆蓋個人設定。
但 Codex Skill 目前不能這樣理解。
如果不同來源有兩個相同 name 的 Skill，Codex 不會自動合併它們，也不能假設其中一個一定覆蓋另一個。依官方文件的說明，同名技能可能同時出現在技能選擇器中。
因此，這四種分類比較準確的說法是「技能來源範圍」，而不是「技能覆寫層級」。
為了降低同名衝突，團隊可以採用更明確的名稱，例如：
payment-api-review company-security-check personal-weekly-summary
同時，也要把 description 寫清楚，具體說明技能能處理什麼工作、什麼情況應觸發，以及哪些情況不應使用。
選單上的來源標籤是固定規格嗎？
技能選擇器可能使用「專案」、「個人」或「系統」等文字協助辨識來源，但不應把這些顯示文字視為跨產品、跨版本都不會改變的固定規格。
OpenAI 官方文件確認，Codex 的初始技能清單會包含技能名稱、說明與檔案路徑；同名技能也可能同時出現在選擇器中。但是，官方沒有保證 ChatGPT 桌面版、Codex CLI 與 IDE extension 都會使用完全相同的標籤。
實務上，判斷 Skill 來源時，檔案路徑通常比介面顯示名稱更可靠。
Codex 不會立即載入所有技能全文
Codex 採用漸進式載入，也就是 Progressive Disclosure。
啟動時，Codex 主要取得各項 Skill 的名稱、說明與位置。只有當使用者明確指定某項技能，或目前任務符合技能用途時，Codex 才會讀取完整的 SKILL.md。至於 Skill 內的腳本、參考文件與素材，則在真正需要時才會繼續使用。
這種設計可以避免大量技能一次占滿上下文空間，也說明了為什麼 description 是 Skill 設計中最重要的欄位之一。
Skill 如何被觸發？
ChatGPT 與 Codex 可以透過兩種方式啟用 Skill。
第一種是明確指定。在 ChatGPT 中，可以使用 @ 選擇技能；在 Codex CLI 或 IDE extension 中，可以輸入 $skill-name 指定技能，或使用 /skills 查看可用技能。
第二種是自動判斷。當使用者的任務符合 Skill 的 description 時，ChatGPT 或 Codex 可以自動選擇該技能。
如果某項技能不適合被自動觸發，也可以在 agents/openai.yaml 中關閉隱式啟用，只允許使用者明確指定時執行。
Skill 與 Plugin 有什麼不同？
Skill 主要定義可重複使用的工作方法，可以包含操作指示、參考資料、腳本與模板。
Plugin 則是便於安裝與散布的套件，可以包含一個或多個 Skill，也能同時提供連接器、MCP 工具及相關介面資源。
簡單來說：
- 只想為個人或單一專案建立工作流程，可以直接使用 Skill。
- 想跨團隊散布多項技能，或需要連接 GitHub、Google Drive、Slack 等外部服務，較適合包裝成 Plugin。
REPO、USER 與 ADMIN 主要用於本機建立及發現技能；如果希望讓更多人方便安裝、更新，或把工作流程與外部工具一起提供，官方建議採用 Plugin 作為散布方式。
如何選擇適合的放置位置？
選擇 Skill 位置時，可以先問：「誰需要它，以及在哪些工作環境需要它？」
- 只適用於某個 repository 或模組：選擇 REPO。
- 自己在多個專案中都會使用：選擇 USER。
- 同一台機器或容器裡的所有使用者都需要：選擇 ADMIN。
- 由 OpenAI 隨 Codex 提供：屬於 SYSTEM，不自行放置或修改。
如果目標是讓不同公司的使用者直接安裝，或同時提供外部服務連接能力，則應進一步考慮 Plugin，而不是只依賴本機資料夾。
結語
REPO、USER、ADMIN 與 SYSTEM 四種來源的整體架構是正確的，但不能把它們簡化成固定的覆寫層級。
實際管理 Skill 時，還要記住四件事：SYSTEM 的實體目錄不是穩定的官方介面；REPO 的團隊共享需要搭配版本控制；ADMIN 的組織共用需要部署至每個相關環境；同名 Skill 不會自動合併或依四種來源關係覆蓋。
掌握這些差異後，個人與團隊就能更有系統地建立、管理及分享 Codex Skill，避免發生技能找不到、來源混淆或同名衝突等問題，並將重複工作逐步轉化為可維護的 AI 協作流程。
參考資料
本文依 2026 年 8 月 13 日可取得的官方文件整理；產品介面、功能與路徑未來仍可能調整。