--- name: aspire description: >- **WORKFLOW SKILL** - Aspire router. Detects AppHosts, enforces guardrails, and selects the right sub-skill. USE FOR: Aspire AppHost, Aspire CLI, distributed app, cloud-native .NET, aspire start/stop/resource/deploy/destroy/publish/init/new/add/wait/describe/ps/logs/otel, aspire agent init, WithBrowserLogs, WithTerminal, Interaction Service, apphost.mts, TS package managers, Yarn Classic, custom resource commands, .aspire/modules recovery, ProjectResource to DotnetProjectResource migration, or Playwright URL discovery. DO NOT USE FOR: non-Aspire projects or ordinary build/test tasks. INVOKES: aspire-init, aspireify, aspire-project-v2-migration, aspire-orchestration, aspire-deployment, aspire-monitoring. FOR SINGLE OPERATIONS: Route directly to the matching sub-skill. license: MIT metadata: author: Microsoft version: "0.0.4" --- # 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 Three 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](https://github.com/microsoft/aspire-skills/blob/main/skills/aspire-monitoring/SKILL.md) 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. - **"My old TypeScript AppHost uses apphost.ts; how do I migrate?"** → route to `aspire-orchestration` for `aspire update --migrate`. This entry-point/package migration is not Project v2 resource migration. Its package, config, tsconfig, generated-import, and entry-point changes require approval before `aspire update --migrate --yes --non-interactive`; use `aspireify` only if separate source authoring remains afterward. ## 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 | Current `apphost.mts` or legacy `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 0. **Bootstrap branch** — if **no AppHost exists** in the repo, route to [`aspire-init`](https://github.com/microsoft/aspire-skills/blob/main/skills/aspire-init/SKILL.md) for the skeleton drop. If an AppHost stub exists but is **unwired** (no resources declared), route to [`aspireify`](https://github.com/microsoft/aspire-skills/blob/main/skills/aspireify/SKILL.md). Only continue with the steps below once a wired AppHost is present. 1. Confirm workspace is Aspire — identify the AppHost 2. Route lifecycle work to `aspire-orchestration`: prefer `aspire_apphost_start` when the VS Code tool is available; use `aspire start --non-interactive --isolated --apphost ` in worktrees 3. `aspire wait ` before interacting with any resource 4. Inspect state with `aspire describe`, `aspire otel logs`, `aspire logs`, `aspire otel traces`, and `aspire export` before making code changes 5. Before adding integrations, use `aspire integration search ` when the package is unknown, then `aspire add ` when ready to mutate the AppHost 6. When code changes, decide whether the AppHost model changed or only one resource changed. Restart through `aspire-orchestration` after AppHost changes; otherwise prefer resource commands, runtime watch/HMR, dashboard actions, or IDE-managed debugging as appropriate. ## Key Rules - For agent AppHost lifecycle requests, identify one exact AppHost and route to `aspire-orchestration`. New 13.5 C# templates can make `dotnet run` delegate through the CLI bundle, but agents still use the editor lifecycle tool or `aspire start` for detached, noninteractive, exact-target, and worktree-isolated execution. - When VS Code exposes `aspire_apphost_start` or `aspire_apphost_stop`, load deferred contracts and prefer the matching tool, subject to the orchestration skill's worktree and stop-result rules; use start mode `run` unless the user explicitly asks to attach a debugger - If several AppHosts are discovered and the target is unclear, ask which one before taking any lifecycle action - **Always** `aspire wait `, **never** manual HTTP polling - Use `aspire ps` for running AppHost processes and `aspire describe` for resource state/endpoints. Never generate removed 13.5 forms such as `aspire ps --resources` or `aspire ps --include-hidden`. - Use `aspire resource ` for resource operations such as `stop`, `start`, or `rebuild` when available - Treat `aspire stop --force` as data-destructive: it permanently removes persistent resources without another prompt. Use it only after explicit confirmation for one exact AppHost. - 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 ` before editing unfamiliar AppHost APIs - **Always** `aspire docs api search --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 --format Json` for read-only integration discovery - **Never** install the obsolete Aspire workload - **Never** edit `.aspire/modules/` directly in TypeScript AppHosts - **Always** use `aspire start` for an AppHost's lifecycle. When diagnosing or repairing a TypeScript AppHost's package-manager toolchain, defer to [`aspireify`](https://github.com/microsoft/aspire-skills/blob/main/skills/aspireify/SKILL.md) and its package-manager rules; do not substitute a raw package-manager launcher for `aspire start`. - Adding a new project or integration is ordinary `aspireify` wiring. Route to `aspire-project-v2-migration` only when the user wants to replace existing `AddProject`, `addProject`, `AddCSharpApp`, or Blazor gateway resources with Project v2 APIs. That migration requires an eligible 13.6+ AppHost and approval of the exact per-resource edits. ## Routing | Task | Route To | |------|----------| | Start, stop, wait, restart, rebuild | → [aspire-orchestration](https://github.com/microsoft/aspire-skills/blob/main/skills/aspire-orchestration/SKILL.md) | | Create a new Aspire project from a template (`aspire new`) | → [aspire-init](https://github.com/microsoft/aspire-skills/blob/main/skills/aspire-init/SKILL.md) (in-plugin) | | Add Aspire to an existing repo (`aspire init`, drop skeleton) | → [aspire-init](https://github.com/microsoft/aspire-skills/blob/main/skills/aspire-init/SKILL.md) (in-plugin) | | Wire AppHost / scaffold resource graph / add integrations after `aspire init` | → [aspireify](https://github.com/microsoft/aspire-skills/blob/main/skills/aspireify/SKILL.md) (in-plugin) | | Migrate existing legacy project resources to Project v2 | → [aspire-project-v2-migration](https://github.com/microsoft/aspire-skills/blob/main/skills/aspire-project-v2-migration/SKILL.md); assess and obtain approval before edits | | Migrate legacy TypeScript `apphost.ts` (`aspire update --migrate`) | → [aspire-orchestration](https://github.com/microsoft/aspire-skills/blob/main/skills/aspire-orchestration/SKILL.md); hand back to aspireify only if source authoring remains | | Deploy, publish, destroy, pipeline steps | → [aspire-deployment](https://github.com/microsoft/aspire-skills/blob/main/skills/aspire-deployment/SKILL.md) | | Logs, traces, metrics, dashboard, browser logs | → [aspire-monitoring](https://github.com/microsoft/aspire-skills/blob/main/skills/aspire-monitoring/SKILL.md) | | Diagnose a running app — "something's wrong", "show me what's happening", investigate errors / health / unexpected behavior | → [aspire-monitoring](https://github.com/microsoft/aspire-skills/blob/main/skills/aspire-monitoring/SKILL.md) — 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) | | Explicitly configure the Aspire MCP server for agents | → `aspire agent init --mcp` on 13.6+ (see [Skills vs. MCP](#improving-ai-agent-support-aspire-agent-init)) | | 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. **Skills vs. MCP.** Installing skills and configuring the Aspire MCP server are separate choices: - In Aspire 13.6+, the agent setup chained from `aspire new` and `aspire init` preselects the recommended repository-local skills (including `aspireify`) and does **not** offer MCP configuration. Standalone `aspire agent init` keeps an MCP choice that is off by default, and non-interactive runs never configure MCP by default. - If MCP config is missing after a successful init or skill refresh where MCP was **not** explicitly requested, that is expected. Don't treat it as a defect to repair, and don't claim MCP was installed. If the user explicitly ran `aspire agent init --mcp` (or selected MCP interactively) and MCP config is still missing, treat that as a failed opt-in and investigate it. - Configure MCP only when the user explicitly asks for it. Check `aspire --version` first: - **13.6+** — `aspire agent init --mcp` (add `--non-interactive` for agent execution). Keep any `--skills` / `--skill-locations` values the user already chose. `--mcp=false` is an explicit opt-out. - **13.5** — there is no `--mcp` flag. Have the user run `aspire agent init` interactively and select the MCP server option. - Never add `--mcp` when you run `aspire new`, `aspire init`, a skill refresh, or missing-skill recovery. ## Sub-Skills ### aspire-init First-run flow only. Owns the skeleton drop for repos that do **not** yet have an AppHost — picks `aspire new