microsoft · julia-yin · Feb 25, 2026 · Feb 25, 2026 · Feb 25, 2026 · Feb 25, 2026
diff --git a/plugin/skills/azure-kubernetes/SKILL.md b/plugin/skills/azure-kubernetes/SKILL.md
@@ -0,0 +1,128 @@
+---
+name: azure-kubernetes
+license: MIT
+metadata:
+  author: Microsoft
+  version: "1.0.0"
+description: "Plan and create production-ready Azure Kubernetes Service (AKS) clusters. Covers Day-0 decisions and Day-1 configuration, cluster SKUs (Automatic vs Standard), security, monitoring, reliability/performance best practices, upgrades, and networking. WHEN: create AKS cluster, plan AKS configuration, design AKS networking, AKS Automatic vs Standard, AKS security, AKS upgrade strategy, AKS autoscaling, AKS monitoring setup, AKS cost analysis, Day-0 checklist."
+---
+
+# Azure Kubernetes Service
+
+> **AUTHORITATIVE GUIDANCE — MANDATORY COMPLIANCE**
+>
+> This skill produces a **recommended AKS cluster configuration** based on user requirements, distinguishing **Day-0 decisions** (networking, API server — hard to change later) from **Day-1 features** (can enable post-creation). See [CLI reference](./references/cli-reference.md) for commands.
+
+## Quick Reference
+| Property | Value |
+|----------|-------|
+| Best for | AKS cluster planning and Day-0 decisions |
+| MCP Tools | `mcp_azure_mcp_aks`, `mcp_aks_mcp_az_aks_operations` |
-| MCP Tools | `mcp_azure_mcp_aks`, `mcp_aks_mcp_az_aks_operations` |
+| MCP Tools | `mcp_azure_mcp_aks`, `mcp_azure_mcp_az_aks_operations` |
-| MCP Tools | `mcp_azure_mcp_aks`, `mcp_aks_mcp_az_aks_operations` |
+| MCP Tools | `mcp_azure_mcp_aks`, `mcp_azure_mcp_az_aks_operations` |
+| CLI | `az aks create`, `az aks show` |
+| Related skills | azure-diagnostics (troubleshooting), azure-deploy (app deployment) |
+
+## When to Use This Skill
+Activate this skill when user wants to:
+- Create a new AKS cluster
+- Plan AKS cluster configuration for production workloads
+- Design AKS networking (API server access, pod IP model, egress)
+- Set up AKS identity and secrets management
+- Configure AKS governance (Azure Policy, Deployment Safeguards)
+- Enable AKS observability (monitoring, Prometheus, Grafana)
+- Define AKS upgrade and patching strategy
+- Enable AKS cost visibility and analysis
+- Understand AKS Automatic vs Standard SKU differences
+- Get a Day-0 checklist for AKS cluster setup and configuration
+
+## Rules
+1. Start with the user's requirements for provisioning compute, networking, security, and other settings.
+2. Use the AKS MCP server for invoking Azure API and kubectl commands when applicable during the cluster setup and operations processes.
-2. Use the AKS MCP server for invoking Azure API and kubectl commands when applicable during the cluster setup and operations processes.
+2. Use the `azure` MCP server and its AKS-related MCP tools to invoke Azure APIs and perform AKS and kubectl operations whenever possible during cluster setup and ongoing operations; if required functionality is not available via MCP tools, fall back to Azure CLI and kubectl commands.
-2. Use the AKS MCP server for invoking Azure API and kubectl commands when applicable during the cluster setup and operations processes.
+2. Use the `azure` MCP server and its AKS-related MCP tools to invoke Azure APIs and perform AKS and kubectl operations whenever possible during cluster setup and ongoing operations; if required functionality is not available via MCP tools, fall back to Azure CLI and kubectl commands.
+3. Determine if AKS Automatic or Standard SKU is more appropriate based on the user's need for control vs convenience. Default to AKS Automatic unless specific customizations are required.
+4. Document decisions and rationale for cluster configuration choices, especially for Day-0 decisions that are hard to change later (networking, API server access).
+
+
+## Required Inputs (Ask only what’s needed)
+If the user is unsure, use safe defaults.
+- Cluster environment: dev/test or production
+- Region(s), availability zones, preferred node VM sizes
+- Expected scale (node/cluster count, workload size)
+- Networking requirements (API server access, pod IP model, ingress/egress control)
+- Security and identity requirements, including image registry
+- Upgrade and observability preferences
+- Cost constraints
+
+## Workflow
+
+### 1. Cluster Type
+- **AKS Automatic** (default): Best for most production workloads, provides a curated experience with pre-configured best practices for security, reliability, and performance. Use unless you have specific custom requirements for networking, autoscaling, or node pool configurations not supported by NAP.
+- **AKS Standard**: Use if you need full control over cluster configuration, will require additional overhead to setup and manage.
+
+### 2. Networking (Pod IP, Egress, Ingress, Dataplane)
+
+**Pod IP Model** (Key Day-0 decision):
+- **Azure CNI Overlay** (recommended): pod IPs from private overlay range, not VNet-routable, scales to large clusters and good for most workloads
+- **Azure CNI (VNet-routable)**: pod IPs directly from VNet (pod subnet or node subnet), use when pods must be directly addressable from VNet or on-prem
+  - Docs: https://learn.microsoft.com/azure/aks/azure-cni-overlay
+
+**Dataplane & Network Policy**:
+- **Azure CNI powered by Cilium** (recommended): eBPF-based for high-performance packet processing, network policies, and observability
+
+**Egress**:
+- **Static Egress Gateway** for stable, predictable outbound IPs
+- For restricted egress: UDR + Azure Firewall or NVA
+
+**Ingress**:
+- **App Routing addon with Gateway API** — recommended default for HTTP/HTTPS workloads
+- **Istio service mesh with Gateway API** — for advanced traffic management, mTLS, canary deployments
+- **Application Gateway for Containers** — for L7 load balancing with WAF integration
+
+**DNS**:
+- Enable **LocalDNS** on all node pools for reliable, performant DNS resolution
+
+### 3. Security
+- Use **Microsoft Entra ID** everywhere (control plane, Workload Identity for pods, node access). Avoid static credentials.
+- Azure Key Vault via **Secrets Store CSI Driver** for secrets
+- Enable **Azure Policy** + **Deployment Safeguards**
+- Enable **Encryption at rest** for etcd/API server; **in-transit** for node-to-node
+- Allow only signed, policy-approved images (Azure Policy + Ratify), prefer **Azure Container Registry**
+- **Isolation**: Use namespaces, network policies, scoped logging
+
+### 4. Observability
+- Use Azure Monitor and Container Insights for AKS monitoring enablement (logs + Prometheus + Grafana).
+
+### 5. Upgrades & Patching
+- Configure **Maintenance Windows** for controlled upgrade timing
+- Enable **auto-upgrades** for cluster and node OS to stay up-to-date with security patches and Kubernetes versions
+- Consider **LTS versions** for enterprise stability (2-year support) by upgrading your cluster to the AKS Premium tier
+- **Multi-cluster upgrades**: Use **AKS Fleet Manager** for staged rollout across test → production clusters
+
+### 6. Performance
+- Use **Ephemeral OS disks** (`--node-osdisk-type Ephemeral`) for faster node startup
+- Select **Azure Linux** as node OS (smaller footprint, faster boot)
+- Enable **KEDA** for event-driven autoscaling beyond HPA
+
+### 7. Node Pools & Compute
+- **Dedicated system node pool**: At least 2 nodes, tainted for system workloads only (`CriticalAddonsOnly`)
+- Enable **Node Auto Provisioning (NAP)** on all pools for cost savings and responsive scaling
+- Use **latest generation SKUs (v5/v6)** for host-level optimizations
+- **Avoid B-series VMs** — burstable SKUs cause performance/reliability issues
+- Use SKUs with **at least 4 vCPUs** for production workloads
+- Set **topology spread constraints** to distribute pods across hosts/zones per SLO
+
+### 8. Reliability
+- Deploy across **3 Availability Zones** (`--zones 1 2 3`)
+- Use **Standard tier** for zone-redundant control plane + 99.95% SLA for API server availability
+- Enable **Microsoft Defender for Containers** for runtime protection
+- Configure **PodDisruptionBudgets** for all production workloads
+- Use **topology spread constraints** to ensure pod distribution across failure domains
+
+### 9. Cost Controls
+- Use **Spot node pools** for batch/interruptible workloads (up to 90% savings)
+- **Stop/Start** dev/test clusters: `az aks stop/start`
+- Consider **Reserved Instances** or **Savings Plans** for steady-state workloads
+
+## Guardrails / Safety
+- Do not request or output secrets (tokens, keys, subscription IDs).
+- If requirements are ambiguous for day-0 critical decisions, ask the user clarifying questions. For day-1 enabled features, propose 2–3 safe options with tradeoffs and choose a conservative default.
+- Do not promise zero downtime; advise workload safeguards (PDBs, probes, replicas) and staged upgrades along with best practices for reliability and performance.
+- If user asks for actions that require privileged access, provide a plan and commands with placeholders.
diff --git a/plugin/skills/azure-kubernetes/references/cli-reference.md b/plugin/skills/azure-kubernetes/references/cli-reference.md
@@ -0,0 +1,33 @@
+# CLI Reference for AKS
+
+```bash
+# List AKS clusters
+az aks list --output table
+
+# Show cluster details
+az aks show --name <cluster-name> --resource-group <resource-group>
+
+# Get available Kubernetes versions
+az aks get-versions --location <location> --output table
+
+# Create AKS Automatic cluster
+az aks create --name <cluster-name> --resource-group <resource-group> --sku automatic \
+  --network-plugin azure --network-plugin-mode overlay \
+  --enable-oidc-issuer --enable-workload-identity
+
+# Create AKS Standard cluster
+az aks create --name <cluster-name> --resource-group <resource-group> \
+  --node-count 3 --zones 1 2 3 \
+  --network-plugin azure --network-plugin-mode overlay \
+  --enable-cluster-autoscaler --min-count 1 --max-count 10
+
+# Get credentials
+az aks get-credentials --name <cluster-name> --resource-group <resource-group>
+
+# List node pools
+az aks nodepool list --cluster-name <cluster-name> --resource-group <resource-group> --output table
+
+# Enable monitoring
+az aks enable-addons --name <cluster-name> --resource-group <resource-group> \
+  --addons monitoring --workspace-resource-id <workspace-resource-id>
+```
diff --git a/plugin/skills/azure-prepare/SKILL.md b/plugin/skills/azure-prepare/SKILL.md
@@ -4,7 +4,7 @@ description: "Prepare Azure apps for deployment (infra Bicep/Terraform, azure.ya
 license: MIT
 metadata:
   author: Microsoft
