Source: microsoft/azure-skills · Maintainer: Microsoft · License: MIT · Checked: 24 October 2026
What is the Azure diagnostics skill?
The Azure diagnostics skill teaches a coding agent how to troubleshoot Azure production problems in a fixed order: symptoms, resource health, logs, metrics, then recent changes. It is for developers and on-call engineers who run apps on Azure Container Apps, App Service, Functions, AKS or virtual machines and want the agent to gather evidence before it guesses.
Its description reads: "Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage." It then lists triggers such as app service high CPU, container app 503 or target port mismatch, pod pending, crashloop, VM RDP and SSH failures, KQL, and Service Bus dead letters.
It ships in microsoft/azure-skills, the Azure Skills Plugin, which the README groups under "Troubleshoot, monitor, and govern." The README says the repo is synced automatically from microsoft/GitHub-Copilot-for-Azure. The SKILL.md frontmatter lists version 1.2.11 and author Microsoft.
As of 24 October 2026, its skills.sh page listed about 567,600 installs (snapshot, 24 October 2026).
What does it do?
The SKILL.md sets nine rules and a five-step flow, then routes each service to its own guide.
Key rules:
- Start with a systematic diagnosis flow.
- Use supplied evidence first. If you ask for evidence-only analysis or forbid live access, don't query or modify Azure.
- Use AppLens through MCP when available, and check resource health before digging into logs.
- Prefer the bundled diagnostic scripts over ad hoc calls when identifiers are known and live collection is allowed.
- Document findings and the remediation steps tried.
The quick diagnosis flow: identify symptoms, check resource health, review logs, analyze metrics, investigate recent changes.
Guides by service:
| Service | Common issues covered |
|---|---|
| Container Apps | Image pull failures, cold starts, health probes, port mismatches |
| App Service | High CPU, deployment failures, crashes, slow responses, TLS and custom domains |
| Function Apps | Invocation failures, timeouts, binding errors, cold starts, missing app settings |
| AKS | Cluster access, nodes, kube-system, scheduling, crash loops, ingress, DNS, upgrades |
| Virtual machines | RDP and SSH connectivity, NSG or firewall blocks, credential resets, VM agent issues |
| Messaging | Event Hubs and Service Bus SDK errors, AMQP failures, message locks |
The folder holds about 54 files: the guides, a KQL query library (recent errors, failed requests, slow requests, dependency failures), Azure Resource Graph queries, and paired Bash and PowerShell scripts such as containerapp-diagnostics, appservice-diagnostics, aks-baseline, pod-evidence and test-messaging-connectivity. The Container Apps script's header says it "only gathers and labels output; it does not interpret the results."
The MCP calls it names map to tools in the Azure MCP Server, whose tool list includes Azure App Lens ("Diagnose and analyze application performance issues"), Azure Monitor ("Query Azure Monitor logs and metrics") and Azure Resource Health ("Check availability status, view health events, and track service-impacting issues"). Without MCP, it falls back to Azure CLI commands such as az monitor activity-log list and az containerapp logs show.
How do you install the Azure diagnostics skill?
The repo README documents these routes.
Claude Code: the Azure Skills Plugin. Run inside Claude Code:
/plugin install azure@claude-plugins-official
Or run /plugin and search for "azure". The plugin bundles all the Azure skills with the Azure MCP Server, which the README says gives agents "200+ structured tools across 40+ Azure services." Update with /plugin update azure@claude-plugins-official. See Claude Code plugins and Claude Code MCP.
GitHub Copilot CLI:
/plugin marketplace add microsoft/azure-skills
/plugin install azure@azure-skills
Codex and Cursor. The README says to run codex plugin marketplace add microsoft/azure-skills, then install azure from /plugins; for Cursor, use the Cursor Marketplace or Settings, then Plugins. See Codex skills and Cursor skills.
Skill only. The command on skills.sh:
npx skills add https://github.com/microsoft/azure-skills --skill azure-diagnostics
This copies the skill files but not the MCP configuration, so the agent falls back to Azure CLI unless you have set up the Azure MCP Server yourself; Microsoft Learn covers that.
Prerequisites, per the README: an Azure subscription, Node.js 18 or later for npx, and the Azure CLI signed in with az login.
How do you use it?
Describe the symptom and give identifiers if you have them: subscription, resource group, app or cluster name. The skill is model-invoked, so the agent can load it when you ask it to troubleshoot an Azure issue.
Example prompts (suggestions; the first is from the README's prompt list):
Troubleshoot why my container app is failing health probes.My App Service app in rg-prod has had high CPU since this morning's deploy. Find the cause.Pods in the payments namespace on aks-prod are stuck in Pending. Diagnose, read-only.I can't SSH into vm-build-01. Check NSG rules and the VM agent.Here are the Service Bus logs from last night. Explain the lock lost errors without querying Azure.
The last prompt uses the evidence-only rule: the agent works from what you paste and lists what it would verify live.
Tips and limits
From the repo and skills.sh, not from testing:
- Read-only by default, not read-only by design. The AKS and VM guides both say to default to read-only diagnostics, and the AKS guide says to keep its checks read-only "unless the user explicitly asks for remediation." The skill runs with your Azure credentials, so review any fix before approving it. Claude Code permissions can limit what runs without asking.
- It runs shell scripts. The bundled scripts call the Azure CLI and
kubectl. Read them before allowing them if your policy requires it. - AKS has an optional add-on. The rules mention an optional
aks-skillsadd-on and say baseline AKS diagnostics stay available without it. - The plugin adds telemetry hooks. The Azure plugin's Claude Code hooks run a telemetry script on session start and after tool use. The README says to set
AZURE_MCP_COLLECT_TELEMETRY=falseto opt out. - Sovereign clouds need extra setup. The README says the Azure MCP Server targets Azure Public Cloud by default, with steps for Azure China and Azure US Government.
- Security audits. On skills.sh, Gen Agent Trust Hub, Socket and Snyk all rated it Pass as of 24 October 2026.
The MIT License lets you copy and change the skill as long as you keep Microsoft's copyright notice.
Save it in your Kipt library
If you want your own edited copy, for example with your team's resource groups and runbook links added, Kipt can hold it. Open Skills and paste the skill's GitHub folder link into the import box, or drop the folder or a .zip. A copy carries the skill files and scripts only, not the plugin's MCP configuration or hooks. Skills in your private GitHub repo install into Claude Code or Codex with one command:
npx skills add https://github.com/<you>/<repo>.git --all -g
Kipt is not affiliated with Microsoft.
Similar skills
- Microsoft Foundry skill: Microsoft's skill for Foundry agents and models, from the same plugin, with its own troubleshoot sub-skill.
- Systematic debugging skill: the Superpowers root-cause process for any bug.
- Diagnosing bugs skill: Matt Pocock's approach to reproducing and fixing bugs.
- Kubernetes skill: generates Kubernetes manifests.
- Claude Code for DevOps: infrastructure and incident work with guardrails.