OpenHands公式ドキュメントで現在案内されているルールの置き場所は、大きく2つです。常に読み込ませる短い共通規則はAGENTS.md、特定の作業だけで必要になる手順や資料はSKILL.mdを使います。OpenHands Skillsの公式概要でも、Skillsは必要な知識を段階的に扱う仕組みとして説明されています。

症状： iOSリポジトリの規則が長文化し、Agentが毎回すべてを読み込むうえ、Xcodeの成功まで文章だけで判断してしまう。
最短解法： AGENTS.mdには全タスク共通の最小規則だけを残し、SwiftやXcodeの手順はSkillsへ分け、最後はMac上のビルド・テスト・署名確認を別ゲートにします。

この記事は、OpenHandsの基本方針を統一したいリポジトリ管理者、按需でiOS専用手順を呼び出したいモバイル開発者、Skillに含まれるスクリプトや権限を監査するプラットフォーム・セキュリティ担当者向けです。単にファイル形式を覚えるのではなく、誰が維持し、いつ読み込み、何を実行ログで確認するかを決めたい場合に適しています。

更新情報： 2026年9月6日時点で、OpenHandsの公式資料ではSkillsが現在の名称として扱われ、一部のMicroagents関連パスは旧形式または非推奨の位置付けです。ディレクトリの優先順位や互換パスは、導入時に公式のSDK Skillガイドで再確認してください。

ルールを常時読み込むAGENTS.md

AGENTS.mdに向いているのは、リポジトリの目的、主要ディレクトリ、基本的なセットアップ、変更してはいけない境界、共通CI門扉などです。どのタスクでも必要で、短く検証しやすい内容に限定してください。

例えば、次のような情報です。

  • アプリ本体、テスト、生成物、設定ファイルの場所
  • パッケージ依存関係を変更した場合に確認するファイル
  • 必須の静的解析やユニットテスト
  • 秘密情報をコミットしないこと
  • 変更前に参照すべき既存のワークフロー

ここにSwiftUIの画面追加手順、署名証明書の扱い、UITestの失敗例まで詰め込むと、共通コンテキストが重くなります。AGENTS.mdは開発マニュアルではなく、Agentが毎回守る境界線です。実際のファイル構成とCI設定を情報源にして、存在しないスクリプトや古いコマンドを書かないことが重要です。

条件付きの知識をOpenHands Skillsへ分離

OpenHands SkillsとAGENTS.mdの違いは、優先度よりも「常に必要か、作業時だけ必要か」です。Skillは、特定のフレームワーク、モジュール、障害対応、リリース作業などに必要な知識を、条件付きで読み込ませるために使います。

SKILL.mdの説明文は、Agentが「この作業なら呼び出す」と判断できる表現にしてください。「iOS関連」だけでは広すぎます。「Xcodeプロジェクトのビルド失敗を調査するとき」「SwiftUIの画面とUITestを同時に変更するとき」のように、対象と発火条件を記述します。Skillsの構造やSDKからの利用方法は、公式SDK資料のSkill説明に合わせて確認します。

AGENTS.mdとSkillで同じルールを複製するのは避けてください。例えば、秘密情報を扱わないという共通規則はAGENTS.mdに一度だけ書き、証明書の確認手順や署名エラーの切り分けはiOS Skillに置きます。片方だけ更新されると、Agentが矛盾した判断をするためです。

OpenHands MicroagentsからSkillsへの移行

旧Microagentsの内容をすべて一括変換する必要はありません。まず、現在のタスクで呼び出されているもの、複数リポジトリで共有されているもの、実行権限を持つものを分類してください。単なる説明文はSkillへ移し、常時必要な短い規則はAGENTS.mdへ戻し、使われていない旧定義は回退できる形で保管します。

移行前後で同じ低リスクの修正タスクを実行し、読み込まれた規則、実行されたコマンド、変更ファイルを比較します。ファイル名を変更しただけで、実際のロード結果が同じとは限りません。公式資料で旧パスの扱いが更新された場合は、互換性を前提にせず再検証してください。

iOS専用SkillとXcodeの境界

iOSチームのSkillには、Swiftの記述規約、プロジェクトの入口、対象Scheme、テストターゲット、典型的なエラーの読み方をまとめられます。ただし、Xcodeのバージョン、利用可能なシミュレーター、実際のビルドコマンドは、Skillに固定値として書き込む前にプロジェクトやCI設定から確認します。

iOSプロジェクトのXcodeコマンドをAGENTS.mdへ置く場合

毎回すべての変更で実行する共通チェックなら、AGENTS.mdに「CIで定義された標準コマンドを実行する」と記載できます。一方、特定のSchemeだけを使うUI変更、実機が必要な署名確認、時間のかかる統合テストは、iOS SkillまたはCIの個別ジョブへ分ける方が安全です。

コマンドを知っていることと、実行して成功したことは別です。Appleのビルドと実行に関する公式ガイドが示す操作でも、署名設定、依存関係、接続先の状態によって結果は変わります。Xcodeのテスト結果の確認方法も参照し、ログや失敗テストを成果物に残してください。

プラットフォーム管理とセキュリティ境界

複数リポジトリでルールを共有する場合は、プロジェクト固有のAGENTS.md、利用者単位のSkills、旧ディレクトリの関係を文書化します。同名の規則が複数箇所にあると、後から見た担当者にはどれが有効か分からない「見えない上書き」が起きます。

