Microsoft Cloud API Skills - Agent Context

Note: This document is the master design specification for human maintainers. For the machine-readable agent contract, see AGENTS.md in the repository root.

Project Objective

This project provides a modular package of reusable skills for working with different Microsoft cloud service APIs. The goal is to generalize and abstract the connection patterns, authentication flows, and API interaction models observed across diverse Microsoft cloud automation scenarios into a cohesive, reusable toolkit.

Core Principle: No secret material is embedded in any skill. All skills require explicit secret management through the approved hierarchy, with clear prerequisites documented per skill.

Scope and Service Coverage

Modular Skill Architecture

Each skill is designed as an independent, composable unit following PowerShell module conventions (where applicable) or script-based wrappers:

.
├── skills/
│   ├── Common.psm1                       # Shared auth, REST, pagination, endpoint resolution
│   ├── graph/
│   │   ├── SKILL.md                      # Graph-specific patterns, toolchain, examples
│   │   ├── Connect-GraphApi.ps1
│   │   ├── Invoke-GraphRequest.ps1
│   │   └── auth/
│   ├── azure/
│   │   ├── SKILL.md                      # ARM-specific patterns, async ops, examples
│   │   ├── Connect-AzureApi.ps1
│   │   ├── Invoke-AzureRestMethod.ps1
│   │   └── auth/
│   ├── dataverse/
│   │   ├── SKILL.md                      # OData, GDS, file ops, examples
│   │   ├── Connect-DataverseApi.ps1
│   │   ├── Invoke-DataverseRequest.ps1
│   │   ├── Get-DataverseEnvironment.ps1
│   │   └── auth/
│   ├── powerplatform/
│   │   ├── SKILL.md                      # BAP API, ARM token, examples
│   │   ├── Connect-PowerPlatformApi.ps1
│   │   └── Get-PowerPlatformEnvironment.ps1
│   ├── copilotstudio/
│   │   ├── SKILL.md                      # Dataverse bot entity, knowledge sources, examples
│   │   ├── Deploy-CopilotAgent.ps1
│   │   ├── Get-CopilotAgentInfo.ps1
│   │   └── Manage-CopilotKnowledge.ps1
│   ├── sentinel/
│   │   ├── SKILL.md                      # ARM management plane, incidents, alert rules
│   │   ├── Invoke-SentinelArmRequest.ps1
│   │   ├── Get-SentinelIncident.ps1
│   │   └── Get-SentinelAlertRule.ps1
│   ├── loganalytics/
│   │   ├── SKILL.md                      # KQL, workspace lifecycle, DCE/DCR, ingestion fallback
│   │   ├── Connect-LogAnalyticsApi.ps1
│   │   ├── Invoke-LogAnalyticsKqlQuery.ps1
│   │   ├── New-LogAnalyticsWorkspace.ps1
│   │   ├── New-LogAnalyticsCustomTable.ps1
│   │   ├── New-LogAnalyticsIngestionPipeline.ps1
│   │   ├── Send-LogAnalyticsData.ps1
│   │   └── auth/
│   ├── teams/
│   │   ├── SKILL.md                      # Graph v1.0 patterns, examples
│   │   ├── Get-TeamsChannel.ps1
│   │   ├── Get-TeamsMember.ps1
│   │   └── Invoke-TeamsGraphRequest.ps1
│   ├── intune/
│   │   ├── SKILL.md                      # v1.0 vs beta, list-vs-get, examples
│   │   ├── Get-IntuneDevice.ps1
│   │   ├── Get-IntuneConfigurationPolicy.ps1
│   │   └── Invoke-IntuneGraphRequest.ps1
│   ├── vm-guest-management/
│   │   ├── SKILL.md                      # Run Command, Bastion, SSH patterns
│   │   ├── Invoke-VmRunCommand.ps1
│   │   ├── Connect-VmBastionSsh.ps1
│   │   ├── Invoke-VmSshKeyRotation.ps1
│   │   └── Configure-VmSshServer.ps1
│   ├── sharepoint-online/                # Gap — directory placeholder only
│   │   └── SKILL.md                      # SharePoint Online gap documentation
│   ├── powerplatform/                    # Covered
│   └── copilotstudio/                    # Covered
├── prerequisites/
│   ├── Setup-AuthenticationContext.ps1   # Guided auth method detection and setup
│   ├── Install-RequiredModules.ps1       # Az, Microsoft.Graph, etc.
│   └── Test-Prerequisites.ps1            # Verify environment readiness
├── docs/
│   ├── auth-patterns.md                  # Decision matrix for auth method selection
│   ├── environment-endpoints.md          # Commercial vs Gov vs China endpoint mapping
│   ├── secret-management.md              # Secret hierarchy and configuration guidance
│   ├── token-chaining.md                 # Cross-platform token chaining patterns and examples
│   ├── patterns-and-caveats.md           # Observed patterns, lessons learned, and edge cases
│   ├── multi-tenant-auth.md              # Multi-tenant and multi-context authentication guidance
│   ├── project-positioning.md            # Ecosystem positioning and unique value proposition
│   ├── competitive-landscape.md          # Competitor and alternative analysis
│   └── future-considerations.md          # Optional integration opportunities (not in scope)
├── .env.example                          # Environment variable template with multi-tenant prefixes
├── config.example.yaml                   # Example multi-tenant configuration file
├── README.md                             # Project overview, quickstart, file map
└── agents.md                             # This file — master index and design specification

