Skip to content
Get packs

Guide · Agent skill

How to use the Aspire Distributed-App Helper agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The Aspire skill is a set of instructions and reference notes that teaches an AI agent how to work with Aspire, a toolkit for running several services (APIs, frontends, databases, workers) together from one orchestrator project called the AppHost. This guide explains what the skill does, how to install it, how to ask for help in plain language, and what to check before you rely on its output. By the end you will be able to install the skill and ask an agent to scaffold, run, or troubleshoot an Aspire app.

Aspire Distributed-App Helpergithub/awesome-copilot · MIT

Quick start

  1. 1Check prerequisites. Confirm the .NET SDK 10.0 or later and a container runtime such as Docker Desktop, Podman or Rancher Desktop are installed.
  2. 2Install the Aspire CLI. Run the install script for your operating system from aspire.dev, then run aspire --version to confirm it works.
  3. 3Download and unzip the skill. Download the aspire skill ZIP from this page and unzip it into ~/.claude/skills/ or your project's .claude/skills/ folder.
  4. 4Or upload it in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
  5. 5Ask for an Aspire task. Describe what you want in plain language, naming Aspire and your services, for example a new AppHost for a .NET API and a Python service.
  6. 6Review the output. Check the commands and code the agent proposes against aspire --help or the official docs, then run them yourself.

What is an agent skill, and what does the Aspire skill do?

An agent skill is a folder containing a SKILL.md file and optional reference files. When installed, an AI agent can load these instructions when a task matches the skill's description, so it works from documented guidance instead of guessing.

The Aspire skill covers the Aspire CLI, AppHost orchestration, service discovery, integrations, the MCP server, the VS Code extension, Dev Containers, GitHub Codespaces, project templates, the dashboard, and deployment. With it installed, the agent knows Aspire's CLI commands, project templates, service discovery, integrations, dashboard, MCP setup and deployment options, and can load detailed reference notes when a task needs them.

  • Scaffold an AppHost and wire services together
  • Explain how services find each other through environment variables
  • Help diagnose startup errors and Aspire diagnostic codes
  • Describe deployment options for Docker, Kubernetes, Azure Container Apps and Azure App Service

What you need before installing the skill

The skill assumes a working .NET and container setup. The AppHost is itself a .NET project, so the .NET SDK is required even if your services are written in Python or JavaScript.

  • .NET SDK 10.0 or later
  • A container runtime such as Docker Desktop, Podman or Rancher Desktop
  • Aspire CLI, installed with a script from aspire.dev
  • Optional: an MCP-capable assistant and Context7 for documentation lookup
  • Optional: VS Code with C# Dev Kit, Visual Studio 2022 or JetBrains Rider
aspire --version

Install the Aspire skill

Download the aspire skill ZIP from this page and unzip it. You can install it in one of two places. For a personal install available in all your projects, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.

In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

  • Personal: ~/.claude/skills/
  • Per project: .claude/skills/ inside your project folder
  • Claude apps: Settings → Capabilities → Skills

Install the Aspire CLI and templates

The skill does not install the tools for you. Install the Aspire CLI with the script for your operating system, then confirm it works. The skill's reference also lists templates you can install with the .NET CLI.

  • Templates include aspire-starter, aspire-ts-cs-starter, aspire-py-starter and aspire-apphost-singlefile
# Linux / macOS curl -sSL https://aspire.dev/install.sh | bash # Windows PowerShell irm https://aspire.dev/install.ps1 | iex # Verify aspire --version # Install templates dotnet new install Aspire.ProjectTemplates

How to trigger the skill with natural requests

You do not need special syntax. The skill is meant to load when you ask for work on an Aspire distributed application to create, run, debug, configure, deploy or troubleshoot it. Name Aspire in your request so the agent connects it to the skill.

Be specific about your goal and your services. The agent works best when it knows which languages and resources you need.

  • "Create an Aspire AppHost that runs a .NET API, a Python ML service and a Vite React frontend with Redis."
  • "My Aspire app fails to start; the API starts before Postgres is ready. Help me fix the ordering."
  • "Explain diagnostic code ASPIRE... from this build output and how to resolve it."
  • "Set up an Aspire deployment to Azure Container Apps."

What the skill can and cannot do for you

The skill's guidance is a summary. Its own notes say Aspire changes between releases, so commands and APIs may differ from what the agent describes. For documentation lookups it points to the Aspire MCP server when your CLI version supports docs search, and to Context7 as a fallback. Check any command against aspire --help or the official docs before you run it on something important.

The skill does not run scripts by itself, but it does use the network, for example when it looks up documentation through MCP or Context7.

Safety notes: scripts and network access

The skill's listing states that it runs no scripts and uses the network. Network use is for documentation lookup. Commands the agent suggests, such as the install script above, are still run by you or by the agent with your approval, so review them before running.

Treat deployment advice as a starting point for review, not a final decision. The skill itself warns against making production deployment decisions without review.

  • Runs scripts: no
  • Uses network: yes (documentation lookup via MCP or Context7)
  • Review install scripts and deployment commands before running them

Tips for getting better results

Give the agent your exact error text and the CLI version from aspire --version. The skill's troubleshooting reference is organised around diagnostic codes and common errors, so those details help it find the right entry.

For work across several languages, say which services are .NET and which are Python, Node or Go, since the AppHost wiring differs between them.

  • Include the full error output and your Aspire CLI version
  • Name each service and its language
  • Ask for a plan first, then review it before the agent edits files

What people use it for

  • Scaffolding a new AppHost that wires a .NET API, a Python service and a frontend together
  • Setting up service discovery so one service can reach another without hard-coded addresses
  • Diagnosing a service that fails to start or starts in the wrong order
  • Choosing and wiring integrations such as Redis or Postgres from the integrations catalog
  • Preparing deployment steps for Docker, Kubernetes, Azure Container Apps or Azure App Service

Frequently asked questions

How do I install the Aspire agent skill?

Download the aspire skill ZIP from this page and unzip it into ~/.claude/skills/ for a personal install, or into a project's .claude/skills/ folder for a single project. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.

What do I need before using the Aspire skill?

You need the .NET SDK 10.0 or later, even for non-.NET services, plus a container runtime such as Docker Desktop, Podman or Rancher Desktop. The Aspire CLI is installed separately with a script from aspire.dev. Visual Studio, VS Code or Rider are optional.

Do I need .NET to use Aspire if my app is in Python or JavaScript?

Yes. The skill's guidance is that the AppHost itself is a .NET project, so the .NET SDK is required even when your workloads are Python or JavaScript. Non-.NET services run as containers or executables under the AppHost.

Is the Aspire skill free?

The skill is listed under the MIT licence. This page does not state pricing for Aspire beyond the licence of the skill itself, so check the licence file in the repository for the terms.

How does the Aspire skill compare with using the docs directly?

The skill gives the agent a summary of Aspire's CLI, templates, integrations and deployment options, plus reference notes it loads when needed. The skill's own notes say it may lag behind Aspire releases, so for the latest details use the MCP docs tools, Context7, or aspire.dev.

Why does my Aspire app fail to start?

Start by copying the exact error and running aspire --version. Give both to the agent so it can check the troubleshooting reference for diagnostic codes and startup ordering. Services that depend on others can be gated with WaitFor, which waits on health checks.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you are building a multi-service app with Aspire and want an agent that knows its CLI, templates and wiring patterns. Pick something else if you have no interest in .NET or need guaranteed-current guidance for production deployments, since the skill is a summary that can lag behind Aspire releases.

Download the skill