How to use the Azure Architecture Autopilot agent skill

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

An agent skill is a folder of instructions and supporting files that an AI agent loads when your request matches the skill's purpose. This skill is described as a pipeline. It either designs a new Azure architecture or analyses existing resources, then moves through modification, code generation and deployment in stages.

Each stage is described in a separate reference file that the agent follows. The stages cover scanning existing resources, interactive design, Bicep generation, Bicep review and deployment.

• Designs Azure infrastructure from a natural-language request, such as a RAG or AI platform.
• Scans an existing resource group and draws a diagram of it.
• Produces an interactive HTML architecture diagram using bundled Python scripts (scripts/cli.py), with refinement through conversation.
• Generates Bicep templates, reviews them and checks compilation.
• Runs validate, what-if and deploy steps, with a what-if check before deployment.

Install the azure-architecture-autopilot skill

Download the skill as a ZIP from the directory page and unzip it. Place the folder in one of two locations, depending on whether you want it available everywhere or only in one project.

For a personal install across projects, unzip it into ~/.claude/skills/. For a project-only install, unzip it into the .claude/skills/ folder inside that project.

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

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check the requirements before you start

The skill depends on several tools. Scanning and deployment need an Azure subscription and the Azure CLI, so check these first. Diagram generation runs through Python scripts, so Python 3 must be available.

The agent also needs access to Microsoft Learn documentation pages through web_fetch, and an environment that provides web_fetch, web_search, ask_user and PowerShell tools. The skill notes that az, python and bicep are often not on the PATH, so the agent looks for them on disk.

• Python 3 (for scripts/cli.py)
• Azure CLI (az), signed in to an Azure subscription for scanning and deployment
• Bicep CLI for compilation checks
• Access to Microsoft Learn pages fetched via web_fetch
• An agent environment providing web_fetch, web_search, ask_user and PowerShell

How to trigger the skill with natural requests

You do not need a special command. Describe what you want in plain language and the agent decides which path to follow. Requests to create something lead to a new design. Requests to analyse or draw a diagram of existing resources lead to a scan first.

If it is unclear which path you want, the agent asks you directly with a choice between designing a new architecture and analysing and modifying existing resources.

• "Create a RAG architecture on Azure" (new design)
• "Set up a RAG architecture" (new design)
• "Analyze my current Azure infrastructure" (existing analysis)
• "Draw a diagram for rg-xxx" (existing analysis, using your resource group name)
• "I want to reduce costs" or "Strengthen security" (modifying an existing design)

Walk through a typical new design

For a new design, the agent first collects your requirements and produces an interactive diagram in Phase 1. You review and confirm it. Only after the diagram has been shown and you have confirmed it does the agent generate Bicep code.

Phase 2 generates the Bicep templates, Phase 3 reviews them and checks compilation, and Phase 4 runs validate, then what-if, then deploy. The skill says not to skip phases, especially the what-if step between Phase 3 and Phase 4.

• Phase 1: interactive design and diagram, confirmed by you
• Phase 2: Bicep generation
• Phase 3: code review and compilation verification
• Phase 4: validate, what-if, then deploy

Analyse and modify existing resources

For an existing environment, the agent scans resources first (Phase 0), infers relationships between them and draws a diagram. It then asks what you would like to change. Your modification request goes to Phase 1, which confirms the changes and updates the diagram, before Phases 2 to 4 follow.

If you request changes after a deployment, the agent returns to Phase 1 rather than the scan step.

• Phase 0: scan existing resources, infer relationships and draw the diagram
• Describe the change you want in natural language
• Phase 1: confirm modifications and update the diagram
• Phases 2 to 4: generate, review and deploy

Safety notes: scripts and network use

This skill runs scripts and uses the network. The agent executes Azure CLI commands that can create or change billable resources. The skill's own guidance is that production deployments need a human to review the Bicep and the what-if output before anything is created.

The diagram engine is bundled inside the skill's scripts/ folder and, according to the skill, needs no pip install and no network access to generate diagrams. Documentation lookups for Azure services do use the network through web_fetch.

• Review the Bicep code and the what-if output yourself before approving deployment.
• Scanning and deployment act on your Azure subscription through the az CLI.
• Only use it with a subscription you are allowed to change, since deployments create billable resources.
• Diagram generation runs bundled Python scripts; read scripts/cli.py if you want to inspect them.

Tips for better results

Give the agent concrete requirements. The skill is strongest on RAG, AI and data platforms such as Microsoft Foundry, Azure OpenAI, AI Search, ADLS Gen2, Key Vault, Microsoft Fabric and Azure Data Factory. Other Azure services are also supported, with documentation looked up as needed.

Name the resource group when you want an analysis, so the scan targets the right resources. Review each diagram before you move on, because Bicep is only generated after you confirm the design.

• State the workload, for example a RAG system or a data platform.
• Name the resource group (for example rg-xxx) for scans.
• Confirm the diagram before asking for Bicep.
• Ask for a specific change in plain words, such as cost or security.