-  version: "1.0.3"
+  version: "1.0.4"
 ---
 
 # Azure Prepare

diff --git a/plugin/skills/azure-prepare/references/architecture.md b/plugin/skills/azure-prepare/references/architecture.md
@@ -22,18 +22,46 @@ Select hosting stack and map components to Azure services.
 | Workflow / orchestration | | ✓✓ (Durable Functions + DTS) | |
 | Minimal ops overhead | | ✓✓ | ✓ |
 
+### Container Hosting: Container Apps vs AKS
+
+| Factor | Container Apps | AKS |
+|--------|:--------------:|:---:|
+| **Scale to zero** | ✓✓ | |
+| **Kubernetes API access** | | ✓✓ |
+| **Custom operators/CRDs** | | ✓✓ |
+| **Service mesh** | Dapr (built-in) | Istio, Cilium |
+| **GPU workloads** | | ✓✓ |
+| **Best for** | Microservices, event-driven | Full K8s control, complex workloads |
+
+#### When to Use Container Apps
+- Microservices without Kubernetes complexity
+- Event-driven workloads (KEDA built-in)
+- Need scale-to-zero for cost optimization
+- Teams without Kubernetes expertise
+
+#### When to Use AKS
+- Need Kubernetes API/kubectl access
+- Require custom operators or CRDs
+- Service mesh requirements (Istio, Linkerd)
+- GPU/ML workloads
+- Complex networking or multi-tenant architectures
+
+> **AKS Planning:** For AKS SKU selection (Automatic vs Standard), networking, identity, scaling, and security configuration, invoke the **azure-kubernetes** skill.
+
 ## Service Mapping
 
 ### Hosting
 
 | Component Type | Primary Service | Alternatives |
 |----------------|-----------------|--------------|
 | SPA Frontend | Static Web Apps | Blob + CDN |
