skill

aks-known-issues — Claude Code skill: what it does, how to install

Q: How to install aks-known-issues in Claude Code?

Run both commands in sequence: first `/plugin marketplace add microsoft/skills`, then `/plugin install aks-skills@skills`.

Q: When should aks-troubleshooting be used instead?

Use `aks-troubleshooting` for quota exhaustion, bare error wrappers without nested details, or broad symptoms that lack an exact catalog signature.

Diagnoses documented Azure Kubernetes Service failures from exact error signatures. It pinpoints causes and official fixes for node, VM, and extension errors.

Install into Claude Code · Plugin marketplace All methods and platforms ↓

/plugin marketplace add microsoft/skills
/plugin install aks-skills@skills

Open on GitHub

What aks-known-issues does

The skill matches AKS provisioning and runtime failures against Microsoft's catalog of documented issues. It targets explicit error signatures such as VMCannotFitEphemeralOSDisk, NodePoolMcVersionIncompatible, zone capacity failures like ZonalAllocationFailed, and nested vmssCSE extension timeouts including VMExtensionError_K8SAPIServerConnFail.

Every lookup requires the full signature alongside its qualifiers, such as VM size, region, or zone. Partial error codes and bare numbers get rejected. Quota limit breaches are outside this catalog, so those incidents belong in aks-troubleshooting. The skill runs without extra MCP servers by relying on read-only Azure CLI queries or available Azure tools.

Mutations to infrastructure always pause for direct approval before executing. Without all qualifying parameters in the prompt, the skill will not trigger a fix.

What it helps with

resolve VMCannotFitEphemeralOSDisk failures during node pool creation
diagnose VMExtensionError_K8SAPIServerConnFail during vmssCSE node provisioning
find documented workarounds for ZonalAllocationFailed with insufficient zone capacity
troubleshoot OverconstrainedAllocationRequest errors with specific placement constraints

Example prompts for the agent

Node pool deployment failed with VMCannotFitEphemeralOSDisk. What is the fix according to Microsoft docs?
My AKS cluster threw VMExtensionError_K8SAPIServerConnFail on vmssCSE. Show the cause and resolution steps.
Resolve AKS error ZonalAllocationFailed with insufficient zone capacity in westeurope zone 1.

How to install aks-known-issues

1Plugin marketplace

/plugin marketplace add microsoft/skills

/plugin install aks-skills@skills

This installs the whole aks-skills plugin with all its skills

2Skills CLI (Vercel)

npx skills add microsoft/skills --skill aks-known-issues -a claude-code

3Manually: put the files in place

~/.claude/skills/aks-known-issues/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/aks-known-issues/

Manually: put the files in place

.agents/skills/aks-known-issues/SKILL.md

For all projects use ~/.agents/skills/

Manually: put the files in place

.cursor/skills/aks-known-issues/SKILL.md

Cursor also reads .agents/skills/ and .claude/skills/

1GitHub CLI

gh skill install microsoft/skills aks-known-issues

2Manually: put the files in place

.github/skills/aks-known-issues/SKILL.md

Platform CLI

gemini skills install https://github.com/microsoft/skills --path .github/plugins/aks-skills/skills/aks-known-issues

Manually: put the files in place

.devin/skills/aks-known-issues/SKILL.md

The legacy .windsurf/skills/ path still works

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about aks-known-issues

How to install aks-known-issues in Claude Code?

Run both commands in sequence: first /plugin marketplace add microsoft/skills, then /plugin install aks-skills@skills.

What does aks-known-issues do?

It identifies AKS root causes from specific error signatures, providing the documented fix, Microsoft Learn references, and read-only verification commands.

When should aks-troubleshooting be used instead?

Use aks-troubleshooting for quota exhaustion, bare error wrappers without nested details, or broad symptoms that lack an exact catalog signature.

Source text

SKILL.md · MIT

---
name: aks-known-issues
license: MIT
metadata:
  author: Microsoft
  version: "1.2.1"
