Skip to content
Get packs

Guide · Agent skill

How to use the Azure Well-Architected Review agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The azure-well-architected-review skill is a set of instructions that teaches an AI agent to run a structured Azure Well-Architected Framework review of your workload. It is useful for engineers and architects preparing an Azure project for production, or checking that code and live resources still match. After this guide you will know what the skill does, how to install it, how to trigger it with a plain request, and what it needs before it runs.

Azure Well-Architected Reviewgithub/awesome-copilot · MIT

Quick start

  1. 1Download and unzip the skill. Download the azure-well-architected-review ZIP from this page and unzip it, so the folder contains SKILL.md.
  2. 2Place the skill folder. Copy the folder to ~/.claude/skills/ for personal use, or to .claude/skills/ inside your project. You can also upload it under Settings → Capabilities → Skills in the Claude apps.
  3. 3Authenticate Azure CLI. Make sure the Azure CLI (az) is installed and signed in to the subscription you want reviewed, preferably with read-only access.
  4. 4Configure the GitHub MCP server. Set up and authenticate the GitHub MCP server so the agent can create issues if you approve them.
  5. 5Ask for a review in plain language. Request a Well-Architected review of the repository or a named resource group, and confirm the scope when the agent asks.
  6. 6Read the risk summary. Review the High, Medium and Low findings and the top high-risk items before deciding what to do.
  7. 7Confirm or decline issue creation. Answer yes only if you want GitHub issues created. Any other answer prints the findings to the console without creating issues.

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

An agent skill is a folder containing a SKILL.md file that gives an AI agent a repeatable workflow to follow when a matching request comes in. This skill, from the awesome-copilot collection on GitHub, is licensed under MIT.

When you ask the agent to review an Azure project, it follows a checklist built from Microsoft's Well-Architected Framework. The checklist covers five pillars: Reliability, Security, Cost Optimization, Operational Excellence and Performance Efficiency. The agent reads your Bicep, Terraform or ARM files, lists the Azure resources that actually exist using the Azure CLI, and flags gaps such as missing backups, open network rules, or resources created by hand in the portal.

  • Compares infrastructure-as-code files with live resources to find drift
  • Ranks each finding as High, Medium or Low risk
  • Can create GitHub issues to track remediation, with one issue per finding and an EPIC issue

Install the skill (ZIP download or Claude apps upload)

Download the ZIP of the skill from this page and unzip it. Then place the skill folder in one of these locations:

For a personal skill available across your projects, put it in ~/.claude/skills/. For a skill limited to one project, put it in the project's .claude/skills/ folder.

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

  • Personal: ~/.claude/skills/azure-well-architected-review/
  • Project: .claude/skills/azure-well-architected-review/
  • Claude apps: Settings → Capabilities → Skills

Set up the prerequisites

The skill depends on three things being in place before it starts. Without them the review cannot inventory your live environment or create issues.

  • Azure CLI (az) installed and authenticated
  • IaC files in the repository (Bicep, Terraform or ARM templates)
  • GitHub MCP server configured and authenticated
  • Optional: the microsoft.docs.mcp MCP server, which lets the agent query up-to-date Microsoft documentation
az login

How do you trigger the review with a natural request?

You do not need a special command. Describe what you want in plain language and mention Azure and a review, for example asking the agent to review the Azure architecture of the current project or to run a Well-Architected check on your Bicep files. The agent will confirm the subscription or resource group in scope before it starts.

Good requests name the scope. Saying which resource group to review helps the agent avoid inventorying unrelated resources.

  • Run an Azure Well-Architected review on this repository's Bicep files.
  • Check my Azure resource group rg-app-prod against the Well-Architected Framework and tell me what is risky.
  • Find drift between my Terraform code and what is deployed in Azure.

What happens during a review?

The agent works in steps. It first loads current Well-Architected guidance, then scans the repository for IaC files (Bicep, Terraform and ARM templates) and inventories live resources with az resource list. It compares the two to find drift, then checks each pillar against its checklist.

Each finding is classified as High Risk (security vulnerability, single point of failure, no backup or recovery), Medium Risk (suboptimal reliability, cost inefficiency, performance concern) or Low Risk (best practice deviation, minor optimization).

  • Step 1: Load Well-Architected reference guidance
  • Step 2: Discover IaC and architecture, and generate a Mermaid architecture diagram
  • Step 3: Review each pillar
  • Step 4: Classify risk
  • Step 5: Show a summary and ask for confirmation

Confirm before GitHub issues are created

The skill shows a summary with finding counts and the top high-risk items, then asks whether to create GitHub issues. It only proceeds on an explicit yes. Any other answer, or no answer, means no issues are created and the full findings are printed to the console instead.

Issues are titled in the form [WAF-PILLAR] Brief Finding — Risk Level and labelled with well-architected and the pillar name. Each issue includes a remediation section, with an IaC fix preferred where possible.

Safety notes: scripts and network access

This skill runs scripts and uses the network. It lists resources with the Azure CLI, calls Microsoft documentation sources, and can create GitHub issues through the GitHub MCP server. Run it with read-only Azure credentials where you can, and avoid production subscriptions unless you have reviewed what it will access.

Treat findings as a checklist, not an audit. The agent may miss issues or misjudge context, so it does not replace a professional security audit or a compliance certification.

  • Use read-only credentials for Azure, especially on production subscriptions
  • Review the summary before answering yes to issue creation
  • Check the GitHub repository before issues are created on it

What people use it for

  • Checking a new Azure workload for missing backups, open NSG rules or unencrypted endpoints before a production launch
  • Finding resources created manually in the portal that are not represented in Bicep or Terraform
  • Turning review findings into tracked GitHub issues grouped under an EPIC issue for the team to work through
  • Repeating the same checklist-based review over time to see whether an architecture is improving

Frequently asked questions

How do I install the azure-well-architected-review skill?

Download the ZIP from this page and unzip it. Put the azure-well-architected-review folder in ~/.claude/skills/ for personal use or in .claude/skills/ inside a project. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.

What do I need to run the Azure Well-Architected review skill?

You need the Azure CLI (az) installed and authenticated, IaC files in the repository (Bicep, Terraform or ARM templates), and the GitHub MCP server configured and authenticated. The microsoft.docs.mcp server is optional and provides up-to-date Microsoft documentation.

Is the Azure Well-Architected review skill free?

The skill is published under the MIT licence in the github/awesome-copilot repository. The page does not list pricing, and the Azure and GitHub services it uses have their own terms.

Does the skill work with Terraform and ARM templates, or only Bicep?

It scans for Bicep, Terraform and ARM template files. It also inventories live resources, so it can compare code with what is deployed.

Does this skill create GitHub issues automatically?

No. After the review it shows a summary and asks whether to create issues. It only creates them on an explicit yes. Otherwise it prints the findings to the console.

Can I use this skill on a project that is not hosted on Azure?

No. The checklist and Azure CLI commands are specific to Azure, so the skill is not suitable for projects hosted elsewhere.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits teams preparing an Azure workload for production, engineers who want to catch drift between Bicep or Terraform and live resources, and architects who want a repeatable checklist review. Pick something else if your project is not on Azure, or if you need a formal security audit or compliance certification, since the agent applies a checklist and can miss issues.

Download the skill