症狀：Codex CLI 沒有採用 Xcode skills，或技能已顯示但專案仍無法建置。
最快解法：先在裝有 Xcode 27 的 Mac 匯出 agent skills，再放入 Codex CLI 實際使用的技能目錄；技能被發現、專案權限可用、Xcode 建置通過，必須分開驗收。
這篇適合使用 Codex CLI 維護 Swift、iOS 或 macOS 專案，並想重用 Xcode agent skills 的獨立開發者。
如果你負責小團隊的 Agent 工具與權限設定，或沒有本地 Mac、仍須驗證 Xcode 建置結果，也可依本文逐步檢查。
最後更新於 2026 年 10 月 10 日；版本與功能資料核對自 Apple 開發者發布頁、Xcode 27 Release Notes、Apple Agent 擴充文件及 Codex Skills 文件。
SECTION 01匯出前先確認：目前終端機使用的是哪套 Xcode？
Xcode agent skills 是給 Agent 使用的任務指引，不會自動替 Codex 開啟專案檔案、批准終端機命令，或保證 xcodebuild 能完成編譯。這次設定的範圍是讓 Codex CLI 找到並呼叫技能；專案存取權與建置結果則另行驗收。
Apple 的發布頁記錄 Xcode 27.1 RC 於 2026 年 10 月 5 日發布；這項資料只確認該版本的發布日期，不代表它在之後任何時間都是最新版本。開始前，先核對你實際安裝及選用的 Xcode，並以 Apple 的 Xcode Agent 擴充說明和對應版本的 Release Notes 確認匯出功能與選項。
在同一個終端機工作階段執行：
xcodebuild -version
xcode-select -p
xcrun --find xcodebuild
xcodebuild -version 用來確認版本；xcode-select -p 顯示目前選取的開發者目錄；xcrun --find xcodebuild 則讓你核對命令實際解析到的工具位置。Apple 對 命令列工具安裝與選取及 Xcode 命令列工具有官方說明。不要只看 Xcode 圖形介面裡的版本名稱：若終端機選到另一套 Xcode，從該工作階段執行匯出就可能不是你預期的來源。
| 檢查項目 | 執行或確認方式 | 未通過時先處理 |
|---|---|---|
| Xcode 版本 | 執行 xcodebuild -version，與 Apple 對應版本資料核對 |
確認安裝版本及其 Release Notes，不要套用其他版本的說明 |
| 開發者目錄 | 執行 xcode-select -p，檢查路徑是否指向預期的 Xcode |
先確認本機工具選擇；共用主機上不要未經協調就變更全域設定 |
| Codex CLI 工作目錄 | 在啟動 Codex 的同一個專案目錄檢查 | 避免在不同資料夾匯入或啟動，造成專案層級技能未被找到 |
| 專案狀態 | 確認工作樹與測試分支可辨識 | 先保存既有修改，避免把驗收變更混入日常工作 |
Xcode 27.1 RC 的 skills 要怎麼匯出給 Codex CLI？
先從 Apple 的文件確認目前安裝版本支援的匯出方式，再在上述已核對的 Xcode 工具環境執行 xcrun agent skills export 流程。不同版本可用的選項與輸出方式應以文件及命令本身顯示的說明為準；不要照抄其他版本的參數，也不要假定 Beta 版 Release Notes 中的 Codex workaround 是 RC 或所有安裝環境都必須使用的方式。
注意：匯出命令成功，只能作為「來源端產生了檔案」的證據。請記錄實際輸出位置，並檢查輸出內容；在 Codex CLI 端確認技能已被發現以前，不要把它標記為匯入完成。
SECTION 02執行匯出：先留下可檢查的檔案證據
Apple 說明 Xcode 可擴充 Agent，並提供 agent skills 的匯出指引。依該文件核對安裝版本適用的用法後，再在專案或明確的暫存位置執行匯出。若 Apple 提供針對 Codex 的專門目的地或選項，僅在文件明確適用於你目前版本時採用；若文件描述的是一般匯出，則依其輸出結果再進行放置，不要把兩種流程混成一個保證適用的命令。
匯出後記下三項證據：使用的 Xcode 版本、執行命令時所在的目錄，以及實際生成的技能資料夾與檔案。依 Codex 技能結構與發現說明及其 Skills 文件，確認輸出的技能資料夾中有 Codex 可讀取的 SKILL.md，而且檔案內容不是空白或只有來源端的說明文字。不要僅憑終端機出現「完成」訊息判定 Codex 已經讀到它。
SECTION 03放置技能檔案：按 Codex CLI 的目錄規則選擇範圍
Codex 技能可以放在專案層級或使用者層級。若只有單一程式碼庫要用，先考慮專案內的 .agents/skills/；若希望同一個使用者在不同專案重用，可依官方文件使用使用者層級的技能位置。下表列的是常見選擇，不表示任意工具或所有 Codex 設定都會從相同目錄載入；實際發現規則仍以 Codex 官方 Skills 說明為準。
| 放置方式 | 典型位置 | 適用情況 | 驗收重點 |
|---|---|---|---|
| 專案層級 | <project>/.agents/skills/<skill-name>/SKILL.md |
技能只與這個專案或團隊工作流有關 | 從該專案目錄啟動 Codex CLI，檢查技能是否出現在可用技能中 |
| 使用者層級 | 使用者家目錄下的 .agents/skills/<skill-name>/SKILL.md |
你要在多個個人專案重用 | 使用同一個使用者帳號啟動 Codex，再於另一個受控專案驗證 |
| 暫存匯出位置 | 以匯出命令實際回報的路徑為準 | 先檢查來源檔，再決定要放入哪個技能目錄 | 不要把暫存位置誤認為 Codex 自動掃描的目錄 |
匯出的 Xcode skills 應該放在哪個 Codex 目錄？
先判斷技能要跟著專案共享，還是由同一個使用者跨專案重用：前者放在該專案的技能目錄，後者放在使用者層級目錄。每個技能都應保留自己的資料夾與 SKILL.md；不要把多份技能內容任意合併成一個檔案，也不要只因檔案存在某處就推定 Codex 會讀取。
放置後關閉並重新啟動 Codex CLI 工作階段，再以同一個目錄啟動，能避免把工作階段未重新載入誤判成匯入失敗。若你們的 Codex CLI 文件或介面提供明確的重新載入方式，依該版本說明操作；不要假定每個版本都支援相同的即時重載行為。
SECTION 04首次呼叫與權限驗收：將三種結果拆開看
先用不修改程式碼的要求，請 Codex 說明它是否找到指定技能、準備如何使用其中的指引，以及它讀到的技能名稱。這一步只測技能發現與呼叫，不要要求它直接編輯檔案或執行建置。若 Codex 看不到技能，優先檢查目錄層級、資料夾結構、SKILL.md 是否存在，以及啟動位置；若看得到卻沒有採用，改用明確提及技能名稱的低風險任務，再檢查工作階段是否已重新載入。
| 驗收項目 | 低風險檢查 | 通過代表什麼 | 不代表什麼 |
|---|---|---|---|
| 技能發現 | 要求 Codex 列出或解釋目標技能內容 | Codex 能讀到該技能 | 專案檔案、命令或 Xcode 已獲准 |
| 技能呼叫 | 指定技能名稱，請它只提出檢查步驟 | Codex 在回應中採用技能指引 | 它已正確修改程式碼或完成建置 |
| 專案存取 | 先要求讀取一個已知的專案檔案 | 該工作階段能存取指定檔案 | 其他目錄、憑證或命令也可存取 |
| 命令執行 | 由你批准必要的唯讀檢查命令 | 指定命令在目前權限下可執行 | 所有 shell 命令都應開放 |
| Xcode 建置 | 在可回退的分支執行實際建置並檢查日誌 | 此環境中的該次建置通過 | 發布、簽名或其他目的地也已通過 |
Codex 看得到 Xcode skill、卻不會呼叫時怎麼辦？
先確認技能的描述與觸發條件能對應目前任務，然後重新啟動工作階段，明確要求 Codex 使用該技能處理一項不會改檔的檢查。仍未呼叫時，核對是否在正確專案目錄啟動、技能是否位於 Codex 支援的目錄，以及資料夾是否包含可讀取的 SKILL.md。不要為了讓技能「看起來能用」而開放無關目錄或廣泛命令權限。
提醒：技能是指引，不是權限憑證。請分別設定並驗證專案檔案存取與命令批准；不要把授予過寬的命令權限當成匯入技能的必要步驟。
SECTION 05真實專案驗收：建置成功才算碰到 Xcode 工具鏈
技能被發現，不代表 Codex 可讀取專案；能讀取專案，也不代表它能執行 Xcode 建置。要驗證最後一項，先建立可回退的分支或使用測試專案，再以專案本身的 scheme、目的地與組態執行建置。可先由你確認可用設定，再讓 Codex 執行經批准的命令，例如：
xcodebuild -list -project <專案路徑>/<專案名稱>.xcodeproj
xcodebuild -project <專案路徑>/<專案名稱>.xcodeproj \
-scheme <Scheme> \
-destination '<依專案調整的目的地>' \
build
若專案使用 workspace，將 -project 換成符合專案結構的 -workspace；不要同時猜測專案名稱、scheme 或目的地。檢查建置結束狀態及日誌中的錯誤，而不是只看 Codex 是否回報「完成」。若建置失敗，記下使用的 Xcode 版本、命令、目的地和錯誤段落，先區分技能指引錯誤、命令授權問題與專案本身的編譯問題，再決定要修正哪一層。
導入後如何確認 Codex 能建置 iOS 專案？
在測試分支中，先確認它讀到預期的專案設定，再執行與該專案相符的 xcodebuild 命令；最後由建置日誌確認結果，並視需要檢查產物。技能呼叫成功只能證明 Agent 用上了指引，不能代替編譯、測試、簽名或發布驗收。
| 觀察結果 | 最可能需要檢查的環節 | 下一步 |
|---|---|---|
| 找不到技能 | 放置目錄、檔案結構、啟動目錄或工作階段載入 | 對照 Codex 文件檢查目錄，再重開工作階段 |
| 找到技能但無法讀專案 | Codex 對專案路徑的存取權 | 先批准最小必要的專案存取，再做唯讀檢查 |
| 能讀專案但命令被拒絕 | 目前的命令授權設定 | 逐條批准必要命令，不要直接開放不受限執行 |
| 命令已執行但建置失敗 | 工具鏈選擇、scheme、目的地或程式碼錯誤 | 以 Xcode 日誌定位原因，不將編譯錯誤歸咎於技能匯入 |
| 建置通過但發布未驗收 | 簽名、發布設定或上架流程尚未驗證 | 把建置、測試、簽名與發布分成不同檢查項目 |
按順序完成這份驗收清單
- [ ] 記錄 Xcode 版本，並確認終端機選取的是同一套 Xcode。
- [ ] 按 Apple 對目前版本的文件執行
xcrun agent skills export流程。 - [ ] 記錄匯出路徑，確認技能資料夾中有可讀取的
SKILL.md。 - [ ] 根據重用範圍，將技能放到 Codex CLI 支援的專案層級或使用者層級目錄。
- [ ] 重新啟動 Codex CLI 工作階段，先以不修改程式碼的要求驗證技能發現與呼叫。
- [ ] 分別檢查專案檔案存取、命令批准與 Xcode 工具鏈；不以放寬所有權限代替診斷。
- [ ] 在可回退的分支或測試專案執行建置，核對日誌與預期產物。
若你沒有本地 Mac，但需要完成技能匯出、macOS 權限設定或真實 Xcode 專案建置，遠端 Mac 可以補足必須在 macOS 上執行的環節；它不能替你免除 Codex 技能、專案存取及建置結果的分別驗收。你可先了解 MACNOX 遠端 Mac 方案與方案費用，再按測試時長及是否需要持續運作的建置環境評估。
對照來看，Windows 或 Linux 主機無法直接取代 Xcode 所需的 macOS 工具鏈；自購 Mac 則有一次性硬體支出與維護責任，本地環境也未必適合長時間作為共用建置節點。遠端 Mac 需要持續付費，且圖形操作會受連線品質影響，因此若你已長期承受穩定重負載，或需要本機實體介面，購買或自管實機可能更合適。若目前只是缺少一段可用的 macOS/Xcode 環境，用 MACNOX 租用遠端 Mac，便可先完成匯出、配置與真實建置驗證，再依實際工作負載決定是否長期自建。