jonathan-vella

Authoritative reference for VS Code Copilot customization mechanisms: instructions, prompt files, custom agents, agent skills, MCP servers, hooks, and plugins. Use when deciding which customization type to use, creating new .instructions.md/.prompt.md/.agent.md/SKILL.md/mcp.json files from scratch, or debugging why a customization is not loading. DO NOT USE FOR: routine file edits where the format is already known.

**UTILITY SKILL** — Two-mode context-window management. RUNTIME: artifact compression (full/summarized/minimal) used by orchestrator and codegen agents. AUDIT: post-mortem analysis of Copilot debug logs (token profiling, redundancy + hand-off gap detection) used by 11-Context Optimizer. WHEN: "context optimization", "token budget", "runtime compression", "log parsing". DO NOT USE FOR: infra, IaC code, deployments.

**WORKFLOW SKILL** — Maintains repository documentation accuracy and freshness across the docs site, agent files, and changelog. WHEN: "update docs", "doc gardening", "staleness check", "changelog entry", "repo explanation", "agent change docs", "skill change docs". DO NOT USE FOR: agent definitions (edit `.agent.md` directly), SKILL.md content authoring, site theme/build.

**ANALYSIS SKILL** — Query official Microsoft documentation to understand concepts, find tutorials, and learn how services work. WHEN: "Microsoft Learn", "Azure docs", "quickstart guide", "limits and quotas", "WAF reference", "architecture pattern docs". DO NOT USE FOR: Azure pricing (use azure-pricing MCP).

**ANALYSIS SKILL** — Audit-grade reference for Anthropic Claude and OpenAI GPT-5.5 prompting best practices. WHEN: "claude prompting", "gpt-5.5 prompting", "audit agent", "review prompt", "vendor best practices", "anthropic best practices", "openai prompting". DO NOT USE FOR: routine prompt edits where rules are already known, generic markdown style (markdown.instructions.md).

**UTILITY SKILL** — Machine-readable workflow DAG for the multi-step agent pipeline. Defines node types, edge conditions, gates, and fan-out patterns. WHEN: "orchestrator step routing", "resume from graph", "workflow validation", "workflow DAG", "workflow gate", "fan-out pattern". USE FOR: orchestrator step routing, resume-from-graph, workflow validation. DO NOT USE FOR: Azure infrastructure, code generation, troubleshooting.

**UTILITY SKILL** — Reusable Azure Bicep patterns: hub-spoke, private endpoints, diagnostics, AVM composition. WHEN: "hub-spoke Bicep", "private endpoint module", "diagnostic settings", "AVM Bicep composition". USE FOR: Bicep template design, hub-spoke networking, private endpoint patterns, AVM modules. DO NOT USE FOR: Terraform code (use terraform-patterns), architecture decisions (use azure-adr), troubleshooting, diagram generation (use drawio).

**UTILITY SKILL** — Azure infrastructure defaults: regions, tags, naming (CAF), AVM-first policy, security baseline, unique suffix patterns. WHEN: "Azure naming convention", "CAF naming", "resource tags", "AVM module", "security baseline", "region default". USE FOR: any agent generating or planning Azure resources. DO NOT USE FOR: artifact template structures (use azure-artifacts), pricing lookups (read references/pricing-guidance.md on demand).

Shared IaC deploy patterns for Bicep and Terraform deploy agents: deployment strategies, circuit breaker, known deploy issues. For preflight validation (auth, governance, stop rules), see azure-validate. USE FOR: Phased deployment, circuit breaker, deploy-specific known issues. DO NOT USE FOR: Preflight validation (use azure-validate), code generation (use azure-bicep-patterns or terraform-patterns).

Guidance for instrumenting webapps with Azure Application Insights. Provides telemetry patterns, SDK setup, and configuration references. WHEN: how to instrument app, App Insights SDK, telemetry patterns, what is App Insights, Application Insights guidance, instrumentation examples, APM best practices.

