microsoft/azure-skills

What It Does

Microsoft's official Azure agent plugin, shipped as a hybrid pack: 28 top-level skills (38 SKILL.md files counting sub-skills) that teach a coding agent how Azure work gets done, plus MCP server configuration that wires the Azure MCP Server (npm @azure/mcp) into the host for live execution. The skills cover preparation, validation, deployment, diagnostics, cost, Kubernetes, storage, messaging, Kusto, Entra identity, and Microsoft Foundry, including nested sub-skills like the Foundry fine-tuning pipeline with offline data validators. The repo is an automated sync mirror of microsoft/GitHub-Copilot-for-Azure: bot commits push plugin files here, and contributions are directed upstream. It targets Claude Code, GitHub Copilot (CLI, VS Code, IntelliJ), Cursor, Codex CLI, Gemini CLI, and OpenCode via the APM installer.

The Good

Demand at a scale no other reviewed vendor pack reaches. The skills.sh API reports 40 registry entries under microsoft/azure-skills totaling 12,209,310 all-time installs: microsoft-foundry leads at 560,320, and 13 skills sit between 540,750 and 556K each (azure-diagnostics 553,657, azure-prepare 553,074, azure-ai 552,989). That is 12.2M installs against 1,434 stars and 242 forks, the widest absolute star-to-install gap GearScope has measured, ahead of prisma/skills (1.69M installs on 53 stars).

The verbatim-guide test passed on the first try, both directions. The finetuning sub-skill documents python scripts/validate/validate_sft.py data.jsonl, so we ran exactly that. On valid data: exit 0, "Data is valid for SFT fine-tuning!", with computed token statistics (avg 16, min 8, max 25). On malformed data (an invalid banana role, a non-JSON line, a missing messages field, an empty array): exit 1 with five line-level diagnostics, each naming the record, the message index, and the exact problem ("Invalid role 'banana' (expected: {'system', 'user', 'tool', 'assistant'})", "Line 3: Invalid JSON (Expecting value: line 1 column 1)"). The sibling data_stats.py also runs offline and prints role distributions. This is the strongest offline functional evidence a doc-heavy pack can produce.

The guidance layer is engineered, not prompted. Every skill frontmatter carries explicit routing ("USE ONLY when... DO NOT USE FOR... WHEN: ...") that names which sibling skill to defer to. Hard guardrails are concrete: azure-prepare forbids generating SQL Server administratorLogin credentials anywhere in Bicep, forbids deleting the user's workspace, and requires ask_user before destructive actions. A cross-skill file contract (.azure/deployment-plan.md, written by azure-prepare, consumed by azure-validate and azure-deploy) ties the pipeline together. Progressive disclosure is real: 5,081 lines across the 38 SKILL.md files (median 108) front 834 reference files totaling 80,512 lines, a 16:1 ratio.

Release discipline and version lockstep. 143 changelog entries with upstream PR links; the latest tag v1.2.36, the plugin.json version, the changelog head, and the version Claude Code reports after install all read 1.2.36. The npm runtime matches too: npm view @azure/mcp version and the MCP handshake serverInfo both report 3.0.0-beta.39.

Every install route tested worked, byte-identically. The README-verbatim npx skills add command landed all 28 skills into an isolated ~/.agents/skills, and recursive diffs against the clone were empty (including the whole microsoft-foundry sub-tree). The Claude flow (claude plugin marketplace add microsoft/azure-skills, then install) succeeded and reported v1.2.36 enabled, with 28 skills in the plugin cache. Both individual plugin manifests pass claude plugin validate --strict.

The Bad

