azure-policy

name	azure-policy
description	Expert knowledge for Azure Policy development including troubleshooting, best practices, decision making, architecture & design patterns, security, configuration, integrations & coding patterns, and deployment. Use when authoring JSON policies, Machine Config, DevOps policy-as-code, Terraform/Gatekeeper, or CI/CD governance, and other Azure Policy related development tasks. Not for Azure Blueprints (use azure-blueprints), Azure Resource Manager (use azure-resource-manager), Azure Role-based access control (use azure-rbac), Azure Security (use azure-security).
compatibility	Requires network access. Uses mcp_microsoftdocs:microsoft_docs_fetch or fetch_webpage to retrieve documentation.
metadata	{"generated_at":"2026-08-09","generator":"docs2skills/1.0.0"}

Azure Policy Skill

This skill provides expert guidance for Azure Policy. Covers troubleshooting, best practices, decision making, architecture & design patterns, security, configuration, integrations & coding patterns, and deployment. It combines local quick-reference content with remote documentation fetching capabilities.

How to Use This Skill

IMPORTANT for Agent: Use the Category Index below to locate relevant sections. For categories with line ranges (e.g., L35-L120), use read_file with the specified lines. For categories with file links (e.g., [security.md](security.md)), use read_file on the linked reference file

IMPORTANT for Agent: If metadata.generated_at is more than 3 months old, suggest the user pull the latest version from the repository. If mcp_microsoftdocs tools are not available, suggest the user install it: Installation Guide

This skill requires network access to fetch documentation content:

• Preferred: Use mcp_microsoftdocs:microsoft_docs_fetch with query string from=learn-agent-skill. Returns Markdown.
• Fallback: Use fetch_webpage with query string from=learn-agent-skill&accept=text/markdown. Returns Markdown.

Category Index

Category	Lines	Description
Troubleshooting	L36-L42	Diagnosing and fixing Azure Policy non-compliance, Machine Configuration deployment issues, and common policy/SDK errors (evaluation failures, assignment problems, and API/CLI issues).
Best Practices	L43-L50	Best practices for safely testing and deploying Azure Policy and Machine/Guest Configuration, including PSDSC behavior changes, impact evaluation, and safe rollout strategies.
Decision Making	L51-L58	Guidance on planning migrations from DSC/Automanage to Machine Configuration/Azure Policy and choosing recommended policy definitions for managing and securing VMs.
Architecture & Design Patterns	L59-L63	Designing Azure Policy-as-Code workflows, integrating with CI/CD, GitOps, and approvals, and structuring policy repos, environments, and automation for scalable governance.
Security	L64-L168	Security and compliance baselines with Azure Policy: mapping to standards (CIS, NIST, ISO, FedRAMP, PCI, etc.), machine/guest config baselines, and enforcing MFA and signed configurations.
Configuration	L169-L208	Designing, assigning, and managing Azure Policy and Machine Configuration: JSON structures, effects, guest config packages, compliance data, remediation, tags, identities, and exemptions.
Integrations & Coding Patterns	L209-L238	Patterns for writing reusable Azure Policy definitions (operators, fields, effects, tags, initiatives) and integrating/automating them via Terraform, Kubernetes/Gatekeeper, VS Code, Event Grid, and Resource Graph
Deployment	L239-L249	How to deploy and assign Machine Configuration packages via ARM/Bicep/Terraform/REST, publish them to storage, export policy for policy-as-code, and enforce Azure Policy in DevOps pipelines

Troubleshooting

Topic	URL
Troubleshoot Azure Machine Configuration deployments	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/overview/04-operations-troubleshooting
Diagnose causes of Azure Policy non-compliance	https://learn.microsoft.com/en-us/azure/governance/policy/how-to/determine-non-compliance
Troubleshoot common Azure Policy errors and SDK issues	https://learn.microsoft.com/en-us/azure/governance/policy/troubleshoot/general

Best Practices

Topic	URL
Test Machine Configuration packages with GuestConfiguration tools	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/3-test-package
Understand PSDSC behavior changes in Machine Configuration	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/whats-new/psdsc-in-machine-configuration
Evaluate impact before deploying new Azure policies	https://learn.microsoft.com/en-us/azure/governance/policy/concepts/evaluate-impact
Apply safe deployment practices to Azure Policy	https://learn.microsoft.com/en-us/azure/governance/policy/how-to/policy-safe-deployment-practices

Decision Making