Creates Azure Architecture Decision Records with WAF mapping, alternatives, and consequences. USE FOR: ADR creation, architecture decisions, trade-off analysis, WAF pillar justification. DO NOT USE FOR: Bicep/Terraform code generation, diagram creation, cost estimates.

Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.

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.

Artifact template structures, H2 compliance rules, and documentation styling for agent outputs (Steps 1-7). USE FOR: generating any agent artifact, checking H2 structure compliance. DO NOT USE FOR: Azure resource configuration (use azure-defaults), Bicep/Terraform patterns (use bicep-patterns or terraform-patterns).

Reusable Azure Bicep patterns: hub-spoke, private endpoints, diagnostics, AVM composition. USE FOR: Bicep template design, hub-spoke networking, private endpoint patterns, AVM modules. DO NOT USE FOR: Terraform code, architecture decisions, troubleshooting, diagram generation.

Assess and migrate cross-cloud workloads to Azure. Generates assessment reports and converts code from AWS, GCP, or other providers to Azure services. WHEN: migrate Lambda to Azure Functions, migrate AWS to Azure, Lambda migration assessment, convert AWS serverless to Azure, migration readiness report, migrate from AWS, migrate from GCP, cross-cloud migration.

Creates Azure Architecture Decision Records (ADRs) with WAF mapping, alternatives, consequences, and implementation guidance; use for architecture decision documentation requests.

Defines canonical artifact templates, H2 structures, and documentation styling rules for agent outputs (Steps 1-7); use for artifact generation, formatting, and template compliance.

Provides Azure defaults for naming, regions, tags, AVM-first modules, security baselines, WAF criteria, governance discovery, and pricing guidance across all agents.

Azure resource troubleshooting patterns including KQL templates, metric thresholds, health checks, and remediation playbooks. Use when diagnosing unhealthy Azure resources or building diagnostic workflows.

Maintains repository documentation accuracy and freshness; use for doc updates, agent or skill changes, staleness checks, changelog entries, and repo explanation requests.

Handles GitHub issues, pull requests, repositories, Actions, releases, and API tasks using MCP-first workflows with gh CLI fallback for advanced operations.

HackOps platform business rules, role matrix, lifecycle states, and scoring invariants. Use when building API routes, writing tests, or validating business logic for the HackOps hackathon management platform. Keywords: hackathon, team, coach, hacker, admin, rubric, scoring, leaderboard, event code, progression.

Next.js 15+ App Router patterns for the HackOps platform. Covers route handlers, server/client components, middleware, layouts, and data fetching. Use when building pages, API routes, or debugging Next.js behavior. Keywords: Next.js, App Router, route handler, server component, client component, middleware, layout, RSC.

**WORKFLOW SKILL** — Plan, create, and operate AKS (Arc) clusters on Azure Local: requirements, create via portal/CLI/API, node pools & autoscaling, upgrades, networking, storage, security/identity, and monitoring. WHEN: "AKS on Azure Local", "AKS Arc", "create AKS cluster Azure Local", "Kubernetes on Azure Local", "AKS hybrid", "node pool Azure Local", "autoscale AKS Arc", "upgrade AKS Arc cluster". USE FOR: AKS cluster lifecycle on Azure Local. DO NOT USE FOR: AKS in Azure cloud (use azure-kubernetes), model serving on AKS (use airunway-aks-setup).

**WORKFLOW SKILL** — Deploy an Azure Local instance via Azure portal or ARM template: prerequisites, software download, OS install, Arc registration, and cloud deployment. WHEN: "deploy Azure Local", "install Azure Local", "Azure Local deployment", "deploy via portal", "Azure Local ARM template", "register Azure Local with Arc", "download Azure Local software". USE FOR: running a fresh Azure Local 23H2+ deployment end to end. DO NOT USE FOR: planning/sizing (use azlocal-plan-size), SFF edge devices (use azlocal-sff), AKS clusters (use aksarc-on-azure-local).

