Microsoft Graph Agent Skill

27,700以上のMicrosoft Graph APIをすべてローカルで検索・参照・呼び出し、ネットワーク呼び出しは不要です。3つの検索コマンドを使って適切なエンドポイントを見つけ、権限とパラメータを確認した後、必要に応じて呼び出しを直接実行するか、Graph MCPサーバーに処理を委譲します。

含まれるもの

Microsoft Graph APIは27,700以上のエンドポイントを備えており、毎週更新されます。LLMの学習データカットオフをはるかに超えています。このスキルは完全なAPI表面をローカルインデックスとしてバンドルしており、ネットワーク呼び出しなしで瞬時に検索できます。

インデックス	数	内容
OpenAPI エンドポイント	27,700以上	パス、メソッド、サマリー、説明、権限スコープ
エンドポイント ドキュメント	6,200以上	権限（委任/アプリ）、クエリパラメータ、必須ヘッダー、デフォルト vs $selectのみのプロパティ
リソース スキーマ	4,200以上	すべてのプロパティと型、サポートされている $filter オペレータ、デフォルト/select-onlyフラグ
コミュニティ サンプル	随時追加	検証済みのクエリで、自然言語タスクを正確なAPI呼び出しにマッピング

実行方法

msgraph CLIはこのスキルにバンドルされています。すべてのコマンドをこのスキルディレクトリのランチャースクリプトで実行します:

• macOS / Linux: bash <path-to-this-skill>/scripts/run.sh <command> [args...]
• Windows: powershell <path-to-this-skill>/scripts/run.ps1 <command> [args...]

例えば、macOSでメール関連のAPIを検索する場合:

bash /home/user/.opencode/skills/msgraph/scripts/run.sh openapi-search --query "send mail"

以下のすべての例では、msgraph は完全なランチャー呼び出しの短縮形です。

適切なAPIを見つける

これはスキルの主な目的です。段階的なルックアップ戦略に従います。各段階がより詳細な情報を追加します:

1. 独自の知識 — よく知られているエンドポイント（/me、/users、/groups）を最初に試します。
2. sample-search — キュレーション済みの検証済みサンプル。最高の品質です。一般的なタスクと複数ステップのワークフローに使用します。
3. api-docs-search — エンドポイントごとの権限、サポートされるクエリパラメータ、必須ヘッダー、デフォルト vs $selectのみのプロパティ、フィルタオペレータ付きのリソースプロパティの詳細。
4. openapi-search — 27,700のGraph APIの完全なカタログ。他の方法ではエンドポイントが見つからない場合に使用します。
5. リファレンス ファイル — クエリパラメータ、高度なクエリ、ページング、バッチ処理、スロットリング、エラー、ベストプラクティスに関する概念ドキュメント。特定のガイダンスが必要な場合のみ読みます。

この順序はガイダンスです。タスクに基づいて調整してください。例えば、エンドポイントは既に知っているが権限が必要な場合は、api-docs-search に直接進んでください。

sample-search

自然言語タスクを正確なMicrosoft Graph APIクエリにマッピングするキュレーション済みコミュニティサンプルを検索します:

msgraph sample-search --query "conditional access policies"
msgraph sample-search --product entra
msgraph sample-search --query "managed devices" --product intune

フラグ	説明
--query	フリーテキスト検索（intentとqueryフィールドを検索）
--product	製品でフィルタ: entra、intune、exchange、teams、sharepoint、security、general
--limit	最大結果数（デフォルト: 10）

--query または --product の少なくとも1つが必須です。結果には複数ステップのワークフローが含まれます。

api-docs-search

特定のエンドポイントまたはリソースタイプの詳細なドキュメントを参照します:

msgraph api-docs-search --endpoint /users --method GET
msgraph api-docs-search --resource user
msgraph api-docs-search --query "ConsistencyLevel"

フラグ	説明
--endpoint	エンドポイントパスで検索（例: /users、/me/messages）
--resource	リソースタイプ名で検索（例: user、group、message）
--method	HTTPメソッドでフィルタ: GET、POST、PUT、PATCH
--query	すべてのフィールド全体のフリーテキスト検索
--limit	最大結果数（デフォルト: 10）

--endpoint、--resource、--query のいずれかが必須です。