-| SSR Web App | Container Apps | App Service |
-| REST/GraphQL API | Container Apps | App Service, Functions |
-| Background Worker | Container Apps | Functions |
-| Scheduled Task | Functions (Timer) | Container Apps Jobs |
-| Event Processor | Functions | Container Apps |
+| SSR Web App | Container Apps | App Service, AKS |
+| REST/GraphQL API | Container Apps | App Service, Functions, AKS |
+| Background Worker | Container Apps | Functions, AKS |
+| Scheduled Task | Functions (Timer) | Container Apps Jobs, Kubernetes CronJob (on AKS) |
+| Event Processor | Functions | Container Apps, AKS + KEDA |
+| Microservices (full K8s) | AKS | Container Apps |
+| GPU/ML Workloads | AKS | Azure ML |
 
 ### Data
 

diff --git a/tests/azure-kubernetes/__snapshots__/triggers.test.ts.snap b/tests/azure-kubernetes/__snapshots__/triggers.test.ts.snap
@@ -0,0 +1,103 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`azure-kubernetes - Trigger Tests Trigger Keywords Snapshot skill description triggers match snapshot 1`] = `
+{
+  "description": "Plan and create production-ready Azure Kubernetes Service (AKS) clusters. Covers Day-0 decisions and Day-1 configuration, cluster SKUs (Automatic vs Standard), security, monitoring, reliability/performance best practices, upgrades, and networking. WHEN: create AKS cluster, plan AKS configuration, design AKS networking, AKS Automatic vs Standard, AKS security, AKS upgrade strategy, AKS autoscaling, AKS monitoring setup, AKS cost analysis, Day-0 checklist.",
+  "extractedKeywords": [
+    "aks",
+    "analysis",
+    "automatic",
+    "autoscaling",
+    "azure",
+    "best",
+    "checklist",
+    "cli",
+    "cluster",
+    "clusters",
+    "configuration",
+    "container",
+    "cost",
+    "covers",
+    "create",
+    "day-0",
+    "day-1",
+    "decisions",
+    "deploy",
+    "design",
+    "diagnostic",
+    "entra",
+    "identity",
+    "key vault",
+    "kubernetes",
+    "mcp",
+    "monitor",
+    "monitoring",
+    "networking",
+    "observability",
+    "performance",
+    "plan",
+    "practices",
+    "production-ready",
+    "reliability",
+    "security",
+    "service",
+    "setup",
+    "skus",
+    "standard",
+    "strategy",
+    "upgrade",
+    "upgrades",
+    "when",
+  ],
+  "name": "azure-kubernetes",
+}
+`;
+
+exports[`azure-kubernetes - Trigger Tests Trigger Keywords Snapshot skill keywords match snapshot 1`] = `
+[
+  "aks",
+  "analysis",
+  "automatic",
+  "autoscaling",
+  "azure",
+  "best",
+  "checklist",
+  "cli",
+  "cluster",
+  "clusters",
+  "configuration",
+  "container",
+  "cost",
+  "covers",
+  "create",
+  "day-0",
+  "day-1",
+  "decisions",
+  "deploy",
+  "design",
+  "diagnostic",
+  "entra",
+  "identity",
+  "key vault",
+  "kubernetes",
+  "mcp",
+  "monitor",
+  "monitoring",
+  "networking",
+  "observability",
+  "performance",
+  "plan",
+  "practices",
+  "production-ready",
+  "reliability",
+  "security",
+  "service",
+  "setup",
+  "skus",
+  "standard",
+  "strategy",
+  "upgrade",
+  "upgrades",
+  "when",
+]
+`;