**WORKFLOW SKILL** — Deploy and operate Azure Local Small Form Factor (SFF) for ruggedized/edge single-host scenarios: subscription setup, install (incl. in a VM), connect via portal, run containerized/GPU workloads, and troubleshoot. WHEN: "Azure Local small form factor", "SFF Azure Local", "ruggedized Azure Local", "edge single host Azure Local", "SFF install", "SFF in a VM", "SFF configurator app", "SFF containerized workloads". USE FOR: SFF edge/single-host evaluation and operation. DO NOT USE FOR: multi-node cluster deployment (use azlocal-deploy).

**ANALYSIS SKILL** — Troubleshoot Azure Local deployment, registration, and update failures: collect logs, use the diagnostic support tools, and open support. WHEN: "troubleshoot Azure Local", "Azure Local deployment failed", "collect logs Azure Local", "Azure Local registration issue", "deployment validation failed", "diagnostic support tool", "update failed Azure Local", "Configurator app issue". USE FOR: diagnosing Azure Local infrastructure failures. DO NOT USE FOR: tenant app/Kubernetes debugging (use azure-diagnostics).

**WORKFLOW SKILL** — Create and manage Arc VMs on Azure Local (single or at scale via Bicep): VM images, logical networks, NICs, GPU (DDA/partitioning), and Trusted Launch. WHEN: "create Azure Local VM", "create Azure Local VMs at scale", "Azure Local VM Bicep", "deploy multiple Azure Local VMs", "Arc VM Azure Local", "manage Azure Local VMs", "Azure Local VM image", "attach GPU Azure Local", "GPU partitioning Azure Local", "Trusted Launch Azure Local", "VM extensions Azure Local". USE FOR: Arc VM lifecycle and at-scale Bicep VM deployment on an Azure Local instance. DO NOT USE FOR: cluster networking design (use azlocal-networking), choosing a workload type (use azlocal-workloads).

**WORKFLOW SKILL** — Run workloads on Azure Local: Arc VMs, AKS clusters, SQL Server, and Azure Virtual Desktop (AVD). Routes to the right workload path. WHEN: "run workloads on Azure Local", "AVD on Azure Local", "Azure Virtual Desktop Azure Local", "SQL Server on Azure Local", "run AKS on Azure Local", "deploy app to Azure Local", "workloads Azure Local". USE FOR: choosing and starting a workload type on an existing instance. DO NOT USE FOR: deep AKS cluster lifecycle (use aksarc-on-azure-local), VM image/NIC lifecycle (use azlocal-vm-management).

**WORKFLOW SKILL** — Configure Azure Local host and tenant networking: Network ATC intents, software-defined networking (SDN), Network Controller, datacenter firewall, and network security groups (NSGs). WHEN: "Azure Local networking", "Network ATC", "configure SDN Azure Local", "Network Controller", "datacenter firewall", "network security groups Azure Local", "NSG Azure Local", "logical networks Azure Local". USE FOR: host networking intents and tenant SDN/firewall/NSG configuration. DO NOT USE FOR: VM lifecycle (use azlocal-vm-management), cloud Azure networking (use azure-enterprise-infra-planner).

**ANALYSIS SKILL** — Manage Azure Local security: security baseline/defaults, BitLocker encryption, Secure Boot, Microsoft Defender for Cloud, and compliance assurance (ISO 27001, PCI DSS, HIPAA, FedRAMP). WHEN: "Azure Local security", "security baseline Azure Local", "BitLocker Azure Local", "Secure Boot Azure Local", "Defender for Cloud Azure Local", "Azure Local compliance", "application control WDAC". USE FOR: hardening an Azure Local instance and mapping to compliance standards. DO NOT USE FOR: cloud subscription compliance scans (use azure-compliance).