共有Skillには、少なくとも所有者、バージョン、変更レビュー担当、回退方法を持たせてください。共通化を急ぐより、まず一つのテストリポジトリでロード結果を固定し、その後に他のリポジトリへ展開する方が調査しやすくなります。移行中は旧定義を削除せず、同じタスクで新旧の差分を確認してから切り替えます。

Skillにスクリプトや参考資料を含める場合

OpenHands Skillには、Markdownの説明だけでなく、補助スクリプト、参考資料、ツール設定を関連付けられます。ただし、これは「文章を追加しただけ」ではありません。Skillsの公式アーキテクチャ資料を確認し、実行される資源までレビュー対象にしてください。

特に次を確認します。

  • スクリプトに実行権限が付いているか
  • 引数や環境変数から動的な内容を受け取るか
  • MCPツールが書き込みや外部通信を行うか
  • リポジトリ外の秘密情報や証明書へアクセスできるか
  • 失敗時に処理を止めるか、後続処理へ進むか
  • 実行ログにトークンや個人情報が残らないか

セキュリティ上の結論は、Skillの記述だけで出してはいけません。許可・拒否のテスト、実行ログ、アクセス範囲の確認を組み合わせます。OpenHandsのHooksに関する公式資料も参照し、フックとSkillの責務を混同しないようにしてください。

注意： 「Agentが署名を確認した」「テストを完了した」という返答は、Mac上の実行証拠ではありません。コマンド、対象Scheme、終了状態、失敗テスト、生成された成果物を受け渡し条件にしてください。

Mac受け入れ門扉と担当者の分離

OpenHandsからMac環境へ渡す成果物は、少なくとも次の単位に分けます。

  1. 変更パッチまたはコミット識別子
  2. 依存関係や生成ファイルの変更
  3. 実行したテストと未実行テスト
  4. ビルド対象、Scheme、シミュレーターまたは実機の条件
  5. 署名・配布権限に関する保留事項
  6. 失敗ログと再現手順

ビルド、シミュレーター試験、署名、配布操作は同じ権限で連続実行させない方がよいです。コード修正を担当するAgentと、署名・公開権限を持つ担当者を分ければ、プロンプト上の指示がそのまま高い権限の操作へ拡大するリスクを抑えられます。

XcodeのSchemeやビルド設定は、公式のビルドScheme設定資料と実際のプロジェクト設定を突き合わせます。Skillは作業を案内しますが、Macでの受け入れを代行する証明書にはなりません。

導入前に実行する確認リスト

  • [ ] AGENTS.mdから、特定フレームワークだけに必要な説明を分離する
  • [ ] AGENTS.mdに残した各規則が、実ファイルまたはCI設定で検証できることを確認する
  • [ ] iOS Skillに発火条件、対象Scheme、対象テストの範囲を記載する
  • [ ] Xcodeのバージョンやシミュレーター条件を、固定文ではなく現行設定から照合する
  • [ ] Microagentsの旧定義を分類し、移行後の回退方法を保存する
  • [ ] Skill付属スクリプトの権限、MCP接続、秘密情報への経路を監査する
  • [ ] 同じ低リスク修正で、移行前後のロード結果と実行ログを比較する
  • [ ] Mac受け入れ用に、パッチ、依存関係、テスト結果、署名状態を引き渡す
  • [ ] Agentの自己申告ではなく、Mac上のログを最終合否の根拠にする

役割別の選択スコア

次の表は機能の優劣ではなく、iOSチーム内での責務に対する適合度を5点満点で整理したものです。点数は記事の判断基準であり、製品の実測性能を示すものではありません。

担当・用途 AGENTS.md OpenHands Skills Mac受け入れ門扉
リポジトリ目的と構造の共有 5 2 1
特定のSwift・Xcode作業 2 5 2
複数リポジトリへの再利用 3 4 2
スクリプト・ツール権限の統制 3 3 5
ビルド・テスト・署名の事実確認 1 2 5
変更後の回退と監査 4 4 5

この比較から、AGENTS.mdかSkillsかの二択にする必要はありません。共通ルールはAGENTS.md、専門知識はSkills、実行結果の合否はMac門扉という三分割が、役割の重なりを最も減らします。

自前のMacだけで長時間のXcode検証を続ける方法は、低頻度の個人作業なら十分です。しかし、端末の占有、macOSやXcode環境の差、実機接続の不安定さ、署名権限を同じ端末に集めるリスクが、チーム運用では隠れた負担になります。必要な期間だけSSHMacのMac環境を借り、OpenHandsの成果物を独立したMac受け入れへ渡す構成なら、ルール管理と検証環境を分離しやすくなります。利用条件を確認する場合は、Mac miniレンタルプランを参照し、継続的な負荷や物理デバイス接続が必要なら、レンタルだけで完結するかを先に確認してください。

まずは本番公開ではなく、画面文言の変更やテスト追加のような低リスクのiOS作業でロード結果を比べるのが安全です。Macを継続的に確保できない場合だけ、SSHMacの案内ページで利用形態を確認し、Xcodeのビルド・シミュレーター試験・署名をそれぞれ独立した受け入れ条件として設計してください。