How to use the Azure Deployment Preflight agent skill

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file and optional reference files. When you install one, an AI agent such as Claude can load its instructions and follow them when a task matches the skill's description. This skill is for work that involves deploying Bicep templates to Azure.

When activated, the agent follows a fixed process. It detects whether your project uses the Azure Developer CLI (azd) or the Azure CLI (az), finds your .bicep files, checks their syntax with the Bicep CLI, and runs a what-if preview. It then writes a preflight-report.md file in your project root summarising the issues, the planned changes and recommended next steps.

• Checks Bicep syntax with the Bicep CLI
• Previews creates, changes and deletes with what-if or azd provision --preview
• Checks permissions and falls back to ProviderNoRbac validation if RBAC errors occur
• Writes preflight-report.md to the project root

Install the Azure Deployment Preflight skill

Download the ZIP for the azure-deployment-preflight skill from this page and unzip it. For a personal setup, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder so it applies only there.

If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/azure-deployment-preflight
• Project install: .claude/skills/azure-deployment-preflight inside your project
• Claude apps: Settings → Capabilities → Skills

Install the tools the skill needs

The skill runs real Azure and Bicep commands, so those tools must be installed on your machine first. Check each one from a terminal. The skill recommends Azure CLI 2.76.0 or newer for the --validation-level option. You also need an Azure login with access to the target subscription or resource group.

Azure MCP Tools are optional and are used only for documentation lookups.

• Azure CLI (az), version 2.76.0 or newer recommended
• Azure Developer CLI (azd), needed only for projects with azure.yaml
• Bicep CLI (bicep)
• An Azure login: az login or azd auth login
• Optional: Azure MCP Tools

How to trigger the skill with natural requests

You do not need a special command. Describe what you are about to do, and the agent will match your request against the skill's description. The skill activates when you mention deploying to Azure, validating Bicep files, checking deployment permissions, previewing infrastructure changes, running what-if, or preparing for azd provision.

Be specific about the file or environment when you can. If the agent cannot find a resource group, subscription, location or environment, it will ask you before continuing.

• "Validate my Bicep deployment before I run it"
• "Run what-if on infra/main.bicep against my dev resource group"
• "Check whether I have permission to deploy this template"
• "Preview the infrastructure changes before azd provision"

Example: preflight before azd provision

Suppose your project has an azure.yaml file and infra/main.bicep. You ask the agent to validate the deployment. The skill detects the azd project, finds the Bicep files, runs bicep build on the template and then runs a preview with azd provision --preview. If you have more than one environment, the agent specifies one with --environment.

When it finishes, open preflight-report.md in your project root. It lists the syntax results, the resources to be created, changed or deleted, and the recommended next steps.

Example: standalone Bicep with az deployment group

If the project has no azure.yaml, the skill picks the az deployment command from the targetScope declaration in your Bicep file. For a resource group scope, it runs what-if with the Provider validation level first. If that fails because of RBAC permission errors, it retries with ProviderNoRbac and notes the fallback in the report.

Replace the placeholders with your own values. The skill asks you for these details if it does not have them.

• Resource group scope uses az deployment group what-if
• Subscription scope uses az deployment sub what-if
• Management group scope uses az deployment mg what-if
• Tenant scope uses az deployment tenant what-if

Safety notes: scripts and network access

This skill runs scripts and uses the network. The commands it runs talk to your live Azure subscription. Validation is designed to report, not to deploy or fix resources, but running the underlying Azure commands against a live subscription can still have side effects on your account.

Review what the agent plans to run before you approve it, especially if you are working against a production subscription. Use a non-production resource group or environment when you can.

• The skill runs scripts and makes network calls to Azure
• It only validates and reports; it does not intentionally deploy or repair resources
• Underlying Azure commands can still affect your account, so check the target first

Tips for getting useful results

Keep your parameter files next to the Bicep templates so the skill can find them automatically. It looks for a matching .bicepparam file, a .parameters.json file, or parameters.json in the same directory.

Read the Issues and What-If sections of the report before running a real deployment. If the report says it fell back to ProviderNoRbac, your account may lack full deployment permissions, so the preview may be less complete.

• Name parameter files to match the Bicep file, such as main.bicepparam beside main.bicep
• Use azd env list to see which environments exist
• Fix Issues in the report and re-run the preview before deploying