description: "Lookup documented AKS fixes only when the prompt includes an exact catalog signature and all of its qualifiers: VMCannotFitEphemeralOSDisk; NodePoolMcVersionIncompatible; 'NodeImageVersion is not accepted'; AKS SkuNotAvailable with size, location, and zone; ZonalAllocationFailed with insufficient zone capacity; OverconstrainedAllocationRequest with listed constraints; nested AKS vmssCSE/CSE VMExtensionError_OutboundConnFail, VMExtensionError_K8SAPIServerConnFail, or VMExtensionError_K8SAPIServerDNSLookupFail; or AllocationFailed with the full cataloged internal-error or insufficient-regional-capacity message. Never use for quota errors, code-only or bare wrappers, generic symptoms, incomplete signatures, or failures outside AKS; use aks-troubleshooting or azure-diagnostics."
---

# AKS Known Issues

## Quick Reference

| Property | Value |
|---|---|
| Best for | Exact signature plus AKS operation |
| Output | Cause, fix, and Learn citation |

Use the [catalog](references/error-code-map.md).

## When to Use This Skill

Named catalog signatures only. Generic AKS → `aks-troubleshooting`; non-AKS →
no AKS skill.

If every qualifier for a catalog row is not present, do not use this skill.
This catalog has no quota-error rows; route AKS quota incidents to
`aks-troubleshooting`.

## MCP Tools

None required. Use advertised read-only Azure tools or CLI queries.

## Workflow

1. Capture exact code, nested message, operation, and AKS resource.
2. Require every qualifier; codes are not substrings.
3. Give cause, fix, citation, and read-only verification.
4. State what ran; require explicit approval before every mutation.

## Error Handling

| Input | Response |
|---|---|
| Bare wrapper/number | Request nested signature and CSE context |
| Generic AKS | `aks-troubleshooting` |
| Non-AKS | No AKS skill |

Similar skills

All skills for Cloud: AWS, Azure, GCP →

caveman-manage JuliusBrussee Checks Caveman Cloud experiment state and evidence, then recommends one action or blocks an unsafe request. Use it before starting, approving, cancelling, or rolling back an experiment. CX Codex +1 104,200installs workers-best-practices cloudflare Guides coding agents on production Cloudflare Workers standards, Wrangler typing, observability setup, and runtime anti-pattern checks. CX Codex +1 126,100installs cloudflare-email-service cloudflare A skill for Cloudflare Email Sending and Email Routing: it walks the agent through sending and receiving mail in Workers. CX Codex +1 102,300installs firebase-basics official google This skill sets up the Firebase CLI, handles sign-in, creates or switches projects, and downloads Android or iOS app configuration files. CX Codex 14,100installs cloudflare-one cloudflare Walks your agent through designing, configuring and troubleshooting Cloudflare One Zero Trust and SASE deployments. Useful when you need Access, Gateway or tunnel work done without digging through docs yourself. CX Codex +1 93,100installs cloudflare-one-migrations cloudflare Plans a migration from VPN, SWG or SASE to Cloudflare One: maps policies to Cloudflare resources, flags parity gaps and stages the rollout. CX Codex +1 89,500installs

From the same set242

The whole set →

azure-advisor-actionability This skill turns an Azure Advisor recommendation into step-by-step remediation with real resource values filled in. Useful when you need to act on an Advisor note instead of guessing. ★ 3,149repo stars azure-search-nav Creates Azure portal deep links to specific blades and menus for AKS, Arc-enabled Kubernetes, and Compute resources based on text queries. ★ 3,149repo stars aks-troubleshooting Investigates live Azure Kubernetes Service incidents in read-only mode and ties symptoms to evidence-backed causes. Use it for AKS failures. ★ 3,149repo stars aks-network-capture Collects bounded packet captures from AKS nodes plus Azure network configuration, so you can show where packets actually drop. ★ 3,149repo stars aks-gpu-inference Investigate AKS GPU and KAITO incidents using cluster events, status, and available metrics. Useful for Pending GPU pods, model-load OOMs, and scaling issues. ★ 3,149repo stars Project Scaffolder Generates a working full-stack Azure AI Foundry project: React frontend, FastAPI backend, azd infrastructure. Useful when you want code that runs, not an empty folder. ★ 3,149repo stars Presenter Mode Developer Implements presenter view, teleprompter notes, and keyboard navigation for CoreAI DIY. Useful when preparing demo workflows. ★ 3,149repo stars Infrastructure Engineer A subagent that handles CoreAI DIY infrastructure: Azure Container Apps, Cosmos DB, Bicep templates and azd deployments. Useful when infra/main.bicep needs a change or a deploy fails. ★ 3,149repo stars