# AKS Skills

> Agent skills for operating Azure Kubernetes Service (AKS): troubleshooting, cost, AKS Automatic readiness, GPU/inference, packet capture, and cluster design. The deep Day-2 AKS operator — complements the Azure Skills plugin; works with Claude Code, GitHub Copilot, and Azure SRE Agent.

- **Type:** MCP server
- **Install:** `agentstack add mcp-azure-aks-skills`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Azure](https://agentstack.voostack.com/s/azure)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Azure](https://github.com/Azure)
- **Source:** https://github.com/Azure/AKS-Skills

## Install

```sh
agentstack add mcp-azure-aks-skills
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# AKS Skills

[](LICENSE)
[](https://agentskills.io)
[](https://learn.microsoft.com/azure/aks/)

Agent skills for operating **Azure Kubernetes Service (AKS)** clusters. AKS Skills is the deep Day-2 AKS operator — troubleshoot live incidents, optimize cost, assess AKS Automatic readiness, run GPU/inference workloads, and capture packet-level evidence. It complements the broader [Azure Skills](https://github.com/microsoft/azure-skills) plugin (the provisioning engine); install both.

This is a **dedicated repo**, not a folder inside the all-up Azure Skills plugin, so it can go deep on AKS Day-2 operations without bloating the general Azure plugin, and ship on the AKS team's own cadence. See **[docs/skills-vs-azure-skills.md](docs/skills-vs-azure-skills.md)** for the boundary and why.

A "skill" is a folder with a `SKILL.md` (YAML front matter + guidance) plus optional `references/` and `scripts/`. A host agent reads the skill descriptions, picks the relevant one, loads its `SKILL.md`, and progressively reads references or runs scripts. The format is the open [Agent Skills standard](https://agentskills.io), so these skills run across Claude Code, GitHub Copilot, Azure SRE Agent, openclaw, and other compatible hosts.

## Skills

| Skill | What it does |
| --- | --- |
| [`aks-troubleshooting`](skills/aks-troubleshooting) | Root-cause live AKS incidents: pod crashes, node failures, DNS/networking, ingress, upgrades, spot/zone disruptions. Read-only, evidence-first. |
| [`aks-known-issues`](skills/aks-known-issues) | Match a specific AKS error code or message to the documented cause and fix, with a Microsoft Learn citation. Deterministic lookup, not an investigation. |
| [`aks-cost-optimization`](skills/aks-cost-optimization) | Reduce AKS spend: rightsizing, autoscaler tuning, spot pools, cost visibility, anomaly detection. |
| [`aks-automatic-readiness`](skills/aks-automatic-readiness) | Assess workloads and clusters for AKS Automatic compatibility; generate fixes; guide migration. |
| [`aks-gpu-inference`](skills/aks-gpu-inference) | Day-2 GPU and model-inference operations: scheduling/quota, KAITO Workspaces, GPU cost/scaling, DCGM observability. |
| [`aks-network-capture`](skills/aks-network-capture) | Packet-level evidence: bounded, distributed capture and Azure-side network analysis. Escalation tool. |
| [`aks-cluster-setup`](skills/aks-cluster-setup) | Make AKS-specific cluster design decisions, then delegate provisioning to Azure Skills. |

## Try it

Once installed, just describe the problem in natural language — the host agent picks the right skill by its description. For example:

- *"A pod in my `payments` namespace is stuck in CrashLoopBackOff — investigate."* → `aks-troubleshooting`
- *"My node pool create failed with `VMCannotFitEphemeralOSDisk` — is this a known issue, and how do I fix it?"* → `aks-known-issues`
- *"My AKS bill jumped this month; help me rightsize and find idle nodes."* → `aks-cost-optimization`
- *"Is my cluster ready to move to AKS Automatic? What needs to change?"* → `aks-automatic-readiness`
- *"My GPU pod is Pending with 'Insufficient nvidia.com/gpu' and the KAITO workspace never becomes ready."* → `aks-gpu-inference`
- *"Egress to Azure SQL fails but pod-to-pod works — I want packet-level proof of where it drops."* → `aks-network-capture`
- *"Design and stand up a production AKS cluster with a private API server."* → `aks-cluster-setup`

Skills default to **read-only** investigation and ask before changing anything.

## Install

| Host | Install |
| --- | --- |
| **Claude Code** | `/plugin marketplace add Azure/AKS-Skills`, then `/plugin install aks@aks-skills` |
| **GitHub Copilot CLI** | `/plugin marketplace add Azure/AKS-Skills`, then `/plugin install aks@aks-skills` |
| **Azure SRE Agent** | Install from URL: `https://github.com/Azure/AKS-Skills` (reads `plugin.json` + `skills/`) |
| **Any Agent Skills host** | `npx skills add https://github.com/Azure/AKS-Skills --all` (installs the skills; `.mcp.json` wiring is not applied on this path — skills fall back to `az`/`kubectl`) |

For deployment/provisioning, also install [Azure Skills](https://github.com/microsoft/azure-skills).

## Prerequisites

- **`kubectl`** and the **Azure CLI (`az`)** on `PATH`, authenticated to your cluster/subscription (`az login`, `az aks get-credentials`).
- The **Azure MCP server** (`@azure/mcp`) is wired via [`.mcp.json`](.mcp.json); skills prefer the AKS MCP tools and fall back to `az`/`kubectl`.
- Skills default to **read-only** operations and ask before making changes.

## Disconnected, self-hosted, and non-frontier use

The skills are plain text with a deterministic `az`/`kubectl` fallback: they don't require internet egress or a specific vendor API, so nothing structurally prevents running them against a smaller, self-hosted, or non-frontier model. Whether such a model actually *follows* a given skill reliably is a separate, empirical question — the skills aren't tuned or validated against non-frontier models today, and the eval harness below is the tool for measuring that gap, not a claim that it's already closed. If you're running in an air-gapped, sovereign, or self-hosted setup — for example a small local model in an Arc-based investigator — a few things already work today:

- **No Azure MCP server required.** The [`.mcp.json`](.mcp.json) wiring is a convenience; every skill falls back to `az`/`kubectl`, so an agent with only the local CLIs still works. The MCP server is **pinned to an exact `@azure/mcp` version** (not `@latest`), so a disconnected host can pre-cache that one package — or skip it entirely and rely on the fallback.
- **Local / offline install.** No GitHub connection is needed at runtime. Clone the repo and point your host at the local copy — in Claude Code, `/plugin marketplace add ` (the marketplace declares a local `source`), or point the agent directly at the local `skills/` folder. The install rows above that reference `Azure/AKS-Skills` or `npx skills add ` need network; the local path does not.
- **Evaluate any model against the skills.** The eval harness can target any OpenAI-compatible endpoint — a hosted deployment or a local model server (llama.cpp, vLLM, Ollama) — by setting `OPENAI_BASE_URL` (and `EVAL_MODEL`). This is how you measure how well the skills perform on a smaller, self-hosted, or non-frontier model, not just frontier ones. See [evals/README.md](evals/README.md).
- **Air-gapped clusters.** A few skills run debug/capture pods that pull images from `mcr.microsoft.com`. In a cluster with no registry egress, mirror those images into your private registry first.
- **Product integration boundary.** Local/non-frontier model support makes the skill contract portable; it does not define a separate AKS troubleshooting experience or replace HolmesGPT. Runtime selection and reconnect handoff belong to the consuming product.

## Contributing

Contributions are welcome. AKS Skills accepts **deep, AKS-specific Day-2 operational knowledge and AKS-specific design opinions** — not generic Azure provisioning, generic Kubernetes any model already knows, or cross-resource workflows (those belong in Azure Skills). Every skill must meet the [Skill Contract](docs/skill-contract.md). See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT. See [LICENSE](LICENSE).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Azure](https://github.com/Azure)
- **Source:** [Azure/AKS-Skills](https://github.com/Azure/AKS-Skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-azure-aks-skills
- Seller: https://agentstack.voostack.com/s/azure
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.