Skip to content

[docs] docs: document Aspire workflow skills external bundle migration #1077

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
David Pine (IEvangelist) merged 7 commits into from
Jun 1, 2026
Merged

[docs] docs: document Aspire workflow skills external bundle migration #1077

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
3f6d1fa
docs: document Aspire workflow skills external bundle migration
aspire-repo-bot[bot] May 26, 2026
28bb230
Address review feedback (8 threads)
IEvangelist May 29, 2026
1f5a393
Merge release/13.4 into skills docs PR
IEvangelist Jun 1, 2026
609fb4f
Consolidate Aspire AI skills docs
IEvangelist Jun 1, 2026
dc3b5ec
Merge latest release/13.4
IEvangelist Jun 1, 2026
0284012
Fix agent init output summary docs
IEvangelist Jun 1, 2026
c5e8741
Merge latest release/13.4
IEvangelist Jun 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 43 additions & 26 deletions src/frontend/src/content/docs/get-started/ai-coding-agents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Aspire gives coding agents the same visibility into your running application tha

The Aspire CLI is built for agent-driven workflows — commands support non-interactive execution to avoid blocking on prompts, and many commands support `--format Json` for structured plain text output. Key commands include `aspire start` (background execution), `aspire start --isolated` (parallel worktrees), `aspire wait` (block until healthy), `aspire describe`, `aspire logs`, and `aspire docs search`.

The Aspire skill file (installed by `aspire agent init`) teaches agents all of these patterns automatically.
Aspire workflow skills installed by `aspire agent init` teach agents these patterns automatically.

## Get started

Expand All @@ -46,44 +46,61 @@ When you create a new Aspire project with `aspire new` or `aspire init`, you're
| **GitHub Skills** | `.github/skills/` | VS Code / GitHub Copilot specific |
| **OpenCode** | `.opencode/skill/` | OpenCode specific |

