# Aspire skills

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 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
  agents](/get-started/ai-coding-agents/).
</LearnMore>

## Install Aspire guidance

Choose the tab that matches your coding agent or installer path. The Aspire CLI path is recommended for project-local setup because it installs Aspire skill files into detected agent environments.

Use Aspire's first-party agent setup when creating a new app, adding Aspire to an existing repo, or refreshing agent guidance later.

```bash title="Aspire CLI"
aspire new
# select y when prompted to configure AI agent environments

aspire init
# select y when prompted to install Aspire agent guidance

aspire agent init
```

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. 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
```

Add the Aspire skills marketplace once, then install the Aspire plugin by name.

```bash title="GitHub Copilot CLI"
copilot plugin marketplace add microsoft/aspire-skills
copilot plugin install aspire@aspire-skills
```

Use this path for terminal workflows where GitHub Copilot needs Aspire-specific guidance for AppHost, lifecycle, deployment, and diagnostics tasks.

Start Claude Code in your terminal, add the Aspire marketplace, then install the Aspire plugin.

```bash title="Claude Code CLI"
claude
/plugin marketplace add microsoft/aspire-skills
/plugin install aspire@aspire-skills
```

Run the slash commands inside the Claude Code CLI session.

Add the Aspire marketplace, then install Aspire from the Codex plugins UI.

```bash title="Codex CLI"
codex plugin marketplace add microsoft/aspire-skills
# then open /plugins and install aspire
```

Use this path for terminal-first Codex work that needs repeatable Aspire setup, orchestration, and diagnostics guidance.

Use APM to install Aspire skills into agent hosts that support OpenCode-compatible skill locations.

```bash title="OpenCode"
apm install microsoft/aspire-skills
opencode
```

Use this path when APM is your preferred way to manage agent skills.

Use the Skills-compatible installer when your agent host supports skills.sh-managed skill locations.

```bash title="skills.sh NPX"
npx skills add microsoft/aspire-skills
```

For hosts that need an explicit skills directory and target agent, install from the `skills/` folder:

```bash title="skills.sh NPX with explicit target"
npx skills add https://github.com/microsoft/aspire-skills/tree/main/skills \
  -a github-copilot -g -y
```

In that command, `-a github-copilot` selects the target agent, `-g` installs globally, and `-y` accepts prompts.

## Aspire workflow skills

| Skill                  | Use it for                                                                                             | What it teaches                                                                                                                                                          |
| ---------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `aspire`               | Routing Aspire tasks to the right workflow                                                             | Detect the AppHost, apply Aspire safety guardrails, and choose the appropriate workflow for the user's request                                                           |
| `aspire-init`          | Starting a new Aspire app or adding Aspire to an existing repo                                         | Choose `aspire new` or `aspire init`, create the AppHost skeleton, and hand off existing-codebase wiring to `aspireify`                                                  |
| `aspire-orchestration` | Managing the local AppHost lifecycle                                                                   | Start, stop, restart, wait for, and inspect Aspire resources, including recovery from port conflicts and orphaned processes                                              |
| `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 |

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 every Aspire workflow skill and selected companion skills:

- .agents/skills/
  - aspire/
    - SKILL.md
  - aspire-init/
    - SKILL.md
  - aspire-orchestration/
    - SKILL.md
  - aspire-monitoring/
    - SKILL.md
  - aspire-deployment/
    - SKILL.md
  - aspireify/
    - SKILL.md
  - playwright-cli/
    - SKILL.md
  - dotnet-inspect/
    - SKILL.md

Other supported locations use the same skill folder names:

| Location          | Directory          | Notes                                              |
| ----------------- | ------------------ | -------------------------------------------------- |
| **Standard**      | `.agents/skills/`  | Supported by VS Code, GitHub Copilot, and OpenCode |
| **Claude Code**   | `.claude/skills/`  | Claude Code specific                               |
| **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
- [aspire agent init command](/reference/cli/commands/aspire-agent-init/)
- [aspire init command](/reference/cli/commands/aspire-init/)