**ANALYSIS SKILL** — Audit-grade reference for Anthropic Claude and OpenAI GPT-5.5 prompting best practices. WHEN: "claude prompting", "gpt-5.5 prompting", "audit agent", "review prompt", "vendor best practices", "anthropic best practices", "openai prompting". DO NOT USE FOR: routine prompt edits where rules are already known, generic markdown style (markdown.instructions.md).

**UTILITY SKILL** — Artifact template structures, H2 compliance rules, and documentation styling for agent outputs (Steps 1-7). WHEN: "generate artifact", "check H2 structure", "artifact template", "step 7 as-built". USE FOR: generating any agent artifact, checking H2 structure compliance. DO NOT USE FOR: Azure resource configuration (use azure-defaults), Bicep/Terraform patterns (use azure-bicep-patterns or terraform-patterns).

**UTILITY SKILL** — Azure infrastructure defaults: regions, tags, naming (CAF), AVM-first policy, security baseline, unique suffix patterns. WHEN: "Azure naming convention", "CAF naming", "resource tags", "AVM module", "security baseline", "region default". USE FOR: any agent generating or planning Azure resources. DO NOT USE FOR: artifact template structures (use azure-artifacts), pricing lookups (read references/pricing-guidance.md on demand).

**WORKFLOW SKILL** — Maintains repository documentation accuracy and freshness across the docs site, agent files, and changelog. WHEN: "update docs", "doc gardening", "staleness check", "changelog entry", "repo explanation", "agent change docs", "skill change docs". DO NOT USE FOR: agent definitions (edit `.agent.md` directly), SKILL.md content authoring, site theme/build.

**UTILITY SKILL** — Shared IaC deploy patterns for Bicep + Terraform agents: deployment strategies, circuit breaker, known deploy issues. WHEN: "phased deployment", "circuit breaker", "deploy strategy", "deploy issue", "shared IaC pattern". DO NOT USE FOR: preflight (azure-validate), code generation (azure-bicep-patterns / terraform-patterns).

**UTILITY SKILL** — Reusable Azure Bicep patterns: hub-spoke, private endpoints, diagnostics, AVM composition. WHEN: "hub-spoke Bicep", "private endpoint module", "diagnostic settings", "AVM Bicep composition". USE FOR: Bicep template design, hub-spoke networking, private endpoint patterns, AVM modules. DO NOT USE FOR: Terraform code (use terraform-patterns), architecture decisions (use azure-adr), troubleshooting, diagram generation (use drawio).

**UTILITY SKILL** — Two-mode context-window management. RUNTIME: artifact compression (full/summarized/minimal) used by orchestrator and codegen agents. AUDIT: post-mortem analysis of Copilot debug logs (token profiling, redundancy + hand-off gap detection) used by 11-Context Optimizer. WHEN: "context optimization", "token budget", "runtime compression", "log parsing". DO NOT USE FOR: infra, IaC code, deployments.

**ANALYSIS SKILL** — Query official Microsoft documentation to understand concepts, find tutorials, and learn how services work. WHEN: "Microsoft Learn", "Azure docs", "quickstart guide", "limits and quotas", "WAF reference", "architecture pattern docs". DO NOT USE FOR: Azure pricing (use azure-pricing MCP).

Creates Azure Architecture Decision Records (ADRs) with WAF mapping, alternatives, consequences, and implementation guidance; use for architecture decision documentation requests.

Defines canonical artifact templates, H2 structures, and documentation styling rules for agent outputs (Steps 1-7); use for artifact generation, formatting, and template compliance.

Provides Azure defaults for naming, regions, tags, AVM-first modules, security baselines, WAF criteria, governance discovery, and pricing guidance across all agents.

Azure architecture diagram generation skill for high-quality, non-Mermaid outputs. Produces deterministic Python `diagrams` + Graphviz artifacts (`.py` + `.png`/`.svg`) for design and as-built documentation. Use for Step 3 and Step 7 architecture visuals, dependency visuals, and topology diagrams with enforced layout and naming conventions.