1. Select the **skills and tools** to install into those locations. All options are pre-selected by default:
- **Aspire skill** — teaches your AI agent how to use Aspire CLI commands
- **Playwright CLI** — enables browser automation for testing web resources
- **dotnet-inspect skill** — teaches your AI agent to query .NET API surfaces
1. Select the **skills and tools** to install into those locations. The Aspire workflow skills from [`microsoft/aspire-skills`](https://github.com/microsoft/aspire-skills) are:
- **aspire** — routes Aspire tasks to the right workflow
- **aspire-init** — creates a new Aspire app or adds an Aspire skeleton to an existing repo
- **aspire-orchestration** — starts, stops, waits for, and manages Aspire resources
- **aspire-monitoring** — inspects logs, traces, metrics, resource state, and diagnostics data
- **aspire-deployment** — publishes, deploys, and tears down Aspire apps
- **aspireify** — wires an AppHost after `aspire init`

The flow pre-selects the workflow skills that apply to the command you're running. Add Playwright CLI for browser checks, dotnet-inspect for .NET API surface queries, or select **Install Aspire MCP server** if the agent needs live data from a running Aspire app.

:::note[Aspire workflow skills bundle]
Aspire workflow skills are distributed through the [`microsoft/aspire-skills`](https://github.com/microsoft/aspire-skills) GitHub release assets. Aspire 13.4 includes an embedded snapshot for default installs, and the optional remote fetch path can download matching release assets. Companion options such as Playwright CLI and dotnet-inspect are installed separately when selected.
:::

</Steps>

## What gets configured

The `aspire agent init` command detects your AI development environment and creates the appropriate configuration files:

### Aspire skill file
### Aspire workflow skill files

Aspire workflow skills teach your AI coding agent how to work with Aspire. The top-level `aspire` skill routes requests to focused skills for initialization, orchestration, monitoring, deployment, and AppHost wiring.

The skill file teaches your AI coding agent how to work with Aspire. It includes a CLI command reference, key workflows (starting apps, debugging issues, adding integrations), and important rules to follow. The file is installed into each selected skill location:
For example, a standard location can contain:

<FileTree>

- .agents/skills/aspire/
- SKILL.md Standard (VS Code, GitHub Copilot, OpenCode)
- .github/skills/aspire/
- SKILL.md GitHub Copilot (legacy location)
- .claude/skills/aspire/
- SKILL.md Claude Code
- .opencode/skill/aspire/
- SKILL.md OpenCode
- .agents/skills/
- aspire/
- SKILL.md
- aspire-init/
- SKILL.md
- aspire-orchestration/
- SKILL.md
- aspire-monitoring/
- SKILL.md
- aspire-deployment/
- SKILL.md
- aspireify/
- SKILL.md

</FileTree>

The skill file guides your agent on how to:
The skills guide your agent on how to:

- Start and manage your Aspire application (`aspire start`, `aspire stop`, `aspire describe`)
- Debug issues using structured logs and distributed traces
- Add integrations with `aspire add` and search documentation with `aspire docs`
- Use resource MCP tools for database queries and other resource-specific operations
- Route first-run setup, AppHost wiring, monitoring, orchestration, and deployment work to focused workflows

### dotnet-inspect skill

The `dotnet-inspect` skill teaches your AI agent to query .NET API surfaces using the [`dotnet-inspect`](https://github.com/richlander/dotnet-inspect) tool. It's installed alongside the Aspire skill in each selected location:
The `dotnet-inspect` companion skill teaches your AI agent to query .NET API surfaces using the [`dotnet-inspect`](https://github.com/richlander/dotnet-inspect) tool. When selected, it's installed into each selected location:

<FileTree>

Expand All @@ -100,8 +117,8 @@ The `dotnet-inspect` skill teaches your AI agent to query .NET API surfaces usin

The skill enables your agent to inspect NuGet package API surfaces, compare API changes between package versions, and explore .NET types and members.

:::note[Skill conflict]
The `dotnet-inspect` skill should not be installed alongside the Aspire skill. The Aspire skill already includes support for `aspire docs api` subcommands, providing a powerful way to query Aspire APIs across both C# and TypeScript.
:::note[When to use dotnet-inspect]
Install `dotnet-inspect` when an agent needs broad .NET API surface queries. For Aspire-specific API docs, the Aspire skills guide agents to use `aspire docs api` commands across both C# and TypeScript.
:::

### Aspire MCP server
Expand All @@ -110,22 +127,22 @@ The MCP server gives your AI agent direct runtime access to your running Aspire

## Migrate from AGENTS.md

If your project has an `AGENTS.md` file from a previous version of Aspire, you can migrate to the new skill file format. The skill file provides better structure and is recognized natively by AI coding agents.
If your project has an `AGENTS.md` file from a previous version of Aspire, you can migrate to the new skill file format. Skill files provide better structure and are recognized natively by AI coding agents.

<Steps>

1. Run `aspire agent init` and select **Install Aspire skill file**.
1. Run `aspire agent init` and select the Aspire workflow skills you want to install.

2. The skill files are created at `.github/skills/aspire/SKILL.md` and `.claude/skills/aspire/SKILL.md`.
2. The skill files are created under each selected skill location, such as `.agents/skills/aspire/SKILL.md` and `.agents/skills/aspire-orchestration/SKILL.md`.

3. Review and delete the old `AGENTS.md` file — the skill file replaces it.
3. Review and delete the old `AGENTS.md` file — the skill files replace it.

</Steps>

<Aside type="tip">
The skill file is more structured than `AGENTS.md` and includes a complete CLI
command reference table, workflow patterns, and rules that the agent follows
automatically. You can customize it for your project's specific needs.
The skill files are more structured than `AGENTS.md` and include complete CLI
command reference tables, workflow patterns, and rules that the agent follows
automatically. You can customize them for your project's specific needs.
</Aside>

## Your first prompts
Expand Down
42 changes: 35 additions & 7 deletions src/frontend/src/content/docs/get-started/aspire-skills.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ import LearnMore from '@components/LearnMore.astro';

Aspire skills are Markdown instruction bundles for AI coding agents. Each skill lives in a folder with a `SKILL.md` file that describes when the skill applies and what workflow the agent should follow. Skills don't run services or expose application data; they teach the agent how to use Aspire tools correctly.

Aspire ships multiple skills for different parts of the app lifecycle. The exact list can vary by Aspire CLI version and project type, but Aspire skills are organized around workflows such as initialization, orchestration, monitoring, deployment, and AppHost wiring.
Aspire ships multiple skills for different parts of the app lifecycle. The exact list can vary by Aspire CLI version and project type, but the [`microsoft/aspire-skills`](https://github.com/microsoft/aspire-skills) bundle includes six workflow skills: `aspire`, `aspire-init`, `aspire-orchestration`, `aspire-monitoring`, `aspire-deployment`, and `aspireify`.

<LearnMore>
To configure AI coding agents end to end, see [Use AI coding
Expand All @@ -35,13 +35,13 @@ aspire init
aspire agent init
```

For non-interactive setup, pass the skill and location options explicitly. To install the available skills into all supported locations, use `all`:
For non-interactive setup, pass the skill and location options explicitly. To install all available skills and companion options into all supported locations, use `all`:

```bash title="Aspire CLI"
aspire agent init --skills all --skill-locations all
```

To install a subset, pass a comma-separated list of skill names:
To install a subset, pass a comma-separated list of skill names. This example installs every Aspire workflow skill from the bundle and the optional Playwright CLI companion skill:

```bash title="Aspire CLI"
aspire agent init --skills aspire,aspire-init,aspire-orchestration,aspire-monitoring,aspire-deployment,aspireify,playwright-cli --skill-locations all
Expand Down Expand Up @@ -117,7 +117,7 @@ In that command, `-a github-copilot` selects the target agent, `-g` installs glo
</TabItem>
</Tabs>

## Available skills
## Aspire workflow skills

| Skill | Use it for | What it teaches |
| ---------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
Expand All @@ -127,17 +127,27 @@ In that command, `-a github-copilot` selects the target agent, `-g` installs glo
| `aspire-monitoring` | Observing running Aspire apps | Inspect resource state, logs, traces, metrics, browser telemetry, and dashboard data before making changes |
| `aspire-deployment` | Publishing, deploying, and tearing down Aspire apps | Use AppHost-modeled deployments for targets such as Docker Compose, Kubernetes, Azure, and AWS |
| `aspireify` | Completing Aspire initialization in an existing codebase after `aspire init` drops an AppHost skeleton | Scan the repo, propose a resource graph, wire projects and containers into the AppHost, connect resources, configure telemetry when appropriate, and validate the wiring |
| `playwright-cli` | Testing running web resources in a browser | Use Playwright CLI for browser automation, including navigation, form interaction, screenshots, and visual checks |

Use the top-level `aspire` skill when the request is about an Aspire app and the right workflow isn't obvious. Use a workflow-specific skill directly when the task is clear, such as `aspire-orchestration` for local lifecycle work, `aspire-monitoring` for telemetry investigation, `aspire-deployment` for publish and deploy workflows, or `aspireify` for existing-codebase AppHost wiring. Use `playwright-cli` when an agent needs to test or inspect a running frontend.
Use the top-level `aspire` skill when the request is about an Aspire app and the right workflow isn't obvious. Use a workflow-specific skill directly when the task is clear, such as `aspire-orchestration` for local lifecycle work, `aspire-monitoring` for telemetry investigation, `aspire-deployment` for publish and deploy workflows, or `aspireify` for existing-codebase AppHost wiring.

## Companion skills and tools

Companion options can be offered by `aspire agent init`, but they aren't part of the `microsoft/aspire-skills` workflow bundle.

| Skill | Use it for | What it teaches |
| ---------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `playwright-cli` | Testing running web resources in a browser | Use Playwright CLI for browser automation, including navigation, form interaction, screenshots, and visual checks |
| `dotnet-inspect` | Querying .NET API surfaces | Inspect available .NET APIs when the workspace contains a .NET AppHost |

Use `playwright-cli` when an agent needs to test or inspect a running frontend. Use `dotnet-inspect` when an agent needs API-surface details for .NET AppHost work.

## Playwright handoff

The `playwright-cli` skill works best alongside the `aspire` skill. The agent will first use Aspire to discover the running app and the correct frontend endpoint, especially when multiple web resources exist. After it has the target URL, it can use the Playwright CLI to automate browser testing.

## Skill locations

Aspire installs each selected skill into the selected skill locations. For example, a standard location can contain:
Aspire installs each selected skill into the selected skill locations. For example, a standard location can contain every Aspire workflow skill and selected companion skills:

<FileTree>

Expand All @@ -156,6 +166,8 @@ Aspire installs each selected skill into the selected skill locations. For examp
- SKILL.md
- playwright-cli/
- SKILL.md
- dotnet-inspect/
- SKILL.md

</FileTree>

Expand All @@ -168,6 +180,22 @@ Other supported locations use the same skill folder names:
| **GitHub Skills** | `.github/skills/` | VS Code / GitHub Copilot specific |
| **OpenCode** | `.opencode/skill/` | OpenCode specific |

## Troubleshoot skill bundle errors

When `aspire agent init` installs Aspire workflow skills, it validates the Aspire skills bundle before copying files. If the embedded bundle that ships with the CLI is corrupted or inconsistent, you might see errors such as:

- `Embedded Aspire skills bundle metadata is invalid: <reason>`
- `Embedded Aspire skills metadata must specify a version.`
- `Embedded Aspire skills archive failed SHA-256 verification. Expected '<expected>', got '<actual>'.`

These errors indicate a problem with the Aspire CLI installation itself, not your project configuration. To resolve the issue, update the CLI:

```bash title="Aspire CLI"
aspire update --self
```

The update replaces the embedded bundle. If your installation method doesn't support self-updating, follow the [Install the Aspire CLI](/get-started/install-cli/) instructions to reinstall or update the CLI. If the problem persists after updating or reinstalling, [open an issue on GitHub](https://github.com/microsoft/aspire/issues).

## See also

- [Use AI coding agents](/get-started/ai-coding-agents/) — set up your project for AI agents
Expand Down
Loading
Loading