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

Use Aspire’s first-party agent setup when creating a new app, adding Aspire to an existing repo, or refreshing agent guidance later. The Aspire CLI is the recommended path for project-local setup because it installs Aspire skill files into detected agent environments.

Set up or refresh agent guidance

Aspire CLI

aspire agent init

Run aspire agent init in an existing Aspire project when you want to set up AI coding agents or refresh installed skill files.

For command options and examples, see the aspire agent init command reference.

Create a new Aspire app

Aspire CLI

aspire new

When prompted to configure AI agent environments, press Y Y Y Y Y Y then Return Return Enter Enter Enter Enter .

For template and command options, see the aspire new command reference.

Add Aspire to an existing repo

Aspire CLI

aspire init

When prompted to install Aspire agent guidance, press Y Y Y Y Y Y then Return Return Enter Enter Enter Enter .

For command options and examples, see the aspire init command reference.

Configure non-interactive setup

For non-interactive setup, add --non-interactive and pass the skill and location options explicitly. Install the Aspire workflow skills together; the top-level aspire skill routes work to workflow-specific skills and isn’t useful as the only Aspire skill. This example installs all available skills into the standard skill location:

Bash

Aspire CLI

aspire agent init \
  --non-interactive \
  --skills all \
  --skill-locations standard

PowerShell

Aspire CLI

aspire agent init `
  --non-interactive `
  --skills all `
  --skill-locations standard

When the same repo is intentionally used with both a Standard-compatible host and Claude Code, install the same skills into both locations:

Bash

Aspire CLI

aspire agent init \
  --non-interactive \
  --skills all \
  --skill-locations standard,claudecode

PowerShell

Aspire CLI

aspire agent init `
  --non-interactive `
  --skills all `
  --skill-locations standard,claudecode

Other installation options

Use these tabs when you need to install from a coding agent’s marketplace or a skills-compatible installer instead of using the Aspire CLI.

Copilot CLI

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

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.

For plugin install details, see Finding and installing plugins for GitHub Copilot CLI.

Claude Code

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

Terminal

claude

Claude Code CLI session

/plugin marketplace add microsoft/aspire-skills
/plugin install aspire@aspire-skills

Run the slash commands inside the Claude Code CLI session.

For plugin marketplace details, see Discover and install prebuilt plugins through marketplaces.

Codex CLI

Add the Aspire marketplace, then open the Codex plugin directory and install the Aspire plugin from the plugin browser.

Terminal

codex plugin marketplace add microsoft/aspire-skills
codex

Codex CLI session

/plugins

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

For plugin install details, see the Codex plugin documentation.

OpenCode

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

OpenCode

apm install microsoft/aspire-skills
opencode

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

For APM install details, see the Agent Package Manager quickstart.

skills.sh

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

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:

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.

For installer options, see the skills.sh CLI documentation.

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

The Aspire CLI setup flow can offer companion options, 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	Inspecting .NET APIs outside Aspire	Query .NET package and type surfaces that aren’t covered by Aspire API docs

Use playwright-cli when an agent needs to test or inspect a running frontend. For Playwright commands and options, see the Playwright command line documentation.

dotnet-inspect scope

Use dotnet-inspect only when an agent needs to inspect .NET code or packages outside Aspire. If you’re only working with Aspire APIs, use the Aspire CLI instead: aspire docs api already provides C# and TypeScript API docs from aspire.dev.

For more information, see the aspire docs api command reference.

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:

Prefer one location

Install skills to a single location for the agent environment you actively use. Select multiple locations only when the same repo is intentionally shared across different agent hosts.

• Каталог.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 the Aspire CLI 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 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.

See also

• Use AI coding agents — set up your project for AI agents
• aspire agent init command
• aspire init command