Aspire

Aspire Skill

Use this skill when the task is about operating an Aspire distributed application through the Aspire CLI rather than falling back to ad-hoc dotnet, docker, or shell workflows.

Resources are typically defined in an AppHost such as, AppHost.cs, apphost.ts, or AppHost/AppHost.csproj (Program.cs).

Use this skill for

• Starting, restarting, and stopping AppHosts with aspire start and aspire stop
• Initializing Aspire in an existing app with aspire init
• Inspecting resources, logs, traces, and docs
• Adding integrations with aspire add
• Recovering missing TypeScript AppHost support files with aspire restore
• Discovering the correct frontend URL before a Playwright handoff
• Understanding unfamiliar Aspire AppHost APIs before editing C# or TypeScript AppHosts
• Managing AppHost secrets and CLI config
• Publishing and deploying Aspire apps, including single named steps with aspire do
• Adding custom dashboard or resource commands with docs-backed AppHost patterns

Do not use this skill for

• Non-Aspire .NET applications
• Container-only workflows that do not involve an Aspire AppHost
• Replacing normal build and test commands when the task is just compiling code or running unit tests

Default workflow

1. Confirm that the workspace is an Aspire app and identify the AppHost.
2. Start the app with aspire start. Use --isolated in git worktrees or whenever shared local state would be risky.
3. Use aspire wait <resource> before interacting with a resource that needs to be healthy.
4. Inspect state with aspire describe, then use aspire otel logs, aspire logs, aspire otel traces, and aspire export before making code changes.
5. Before adding an integration, introducing a custom dashboard/resource command, or using an unfamiliar AppHost API, run aspire docs search <topic> and then aspire docs get <slug> for the pattern or API you plan to implement.
6. Re-run aspire start after AppHost changes. In git worktrees, re-run aspire start --isolated instead of switching to aspire run.

C# AppHosts

When the AppHost is implemented in C# such as AppHost.cs, apphost.cs, or a Program.cs-based AppHost, use Aspire docs to understand the documented API or pattern before editing.

• Use aspire docs search <topic> and aspire docs get <slug> when you need official guidance for an unfamiliar C# API, resource builder pattern, or command shape.
• If the dotnet-inspect skill is available, use it to inspect local C# APIs, overloads, and builder chains when you need help understanding how the API surface is exposed in code.
• Keep dotnet-inspect scoped to understanding APIs and symbols; use Aspire docs for the documented workflow and recommended pattern.

TypeScript AppHosts

When the AppHost is apphost.ts, the .modules/ folder at the project root contains generated TypeScript modules that expose the Aspire APIs available to the AppHost. Common files include .modules/aspire.ts, base.ts, and transport.ts.

• Do not edit .modules/ directly.
• Use aspire add <package> to add integrations and regenerate the available APIs.
• Inspect .modules/aspire.ts after aspire add to see the refreshed API surface.
• The local tsconfig.json often includes .modules/**/*.ts in its compilation scope.

Key rules

• Prefer aspire start over dotnet run for AppHosts. aspire run blocks the terminal and is a poor fit for agent workflows.
• Re-running aspire start is the restart path. In git worktrees, aspire start --isolated is both the start and restart command. Do not combine aspire stop and aspire run.
• Use --apphost <path> when the workspace has multiple AppHosts or discovery is ambiguous.
• Use --format Json when another tool or script needs machine-readable output.
• Do not guess the integration or command shape for unfamiliar AppHost changes. Use aspire docs search first, then aspire docs get before editing AppHost code for integrations, WithCommand, or other non-trivial Aspire APIs.
• For unfamiliar C# AppHost APIs, use Aspire docs as the primary API reference and, if available, use dotnet-inspect only to inspect local symbols, overloads, and builder chains.
• Never install the obsolete Aspire workload.
• When a TypeScript AppHost uses .modules/, do not edit generated files directly. Use aspire add to regenerate APIs and inspect .modules/aspire.ts afterward.
• Prefer official docs from aspire.dev.

Common capabilities

• Use aspire ps when you need to discover running AppHosts before targeting one.
• Use aspire update when the task is to refresh AppHost package references through the supported CLI workflow.
• Use aspire doctor as an early diagnostics step when the local Aspire environment looks unhealthy.
• Use aspire resource, aspire secret, aspire config, aspire publish, aspire deploy, and aspire do when the objective is resource operations, secrets/config management, or deployment.
• Use aspire restore, aspire cache clear, aspire certs trust, and aspire certs clean when the task is local environment maintenance or recovery.

Playwright CLI

If Playwright CLI is already configured in the environment, use Aspire first to discover the running app and its endpoints, especially when multiple frontends exist. Prefer aspire describe --format Json when the handoff needs to be scriptable or you need to disambiguate which frontend URL Playwright should use, then hand browser testing off to Playwright CLI.

References

• For app-level lifecycle, bootstrap, and AppHost-wide commands, see references/app-commands.md.
• For waiting on and operating on individual resources, see references/resource-management.md.
• For app state, logs, traces, and export workflows, see references/monitoring.md.
• For deployment and pipeline-step workflows, see references/deployment.md.
• For docs, secrets, config, diagnostics, cache, and certificates, see references/tools-and-configuration.md.
• For C# AppHost API-understanding guidance, see references/csharp-apphosts.md.
• For TypeScript AppHost guidance, see references/typescript-apphosts.md.
• For Playwright handoff after Aspire endpoint discovery, see references/playwright-handoff.md.
• For investigation order and common agent workflows, see references/agent-workflows.md.