/microsoft-graph-gateway

Microsoft Graph Gateway

Use this skill as the orchestration shell for Microsoft Graph work in this workspace.

This skill does not try to abstract all of Microsoft Graph into a fixed checklist. Instead, it does two things:

1. Route common read requests to the right source.
2. Enforce safe execution rules before Graph writes or advanced reads.

When To Use

• The user wants to read or write Microsoft 365 data from VS Code.
• The request mentions mail, email, inbox, Outlook, meetings, calendar, contacts, OneDrive, SharePoint, Teams, Planner, To Do, users, groups, or Microsoft Graph.
• The user wants an exact Microsoft Graph endpoint, permission, query option, or payload.
• WorkIQ can likely answer a common read request, but Graph may be needed as a fallback.

Routing Rules

Read Routing

• Prefer WorkIQ first for common read scenarios such as inbox checks, meeting lookups, file discovery, and lightweight summaries.
• Use Microsoft Graph for gap-read scenarios when WorkIQ cannot answer, returns insufficient detail, or the user asks for exact Graph semantics.
• Go straight to Microsoft Graph when the user asks for:
  • exact endpoint names or raw REST calls
  • precise properties, $select, $filter, $expand, or API version control
  • Teams, Planner, To Do, directory, or permission-oriented data
  • schema, permission, throttling, batching, delta, or webhook behavior

Write Routing

• Use Microsoft Graph for all writes.
• Treat send, create, update, move, upload, reply, assign, and respond operations as writes.
• Require explicit confirmation before any write.
• Keep delete actions disabled by default or behind a stronger confirmation step.

Operating Model

• This skill is a thin shell.
• The execution substrate can be a Graph CLI, a self-hosted MCP server, or another Graph gateway.
• Do not invent endpoints or permissions from memory when an authoritative lookup is available.
• Keep delegated and application permission flows separate.
• Prefer least-privileged scopes and minimal projections.

Procedure

1. Classify the request as common read, gap-read, or write.
2. For common read, try the WorkIQ route first.
3. For gap-read or write, identify the target Microsoft Graph surface.
4. Check the capability, routing, and substrate references before choosing the execution path.

• raw execution contract
• permission profiles
• curated tool catalog

5. For Microsoft Graph execution, determine:
   • resource area
   • endpoint or tool
   • API version
   • least-privileged permission profile
   • minimal response shape
6. Before any write, present a concise confirmation summary covering target, action, and payload intent.
7. Execute through the chosen substrate.
8. Report the result, including any permission, throttling, or follow-up concerns.

Script Entry Points

• Use Invoke-GraphGateway.ps1 for raw Graph execution through the selected substrate.
• Use invoke-graph-gateway.sh on macOS or Linux when pwsh is installed.
• Use New-GraphWriteConfirmation.ps1 to generate a concise write confirmation summary before execution.
• Use Test-GraphGatewayScaffold.ps1 to smoke-test the current scaffold without live Graph execution.
• Use test-graph-gateway-scaffold.sh on macOS or Linux when pwsh is installed.
• Use Get-GraphGatewayRunnerStatus.ps1 to inspect runner discovery and auth readiness.
• Use get-graph-gateway-runner-status.sh on macOS or Linux when pwsh is installed.
• Use Install-MsGraphRunner.ps1 to bootstrap the preferred merill/msgraph runner into the workspace when you explicitly want local setup.
• Use New-GraphEventResponseRequest.ps1 to generate accept, decline, and tentative meeting-response requests.
• Use New-GraphGatewayAppConfig.ps1 to generate environment snippets for a tenant-approved custom app registration.

Example Assets

• Read Mail Request
• Send Mail Request
• List Events Request
• Create Event Request
• Accept Event Request
• Decline Event Request
• Tentative Event Request
• Custom App Env Example

Done Criteria

• The request was routed to WorkIQ or Microsoft Graph for an explicit reason.
• Graph calls used least-privileged intent and minimal response shape where practical.
• Writes were confirmed before execution.
• Deletes were blocked or separately escalated.
• The response states what happened and any remaining risk or next action.

References

• Capability Matrix
• Routing And Safety
• Substrate Selection
• Raw Execution Contract
• Permission Profiles
• Curated Tools First Wave
• Environment Setup
• Prerequisites
• Troubleshooting