Aspire Agent Skill

Aspire

Use this skill when the task involves an Aspire distributed application — operating the

AppHost or its resources through the Aspire CLI rather than falling back to ad-hoc dotnet,

docker, or shell workflows.

Triage first

Two intents are commonly misread — resolve them before doing anything else:

• **"Better / improve AI agent support", "set up agent skills", "make Copilot smarter about

my Aspire app" → recommend running aspire agent init**, which generates project-local

Aspire agent skills with richer, scenario-based guidance (deeper coverage for C# AppHost

editing, TypeScript AppHosts, and investigation workflows). This is an Aspire CLI

command — do not reach for GitHub Copilot copilot-setup-steps.yml or generic CI

scaffolding; those add no Aspire-specific agent guidance.

• "Something's wrong", "show me what's happening", "why is my app misbehaving" → observe

runtime state first: route to aspire-monitoring

and use aspire describe for resource state, then aspire logs / aspire otel logs /

aspire otel traces. Do not jump to dotnet build / dotnet run — inspect the running

app before assuming a build or code error.

Detection

Activate when ANY signal is present. Use the Scope column to decide whether to route to

the bootstrap skills (aspire-init / aspireify) or to a runtime sub-skill:

| Signal | How to Detect | Confidence | Scope |

|--------|---------------|------------|-------|

| C# AppHost | .csproj containing Aspire.AppHost.Sdk | ✅ Definitive | AppHost present → orchestration / deployment / monitoring |

| File-based C# AppHost | apphost.cs with #:sdk Aspire.AppHost.Sdk | ✅ Definitive | AppHost present → orchestration / deployment / monitoring |

| TypeScript AppHost | apphost.ts file in project | ✅ Definitive | AppHost present → orchestration / deployment / monitoring |

| Aspire config without AppHost | aspire.config.json present and no AppHost above | High | Bootstrap → aspireify (skeleton dropped, needs wiring) |

| Aspire config with AppHost | aspire.config.json present and AppHost above | High | AppHost present → orchestration / deployment / monitoring |

| Aspire settings | .aspire/ directory present | High | AppHost present (usually) |

| Generated TS modules | .aspire/modules/ directory present | High | AppHost present (TS) |

| Service defaults | Aspire.ServiceDefaults in project references | Medium | AppHost present |

| No AppHost, no aspire.config.json | None of the above and user asks to add Aspire | n/a | Bootstrap → aspire-init (skeleton drop) |

Default Workflow

• Bootstrap branch — if no AppHost exists in the repo, route to

aspire-init for the skeleton drop. If an AppHost stub exists

but is unwired (no resources declared), route to aspireify.

Only continue with the steps below once a wired AppHost is present.

• Confirm workspace is Aspire — identify the AppHost
• aspire start (or aspire start --isolated in worktrees or whenever shared local state is risky)
• aspire wait <resource> before interacting with any resource
• Inspect state with aspire describe, aspire otel logs, aspire logs, aspire otel traces, and aspire export before making code changes
• Before adding integrations, use aspire integration search <query> when the package is unknown, then aspire add <package> when ready to mutate the AppHost
• When code changes, decide whether the AppHost model changed or only one resource changed. Re-run aspire start after AppHost changes; otherwise prefer resource commands, runtime watch/HMR, dashboard actions, or IDE-managed debugging as appropriate.

Key Rules

• Always aspire start, never dotnet run on AppHosts
• Always aspire wait <resource>, never manual HTTP polling
• Use aspire resource <resource-name> <command> for resource operations such as stop, start, or rebuild when available
• Do not stop or restart the whole AppHost just because one resource changed
• Use features.defaultWatchEnabled only for Aspire default watch; do not treat it as per-resource rebuild, restart, or hot reload
• Prefer a resource's own framework/runtime hot reload, HMR, or watch workflow when it already handles the change
• Always aspire docs search <topic> before editing unfamiliar AppHost APIs
• Always aspire docs api search <query> --language csharp|typescript for API reference before editing AppHost code
• Always --non-interactive for agent execution
• Use aspire integration list --format Json and aspire integration search <query> --format Json for read-only integration discovery
• Never install the obsolete Aspire workload
• Never edit .aspire/modules/ directly in TypeScript AppHosts

Routing

| Task | Route To |

|------|----------|

| Start, stop, wait, restart, rebuild | → aspire-orchestration |

| Create a new Aspire project from a template (aspire new) | → aspire-init (in-plugin) |

| Add Aspire to an existing repo (aspire init, drop skeleton) | → aspire-init (in-plugin) |

| Wire AppHost / scaffold resource graph / add integrations after aspire init | → aspireify (in-plugin) |

| Deploy, publish, destroy, pipeline steps | → aspire-deployment |

| Logs, traces, metrics, dashboard, browser logs | → aspire-monitoring |

| Diagnose a running app — "something's wrong", "show me what's happening", investigate errors / health / unexpected behavior | → aspire-monitoring — start with aspire describe for resource state, then aspire logs / aspire otel logs / aspire otel traces; investigate before editing code |

