CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

aks-troubleshooting

Debug live Azure Kubernetes Service (AKS) incidents with a read-only, evidence-first investigation. WHEN: pod crashes or Pending, CrashLoopBackOff, OOMKilled, ImagePullBackOff, node NotReady, DNS or ingress failure, connectivity timeout, network policy, SNAT exhaustion, node-pool scaling blocked by QuotaExceeded or InsufficientVCPUQuota, upgrade stuck, spot or zone disruption, a bare VMExtensionProvisioningError or AllocationFailed wrapper, an uncataloged capacity symptom, or 'investigate my AKS cluster'. DO NOT USE FOR: packet capture (use aks-network-capture); GPU or model-serving issues (use aks-gpu-inference); cluster creation or provisioning (use azure-kubernetes); cost (use cost-analysis from the optional azure-cost plugin); pod rightsizing (use azure-kubernetes); a fully qualified documented AKS signature with every required nested qualifier (use aks-known-issues); standalone failures on non-AKS Azure resources (use azure-diagnostics). Unqualified errors and open-ended incidents stay here only for AKS.

Quality

89%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

The canonical home for this skill is aks-troubleshooting in microsoft/GitHub-Copilot-for-Azure

SKILL.md
Quality
Evals
Security

Quality

Content

85%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a disciplined, highly actionable investigation playbook — exact commands, explicit sequencing, validation checkpoints, feedback loops, and AKS-specific gotchas that assume rather than teach — with only minor redundancy in its safety rules. Its one material defect is bundle integrity: the central symptom-routing table and two in-reference links point at eight topic files that are absent from the bundle, breaking the skill's main navigation path.

Suggestions

Add the eight missing topic files (general-diagnostics.md, pod-failures.md, node-issues.md, networking.md, load-balancer-and-ingress.md, network-policy.md, upgrade-operations.md, spot-and-zone-issues.md) to the bundle, or repoint the symptom table's rows for those symptoms to references/symptom-map.md sections and existing files.

Fix the two '../node-issues.md' links in references/symptom-map.md (lines 212 and 244) so the quota/Failed-state branch the SKILL.md body calls 'required reading' actually resolves.

Merge the duplicated 'denial is not a negative result' guidance from the Denied access and Host capability gate rules into one place, and consider moving the host-gate detail into references/azure-mcp.md to trim the always-loaded body.

DimensionReasoningScore

Conciseness

The body is dense and assumes competence — no explanation of what AKS, kubectl, or CNI plugins are; every gotcha bullet embeds a non-obvious AKS fact plus the exact read command (e.g. 'az aks show --query identityProfile', error codes 50/51/52). Level 5 is blocked by genuine repetition: the 'negative result' guidance appears in both the Denied access and Host capability gate rules, and the host-gate paragraph restates tool-preference caveats at length; these could be tightened.

4 / 5

Actionability

Fully executable throughout: copy-paste az/kubectl commands with exact --query projections ('az network vnet subnet show --query {addressPrefix: addressPrefix, used: ipConfigurations | length(@)}'), named error codes, script invocations with full argument lists and the AKS_SUBSCRIPTION_ID pin, and a symptom-map reference that genuinely contains 17 self-contained command blocks. Covers the common cases concretely.

5 / 5

Workflow Clarity

The investigation is explicitly sequenced with validation checkpoints: 'Bind the subscription, cluster, kube context, namespace, and affected resource before collecting evidence', symptom-selects-first-decisive-read ordering, a convergence rule (2-4 hypotheses each with confirming/falsifying signals and a stop condition), pre-flight checks ('kubectl auth can-i', script-side context-endpoint verification), and a remediation feedback loop ('Make one change at a time... then re-test the original signal'). The read-only default plus one-change-at-a-time protocol addresses risk without needing a destructive-op validation cap.

5 / 5

Progressive Disclosure

The design — SKILL.md as a routing overview, a symptom table, one-level-deep references — matches the anchor-5 shape on paper, but scored against the actual bundle, 8 of the 16 routed paths are dead: general-diagnostics.md, pod-failures.md, node-issues.md, networking.md, load-balancer-and-ingress.md, network-policy.md, upgrade-operations.md, and spot-and-zone-issues.md do not exist anywhere in the bundle, and symptom-map.md's '../node-issues.md' links are dead too. This is not the 'minor organization gaps' of level 4 — the primary navigation layer fails for half its routes, and the body twice directs the reader into a required file (node-issues.md) that isn't there.

3 / 5

Total

17

/

20

Passed

Description

90%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, dense description that explicitly states what it does, when to trigger it, and when to route to six sibling skills, with excellent natural trigger terms including exact error strings. Its only weakness is that the capability statement is a single action verb ('Debug ... investigation') — the WHAT leans on the trigger list rather than enumerating its concrete capabilities — and the single-sentence construction is on the long side, though nearly every clause carries routing signal rather than fluff.

DimensionReasoningScore

Specificity

The description names the domain clearly ('Debug live Azure Kubernetes Service (AKS) incidents') with one concrete action framing ('a read-only, evidence-first investigation'), but it does not list several distinct capabilities — the long symptom enumeration serves triggers rather than enumerating what the skill does (root-cause analysis, incident report production, etc. are only in the body). Fits the anchor 'names domain and 1-2 concrete actions, but not comprehensive' rather than level 4, which requires several listed specific actions.

3 / 5

Completeness

Explicitly answers both questions: WHAT — 'Debug live AKS incidents with a read-only, evidence-first investigation'; WHEN — an explicit 'WHEN:' clause with concrete trigger phrases, plus a 'DO NOT USE FOR' clause routing adjacent domains elsewhere. This exceeds the anchor-5 example's clarity of both what and when.

5 / 5

Trigger Term Quality

Exceptional coverage of natural terms users would actually say or paste: 'CrashLoopBackOff', 'OOMKilled', 'ImagePullBackOff', 'node NotReady', 'DNS or ingress failure', 'connectivity timeout', 'SNAT exhaustion', 'QuotaExceeded', 'upgrade stuck', and the literal phrase 'investigate my AKS cluster'. Both exact error strings and plain-language symptom phrasings are present; nothing common is missing.

5 / 5

Distinctiveness Conflict Risk

Clear niche (live AKS incident debugging) with explicit negative routing to every adjacent skill — 'aks-network-capture', 'aks-gpu-inference', 'azure-kubernetes', 'aks-known-issues', 'cost-analysis', 'azure-diagnostics' — and a boundary rule ('Unqualified errors and open-ended incidents stay here only for AKS'). Minimal conflict risk.

5 / 5

Total

18

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

relative_links

Relative link issues: 9 missing

Warning

Total

15

/

16

Passed

Repository

microsoft/azure-skills

Path

.github/plugins/aks-skills/skills/aks-troubleshooting/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.