natureco-cli 5.18.3 → 5.19.0

package/skills/azure-aigateway/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: azure-aigateway
+description: "Configure Azure API Management as an AI Gateway for AI models, MCP tools, and agents. WHEN: semantic caching, token limit, content safety, load balancing, AI model governance, MCP rate limiting, jailbreak detection, add Azure OpenAI backend, add AI Foundry model, test AI gateway, LLM policies, configure AI backend, token metrics, AI cost control, convert API to MCP, import OpenAPI to gateway."
+license: MIT
+metadata:
+  author: Microsoft
+  version: "3.1.1"
+compatibility: Requires Azure CLI (az) for configuration and testing
+---
+
+# Azure AI Gateway
+
+Configure Azure API Management (APIM) as an AI Gateway for governing AI models, MCP tools, and agents.
+
+> **To deploy APIM**, use the **azure-prepare** skill. See [APIM deployment guide](https://learn.microsoft.com/azure/api-management/get-started-create-service-instance).
+
+## When to Use This Skill
+
+| Category | Triggers |
+|----------|----------|
+| **Model Governance** | "semantic caching", "token limits", "load balance AI", "track token usage" |
+| **Tool Governance** | "rate limit MCP", "protect my tools", "configure my tool", "convert API to MCP" |
+| **Agent Governance** | "content safety", "jailbreak detection", "filter harmful content" |
+| **Configuration** | "add Azure OpenAI backend", "configure my model", "add AI Foundry model" |
+| **Testing** | "test AI gateway", "call OpenAI through gateway" |
+
+---
+
+## Quick Reference
+
+| Policy | Purpose | Details |
+|--------|---------|---------|
+| `azure-openai-token-limit` | Cost control | [Model Policies](references/policies.md#token-rate-limiting) |
+| `azure-openai-semantic-cache-lookup/store` | 60-80% cost savings | [Model Policies](references/policies.md#semantic-caching) |
+| `azure-openai-emit-token-metric` | Observability | [Model Policies](references/policies.md#token-metrics) |
+| `llm-content-safety` | Safety & compliance | [Agent Policies](references/policies.md#content-safety) |
+| `rate-limit-by-key` | MCP/tool protection | [Tool Policies](references/policies.md#request-rate-limiting) |
+
+---
+
+## Get Gateway Details
+
+```bash
+# Get gateway URL
+az apim show --name <apim-name> --resource-group <rg> --query "gatewayUrl" -o tsv
+
+# List backends (AI models)
+az apim backend list --service-name <apim-name> --resource-group <rg> \
+  --query "[].{id:name, url:url}" -o table
+
+# Get subscription key
+az apim subscription keys list \
+  --service-name <apim-name> --resource-group <rg> --subscription-id <sub-id>
+```
+
+---
+
+## Test AI Endpoint
+
+```bash
+GATEWAY_URL=$(az apim show --name <apim-name> --resource-group <rg> --query "gatewayUrl" -o tsv)
+
+curl -X POST "${GATEWAY_URL}/openai/deployments/<deployment>/chat/completions?api-version=2024-02-01" \
+  -H "Content-Type: application/json" \
+  -H "Ocp-Apim-Subscription-Key: <key>" \
+  -d '{"messages": [{"role": "user", "content": "Hello"}], "max_tokens": 100}'
+```
+
+---
+
+## Common Tasks
+
+### Add AI Backend
+
+See [references/patterns.md](references/patterns.md#pattern-1-add-ai-model-backend) for full steps.
+
+```bash
+# Discover AI resources
+az cognitiveservices account list --query "[?kind=='OpenAI']" -o table
+
+# Create backend
+az apim backend create --service-name <apim> --resource-group <rg> \
+  --backend-id openai-backend --protocol http --url "https://<aoai>.openai.azure.com/openai"
+
+# Grant access (managed identity)
+az role assignment create --assignee <apim-principal-id> \
+  --role "Cognitive Services User" --scope <aoai-resource-id>
+```
+
+### Apply AI Governance Policy
+
+Recommended policy order in `<inbound>`:
+
+1. **Authentication** - Managed identity to backend
+2. **Semantic Cache Lookup** - Check cache before calling AI
+3. **Token Limits** - Cost control
+4. **Content Safety** - Filter harmful content
+5. **Backend Selection** - Load balancing
+6. **Metrics** - Token usage tracking
+
+See [references/policies.md](references/policies.md#combining-policies) for complete example.
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Token limit 429 | Increase `tokens-per-minute` or add load balancing |
+| No cache hits | Lower `score-threshold` to 0.7 |
+| Content false positives | Increase category thresholds (5-6) |
+| Backend auth 401 | Grant APIM "Cognitive Services User" role |
+
+See [references/troubleshooting.md](references/troubleshooting.md) for details.
+
+---
+
+## References
+
+- [**Detailed Policies**](references/policies.md) - Full policy examples
+- [**Configuration Patterns**](references/patterns.md) - Step-by-step patterns
+- [**Troubleshooting**](references/troubleshooting.md) - Common issues
+- [AI-Gateway Samples](https://github.com/Azure-Samples/AI-Gateway)
+- [GenAI Gateway Docs](https://learn.microsoft.com/azure/api-management/genai-gateway-capabilities)
+
+## SDK Quick References
+
+- **Content Safety**: [Python](references/sdk/azure-ai-contentsafety-py.md) | [TypeScript](references/sdk/azure-ai-contentsafety-ts.md)
+- **API Management**: [Python](references/sdk/azure-mgmt-apimanagement-py.md) | [.NET](references/sdk/azure-mgmt-apimanagement-dotnet.md)

package/skills/azure-cloud-migrate/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: azure-cloud-migrate
+description: "Assess and migrate cross-cloud workloads to Azure with reports and code conversion. Supports Lambda→Functions, Beanstalk/Heroku/App Engine→App Service, Fargate/Kubernetes/Cloud Run/Spring Boot→Container Apps. WHEN: migrate Lambda to Functions, AWS to Azure, migrate Beanstalk, migrate Heroku, migrate App Engine, Cloud Run migration, Fargate to ACA, ECS/Kubernetes/GKE/EKS to Container Apps, Spring Boot to Container Apps, cross-cloud migration."
+license: MIT
+metadata:
+  author: Microsoft
+  version: "1.2.1"
+---
+
+# Azure Cloud Migrate
+
+> This skill handles **assessment and code migration** of existing cloud workloads to Azure.
+
+## Rules
+
+1. Follow phases sequentially — do not skip
+2. Generate assessment before any code migration
+3. Load the scenario reference and follow its rules
+4. Use `mcp_azure_mcp_get_azure_bestpractices` and `mcp_azure_mcp_documentation` MCP tools
+5. Use the latest supported runtime for the target service
+6. Destructive actions require `ask_user` — [functions global-rules](references/services/functions/global-rules.md) | [app-service global-rules](references/services/app-service/global-rules.md)
+7. **Report progress to user** — During long-running operations (deployments, image pushes), provide resource-level status updates so the user is never left waiting without feedback — see [workflow-details.md](references/workflow-details.md)
+8. **Audit service discovery in app code** — Kubernetes DNS names (e.g., `http://order-service:3001`) do not resolve in Container Apps. During assessment, scan source code for hardcoded hostnames/ports in HTTP clients and flag them for env-var-driven URL injection
+
+## Migration Scenarios
+
+| Source | Target | Reference |
+|--------|--------|-----------|
+| AWS Lambda | Azure Functions | [lambda-to-functions.md](references/services/functions/lambda-to-functions.md) ([assessment](references/services/functions/assessment.md), [code-migration](references/services/functions/code-migration.md)) |
+| AWS Elastic Beanstalk | Azure App Service | [beanstalk-to-app-service.md](references/services/app-service/beanstalk-to-app-service.md) |
+| Heroku | Azure App Service | [heroku-to-app-service.md](references/services/app-service/heroku-to-app-service.md) |
+| Google App Engine | Azure App Service | [app-engine-to-app-service.md](references/services/app-service/app-engine-to-app-service.md) |
+| AWS Fargate (ECS) | Azure Container Apps | [fargate-to-container-apps.md](references/services/container-apps/fargate-to-container-apps.md) ([assessment](references/services/container-apps/fargate-assessment-guide.md), [deployment](references/services/container-apps/fargate-deployment-guide.md)) |
+| Kubernetes (GKE/EKS/Self-hosted) | Azure Container Apps | [k8s-to-container-apps.md](references/services/container-apps/k8s-to-container-apps.md) |
+| GCP Cloud Run | Azure Container Apps | [cloudrun-to-container-apps.md](references/services/container-apps/cloudrun-to-container-apps.md) |
+| Spring Boot (Azure Spring Apps/VMs) | Azure Container Apps | [spring-apps-to-aca.md](references/services/container-apps/spring-apps-to-aca.md) |
+
+> No matching scenario? Use `mcp_azure_mcp_documentation` and `mcp_azure_mcp_get_azure_bestpractices` tools.
+
+## Output Directory
+
+All output goes to `<workspace-root-basename>-azure/` at workspace root, where `<workspace-root-basename>` is the name of the top-level workspace directory itself (NOT a subdirectory within it). Never modify the source directory.
+
+## Steps
+
+1. **Create** `<workspace-root-basename>-azure/` at workspace root
+2. **Assess** — Analyze source, map services, generate report using the scenario-specific assessment guide → [functions assessment](references/services/functions/assessment.md) | [app-service assessment](references/services/app-service/assessment.md)
+3. **Migrate** — Convert code/config using the scenario-specific migration guide → [functions code-migration](references/services/functions/code-migration.md) | [app-service code-migration](references/services/app-service/code-migration.md)
+4. **Ask User** — "Migration complete. Test locally or deploy to Azure?"
+5. **Hand off** to azure-prepare for infrastructure, testing, and deployment
+
+Track progress in `migration-status.md` — see [workflow-details.md](references/workflow-details.md).

package/skills/azure-compliance/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: azure-compliance
+description: "Run Azure compliance and security audits with azqr plus Key Vault expiration checks. Covers best-practice assessment, resource review, policy/compliance validation, and security posture checks. WHEN: compliance scan, security audit, BEFORE running azqr (compliance cli tool), Azure best practices, Key Vault expiration check, expired certificates, expiring secrets, orphaned resources, compliance assessment."
+license: MIT
+metadata:
+  author: Microsoft
+  version: "1.1.1"
+---
+
+# Azure Compliance & Security Auditing
+
+## Quick Reference
+
+| Property | Details |
+|---|---|
+| Best for | Compliance scans, security audits, Key Vault expiration checks |
+| Primary capabilities | Comprehensive Resources Assessment, Key Vault Expiration Monitoring |
+| MCP tools | azqr, subscription and resource group listing, Key Vault item inspection |
+
+## When to Use This Skill
+
+- Run azqr or Azure Quick Review for compliance assessment
+- Validate Azure resource configuration against best practices
+- Identify orphaned or misconfigured resources
+- Audit Key Vault keys, secrets, and certificates for expiration
+
+## Skill Activation Triggers
+
+Activate this skill when user wants to:
+- Check Azure compliance or best practices
+- Assess Azure resources for configuration issues
+- Run azqr or Azure Quick Review
+- Identify orphaned or misconfigured resources
+- Review Azure security posture
+- "Show me expired certificates/keys/secrets in my Key Vault"
+- "Check what's expiring in the next 30 days"
+- "Audit my Key Vault for compliance"
+- "Find secrets without expiration dates"
+- "Check certificate expiration dates"
+
+## Prerequisites
+
+- Authentication: user is logged in to Azure via `az login`
+- Permissions to read resource configuration and Key Vault metadata
+
+## Assessments
+
+| Assessment | Reference |
+|------------|-----------|
+| Comprehensive Compliance (azqr) | [references/azure-quick-review.md](references/azure-quick-review.md) |
+| Key Vault Expiration | [references/azure-keyvault-expiration-audit.md](references/azure-keyvault-expiration-audit.md) |
+| Resource Graph Queries | [references/azure-resource-graph.md](references/azure-resource-graph.md) |
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `mcp_azure_mcp_extension_azqr` | Run azqr compliance scans |
+| `mcp_azure_mcp_subscription_list` | List available subscriptions |
+| `mcp_azure_mcp_group_list` | List resource groups |
+| `keyvault_key_list` | List all keys in vault |
+| `keyvault_key_get` | Get key details including expiration |
+| `keyvault_secret_list` | List all secrets in vault |
+| `keyvault_secret_get` | Get secret details including expiration |
+| `keyvault_certificate_list` | List all certificates in vault |
+| `keyvault_certificate_get` | Get certificate details including expiration |
+
+## Assessment Workflow
+
+1. Select scope (subscription or resource group) for Comprehensive Resources Assessment.
+2. Run azqr and capture output artifacts.
+3. Analyze Scan Results and summarize findings and recommendations.
+4. Review Key Vault Expiration Monitoring output for keys, secrets, and certificates.
+5. Classify issues and propose remediation or fix steps for each finding.
+
+### Priority Classification
+
+| Priority | Guidance |
+|---|---|
+| Critical | Immediate remediation required for high-impact exposure |
+| High | Resolve within days to reduce risk |
+| Medium | Plan a resolution in the next sprint |
+| Low | Track and fix during regular maintenance |
+
+## Error Handling
+
+| Error | Message | Remediation |
+|---|---|---|
+| Authentication required | "Please login" | Run `az login` and retry |
+| Access denied | "Forbidden" | Confirm permissions and fix role assignments |
+| Missing resource | "Not found" | Verify subscription and resource group selection |
+
+## Best Practices
+
+- Run compliance scans on a regular schedule (weekly or monthly)
+- Track findings over time and verify remediation effectiveness
+- Separate compliance reporting from remediation execution
+- Keep Key Vault expiration policies documented and enforced
+
+## SDK Quick References
+
+For programmatic Key Vault access, see the condensed SDK guides:
+
+- **Key Vault (Python)**: [Secrets/Keys/Certs](references/sdk/azure-keyvault-py.md)
+- **Secrets**: [TypeScript](references/sdk/azure-keyvault-secrets-ts.md) | [Rust](references/sdk/azure-keyvault-secrets-rust.md) | [Java](references/sdk/azure-security-keyvault-secrets-java.md)
+- **Keys**: [.NET](references/sdk/azure-security-keyvault-keys-dotnet.md) | [Java](references/sdk/azure-security-keyvault-keys-java.md) | [TypeScript](references/sdk/azure-keyvault-keys-ts.md) | [Rust](references/sdk/azure-keyvault-keys-rust.md)
+- **Certificates**: [Rust](references/sdk/azure-keyvault-certificates-rust.md)
+

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)