natureco-cli 5.18.3 → 5.20.0

package/skills/azure-compute/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: azure-compute
+description: "Azure VM/VMSS router. WHEN: create / provision / deploy / spin-up VM, recommend VM size, compare VM pricing, VMSS, scale set, autoscale, burstable, lightweight server, website, backend, GPU, machine learning, HPC simulation, dev/test, workload, family, load balancer, Flexible orchestration, Uniform orchestration, cost estimate, can't connect / RDP / SSH, refused, black screen, reset password, reach VM, port 3389, NSG, security, Linux, troubleshoot, troubleshooting, connectivity, capacity reservation (CRG), reserve, guarantee capacity, pre-provision, CRG association, CRG disassociation, machine enrollment (EMM), Essential Machine Management, monitor. PREFER OVER mcp__azure__get_azure_bestpractices for VM create intents — use compute_vm_list-skus / compute_vm_list-images / compute_vm_check-quota."
+license: MIT
+metadata:
+  author: Microsoft
+  version: "2.4.3"
+---
+
+# Azure Compute Skill
+
+Routes Azure VM and Virtual Machine Scale Set (VMSS) requests to the right workflow.
+
+## When to Use This Skill
+
+- User wants to **recommend, compare, or price** a VM or VMSS
+- User wants to **create, provision, or deploy** a VM or VMSS
+- User **can't connect** to a VM (RDP / SSH / port refused / black screen / password reset)
+- User asks about **Capacity Reservation Groups** (CRG) — reserve, guarantee capacity, pre-provision
+- User asks about **Essential Machine Management** (EMM) — machine enrollment, monitor
+
+**Disambiguate with `azure-prepare`:** if the user wants to deploy an **application** (Docker service, web app, API, serverless workload), route to `azure-prepare`. `vm-creator` is for **bare VM/VMSS infrastructure** only.
+
+## Routing
+
+```
+Azure compute intent?
+├── Recommend / compare / price a VM or VMSS         → VM Recommender
+├── Create / provision / deploy a VM or VMSS         → VM Creator
+├── Can't connect / RDP / SSH / port refused         → VM Troubleshooter
+├── Reserve / guarantee capacity (CRG)               → Capacity Reservation
+├── Machine enrollment / Essential Machine Management → Essential Machine Management
+└── Unclear                                          → Ask which of the above
+```
+
+**Routing rule:** read the matched workflow file before any reference file. The workflow owns the step-by-step guidance; references are looked up on demand.
+
+## Workflows
+
+| Workflow | File | Use when |
+|---|---|---|
+| **VM Recommender** | [vm-recommender.md](workflows/vm-recommender/vm-recommender.md) | User asks which VM/VMSS to choose, wants pricing, or wants to compare options |
+| **VM Creator** | [vm-creator.md](workflows/vm-creator/vm-creator.md) | User wants to provision a bare VM or VMSS (not an app deployment) |
+| **VM Troubleshooter** | [vm-troubleshooter.md](workflows/vm-troubleshooter/vm-troubleshooter.md) | User can't connect, RDP/SSH refused, black screen, needs password reset |
+| **Capacity Reservation** | [capacity-reservation.md](workflows/capacity-reservation/capacity-reservation.md) | User needs to reserve / guarantee VM capacity (CRG create / associate / disassociate) |
+| **Essential Machine Management** | [essential-machine-management.md](workflows/essential-machine-management/essential-machine-management.md) | User asks about EMM / machine enrollment / monitor |