エンドポイント結果には以下が含まれます: 必須権限（委任workschool、委任personal、application）、サポートされるODataクエリパラメータ、必須ヘッダー、デフォルトプロパティ、エンドポイント固有の注釈。

リソース結果には以下が含まれます: 型付きのすべてのプロパティ、サポートされる $filter オペレータ（eq、ne、startsWith等）、各プロパティがデフォルトで返されるか $select が必須かどうか。

openapi-search

27,700のMicrosoft Graph APIのOpenAPIカタログ全体を検索します:

msgraph openapi-search --query "send mail"
msgraph openapi-search --resource messages --method GET

フラグ	説明
--query	フリーテキスト検索（パス、サマリー、説明を検索）
--resource	リソース名でフィルタ（例: users、groups、messages）
--method	HTTPメソッドでフィルタ
--limit	最大結果数（デフォルト: 20）

--query、--resource、--method のいずれかが必須です。

MCPサーバーとの連携

エージェントがMicrosoft Graph MCPサーバー（例: lokka.dev または他のMicrosoft Graph MCPサーバー）にアクセスできる場合、上記の検索ツールを使って適切なエンドポイント、権限、リクエスト構文を見つけて、その情報をMCPサーバーで実行に使用します。

このモード下では、このスキルを通じた認証は不要です。スキルは純粋に知識レイヤーとして機能し、MCPサーバーが認証とAPI実行を処理します。

直接Microsoft Graph API実行

Graph MCPサーバーがない場合、このスキルはMicrosoft 365に認証してMicrosoft Graph APIコールを直接実行できます。

認証

このツールは**委任（ユーザー）とアプリのみ（アプリケーション）**認証をサポートし、環境変数から自動検出されます。

クイックスタート:

msgraph auth status          # サインイン状態を確認
msgraph auth signin          # サインイン（ブラウザを開く）- 推奨
msgraph auth signin --device-code  # デバイスコード経由でサインイン（ヘッドレス）
msgraph auth signout         # セッションをクリア

• 委任認証（デフォルト）: インタラクティブブラウザサインイン、ヘッドレス環境ではデバイスコードフォールバック。段階的な同意をサポート。403では、ツールは必須スコープで再認証して自動的に再試行します。
• アプリのみ認証: MSGRAPH_CLIENT_SECRET、MSGRAPH_CLIENT_CERTIFICATE_PATH、MSGRAPH_FEDERATED_TOKEN_FILE、MSGRAPH_AUTH_METHOD=managed-identity が設定されている場合に自動検出されます。MSGRAPH_TENANT_ID が必須です。

証明書、マネージド ID、ワークロード ID フェデレーション、すべての環境変数を含む詳細な認証設定については、references/docs/authentication.md を参照してください。

Graph APIコールの作成

重要: セッション内で最初の graph-call を実行する前に msgraph auth status を実行して認証を確認してください。

msgraph graph-call <METHOD> <URL> [flags]

読み取り操作

msgraph graph-call GET /me
msgraph graph-call GET /users --select "displayName,mail" --top 10
msgraph graph-call GET /me/messages --filter "isRead eq false" --top 5 --select "subject,from,receivedDateTime"
msgraph graph-call GET /users --filter "startsWith(displayName,'John')"

書き込み操作

重要: 書き込み操作の前にユーザーに確認を求める必要があります。書き込み操作には --allow-writes フラグが必須です。

msgraph graph-call POST /me/sendMail --body '{"message":{"subject":"Hello","body":{"content":"Hi"},"toRecipients":[{"emailAddress":{"address":"user@example.com"}}]}}' --allow-writes
msgraph graph-call PATCH /me --body '{"jobTitle":"Engineer"}' --allow-writes

DELETE は常にブロックされます（フラグに関わらず）。

graph-call フラグ

フラグ	説明	例
--select	OData $select	--select "displayName,mail"
--filter	OData $filter	--filter "isRead eq false"
--top	OData $top（結果を制限）	--top 10
--expand	OData $expand	--expand "members"
--orderby	OData $orderby	--orderby "displayName desc"
--api-version	v1.0 または beta（デフォルト: beta）	--api-version v1.0
--scopes	追加権限スコープをリクエスト	--scopes "Mail.Read"
--headers	カスタムHTTPヘッダー	--headers "ConsistencyLevel:eventual"
--body	リクエストボディ（JSON）	--body '{"key":"value"}'
--output	json（デフォルト）または raw	--output raw
--allow-writes	POST/PUT/PATCHを許可（ユーザー確認が必須）

