microsoft · deankroker · May 21, 2026 · May 21, 2026 · Jun 8, 2026 · Jun 8, 2026
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -13,6 +13,7 @@
 /plugin/skills/appinsights-instrumentation/ @JasonYeMSFT @RickWinter
 /plugin/skills/azure-ai/ @JasonYeMSFT @RickWinter
 /plugin/skills/azure-aigateway/ @azaslonov @RickWinter
+/plugin/skills/azure-arc-servers/ @deankroker @ryperl_msft @rebro2-msft @jackier @RickWinter
 /plugin/skills/azure-cloud-migrate/ @saikoumudi @MadhuraBharadwaj-MSFT @RickWinter
 /plugin/skills/azure-compliance/ @saikoumudi @RickWinter
 /plugin/skills/azure-compute/ @alex-thompson @rakal-dyh @joybb @rmmue21 @RickWinter

@@ -0,0 +1,87 @@
+---
+name: azure-arc-servers
+description: "Azure Arc-enabled servers router. WHEN: Arc Server, Arc-enabled server, Connected Machine agent, azcmagent, hybrid server, on-prem server, onboard to Arc, project a server into Azure, connect machine to Azure, install Connected Machine agent, generate onboarding script, at-scale onboarding, Group Policy onboarding, Configuration Manager onboarding, Ansible onboarding, Service Principal for Arc, Arc Private Link Scope, Arc Gateway, proxy for Arc, agent connectivity, agent status, Connected / Disconnected / Expired / Error, agent upgrade, automatic upgrade, manual upgrade, Extended Security Updates (ESU) for Arc, Hotpatch on Arc, Pay-as-you-go Windows Server, Software Assurance benefits, Microsoft.HybridCompute, hybridcompute/machines. PREFER OVER azure-compute when the user is talking about non-Azure (on-prem, other-cloud, edge) servers being projected into Azure - not about creating an Azure VM."
+license: MIT
+metadata:
+  author: Microsoft
+  version: "0.0.0-placeholder"
+---
+
+# Azure Arc-Enabled Servers Skill
+
+Routes Azure Arc server (Connected Machine) requests to the right workflow.
+
+## When to use this skill
+
+Use this skill when the user is talking about **servers that live outside
+of Azure compute** (on-prem, AWS / GCP, edge, customer datacenter) and
+wants to **project them into Azure** so they can be managed with Azure
+control plane tools (Policy, Update Manager, Monitor, Defender, etc.).
+
+The defining ARM resource type is `Microsoft.HybridCompute/machines`.
+The defining agent is `azcmagent` (Azure Connected Machine agent).
+
+> **Disambiguate with `azure-compute`.** If the user wants to create a
+> brand-new VM **inside Azure** (`Microsoft.Compute/virtualMachines`),
+> route to `azure-compute`. Arc servers are **never** new VMs - the
+> machine already exists.
+
+> **Disambiguate with `azure-local` / `arc-vmware` / `arc-scvmm`.** Those
+> skills handle Arc-enabled infrastructure where Azure stamps **new** VMs
+> on customer hardware through a Resource Bridge / Custom Location. This
+> skill is for the simpler case where a machine already exists and just
+> needs an agent installed.
+
+## Routing
+
+```text
+Arc server intent?
+├── Connect / onboard / install agent / generate script (one machine or many)
+│   → arc-server-onboard
+│
+├── Agent shows Disconnected / Expired / Error
+│   Can't reach Azure / azcmagent connect fails / port blocked
+│   → arc-server-troubleshoot
+│
+├── Upgrade the agent / enable auto-upgrade
+│   Buy / activate Extended Security Updates (ESU)
+│   Enable Hotpatch / Pay-as-you-go Windows Server licensing
+│   → arc-server-manage
+│
+└── Unclear → ask which of the three above
+```
+
+**Routing rule.** Read the matched workflow file *before* any reference
+file. The workflow file owns the step-by-step guidance; references are
+looked up on demand from inside the workflow.
+
+## Workflows
+
+| Workflow | File | Use when |
+|---|---|---|
+| **Onboard** | [arc-server-onboard.md](workflows/arc-server-onboard/arc-server-onboard.md) | User wants to connect one or many existing servers to Azure Arc. Generates the install script and walks the connectivity / auth / management-service choices. |
+| **Troubleshoot** | [arc-server-troubleshoot.md](workflows/arc-server-troubleshoot/arc-server-troubleshoot.md) | Agent status is not `Connected`, install failed, machine fell offline, or extensions won't deploy. |
+| **Manage** | [arc-server-manage.md](workflows/arc-server-manage/arc-server-manage.md) | Day-2 operations: agent upgrades, ESU licensing, Hotpatch, Pay-as-you-go Windows Server, recommended policies, management services (Update Manager, Insights, Change Tracking, Defender, Machine Config). |
+
+## Skill-level references
+
+These references describe concepts that apply across all workflows. Load
+them on demand if the user asks the underlying question.
+
+| Reference | Use when |
+|---|---|
+| [arc-vs-azure-vm.md](references/arc-vs-azure-vm.md) | User is confused about Arc vs Azure VM, asks "should I use Arc or just create a VM", or talks about Arc as if it were a VM service. |
+| [arc-mcp-tools.md](references/arc-mcp-tools.md) | Lookup of Azure MCP and `az` CLI commands for `Microsoft.HybridCompute`. Read before invoking tools. |
+
+## Out of scope for this skill
+
+| Request | Route to |
+|---|---|
+| Create / size / price an Azure VM | `azure-compute` |
+| Azure Local cluster, Arc VM on HCI | `azure-local` (proposed) |
+| Arc-enabled VMware vCenter | `arc-vmware` (proposed) |
+| Arc-enabled SCVMM | `arc-scvmm` (proposed) |
+| Arc Appliance / Resource Bridge | `arc-resource-bridge` (proposed) |
+| AWS / GCP multi-cloud connector | `arc-multicloud` (proposed) |
+| Deploy an application onto an Arc server | `azure-prepare` (then this skill for Arc-specific prereqs) |
+| Essential Machine Management subscription enrollment | `azure-compute` → `essential-machine-management` workflow |
@@ -0,0 +1,147 @@
+# Azure MCP and CLI Tools for Arc Servers
+
+Lookup table for the tools workflows in this skill use. Read this before
+invoking a tool you're not sure about.
+
+> **MCP first, CLI fallback.** Prefer Azure MCP server tools when
+> available. They return structured data and respect the user's MCP
+> auth. Fall back to `az` CLI when MCP coverage is missing.
+
+## Read-only MCP tools (safe to call without confirmation)
+
+| Tool | Purpose |
+|---|---|
+| `mcp__azure__subscription_list` | List subscriptions for the signed-in user. Always use to confirm which subscription owns the Arc machine. |
+| `mcp__azure__group_list` | List resource groups in a subscription. |
+| `mcp__azure__resource_list` | List resources of any type. Filter by `resourceType = "Microsoft.HybridCompute/machines"` to enumerate Arc servers in a sub or RG. |
+| `mcp__azure__resource_show` | Show full ARM properties of an Arc machine. Use to inspect `status`, `agentVersion`, `lastStatusChange`, `errorDetails`. |
+| `mcp__azure__role_assignment_list` | Verify the user / Service Principal has the right roles on the target RG (Azure Connected Machine Onboarding, Azure Connected Machine Resource Administrator). |
+| `mcp__azure__resourcegraph_query` | Run KQL across many subs at once. The best way to scan a fleet. |
+
+### Useful Resource Graph (KQL) queries
+
+```kql
+// All Arc machines and their connection status
+resources
+| where type =~ "microsoft.hybridcompute/machines"
+| project id, name, resourceGroup, subscriptionId, location,
+          status = properties.status,
+          agentVersion = properties.agentVersion,
+          osName = properties.osName,
+          osVersion = properties.osVersion,
+          lastStatusChange = properties.lastStatusChange,
+          errorDetails = properties.errorDetails
+```
+
+```kql
+// Arc machines with outdated agent (older than significant version)
+resources
+| where type =~ "microsoft.hybridcompute/machines"
+| extend agentVersion = tostring(properties.agentVersion)
+| where isnotempty(agentVersion)
+| where agentVersion startswith "0." or agentVersion startswith "1.0" or agentVersion startswith "1.1"
+| project id, name, resourceGroup, location, agentVersion, lastStatusChange = properties.lastStatusChange
+```
+
+```kql
+// Arc machines that are Disconnected or Expired
+resources
+| where type =~ "microsoft.hybridcompute/machines"
+| extend status = tostring(properties.status)
+| where status in ("Disconnected", "Expired", "Error")
+| project id, name, resourceGroup, status, lastStatusChange = properties.lastStatusChange,
+          errorDetails = properties.errorDetails
+```
+
+```kql
+// Arc extensions per machine - useful when an extension fails to install
+resources
+| where type =~ "microsoft.hybridcompute/machines/extensions"
+| project id, name, machineId = tostring(split(id, "/extensions/")[0]),
+          publisher = properties.publisher,
+          extensionType = properties.type,
+          version = properties.typeHandlerVersion,
+          provisioningState = properties.provisioningState
+```
+
+## Write / mutating tools (always confirm with the user first)
+
+| Tool | Purpose |
+|---|---|
+| `mcp__azure__resource_delete` | Delete the Arc machine resource. Only removes the Azure projection; the actual machine is untouched. |
+| Custom REST calls via `mcp__azure__rest_call` (if available) | For uncovered control-plane ops: `licenseProfiles`, `gateways`, agent upgrade PATCH, etc. |
+
+## `az` CLI fallback - Arc-specific commands
+
+```bash
+# List Arc machines in a subscription
+az connectedmachine list --output table
+
+# Show full machine details
+az connectedmachine show \
+    --name <machine-name> \
+    --resource-group <rg>
+
+# List installed extensions on an Arc machine
+az connectedmachine extension list \
+    --machine-name <machine-name> \
+    --resource-group <rg>
+
+# Install an extension (e.g. AzureMonitorWindowsAgent)
+az connectedmachine extension create \
+    --name AzureMonitorWindowsAgent \
+    --machine-name <machine-name> \
+    --resource-group <rg> \
+    --publisher Microsoft.Azure.Monitor \
+    --type AzureMonitorWindowsAgent
+
+# Delete an Arc machine resource (does not touch the underlying machine)
+az connectedmachine delete \
+    --name <machine-name> \
+    --resource-group <rg> \
+    --yes
+```
+
+## On-machine commands (`azcmagent`) - run as admin on the machine
+
+```bash
+# Show agent state, connection status, agent version, errors
+azcmagent show
+
+# Run end-to-end network connectivity checks against required endpoints
+azcmagent check
+
+# Show recent connectivity / heartbeat events
+azcmagent logs
+
+# Connect (onboard). Normally generated by the portal-issued script.
+azcmagent connect \
+    --resource-group <rg> \
+    --tenant-id <tenant> \
+    --location <region> \
+    --subscription-id <sub> \
+    [--service-principal-id <appId> --service-principal-secret <secret>] \
+    [--private-link-scope <plsResourceId>] \
+    [--gateway-id <gatewayResourceId>] \
+    [--proxy-url http://<proxy>:<port>]
+
+# Disconnect from Azure (removes the Azure resource, leaves the agent installed)
+azcmagent disconnect
+
+# Manual upgrade trigger
+azcmagent upgrade
+```
+
+## ARM API endpoints (when only REST will do)
+
+| Resource | Endpoint |
+|---|---|
+| Machine | `/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.HybridCompute/machines/{name}` |
+| Machine extension | `/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.HybridCompute/machines/{name}/extensions/{extName}` |
+| License profile (ESU / PayGo) | `/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.HybridCompute/machines/{name}/licenseProfiles/default` |
+| Private Link Scope | `/subscriptions/{sub}/providers/Microsoft.HybridCompute/privateLinkScopes` |
+| Gateway | `/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.HybridCompute/gateways/{name}` |
+
+API versions move; consult `extension.config.json` in the
+HybridComputeExtension repo for the version the production portal uses
+in each environment.
@@ -0,0 +1,54 @@
+# Arc-Enabled Servers vs Azure VMs
+
+A common source of confusion. Read this if the user is talking about
+"Arc servers" as if they were Azure VMs - or vice versa.
+
+## The mental model
+
+| | Azure VM | Arc-enabled server |
+|---|---|---|
+| Where does the machine live? | In Azure (a Microsoft datacenter) | Anywhere except Azure: on-prem, AWS, GCP, edge, a laptop |
+| Who creates the OS? | Azure - you pick an image / size and Azure provisions it | You. The OS already exists. Arc only projects it. |
+| ARM resource type | `Microsoft.Compute/virtualMachines` | `Microsoft.HybridCompute/machines` |
+| Resource provider | `Microsoft.Compute` | `Microsoft.HybridCompute` |
+| What you install | Nothing - the VM is the resource | `azcmagent` (Azure Connected Machine agent) |
+| What gets billed for the VM itself | Compute hours + storage + networking | Nothing for the machine. You pay for the management services you opt into (Update Manager logs, Defender, ESU, etc.). |
+| Lifecycle action "Stop" / "Delete" | Stops / deletes the actual VM | Stops / deletes the Azure resource. The underlying machine is unaffected. |
+
+## Why a customer would choose Arc
+
+- They already own the hardware (on-prem datacenter, edge device, factory floor).
+- They run workloads in AWS or GCP and want one Azure-native control plane.
+- They need Azure Policy, Defender for Servers, Update Manager, Machine
+  Configuration, Change Tracking, or Monitor Insights on machines that
+  cannot or should not move into Azure.
+- They need to buy **Extended Security Updates** for Windows Server 2012 /
+  2012 R2 - ESU is sold via an Arc license and applied to Arc machines.
+- They want **Pay-as-you-go Windows Server licensing** on customer-owned
+  hardware, billed through Azure.
+
+## Why a customer would choose an Azure VM
+
+- They want Azure to host the OS.
+- They want VM-native features like availability sets, scale sets,
+  Capacity Reservation Groups, ephemeral OS disks, GPU SKUs, etc.
+- They don't have hardware of their own.
+
+## Common confused phrasings and what they actually want
+
+| What the user said | What they probably mean | Route to |
+|---|---|---|
+| "Create an Arc VM" | If they have a physical / non-Azure machine: Arc onboarding. If they mean a VM stamped onto Azure Local / VMware via Arc: a different skill (`azure-local`, `arc-vmware`). | Clarify, then this skill or `azure-local` / `arc-vmware`. |
+| "Spin up an Arc server" | Same as above - clarify. | Clarify first. |
+| "I want to manage my AWS EC2 instance from Azure" | Either install the Connected Machine agent on the EC2 instance (this skill) or use the AWS connector (multi-cloud sync). | This skill for single-instance; `arc-multicloud` (proposed) for bulk sync. |
+| "Connect my on-prem servers to Azure" | This skill - onboard. | [arc-server-onboard](../workflows/arc-server-onboard/arc-server-onboard.md) |
+| "My Arc server is offline" | Troubleshoot agent connectivity. | [arc-server-troubleshoot](../workflows/arc-server-troubleshoot/arc-server-troubleshoot.md) |
+| "Patch my Arc servers" | Azure Update Manager, scoped to Arc. | [arc-server-manage](../workflows/arc-server-manage/arc-server-manage.md) |
+
+## When the answer is "use both"
+
+If the user wants a hybrid fleet (some Azure VMs, some on-prem), use
+**Essential Machine Management** to enroll the subscription so everything
+gets the same baseline of Insights / Update Manager / Change Tracking /
+Machine Config. EMM is handled in the upstream `azure-compute` skill's
+`essential-machine-management` workflow.
@@ -0,0 +1,6 @@
+{
+  "version": "1.0",
+  "pathFilters": [
+    "."
+  ]
+}