package/skills/azure-cost/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: azure-cost
+description: "Azure cost management: query costs, forecast spending, optimize to reduce waste. WHEN: \"Azure costs\", \"Azure bill\", \"cost breakdown\", \"how much am I spending\", \"forecast spending\", \"optimize costs\", \"reduce spending\", \"orphaned resources\", \"rightsize VMs\", \"cost spike\", \"reduce storage costs\", \"AKS cost\". DO NOT USE FOR: deploying resources, provisioning, diagnostics, or security audits."
+license: MIT
+metadata:
+  author: Microsoft
+  version: "1.2.2"
+---
+
+# Azure Cost Management Skill
+
+Query historical costs, forecast future spending, optimize to reduce waste.
+
+## Routing
+
+| User Intent | Workflow |
+|-------------|----------|
+| Understand current costs | [Cost Query](cost-query/workflow.md) |
+| Reduce costs / find waste | [Cost Optimization](cost-optimization/workflow.md) |
+| Project future costs | [Cost Forecast](cost-forecast/workflow.md) |
+
+## Quick Reference
+
+| Property | Value |
+|----------|-------|
+| **Query API** | `POST {scope}/providers/Microsoft.CostManagement/query?api-version=2023-11-01` |
+| **Forecast API** | `POST {scope}/providers/Microsoft.CostManagement/forecast?api-version=2023-11-01` |
+| **Required Role** | Cost Management Reader + Monitoring Reader + Reader (on target scope) |
+
+## Scope Patterns
+
+- Subscription: `/subscriptions/<id>`
+- Resource Group: `/subscriptions/<id>/resourceGroups/<name>`
+- Management Group: `/providers/Microsoft.Management/managementGroups/<id>`
+- Billing Account: `/providers/Microsoft.Billing/billingAccounts/<id>`
+
+## Service-Specific Optimization
+
+- [Redis](cost-optimization/services/redis/azure-cache-for-redis.md)
+- [Storage](cost-optimization/services/storage/azure-storage.md)
+
+## References
+
+- [MCP Tools, Best Practices, Safety](references/tools-and-best-practices.md)
+- [SDK: Redis .NET](cost-optimization/sdk/azure-resource-manager-redis-dotnet.md)