Topic	URL
Plan migration from Azure Automation DSC to Machine Configuration	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/whats-new/migrating-from-azure-automation
Plan migration from DSC extension to Machine Configuration	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/whats-new/migrating-from-dsc-extension
Select recommended Azure Policy definitions for VMs	https://learn.microsoft.com/en-us/azure/governance/policy/concepts/recommended-policies
Plan migration from Automanage Best Practices to Azure Policy	https://learn.microsoft.com/en-us/azure/governance/policy/how-to/migrate-from-automanage-best-practices

Architecture & Design Patterns

Topic	URL
Design Azure Policy as Code governance workflows	https://learn.microsoft.com/en-us/azure/governance/policy/concepts/policy-as-code

Security

Topic	URL
Deploy Machine Configuration security baseline policies	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-security-baselines/deploy-a-baseline-policy-assignment
Customize Machine Configuration security baseline parameters	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-security-baselines/specify-custom-parameters-for-baseline-policy
Author JSON parameters for Machine Configuration baselines	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-security-baselines/understand-baseline-settings-parameter
Sign Machine Configuration packages and enforce signed content	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/6-sign-package
Use regulatory compliance initiatives in Azure Policy	https://learn.microsoft.com/en-us/azure/governance/policy/concepts/regulatory-compliance
Map Azure Policy to Australian ISM PROTECTED	https://learn.microsoft.com/en-us/azure/governance/policy/samples/australia-ism
Map Azure Policy to Australian ISM PROTECTED	https://learn.microsoft.com/en-us/azure/governance/policy/samples/australia-ism
Azure Policy mappings for Microsoft cloud security benchmark	https://learn.microsoft.com/en-us/azure/governance/policy/samples/azure-security-benchmark
Azure Policy mappings for Microsoft cloud security benchmark	https://learn.microsoft.com/en-us/azure/governance/policy/samples/azure-security-benchmark

Configuration

Topic	URL
Understand Machine Configuration assignment resources and metadata	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/concepts/assignments
Assign built-in Machine Configuration policies	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-built-in-policies
Create custom Machine Configuration policy definitions	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/create-policy-definition
Install GuestConfiguration authoring module for Machine Configuration	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/1-set-up-authoring-environment
Create custom Machine Configuration package artifacts	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/2-create-package
Configure access to Machine Configuration packages in Azure Storage	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/5-access-package
Develop custom Machine Configuration packages	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/overview
View and analyze Machine Configuration compliance results	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/view-compliance
Configure prerequisites for Azure Machine Configuration	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/overview/02-setup-prerequisites

Integrations & Coding Patterns

Topic	URL
Assign Azure Policy using Terraform HCL	https://learn.microsoft.com/en-us/azure/governance/policy/assign-policy-terraform
Integrate Azure Policy events with Event Grid	https://learn.microsoft.com/en-us/azure/governance/policy/concepts/event-overview
Use Azure Policy with Kubernetes via Gatekeeper	https://learn.microsoft.com/en-us/azure/governance/policy/concepts/policy-for-kubernetes
Use Azure Policy VS Code extension for aliases	https://learn.microsoft.com/en-us/azure/governance/policy/how-to/extension-for-vscode
Use the count operator in Azure Policy definitions	https://learn.microsoft.com/en-us/azure/governance/policy/samples/pattern-count-operator
Use the count operator in Azure Policy definitions	https://learn.microsoft.com/en-us/azure/governance/policy/samples/pattern-count-operator
Deploy resources with deployIfNotExists Azure Policy	https://learn.microsoft.com/en-us/azure/governance/policy/samples/pattern-deploy-resources
Deploy resources with deployIfNotExists Azure Policy	https://learn.microsoft.com/en-us/azure/governance/policy/samples/pattern-deploy-resources
Apply different effects in Azure Policy definitions	https://learn.microsoft.com/en-us/azure/governance/policy/samples/pattern-effect-details
Apply different effects in Azure Policy definitions	https://learn.microsoft.com/en-us/azure/governance/policy/samples/pattern-effect-details
Use field properties in Azure Policy definitions

Deployment

Topic	URL
Deploy Machine Configuration assignments with ARM templates	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-configuration/azure-resource-manager
Deploy Machine Configuration assignments with Bicep	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-configuration/bicep
Assign Machine Configuration packages using templates	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-configuration/overview
Create Machine Configuration assignments using REST API	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-configuration/rest-api
Deploy Machine Configuration assignments using Terraform	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-configuration/terraform
Publish Machine Configuration packages to Azure storage	https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/4-publish-package
Export Azure Policy resources for policy-as-code	https://learn.microsoft.com/en-us/azure/governance/policy/how-to/export-resources
Enforce Azure Policy in Azure DevOps pipelines	https://learn.microsoft.com/en-us/azure/governance/policy/tutorials/policy-devops-pipelines