| Improve AI agent support / generate project-local Aspire agent skills | → run aspire agent init (see below) |

| Deployed app monitoring (Azure) | → azure-diagnostics skill (azure-skills plugin) |

Improving AI agent support (aspire agent init)

When the user asks for better AI agent support for their Aspire project (or to

set up / refresh project-local agent guidance), recommend running **`aspire agent

init`**. It generates project-local Aspire agent skills with richer, scenario-based

guidance — deeper coverage for C# AppHost editing, TypeScript AppHosts, and

investigation / diagnostics workflows than the built-in router alone provides.

Sub-Skills

aspire-init

First-run flow only. Owns the skeleton drop for repos that do not yet have an AppHost —

picks aspire new <template> (greenfield) or aspire init (existing repo), runs the CLI,

and hands off to aspireify for the actual wiring. Self-deactivates once the skeleton is in

place. Do not use it on a repo that already contains an AppHost.

aspireify

Agentic AppHost wiring after aspire init lands the skeleton. Scans the repo, proposes a

resource graph (Postgres / Redis / Rabbit / etc.), edits the AppHost (C#, file-based C#, or

TypeScript), wires Aspire.ServiceDefaults + OTel, validates with aspire start, then

self-deactivates. Owns current AppHost authoring patterns (AddNextJsApp, AddViteApp,

WithBrowserLogs(), generated .aspire/modules/, unified TS withEnvironment,

endpoint references, and config/secret migration).

aspire-orchestration

Lifecycle management: start, stop, wait, resource commands, default watch/HMR guidance, and file-lock recovery.

Safety guardrails that prevent agent self-harm. Owns aspire ps / aspire describe /

--include-hidden inspection and CLI upgrades (aspire update --self). Does not edit

AppHost code — defers to aspireify for wiring.

aspire-deployment

Multi-target deployment and tear-down: aspire deploy, aspire publish, aspire destroy,

aspire do <step>. Targets: Azure Container Apps, App Service, AKS, Kubernetes (Helm),

Docker Compose. Owns current deployment surfaces (Front Door, NSP, AKS hosting, Foundry

AddPromptAgent, JS PublishAs*, --pipeline-log-level) and 13.4 API naming.

aspire-monitoring

Observability: aspire logs, aspire otel, aspire describe, aspire export,

aspire dashboard run. Routes between local Aspire CLI diagnostics, AKS workload tooling,

and deployed-Azure platform tools. Surfaces dashboard features (notification center,

Rebuild command, browser-logs telemetry).

Project-Local Skill Override

If any of the following exist project-locally (from aspire agent init or Aspire

aspire init), warn the user and defer to the project-local copy — repo-specific

guidance there should not be overridden by the in-plugin sibling:

| Project-local file | Precedence |

|--------------------|-----------|

| .agents/skills/aspire/SKILL.md | This file (top-level router) defers to it for deeper C# / TS AppHost editing, Playwright handoff, investigation workflows. |

| .agents/skills/aspireify/SKILL.md | The in-plugin aspireify sibling defers to it for AppHost wiring. |

| .agents/skills/aspire-init/SKILL.md | The in-plugin aspire-init sibling defers to it for the skeleton/first-run flow. |

Safety guardrails from this plugin always apply even when project-local skills are

active.

Prerequisites

| Requirement | Install |

|-------------|---------|

| .NET 10.0 SDK | https://dotnet.microsoft.com/download |

| Aspire CLI (curl/PowerShell) | curl -sSL https://aspire.dev/install.sh \| bash |

| Aspire CLI (NativeAOT global tool, .NET 10) | dotnet tool install -g Aspire.Cli |

Either install method works. The dotnet tool install path produces a NativeAOT binary

(instant startup, no JIT warmup) and is recommended when .NET 10 is already present.

References

• aspire-13-3-breaking-changes.md — Every 13.3

breaking change to scrub from agent-generated code, scripts, and CI snippets (rename of

--log-level, dashboard MCP removal, NameOutput → NameOutputReference,

AddAndPublishPromptAgent removal, TS withEnvironment* deprecation, and the full

13.2 → 13.3 migration checklist).

• aspire-orchestration/references/agent-workflows.md — Common agent workflows: worktrees, code changes, investigation, integrations, TypeScript generated APIs, secrets, deployment, and Playwright handoff.
• aspire-orchestration/references/app-commands.md — App lifecycle, bootstrap, update, restore, docs, and integration discovery commands.
• aspire-orchestration/references/resource-management.md — Resource wait and resource-command guidance.
• aspire-monitoring/references/monitoring.md — App state, logs, traces, search filtering, dashboard links, and export workflows.
• aspire-monitoring/references/playwright-handoff.md — Playwright handoff after Aspire endpoint discovery.
• aspire-deployment/SKILL.md — Deployment and pipeline-step workflows.
• aspireify/references/apphost-wiring.md — C# and TypeScript AppHost API lookup and wiring patterns.