Aspire skills

Ce contenu n’est pas encore disponible dans votre langue.

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 bundle includes six workflow skills: aspire, aspire-init, aspire-orchestration, aspire-monitoring, aspire-deployment, and aspireify.

To configure AI coding agents end to end, see Use AI coding agents.

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.

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:

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:

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.

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.

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.

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.

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.

npx skills add microsoft/aspire-skills

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

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:

Répertoire.agents/skills/
- Répertoireaspire/
  - SKILL.md
- Répertoireaspire-init/
  - SKILL.md
- Répertoireaspire-orchestration/
  - SKILL.md
- Répertoireaspire-monitoring/
  - SKILL.md
- Répertoireaspire-deployment/
  - SKILL.md
- Répertoireaspireify/
  - SKILL.md
- Répertoireplaywright-cli/
  - SKILL.md
- Répertoiredotnet-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:

aspire update --self

The update replaces the embedded bundle. If your installation method doesn’t support self-updating, follow the Install the Aspire CLI instructions to reinstall or update the CLI. If the problem persists after updating or reinstalling, open an issue on GitHub.