Maintains repository documentation accuracy and freshness; use for doc updates, staleness checks, changelog entries, and repo explanation requests.

Creates conventional commits with diff-aware message generation and intelligent staging; use when users ask to commit changes or invoke /commit.

Handles GitHub issues, pull requests, repositories, Actions, releases, and API tasks using MCP-first workflows with gh CLI fallback for advanced operations.

Guides Astro Starlight site changes using current docs via the Astro MCP server.

Applies the workshop challenge template and visual polish consistently across challenge guides.

Maintains workshop documentation accuracy, consistency, and freshness.

Scaffolds new repository-aligned skills.

Produces workshop-focused architecture and migration diagrams.

Creates conventional commits with diff-aware message generation.

Handles GitHub issues, pull requests, releases, and search workflows.

Artifact template structures, H2 compliance rules, and documentation styling for agent outputs (Steps 1-7). USE FOR: generating any agent artifact, checking H2 structure compliance. DO NOT USE FOR: Azure resource configuration (use azure-defaults), Bicep/Terraform patterns (use bicep-patterns or terraform-patterns).

Reusable Azure Bicep patterns: hub-spoke, private endpoints, diagnostics, AVM composition. USE FOR: Bicep template design, hub-spoke networking, private endpoint patterns, AVM modules. DO NOT USE FOR: Terraform code, architecture decisions, troubleshooting, diagram generation.

Prepare Azure apps for deployment (infra Bicep/Terraform, azure.yaml, Dockerfiles). Use for create/modernize or create+deploy; not cross-cloud migration (use azure-cloud-migrate). WHEN: "create app", "build web app", "create API", "create serverless HTTP API", "create frontend", "create back end", "build a service", "modernize application", "update application", "add authentication", "add caching", "host on Azure", "create and deploy", "deploy to Azure", "deploy to Azure using Terraform", "deploy to Azure App Service", "deploy to Azure App Service using Terraform", "deploy to Azure Container Apps", "deploy to Azure Container Apps using Terraform", "generate Terraform", "generate Bicep", "function app", "timer trigger", "service bus trigger", "event-driven function", "containerized Node.js app", "social media app", "static portfolio website", "todo list with frontend and API", "prepare my Azure application to use Key Vault", "managed identity".

Shared IaC deploy patterns for Bicep and Terraform deploy agents: deployment strategies, circuit breaker, known deploy issues. For preflight validation (auth, governance, stop rules), see azure-validate. USE FOR: Phased deployment, circuit breaker, deploy-specific known issues. DO NOT USE FOR: Preflight validation (use azure-validate), code generation (use azure-bicep-patterns or terraform-patterns).

Reusable Azure Terraform patterns: hub-spoke, private endpoints, diagnostics, AVM-TF modules. USE FOR: Terraform template design, hub-spoke networking, AVM modules, plan interpretation. DO NOT USE FOR: Bicep code, architecture decisions, troubleshooting, diagram generation.

Validate Pi-hole + Unbound suite changes. Use when: checking installer dry-run safety, DNS health, root-owned runtime paths, backups, auto-update, root hints, rescue workflows, or release readiness for this repository.

Safely validate the production Raspberry Pi 4 Pi-hole + Unbound host. Use when: checking live DNS, systemd, cron, root-owned runtime files, auto-update, root hints, Python API, or post-install health without destructive changes.

Validate Unbound recursive DNS changes in this Pi-hole suite. Use when: checking Unbound config, port 5335, DNSSEC, root hints refresh, unbound-checkconf, rollback safety, Pi-hole upstream integration, or DNS health.

Compare the current asset-manager workspace against one of the workshop reference branches (workshop/java-upgrade, workshop/expected, workshop/deployment-expected) so users can self-check migration progress. Use when the user asks "how far am I", "what should I have changed", "what does the expected state look like", or wants a checkpoint diff during the GitHub Copilot app modernization workshop.