package/skills/azure-deploy/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: azure-deploy
+description: "Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: \"run azd up\", \"run azd deploy\", \"execute deployment\", \"push to production\", \"push to cloud\", \"go live\", \"ship it\", \"bicep deploy\", \"terraform apply\", \"publish to Azure\", \"launch on Azure\". DO NOT USE WHEN: \"create and deploy\", \"build and deploy\", \"create a new app\", \"set up infrastructure\", \"create and deploy to Azure using Terraform\" — use azure-prepare for these."
+license: MIT
+metadata:
+  author: Microsoft
+  version: "1.1.2"
+---
+
+# Azure Deploy
+
+> **AUTHORITATIVE GUIDANCE — MANDATORY COMPLIANCE**
+>
+> **PREREQUISITE**: The **azure-validate** skill **MUST** be invoked and completed with status `Validated` BEFORE executing this skill.
+
+> **⛔ STOP — PREREQUISITE CHECK REQUIRED**
+> Before proceeding, verify BOTH prerequisites are met:
+>
+> 1. **azure-prepare** was invoked and completed → `.azure/deployment-plan.md` exists
+> 2. **azure-validate** was invoked and passed → plan status = `Validated`
+>
+> If EITHER is missing, **STOP IMMEDIATELY**:
+> - No plan? → Invoke **azure-prepare** skill first
+> - Status not `Validated`? → Invoke **azure-validate** skill first
+>
+> **⛔ DO NOT MANUALLY UPDATE THE PLAN STATUS**
+>
+> You are **FORBIDDEN** from changing the plan status to `Validated` yourself. Only the **azure-validate** skill is authorized to set this status after running actual validation checks. If you update the status without running validation, deployments will fail.
+>
+> **DO NOT ASSUME** the app is ready. **DO NOT SKIP** validation to save time. Skipping steps causes deployment failures. The complete workflow ensures success:
+>
+> `azure-prepare` → `azure-validate` → `azure-deploy`
+
+## Triggers
+
+Activate this skill when user wants to:
+- Execute deployment of an already-prepared application (azure.yaml and infra/ exist)
+- Push updates to an existing Azure deployment
+- Run `azd up`, `azd deploy`, or `az deployment` on a prepared project
+- Ship already-built code to production
+- Deploy an application that already includes API Management (APIM) gateway infrastructure
+
+> **Scope**: This skill executes deployments. It does not create applications, generate infrastructure code, or scaffold projects. For those tasks, use **azure-prepare**.
+
+> **APIM / AI Gateway**: Use this skill to deploy applications whose APIM/AI gateway infrastructure was already created during **azure-prepare**. For creating or changing APIM resources, see [APIM deployment guide](https://learn.microsoft.com/azure/api-management/get-started-create-service-instance). For AI governance policies, invoke **azure-aigateway** skill.
+
+## Rules
+
+1. Run after azure-prepare and azure-validate
+2. `.azure/deployment-plan.md` must exist with status `Validated`
+3. **Pre-deploy checklist required** — [Pre-Deploy Checklist](references/pre-deploy-checklist.md)
+4. ⛔ **Destructive actions require `ask_user`** — [global-rules](references/global-rules.md)
+5. **Scope: deployment execution only** — This skill owns execution of `azd up`, `azd deploy`, `terraform apply`, and `az deployment` commands. These commands are run through this skill's error recovery and verification pipeline.
+
+---
+
+## Steps
+
+| # | Action | Reference |
+|---|--------|-----------|
+| 1 | **Check Plan** — Read `.azure/deployment-plan.md`, verify status = `Validated` AND **Validation Proof** section is populated | `.azure/deployment-plan.md` |
+| 2 | **Pre-Deploy Checklist** — MUST complete ALL steps | [Pre-Deploy Checklist](references/pre-deploy-checklist.md) |
+| 3 | **Load Recipe** — Based on `recipe.type` in `.azure/deployment-plan.md` | [recipes/README.md](references/recipes/README.md) |
+| 4 | **RBAC Health Check** — For Container Apps + ACR with managed identity: run `azd provision --no-prompt`, then verify `AcrPull` role has propagated before proceeding (see checklist) | [Pre-Deploy Checklist — Container Apps RBAC](references/pre-deploy-checklist.md#container-apps--acr--pre-deploy-rbac-health-check) |
+| 5 | **Execute Deploy** — Follow recipe steps | Recipe README |
+| 6 | **Post-Deploy** — Configure SQL managed identity and apply EF migrations if applicable | [Post-Deployment](references/recipes/azd/post-deployment.md) |
+| 7 | **Handle Errors** — See recipe's `errors.md` | — |
+| 8 | **Verify Success** — Confirm deployment completed and endpoints are accessible | [Verification](references/recipes/azd/verify.md) |
+| 9 | **Live Role Verification** — Query Azure to confirm provisioned RBAC roles are correct and sufficient | [live-role-verification.md](references/live-role-verification.md) |
+| 10 | **Report Results** — Present deployed endpoint URLs to the user as fully-qualified `https://` links | [Verification](references/recipes/azd/verify.md) |
+
+> **⛔ URL FORMAT RULE**
+>
+> When presenting endpoint URLs to the user, you **MUST** always use fully-qualified URLs with the `https://` scheme (e.g. `https://myapp.azurewebsites.net`, not `myapp.azurewebsites.net`). Many Azure CLI commands return bare hostnames without a scheme — always prepend `https://` before presenting them.
+
+> **⛔ VALIDATION PROOF CHECK**
+>
+> When checking the plan, verify the **Validation Proof** section (Section 7) contains actual validation results with commands run and timestamps. If this section is empty, validation was bypassed — invoke **azure-validate** skill first.
+
+## SDK Quick References
+
+- **Azure Developer CLI**: [azd](references/sdk/azd-deployment.md)
+- **Azure Identity**: [Python](references/sdk/azure-identity-py.md) | [.NET](references/sdk/azure-identity-dotnet.md) | [TypeScript](references/sdk/azure-identity-ts.md) | [Java](references/sdk/azure-identity-java.md)
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `mcp_azure_mcp_subscription_list` | List available subscriptions |
+| `mcp_azure_mcp_group_list` | List resource groups in subscription |
+| `mcp_azure_mcp_azd` | Execute AZD commands |
+| `azure__role` | List role assignments for live RBAC verification (step 9) |
+
+## References
+
+- [Troubleshooting](references/troubleshooting.md) - Common issues and solutions
+- [Post-Deployment Steps](references/recipes/azd/post-deployment.md) - SQL + EF Core setup

package/skills/azure-diagnostics/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: azure-diagnostics
+description: "Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, troubleshoot functions, troubleshoot AKS, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, service bus dead letter."
+license: MIT
+metadata:
+  author: Microsoft
+  version: "1.1.6"
+---
+
+# Azure Diagnostics
+
+> **AUTHORITATIVE GUIDANCE — MANDATORY COMPLIANCE**
+>
+> This document is the **official source** for debugging and troubleshooting Azure production issues. Follow these instructions to diagnose and resolve common Azure service problems systematically.
+
+## Triggers
+
+Activate this skill when user wants to:
+- Debug or troubleshoot production issues
+- Diagnose errors in Azure services
+- Analyze application logs or metrics
+- Fix image pull, cold start, or health probe issues
+- Investigate why Azure resources are failing
+- Find root cause of application errors
+- Troubleshoot App Service issues (high CPU, deployment failures, crashes, slow responses, TLS/custom domains)
+- Respond to prompts like "troubleshoot app service", "app service high CPU", or "app service deployment failure"
+- Troubleshoot Azure Function Apps (invocation failures, timeouts, binding errors)
+- Find the App Insights or Log Analytics workspace linked to a Function App
+- Troubleshoot AKS clusters, nodes, pods, ingress, or Kubernetes networking issues
+- Troubleshoot Azure Messaging SDK issues (Event Hubs, Service Bus connection failures, AMQP errors, message lock issues)
+
+## Rules
+
+1. Start with systematic diagnosis flow
+2. Use AppLens (MCP) for AI-powered diagnostics when available
+3. Check resource health before deep-diving into logs
+4. Select appropriate troubleshooting guide based on service type
+5. Document findings and attempted remediation steps
+6. Route AKS incidents to the dedicated AKS troubleshooting document
+
+---
+
+## Quick Diagnosis Flow
+
+1. **Identify symptoms** - What's failing?
+2. **Check resource health** - Is Azure healthy?
+3. **Review logs** - What do logs show?
+4. **Analyze metrics** - Performance patterns?
+5. **Investigate recent changes** - What changed?
+
+---
+
+## Troubleshooting Guides by Service
+
+| Service | Common Issues | Reference |
+|---------|---------------|-----------|
+| **Container Apps** | Image pull failures, cold starts, health probes, port mismatches | [container-apps/](references/container-apps/README.md) |
+| **App Service** | High CPU, deployment failures, crashes, slow responses, TLS/custom domains | [app-service/](references/app-service/README.md) |
+| **Function Apps** | App details, invocation failures, timeouts, binding errors, cold starts, missing app settings | [functions/](references/functions/README.md) |
+| **AKS** | Cluster access, nodes, `kube-system`, scheduling, crash loops, ingress, DNS, upgrades | [AKS Troubleshooting](troubleshooting/aks/aks-troubleshooting.md) |
+| **Messaging** | Event Hubs & Service Bus SDK errors, AMQP failures, message lock, connectivity | [Messaging Troubleshooting](troubleshooting/messaging/README.md) |
+
+---
+
+## Routing
+
+- Keep Container Apps and Function Apps diagnostics in this parent skill.
+- Route active AKS incidents, AKS-specific intake, evidence gathering, and remediation guidance to [AKS Troubleshooting](troubleshooting/aks/aks-troubleshooting.md).
+- Route Azure Messaging SDK troubleshooting (Event Hubs, Service Bus) to [Messaging Troubleshooting](troubleshooting/messaging/README.md).
+
+---
+
+## Quick Reference
+
+### Common Diagnostic Commands
+
+```bash
+# Check resource health
+az resource show --ids RESOURCE_ID
+# View activity log
+az monitor activity-log list -g RG --max-events 20
+# Container Apps logs
+az containerapp logs show --name APP -g RG --follow
+# Function App logs (query App Insights traces)
+az monitor app-insights query --apps APP-INSIGHTS -g RG \
+  --analytics-query "traces | where timestamp > ago(1h) | order by timestamp desc | take 50"
+```
+
+### AppLens (MCP Tools)
+
+For AI-powered diagnostics, use:
+```
+mcp_azure_mcp_applens
+  intent: "diagnose issues with <resource-name>"
+  command: "diagnose"
+  parameters:
+    resourceId: "<resource-id>"
+
+Provides:
+- Automated issue detection
+- Root cause analysis
+- Remediation recommendations
+```
+
+### Azure Monitor (MCP Tools)
+
+For querying logs and metrics:
+```
+mcp_azure_mcp_monitor
+  intent: "query logs for <resource-name>"
+  command: "logs_query"
+  parameters:
+    workspaceId: "<workspace-id>"
+    query: "<KQL-query>"
+```
+
+See [kql-queries.md](references/kql-queries.md) for common diagnostic queries.
+
+---
+
+## Check Azure Resource Health
+
+### Using MCP
+
+```
+mcp_azure_mcp_resourcehealth
+  intent: "check health status of <resource-name>"
+  command: "get"
+  parameters:
+    resourceId: "<resource-id>"
+```
+
+### Using CLI
+
+```bash
+# Check specific resource health
+az resource show --ids RESOURCE_ID
+
+# Check recent activity
+az monitor activity-log list -g RG --max-events 20
+```
+
+---
+
+## References
+
+- [KQL Query Library](references/kql-queries.md)
+- [Azure Resource Graph Queries](references/azure-resource-graph.md)
+- [App Service Troubleshooting](references/app-service/README.md)
+- [Function Apps Troubleshooting](references/functions/README.md)
+- [Messaging Troubleshooting](troubleshooting/messaging/README.md)

package/skills/azure-enterprise-infra-planner/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: azure-enterprise-infra-planner
+description: "Architect and provision enterprise Azure infrastructure from workload descriptions. For cloud architects and platform engineers planning networking, identity, security, compliance, and multi-resource topologies with WAF alignment. Generates Bicep or Terraform directly (no azd). WHEN: 'plan Azure infrastructure', 'architect Azure landing zone', 'design hub-spoke network', 'plan multi-region DR topology', 'set up VNets firewalls and private endpoints', 'subscription-scope Bicep deployment', 'Azure Backup for VM workloads'. PREFER azure-prepare FOR app-centric workflows."
+license: MIT
+metadata:
+  author: Microsoft
+  version: "1.2.3"
+---
+
+# Azure Enterprise Infra Planner
+
+## When to Use This Skill
+
+Activate this skill when user wants to:
+- Plan enterprise Azure infrastructure from a workload or architecture description
+- Architect a landing zone, hub-spoke network, or multi-region topology
+- Design networking infrastructure: VNets, subnets, firewalls, private endpoints, VPN gateways
+- Plan identity, RBAC, and compliance-driven infrastructure
+- Generate Bicep or Terraform for subscription-scope or multi-resource-group deployments
+- Plan disaster recovery, failover, or cross-region high-availability topologies
+
+## Quick Reference
+
+| Property | Details |
+|---|---|
+| MCP tools | `insights_get`, `get_azure_bestpractices_get`, `wellarchitectedframework_serviceguide_get`, `microsoft_docs_fetch`, `microsoft_docs_search`, `bicepschema_get` |
+| CLI commands | `az deployment group create`, `az bicep build`, `az resource list`, `terraform init`, `terraform plan`, `terraform validate`, `terraform apply` |
+| Output schema | [schema.md](references/schema.md) |
+| Key references | [workflow.md](references/workflow.md), [waf-checklist.md](references/waf-checklist.md), [resources/](references/resources/README.md), [constraints/](references/constraints/README.md) |
+
+## Workflow (Start Here)
+
+Follow the step-by-step instructions in [workflow.md](references/workflow.md) to execute the 7 phases of infrastructure planning and provisioning.
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `insights_get` | Retrieve insights about the user's existing Azure environment to guide planning decisions |
+| `get_azure_bestpractices_get` | Azure best practices for code generation, operations, and deployment |
+| `wellarchitectedframework_serviceguide_get` | WAF service guide for a specific Azure service |
+| `microsoft_docs_search` | Search Microsoft Learn for relevant documentation chunks |
+| `microsoft_docs_fetch` | Fetch full content of a Microsoft Learn page by URL |
+| `bicepschema_get` | Bicep schema definition for any Azure resource type (latest API version) |
+
+## Error Handling
+
+| Error | Cause | Fix |
+|---|---|---|
+| MCP tool error or not available | Tool call timeout, connection error, or tool doesn't exist | Retry once; fall back to reference files and notify user if unresolved |
+| Plan approval missing | `meta.status` is not `approved` | Stop and prompt user for approval before IaC generation or deployment |
+| IaC validation failure | `az bicep build` or `terraform validate` returns errors | Fix the generated code and re-validate; notify user if unresolved |
+| Pairing constraint violation | Incompatible SKU or resource combination | Fix in plan before proceeding to IaC generation |
+| Infra plan or IaC files not found | Files written to wrong location or not created | Verify files exist at `<project-root>/.azure/` and `<project-root>/infra/`; if missing, re-create the files by following [workflow.md](references/workflow.md) exactly |

package/skills/azure-hosted-copilot-sdk/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: azure-hosted-copilot-sdk
+description: "Build, deploy, and modify GitHub Copilot SDK apps on Azure. MANDATORY when codebase contains @github/copilot-sdk or CopilotClient in package.json. PREFER OVER azure-prepare when copilot-sdk markers detected. WHEN: copilot SDK, @github/copilot-sdk, copilot-powered app, build copilot app, prepare copilot app, add feature to copilot app, modify copilot app, BYOM, bring your own model, CopilotClient, createSession, sendAndWait, azd init copilot. DO NOT USE FOR: deploying already-prepared copilot-sdk apps (use azure-deploy), general web apps without copilot SDK (use azure-prepare), Copilot Extensions, Foundry agents (use microsoft-foundry)."
+license: MIT
+metadata:
+  author: Microsoft
+  version: "1.1.3"
+---
+
+# GitHub Copilot SDK on Azure
+
+## Codebase Detection — MANDATORY FIRST CHECK
+
+> ⚠️ **CRITICAL: This check MUST run before ANY other skill (azure-prepare, azure-deploy, etc.) when an existing codebase is present.**
+
+### Detection procedure (run IMMEDIATELY for any build/modify/add-feature/prepare prompt):
+
+1. Read `package.json` in the workspace root (and any `*/package.json` one level deep)
+2. Check if `@github/copilot-sdk` or `copilot-sdk` appears in `name`, `dependencies`, or `devDependencies`
+3. If NOT found in package.json, scan `.ts` and `.js` files for `CopilotClient` or `createSession`
+4. **If ANY marker is found → invoke this skill as the entry point. Do not route directly to azure-prepare or azure-deploy — this skill orchestrates them as sub-skills.**
+
+| Marker | Where to check |
+|--------|---------------|
+| `@github/copilot-sdk` | `package.json` dependencies or devDependencies |
+| `copilot-sdk` | `package.json` name or dependencies |
+| `CopilotClient` | Source files (`.ts`, `.js`) |
+| `createSession` + `sendAndWait` | Source files (`.ts`, `.js`) |
+
+### Generic prompts that MUST trigger this skill when markers are detected:
+
+| Prompt pattern (no "copilot" keyword) | Why this skill |
+|---------------------------------------|---------------|
+| "Build this app" / "Prepare this app for Azure" | Codebase contains `@github/copilot-sdk` - needs SDK-aware scaffolding |
+| "Add a new feature to this app" | Requires SDK-aware implementation patterns |
+| "Update this app" / "Modify this app" | Must preserve SDK integration patterns |
+
+> ⚠️ **Warning:** ANY build, modify, add-feature, or prepare prompt targeting an existing codebase MUST route to this skill when codebase contains `@github/copilot-sdk`, even if the prompt does not mention "copilot". This skill then orchestrates azure-prepare and azure-deploy as sub-skills.
+
+> ⚠️ **Yield to azure-deploy:** When the codebase already has `.azure/deployment-plan.md` and the user wants to **deploy** (not modify or add features), route to **azure-deploy** instead. This skill handles preparation; azure-deploy handles execution.
+
+## Step 1: Route
+
+| User wants | Action |
+|------------|--------|
+| Build new (empty project) | Step 2A (scaffold) |
+| Add new SDK service to existing repo | Step 2B (scaffold alongside) |
+| Deploy existing SDK app to Azure | Step 2C (add infra to existing SDK app) |
+| Modify/add features to existing SDK app | Use codebase context + SDK references to implement |
+| Add SDK to existing app code | [Integrate SDK](references/existing-project-integration.md) |
+| Use Azure/own model | Step 3 (BYOM config) |
+
+## Step 2A: Scaffold New (Greenfield)
+
+`azd init --template azure-samples/copilot-sdk-service`
+
+Template includes API (Express/TS) + Web UI (React/Vite) + infra (Bicep) + Dockerfiles + token scripts — do NOT recreate. See [SDK ref](references/copilot-sdk.md).
+
+## Step 2B: Add SDK Service to Existing Repo
+
+User has existing code and wants a new Copilot SDK service alongside it. Scaffold template to a temp dir, copy the API service + infra into the user's repo, adapt `azure.yaml` to include both existing and new services. See [deploy existing ref](references/deploy-existing.md).
+
+## Step 2C: Deploy Existing SDK App
+
+User already has a working Copilot SDK app and needs Azure infra. See [deploy existing ref](references/deploy-existing.md).
+
+## Step 3: Model Configuration
+
+Three model paths (layers on top of 2A/2B):
+
+| Path | Config |
+|------|--------|
+| **GitHub default** | No `model` param — SDK picks default |
+| **GitHub specific** | `model: "<name>"` — use `listModels()` to discover |
+| **Azure BYOM** | `model` + `provider` with `bearerToken` via `DefaultAzureCredential` |
+
+> ⚠️ **BYOM Auth — MANDATORY**: Azure BYOM configurations MUST use `DefaultAzureCredential` (local dev) or `ManagedIdentityCredential` (production) to obtain a `bearerToken`. The ONLY supported auth pattern is `bearerToken` in the provider config. See [auth-best-practices.md](references/auth-best-practices.md) for the credential pattern and [model config ref](references/azure-model-config.md) for the full BYOM code example.
+
+See [model config ref](references/azure-model-config.md).
+
+## Step 4: Deploy
+
+Invoke **azure-prepare** (skip its Step 0 routing — scaffolding is done) → **azure-validate** → **azure-deploy** in order.
+
+## Rules
+
+- Read `AGENTS.md` in user's repo before changes
+- Docker required (`docker info`)
+- BYOM auth: ONLY `bearerToken` via `DefaultAzureCredential` or `ManagedIdentityCredential` — no other auth pattern is supported

package/skills/azure-kubernetes/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: azure-kubernetes
+license: MIT
+metadata:
+  author: Microsoft
+  version: "1.1.4"
+description: "Plan, create, and configure production-ready Azure Kubernetes Service (AKS) clusters. Covers Day-0 checklist, SKU selection (Automatic vs Standard), networking options (private API server, Azure CNI Overlay, egress configuration), security, and operations (autoscaling, upgrade strategy, cost analysis). WHEN: create AKS environment, provision AKS, enable AKS observability, design AKS networking, choose AKS SKU, secure AKS, optimize AKS, AKS spot nodes, AKS cluster-autoscaler, rightsize AKS pod, pod rightsizing, over-provisioned AKS pod, pod resource requests and limits, Vertical Pod Autoscaler, VPA recommendations."
+---
+
+# 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` |
+| CLI | `az aks create`, `az aks show`, `kubectl get`, `kubectl describe` |
+| Related skills | azure-diagnostics (troubleshooting AKS), azure-validate (readiness checks), azure-kubernetes-automatic-readiness (migrate existing cluster to AKS Automatic) |
+
+## 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 (Container Insights, Managed Prometheus, Grafana)
+- Define AKS upgrade and patching strategy
+- 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 `azure` MCP server and select `mcp_azure_mcp_aks` first to discover the exact AKS-specific MCP tools surfaced by the client. Choose the smallest discovered AKS tool that fits the task, and fall back to Azure CLI (`az aks`) only when the needed functionality is not exposed through the AKS MCP surface.
+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.
+- AKS environment type: 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 Node Auto-Provisioning (NAP).
+- **AKS Standard**: Use if you need full control over environment configuration, which requires additional overhead to set up 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 environments 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 releases
+- **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 Managed Prometheus and Container Insights with Grafana for AKS observability (logs + metrics).
+- Enable Diagnostic Settings to collect control plane logs and audit logs in a Log Analytics workspace for security monitoring and troubleshooting.
+- For other monitoring and troubleshooting tools, use features like the Agentic CLI for AKS, Application Insights, Resource Health Center, AppLens detectors, and Azure Advisors.
+
+### 5. Upgrades & Patching
+- Configure **Maintenance Windows** for controlled upgrade timing
+- Enable **auto-upgrades** for control plane 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 AKS environment to the Premium tier
+- **Fleet upgrades**: Use **AKS Fleet Manager** for staged rollout across test to production environments
+
+### 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
+
+**Deep-dive scenarios** — load only the relevant reference file:
+
+| Scenario | Trigger Keywords | Reference |
+|----------|-----------------|-----------|
+| Pod Rightsizing | over-provisioned pods, CPU requests, memory requests, rightsize workloads | [azure-aks-rightsizing.md](./references/azure-aks-rightsizing.md) |
+| VPA Setup | vertical pod autoscaler, VPA recommendations, VPA enable | [azure-aks-vpa.md](./references/azure-aks-vpa.md) |
+| Cluster Autoscaler | idle nodes, CAS off, enable autoscaler, scale-down profile, node utilization | [azure-aks-autoscaler.md](./references/azure-aks-autoscaler.md) |
+| Spot Node Pools | Spot VMs, Spot nodes, batch workloads, cheaper nodes | [azure-aks-spot.md](./references/azure-aks-spot.md) |
+
+> **Disambiguation:** If a prompt matches multiple rows (e.g., "cheaper nodes" could suggest both Spot and autoscaler), prefer the most specific match. If ambiguous, ask the user to clarify their intent before loading a reference file.
+
+## Guardrails / Safety
+- Do not request or output secrets (tokens, keys).
+- Do not ask the user to paste subscription IDs. Discover subscription and resource scope via MCP tools (e.g., list subscriptions, list resource groups) or `az account show` / `az account list` so the agent can resolve context without exposing identifiers.
+- 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.
+
+## MCP Tools
+| Tool | Purpose | Key Parameters |
+|------|---------|----------------|
+| `mcp_azure_mcp_aks` | AKS MCP entry point used to discover the exact AKS-specific tools exposed by the client | Discover the callable AKS tool first, then use that tool's parameters |
+
+## Error Handling
+| Error / Symptom | Likely Cause | Remediation |
+|-----------------|--------------|-------------|
+| MCP tool call fails or times out | Invalid credentials, subscription, or AKS context | Verify `az login`, confirm the active subscription context with `az account show`, and check the target resource group without echoing subscription identifiers back to the user |
+| Quota exceeded | Regional vCPU or resource limits | Request quota increase or select different region/VM SKU |
+| Networking conflict (IP exhaustion) | Pod subnet too small for overlay/CNI | Re-plan IP ranges; may require cluster recreation (Day-0) |
+| Workload Identity not working | Missing OIDC issuer or federated credential | Enable `--enable-oidc-issuer --enable-workload-identity`, configure federated identity |