Live skills still route to retired skills, 8 references across 3 skills. Upstream deliberately retired azure-rbac (PR #2779) and azure-hosted-copilot-sdk (PR #2556), per the changelog. But azure-prepare, the pack's third-most-installed skill (553,074 installs), still tells the agent to invoke azure-observability in four places in references/research.md (also retired) and azure-nodejs-production twice. azure-app-onboard's handoff protocol routes to azure-rbac, and both azure-app-onboard and its prereq skill route to azure-hosted-copilot-sdk. An agent following these references finds nothing to invoke.

Six stale registry entries totaling 1.26M installs point at skills that are gone. Cross-referencing all 40 skills.sh entries against the repo: azure-rbac (486,591 installs), azure-hosted-copilot-sdk (438,447), azure-cost-optimization (209,325), azure-observability (98,306), azure-postgres (27,848), plus five meta skills (sensei, skill-authoring, markdown-token-optimizer, file-test-bug, analyze-test-run, about 1K each) have no skill directory in the current tree. We installed azure-rbac by name to see what a user gets: the skills CLI printed "Found 31 skills / Installing all 31 skills" and silently installed everything, with zero warning that the requested skill does not exist.

The README names skills that are not in the repo. Lines 16 and 19 list azure-hosted-copilot-sdk and azure-rbac among the shipped skills. The README also describes a separate "Foundry MCP" server, but both .mcp.json files (repo root and plugin payload) wire exactly one server: azure. Foundry arrives as a toolset inside @azure/mcp (visible in tools/list), so the capability exists but the server framing does not match the configuration. The "200+ structured tools across 40+ Azure services" claim is similarly loose: tools/list returns 68 registered tools; the larger count presumably includes sub-commands nested inside toolsets, which we could enumerate but not fully expand without credentials.

The Claude marketplace manifest fails strict validation, and telemetry is understated. claude plugin validate . --strict fails on the marketplace file with "No marketplace description provided" (the Cursor marketplace has one; the Claude one does not). Separately, the plugin registers a PostToolUse hook that runs on every tool use in Claude Code, Cursor, and Copilot. The hook is well-built: it only reports events matching azure-skills paths or Azure MCP tool names, it sends no file contents (skill name, version, session id, client name, relative path), and it honors AZURE_MCP_COLLECT_TELEMETRY=false in-script. But the README telemetry section discusses only the MCP server env var and never discloses the hook's existence, and each tracked event spawns npx @azure/mcp synchronously (about 0.5s warm on our host).

Smaller hygiene gaps. Three azure-app-onboard sub-skill SKILL.md files carry no license or version frontmatter while all 35 siblings do; the finetuning sub-skill is stamped "0.0.0-placeholder"; gemini-extension.json reads 1.0.1 against plugin 1.2.36; and the second in-repo plugin (azure-kusto-graph-skills, 3 Kusto graph skills) appears in no README skill list. One tooling caveat outside Microsoft's control: npx skills add ... -a hermes-agent -g resolved the global directory to the real home rather than the isolated $HOME we set, so our test polluted a live profile with 28 skills, which we removed immediately. Hermes users should install without -g or check the landing path.

Smoke Test Results

Host-based hands-on testing on macOS 26.5.2 aarch64 (Node 24.13.1, Claude Code 2.1.152): fresh shallow clone at tag v1.2.36, structural validation with stdlib Python, registry installs in isolated HOME directories, and MCP probes through the reusable stdio client. Live Azure operations were out of scope (no subscription); auth-gated paths were exercised with empty credentials, which returns structured errors rather than hangs.

Run A - Fresh clone, structural validation

$ git clone --depth 1 https://github.com/microsoft/azure-skills.git /tmp/azure-skills-review
✅ 23MB clone, tag v1.2.36, LICENSE (MIT) present

$ ls skills/ | wc -l
✅ 28 top-level skill dirs

$ find skills -name "SKILL.md" | wc -l
✅ 38 (28 top-level + 10 nested sub-skills)

$ python3 azsk-structure.py # frontmatter parse, name==dir, descriptions, 9 manifests
✅ all frontmatter parses, names match dirs, 9/9 JSON manifests valid

$ python3 azsk-refs.py # resolve every references/ and scripts/ path, incl. ../ sibling routes
✅ 450 local cross-references, 0 broken

$ diff -r skills/ .github/plugins/azure-skills/skills/
✅ Copilot-plugin mirror byte-identical to the canonical tree

$ grep README-named skills vs skills/ dirs
❌ README lists azure-rbac and azure-hosted-copilot-sdk; neither exists in the repo

$ grep retired skill names across live skill bodies
❌ 8 dead routes in 3 skills (azure-prepare, azure-app-onboard, azure-app-onboard-prereq)

Pass rate: 7 of 9. Both failures are documentation drift after upstream retirements, not broken packaging; every file that exists is wired correctly.

Full structural log →

Run B - Sandbox with deps preinstalled

$ npm view @azure/mcp version
✅ 3.0.0-beta.39

$ python3 mcp-stdio-client.py --timeout 90 npx -y @azure/mcp@latest server start
✅ initialize: serverInfo "Azure MCP Server" 3.0.0-beta.39, protocol 2024-11-05

$ tools/list
✅ 68 tools (azure, foundry, azd, arm, aks, appservice, role, kusto, ...), all with inputSchema

$ HOME=$ISO npx skills add https://github.com/microsoft/azure-skills/tree/main/.github/plugins/azure-skills/skills -a github-copilot -g -y
✅ 28 skills copied to ~/.agents/skills (README-verbatim command, first try)

$ diff -r $ISO/.agents/skills/microsoft-foundry skills/microsoft-foundry
✅ byte-identical, including the finetuning sub-tree

$ claude plugin marketplace add microsoft/azure-skills
✅ Successfully added marketplace: azure-skills

$ claude plugin install azure@azure-skills
✅ v1.2.36 installed and enabled; 28 skills in the plugin cache

$ claude plugin validate .github/plugins/azure-skills --strict
✅ Validation passed

$ claude plugin validate .github/plugins/azure-kusto-graph-skills --strict
✅ Validation passed

$ claude plugin validate . --strict
❌ marketplace.json: "No marketplace description provided" (strict treats the warning as an error)

Pass rate: 9 of 10. Every functional install route works first try and lands byte-identical content; the sole failure is the missing marketplace description field.

Full with-deps log →

Run C - Functional verification

$ python3 scripts/validate/validate_sft.py valid-sft.jsonl # 2 well-formed records
✅ exit 0, "Data is valid for SFT fine-tuning!", token stats avg 16 / min 8 / max 25

$ python3 scripts/validate/validate_sft.py bad-sft.jsonl # invalid role, bad JSON, missing fields
✅ exit 1, five line-level errors naming record, message index, and exact defect

$ python3 scripts/validate/data_stats.py valid-sft.jsonl
✅ exit 0, role distribution (user 2, assistant 2, system 1), 0 parse errors

$ mcp call: foundry toolset, list_commands, no credentials
✅ fails fast with a structured ChainedTokenCredential error (no hang); documented az login prerequisite

$ mcp call: documentation toolset, list_commands, no credentials
✅ isError: false; the toolset responds locally without auth

$ HOME=$ISO3 npx skills add microsoft/azure-skills azure-rbac -a github-copilot -y
❌ requested skill silently ignored: "Found 31 skills / Installing all 31 skills", no warning

Functional pass rate: 5 of 6. The offline validators and the MCP layer behave exactly as documented, including clean failure modes without credentials. The one failure is the stale-registry trap: a 486K-install entry that no longer resolves to a skill, and a CLI fallback that installs everything without saying why.

Full functional log →

What the runs tell you

The packaging and the offline tooling are in better shape than the documentation: every install route is byte-faithful and the validators give real diagnostics, while the README, the marketplace description, and 6 registry entries trail the retirement decisions recorded in the changelog. For an agent consumer, the load-bearing risk is the 8 dead routes in azure-prepare and azure-app-onboard, which will produce "skill not found" moments mid-workflow until Microsoft sweeps them.

Setup Walkthrough

1. Meet the prerequisites: Node.js 18+ on PATH (npx starts the MCP server), and for live Azure work, az login (plus azd auth login for deployment workflows). The skills and validators themselves need only Python 3 stdlib.
2. Pick an install route. Claude Code: /plugin install azure@claude-plugins-official, or add this repo as a marketplace. GitHub Copilot, Cursor, Codex, Gemini each have a documented one-liner in the README; APM covers six harnesses with apm install microsoft/azure-skills.
3. For a bare skills install into any agent, the README-verbatim command works: npx skills add https://github.com/microsoft/azure-skills/tree/main/.github/plugins/azure-skills/skills -a github-copilot -g -y (swap the agent id; drop -g for a project-local install).
4. Verify: the README suggests asking "What Azure services would I need to deploy this project?" (skills layer) and "List my Azure resource groups" (MCP layer, requires auth).
5. If you care about telemetry, set AZURE_MCP_COLLECT_TELEMETRY=false; this also disables the PostToolUse usage hook. Sovereign cloud users add --cloud AzureChinaCloud or AzureUSGovernment to the MCP server args, which the README covers with per-cloud auth commands.

Alternatives

1. awslabs/mcp - the AWS counterpart: 61 official MCP servers delivering execution without an equivalent curated skills layer. Prefer it if your estate is AWS.
2. googleworkspace/cli - the Google-side analogue: one Rust CLI plus 95 generated Agent Skills with anti-drift regeneration. Prefer it for Google Workspace automation.
3. Bare Azure MCP Server (npx -y @azure/mcp@latest server start) - if you only want the 68-tool execution layer and none of the guidance, wire the server directly and skip the plugin, at the cost of losing the workflows and guardrails.