Authentication Hierarchy

All skills enforce this preference order. See docs/auth-patterns.md for the full decision matrix.

Interactive authentication (device code flow, browser login) is not permitted for skill execution.

Normalized Authentication Parameter Set

All Connect-* functions expose a consistent parameter set. See docs/auth-patterns.md for the full contract.

Multi-Tenant Authentication

Skills support multiple Entra ID tenants via:

• Centralized config file: config.yaml with named profiles + -Profile parameter
• Prefixed environment variables: PROD_TENANT_ID, GOV_CLIENT_ID, etc. + -Prefix parameter

See docs/multi-tenant-auth.md for full guidance.

Documented Gaps

These service domains are scoped but not yet implemented in this PowerShell toolkit. However, dedicated MCP servers now exist for each gap — see docs/future-considerations.md for a comprehensive catalog.

Commands

# Install prerequisites
./prerequisites/Install-RequiredModules.ps1

# Verify environment
./prerequisites/Test-Prerequisites.ps1

# Import service modules with conflict-aware ordering (recommended before using multiple Microsoft modules)
./prerequisites/Import-ConflictSafeModules.ps1

# Run smoke tests (no live auth required)
./prerequisites/Test-Smoke.ps1

# Run token validation tests (audience mismatches, expiry)
./prerequisites/Test-TokenValidation.ps1

# Load .env file (optional)
Import-Module ./skills/Common.psm1
Load-DotEnv -Path "./.env"

# Auto-detect authentication
$authContext = ./prerequisites/Setup-AuthenticationContext.ps1 -Resource "https://management.azure.com/"

# Example: Connect to Graph with explicit parameters
./skills/graph/Connect-GraphApi.ps1 -AuthenticationType ManagedIdentity -Environment AzureCloud

# Example: Connect to Graph with a config profile
./skills/graph/Connect-GraphApi.ps1 -Profile "prod" -ConfigPath "./config.yaml"

# Example: Connect to Graph with prefixed environment variables
./skills/graph/Connect-GraphApi.ps1 -Prefix "GOV" -Environment AzureUSGovernment

Standardized Context Object

All Connect-* scripts return a plain hashtable with these keys:

Service-specific additions:

• Azure ARM: SubscriptionId, ArmEndpoint
• Dataverse: EnvironmentUrl
• Power Platform: BapEndpoint

Downstream skill scripts accept this context via -AuthContext (or -Context for service-specific wrappers) and validate required fields before use.

Stack

• PowerShell (primary skill language)
• Python (auxiliary scripts, certificate handling, token decoding)
• Bicep / Azure CLI (Azure deployment skills)

Documentation Index