症狀：OpenHands 每次都載入大量 iOS 細節，或不同任務讀到互相矛盾的規則。
最快解法：把所有任務都必須看到的短規則放進 AGENTS.md，把特定框架與 Xcode 流程放進 Skills；建置、簽名與裝置驗證最後仍交給獨立的 Mac 門禁。
這個分法適合正在維護 iOS 儲存庫規則的倉庫維護者、需要配置按需流程的移動端開發者，以及負責跨倉庫載入、腳本與權限治理的平台和安全團隊。若你只想讓 Agent 代寫幾段 Swift，而不打算讓它接觸建置或驗收流程，本文的權限部分可以先略讀。
最後更新於 2026 年 9 月 6 日；規則名稱、Skills 狀態與載入行為應以 OpenHands Skills 官方概覽 及實際測試儲存庫再次核對。本文不把舊 Microagents 路徑當成目前首選。
先用角色分清楚規則責任
倉庫維護者：只在 AGENTS.md 保留不可缺少的公共上下文
AGENTS.md 的定位不是 iOS 開發手冊，而是倉庫的最小共同契約。你可以放入三類內容：
- 這個儲存庫解決什麼問題，以及主要目錄從哪裡進入。
- 基本安裝或初始化方式，以及不可省略的環境前置條件。
- 所有一般變更都必須遵守的 CI 門檻，例如先執行哪一類檢查、不可修改哪些生成檔。
判斷標準很簡單：如果一個規則只對某個模組或某類任務有用，就不應因為方便而塞進始終載入的檔案。AGENTS.md 越長，Agent 每次任務都要處理的上下文越多；更嚴重的是，完整手冊往往包含已過時的命令，卻沒有足夠訊息讓 Agent 判斷哪一段才是當前真相。
規則來源應優先取自儲存庫現有檔案、CI 設定和實際工作流程，而不是由維護者憑記憶重寫。對於 OpenHands 的自訂內容，也應對照官方 SDK Skill 指南確認目前的 SKILL.md 形態。
業務開發者：把按需知識拆成可觸發的 Skill
OpenHands Skills 和 AGENTS.md 的關鍵差異，在於「何時需要知道」而不是檔案名稱本身。
Skill 適合承載以下內容：
- 只有使用特定 Swift 框架、功能模組或資料層時才需要的約定。
- 某個測試目標、Scheme 或錯誤類型的處理步驟。
- 需要參考範例、腳本或工具設定才能完成的專門任務。
一個合格的 Skill 描述，應該讓 Agent 能夠判斷「現在是否要載入它」。例如，描述可以指出這是處理 iOS 建置失敗、UI 測試或簽名前檢查的流程；但不要只寫「iOS 開發指南」這種無法觸發的泛稱。官方 Skills 架構文件也把 Skill 視為可按需使用的能力，而不是把所有倉庫背景永久塞進上下文。SDK 的 Skill 架構說明可用來核對這個邊界。
不要在 Skill 裡再複製一份 AGENTS.md 的安裝規則。基礎規則一旦改動，兩份文字很容易只更新一份，Agent 便可能在同一任務中收到互相衝突的要求。Skill 應引用公共規則，並只補充其專門流程。
iOS Skill 應該負責指導，不應假裝完成驗收
移動端開發者：把 Apple 工具鏈流程做成可核實的專項知識
iOS 團隊可以建立一個專門的 Skill，集中說明：
- Swift 風格與工程入口。
- 工作區、Scheme 和測試目標的選擇方式。
- 建置失敗、測試失敗和簽名錯誤的判讀路徑。
- 在模擬器或實體裝置上執行驗證前，必須收集哪些輸出。
但 Xcode 版本、模擬器狀態、Scheme 名稱和建置命令都不應從記憶填入。應先從專案檔、CI 設定或最近一次成功的工作流程核實。Apple 對自訂 Xcode Build Scheme與建置及執行 App分別提供了不同層面的設定與操作說明，這也反映出「知道命令」不等於「環境已可驗收」。
因此，Skill 可以告訴 OpenHands 應該先查什麼、如何選測試目標、哪些錯誤不能自行繞過；它不能宣稱簽名已完成、裝置可用或測試已通過。這些結論必須由 Mac 工作區的建置輸出、測試報告和權限結果支持。
平台工程師：用三層邊界處理載入與共享
你可以把整個規則系統分成三層來治理：
- 專案層：儲存庫內的
AGENTS.md與專案 Skills，描述這個 iOS 專案真正需要的規則。 - 使用者層：個人或團隊共用的 Skills，提供跨倉庫也成立的流程，但不應覆蓋專案的安全門檻。
- 舊路徑層：仍存在的 Microagents 或歷史目錄，只作為遷移背景與回退依據，不當成新專案的首選來源。
具體優先順序、目錄位置和平台支援矩陣會隨 OpenHands 文件更新，不能只依賴舊文章或團隊口述。每次升級都應逐頁核對官方 Skills 概覽及 SDK 指南，並在測試儲存庫中觀察實際載入結果。
跨倉庫共享的 Skill 至少要有版本、所有者和變更審查人。遷移期間不要直接刪除舊內容：先用相同的低風險任務比較新舊載入結果，再決定是否移除回退路徑。否則當同名規則發生不可見覆蓋時，你很難判斷是載入順序、內容變更，還是工具版本造成差異。
安全團隊與發布負責人要把提示和執行分開
安全團隊：審查的不只是 SKILL.md
Skill 可以連結腳本、參考資料和工具設定，因此安全審查不能停留在 Markdown 文字。至少要逐項檢查：
- 腳本是否具有不必要的寫入、刪除或網路連線權限。
- 參考資料是否會帶入動態內容，並影響 Agent 的下一步決策。
- MCP 工具能否讀取敏感路徑、憑證、簽名資料或其他儲存庫。
- 腳本失敗時是否會被當成成功，或以模糊輸出掩蓋阻斷結果。
OpenHands 的 Hooks 文件所涉及的自訂執行與攔截邏輯，也提醒你不能把「規則描述」和「實際可執行操作」混成同一個信任層。官方 Hooks 說明可作為檢查自動化邊界的參考。
安全結論應由執行日誌和阻斷測試支持。例如，測試一個沒有權限的路徑是否真的被拒絕，檢查敏感檔案是否完全沒有出現在輸出中，而不是只看 Skill 是否寫了「不得存取」。
發布負責人：把 Agent 產出交給獨立的 Mac 門禁
OpenHands 完成修改後，交接物應至少包含四項：補丁或提交、依賴變更、已知未完成項目，以及待在 Mac 上執行的測試清單。這些資料讓下一位驗收者能從結果重現判斷，而不是接受 Agent 的一句「已完成」。
Xcode 驗收可拆成三個風險不同的階段：
- 建置：確認工作區、Scheme、依賴與編譯結果。
- 測試：按照測試目標執行，保存失敗案例和測試輸出；Apple 的測試執行與結果判讀文件可作為驗收參考。
- 簽名與發布權限：獨立確認憑證、Provisioning Profile、裝置和發布權限，不把它們視為一般建置成功的附帶結果。
這種拆分能避免一個低風險程式碼修改，意外被解讀為「已具備發布資格」。最終合併條件應依賴可保存、可重查的 Mac 輸出，而不是提示規則或 Agent 自述。
用評分快速決定內容放哪裡
以下評分不是 OpenHands 的官方優先級，而是給團隊審查規則位置的決策工具；每一項以「越符合越適合」為原則：
- 放入
AGENTS.md，適合度 5/5：所有任務都必須知道、內容短、能由倉庫或 CI 驗證，而且長期不依賴特定 Xcode 狀態。 - 放入 iOS Skill，適合度 5/5：只在 Swift、特定模組、測試目標或建置問題出現時需要，並且有清楚的觸發描述。
- 放入獨立 Mac 門禁，適合度 5/5：需要實際 Xcode、模擬器、實體裝置、簽名、憑證或發布權限才能得出結論。
- 不應只放在任何提示檔，適合度 5/5：涉及敏感路徑、可執行腳本、動態內容或不可逆操作，必須另有權限與日誌控制。
第一階段：用可勾選清單完成遷移
- [ ] 從現有儲存庫檔案與 CI 設定列出真正存在的建置、測試和安裝入口。
- [ ] 把倉庫目的、目錄入口和最低公共門檻縮成一份短
AGENTS.md。 - [ ] 將只服務特定框架、模組或任務的內容移到具備明確觸發描述的
SKILL.md。 - [ ] 從 iOS Skill 移除與
AGENTS.md重複的基礎規則，改為引用公共契約。 - [ ] 為每個 Skill 列出腳本、參考資料、MCP 工具和敏感路徑。
- [ ] 使用相同低風險任務比較新舊 Microagents 或規則路徑的實際載入結果。
- [ ] 將補丁、依賴、待測項目和 Mac 驗收輸出納入發布交接物。
- [ ] 在合併前分別保存建置、測試、簽名與權限證據。
完成這份清單後，你仍應先選一個不涉及發布憑證的 iOS 小任務驗證規則載入；不要一開始就拿正式簽名或生產發布工作測試遷移。
常見判斷的獨立答案
OpenHands Skills 和 AGENTS.md 是互相替代嗎？
不是。AGENTS.md 解決「每次都必須知道什麼」，Skills 解決「特定任務何時需要額外知識」。如果把所有內容都放進前者，公共上下文會膨脹；如果把倉庫基本門檻全部拆散到 Skills，Agent 可能在尚未載入專項能力時漏掉不可違反的規則。
舊 Microagents 是否代表必須立即遷移？
不代表。官方目前以 Skills 作為名稱，部分 Microagents 路徑已被標成舊格式或棄用路徑，但遷移仍應以實際載入測試為準。保留短期回退路徑、記錄版本和變更所有者，比直接刪除舊內容更容易追蹤問題。
Xcode 命令是否應全部寫進 AGENTS.md？
不應全部寫入。公共檔案可保留工程入口與不可跳過的 CI 原則；Xcode 版本、Scheme、模擬器、測試目標和簽名條件則應放在 iOS Skill 或驗收文件，並從當前專案和 CI 設定核實。
Skill 附帶腳本時，是否仍只是文件變更？
不是。腳本可能改寫檔案、連線外部工具或讀取敏感路徑，風險已超出文字提示。安全團隊應檢查檔案權限、工具範圍和失敗行為，再以日誌及阻斷測試確認它沒有越過授權邊界。
最後把規則交給能重現的環境
如果你目前使用的方案是把所有 iOS 命令直接塞進單一規則檔，短期看似容易，長期卻會遇到三個實際缺點：Xcode 或 Scheme 變動後內容容易過時；不同角色修改同一份長檔案時難以審查；而且 Agent 說「已完成」並不能替代 Mac 上的測試、簽名和裝置證據。若本地 Mac 無法持續提供穩定的 Xcode 驗收環境，較合理的下一步不是再增加提示文字，而是評估獨立的遠端 Mac 工作區，讓 OpenHands 的改碼結果與 Apple 工具鏈驗收分開管理。
你可以先從一個低風險 iOS 任務驗證 AGENTS.md 與 Skill 的載入差異；若本地硬體、權限或團隊排程仍不足，再參考 SSHMac 的支援入口，了解如何把臨時驗收工作交給獨立 Mac 環境。若要確認服務範圍，也可先查看 SSHMac 的服務入口，再決定租用是否符合你的測試週期；對長期固定重負載或必須直接連接特定實體設備的團隊，自購 Mac 仍可能更合適。