重要なルール

常に（検索と知識）

1. Microsoft Graphのエンドポイントを推測または捏造しない — 呼び出し前に必ず検索で確認します。このスキルが存在するのはエージェントが幻覚を見るためです。必ず使用してください。
2. 段階的なルックアップ戦略を使用 — 知っていることから始めて、必要に応じてsample-search、api-docs-search、openapi-searchを使用します。
3. --select を使用してレスポンスサイズを削減 — 必要なフィールドのみをリクエストします。
4. --top を使用して結果を制限 — 数千のレコード取得を避けます。
5. ConsistencyLevelヘッダーは、ディレクトリオブジェクト（ユーザー、グループなど）に対する $count と $search に必須です。--headers "ConsistencyLevel:eventual" を使用します。
6. デフォルトAPIバージョンはbeta — 本番環境安定のエンドポイントには --api-version v1.0 を使用します。

直接実行を使用する場合（graph-call）

7. セッション内で最初の graph-call の前に認証ステータスを確認します。
8. GETがデフォルト — 特別なフラグは不要です。
9. 書き込み操作には --allow-writes が必須 — ユーザーに確認が必須です。
10. DELETE は常にブロック — ユーザーにこれがサポートされていないことを通知します。
11. 403は自動再認証をトリガー — ツールが追加スコープをリクエストして再試行します（委任認証のみ）。
12. すべての出力はJSON — レスポンスの statusCode と body フィールドをパースします。

エラー処理

ステータス	意味	アクション
401	トークンの有効期限切れ	msgraph auth signin を再度実行
403	権限不足	ツールが段階的な同意で自動的に再試行します。失敗する場合、ユーザーに管理者の同意が必要です。
404	リソースが見つからない	エンドポイントパスを確認
429	レート制限	Retry-After期間待機してから再試行

環境変数

変数	説明	デフォルト
MSGRAPH_CLIENT_ID	カスタムEntra IDアプリクライアントID	Microsoft Graph CLI Toolsアプリ
MSGRAPH_TENANT_ID	ターゲットテナントID（アプリのみ認証に必須）	common
MSGRAPH_API_VERSION	デフォルトAPIバージョン	beta
MSGRAPH_INDEX_DB_PATH	OpenAPIインデックスデータベースへのパス	自動検出
MSGRAPH_SAMPLES_DB_PATH	サンプルインデックスデータベースへのパス	自動検出
MSGRAPH_API_DOCS_DB_PATH	APIドキュメントインデックスデータベースへのパス	自動検出
MSGRAPH_NO_TOKEN_CACHE	永続的なトークンキャッシュを無効化（メモリのみ）	false

認証環境変数の完全なリストについては、references/docs/authentication.md を参照してください。

互換性

検索ツールは完全オフラインで実行され、ネットワークアクセスは不要です。直接API実行には login.microsoftonline.com と graph.microsoft.com へのネットワークアクセスが必要です。システムブラウザはインタラクティブ認証に使用されます。ヘッドレス環境ではデバイスコードフローにフォールバックします。

リファレンス ファイル

特定のガイダンスが必要な場合に、オンデマンドでこれらを読み込みます。事前に読み込まないでください。

ファイル	読むべき時	サイズ
references/REFERENCE.md	一般的なリソースパス、ODataパターン、権限スコープ	~230行
references/docs/authentication.md	詳細な認証設定: 証明書、マネージド ID、ワークロード ID、すべての環境変数	~200行
references/docs/query-parameters.md	OData $select、$filter、$expand、$top、$orderby、$search構文と注意点	~300行
references/docs/advanced-queries.md	ConsistencyLevelヘッダー、$count、$search、ディレクトリオブジェクトに対するne/not/endsWith	~190行
references/docs/paging.md	@odata.nextLinkページング、サーバーサイド vs クライアントサイドページング	~50行
references/docs/batching.md	$batchエンドポイント、複数リクエストの結合、dependsOnシーケンシング	~280行
references/docs/throttling.md	429処理、Retry-After、バックオフ戦略	~90行
references/docs/errors.md	HTTPステータスコード、エラーレスポンス形式、エラーコード	~105行
references/docs/best-practices.md	パフォーマンスのための$select、ページング、デルタクエリ、バッチ処理	~155行