working-with-aspire

Q: How do I install working-with-aspire?

Run npx skills add https://github.com/mhagrelius/dotfiles --skill working-with-aspire in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/working-with-aspire/ (personal) or .claude/skills/working-with-aspire/ (project).

by mhagreliusBackend & APIs

Use when building distributed apps with Aspire; orchestrating .NET, JavaScript, Python, or polyglot services; when environment variables or service discovery aren't working; when migrating from .NET Aspire 9 to 13+ or Community Toolkit; when seeing AddNpmApp deprecated errors; when OTEL not appearing in dashboard; when ports change on restart breaking OAuth; when configuring MCP server for AI assistants; when debugging Aspire apps and need to check resource status or logs

Installs: 42
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/mhagrelius/dotfiles --skill working-with-aspire

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads working-with-aspire automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Working with .NET Aspire 13

For AI Assistants: Use MCP Tools

CRITICAL: When helping users debug Aspire applications, use the Aspire MCP tools instead of curl, external HTTP calls, or suggesting manual dashboard inspection.

Task	MCP Tool	NOT This
Check resource status	`list_resources`	❌ curl to dashboard API
Get service logs	`list_console_logs`	❌ curl, docker logs
View traces	`list_traces`	❌ curl to OTLP endpoint
Find errors in traces	`list_trace_structured_logs`	❌ manual dashboard search
List available AppHosts	`list_apphosts`	❌ file system search

If MCP is not configured, guide the user to run aspire mcp init in their AppHost directory.

Quick Reference

Task	Reference File
AppHost patterns, resources, lifecycle	`app-host.md`
Azure integrations (databases, messaging, AI)	`azure-integrations.md`
Database integrations (Postgres, SQL, Mongo)	`database-integrations.md`
Caching (Redis, Valkey, Garnet)	`caching-integrations.md`
Messaging (Kafka, RabbitMQ, NATS)	`messaging-integrations.md`
Polyglot (Node.js, Python, Go, Rust, Java)	`polyglot-integrations.md`
Deployment, CLI, and aspire do pipelines	`deployment-cli.md`
Testing with Aspire	`testing.md`
Errors and troubleshooting	`diagnostics.md`
MCP integration for AI assistants	`mcp-integration.md`
VS Code extension	`vs-code-extension.md`
Certificate trust configuration	`certificate-config.md`
Migration from 9.x to 13.x	`aspire-13-migration.md`

Common Mistakes

❌ Wrong: Using non-existent or deprecated APIs

Wrong	Correct	Why
`AddPythonUvicornApp`	`AddUvicornApp`	Method is just `AddUvicornApp`
`AddNpmApp`	`AddViteApp` or `AddJavaScriptApp`	`AddNpmApp` removed in 13.0
`AddPythonApp` for FastAPI	`AddUvicornApp`	Use AddUvicornApp for ASGI (FastAPI, Starlette)
`Aspire.Hosting.NodeJs`	`Aspire.Hosting.JavaScript`	Package renamed in 13.0

❌ Wrong: Putting secrets in appsettings.json

// WRONG - secrets exposed in source control
// appsettings.json: { "Parameters": { "api-key": "secret123" } }

// CORRECT - use user-secrets for development
// dotnet user-secrets set "Parameters:api-key" "secret123"

Aspire 13 Breaking Changes

Critical: Migration from Aspire 9.x requires attention. See aspire-13-migration.md for full details.

JavaScript/Node.js Changes (13.0)

// BEFORE (9.x) - REMOVED IN 13.0
builder.AddNpmApp("frontend", "../app", scriptName: "dev", args: ["--no-open"])

// AFTER (13.0) - Use AddJavaScriptApp or AddViteApp
builder.AddJavaScriptApp("frontend", "../app")
    .WithRunScript("dev")
    .WithArgs("--no-open");

// For Vite/React specifically:
builder.AddViteApp("frontend", "../app")
    .WithHttpEndpoint(env: "PORT");

// Package renamed: Aspire.Hosting.NodeJs → Aspire.Hosting.JavaScript

Azure Redis Changes (13.1)

// BEFORE (13.0) - DEPRECATED
builder.AddAzureRedisEnterprise("cache")

// AFTER (13.1)
builder.AddAzureManagedRedis("cache")

Network Context Changes (13.0)

// BEFORE (9.x) - containerHostName parameter removed
await resource.ProcessArgumentValuesAsync(
    executionContext, processValue, logger,
    containerHostName: "localhost", cancellationToken);

// AFTER (13.0) - Use NetworkIdentifier
await resource.ProcessArgumentValuesAsync(
    executionContext, processValue, logger, cancellationToken);

// Get endpoints with network context
var endpoint = api.GetEndpoint("http", KnownNetworkIdentifiers.DefaultAspireContainerNetwork);

Publishing API Changes (13.0)

// BEFORE (9.x)
public class MyPublisher : IDistributedApplicationPublisher { }

// AFTER (13.0) - Use aspire do pipelines instead
// IDistributedApplicationPublisher is deprecated

Aspire 13.0+ New Features

Certificate Trust Automation

// Automatic - no configuration needed
var pythonApi = builder.AddUvicornApp("api", "./api", "main:app");
var nodeApi = builder.AddJavaScriptApp("frontend", "./frontend");
// Both automatically trust development certificates

MCP Integration for AI Assistants

# Initialize MCP for Claude Code, GitHub Copilot, etc.
aspire mcp init

aspire do Pipeline System

aspire do build           # Build container images
aspire do push            # Push to registry
aspire do deploy          # Full deployment
aspire do diagnostics     # Show available steps

aspire init (Aspirify Existing Projects)

aspire init               # Interactive setup
aspire init --single-file # Create .cs AppHost without .csproj

Single-File AppHost

// apphost.cs - no project file needed
#:package Aspire.Hosting@*
#:package Aspire.Hosting.Redis@*

var builder = DistributedApplication.CreateBuilder(args);
var cache = builder.AddRedis("cache");
builder.Build().Run();

Common Patterns

FastAPI + React (Vite) Full Stack

// Required packages:
// dotnet add package Aspire.Hosting.Python
// dotnet add package Aspire.Hosting.JavaScript  (NOT NodeJs!)
// dotnet add package Aspire.Hosting.PostgreSQL

var builder = DistributedApplication.CreateBuilder(args);

// Database
var db = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// FastAPI backend - use AddUvicornApp (NOT AddPythonApp!)
var api = builder.AddUvicornApp("api", "../api", "main:app")
    .WithHttpEndpoint(port: 8000, env: "PORT")
    .WithReference(db)
    .WaitFor(db);

// React frontend - use AddViteApp (NOT AddNpmApp!)
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithExternalHttpEndpoints()
    .WithReference(api);

builder.Build().Run();

Frontend reads API URL from env: process.env.services__api__http__0

Basic AppHost Structure

var builder = DistributedApplication.CreateBuilder(args);

// Database
var db = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// API with database reference
var api = builder.AddProject<Projects.Api>("api")
    .WithReference(db)
    .WaitFor(db);

// Frontend with API reference
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

Service Discovery Pattern

// Producer exposes endpoint
var api = builder.AddProject<Projects.Api>("api")
    .WithHttpEndpoint(port: 5000, name: "api");

// Consumer references it (gets services__api__api__0 env var)
builder.AddProject<Projects.Web>("web")
    .WithReference(api);

Health Checks and Wait

var db = builder.AddPostgres("db");
var cache = builder.AddRedis("cache");

builder.AddProject<Projects.Api>("api")
    .WithReference(db)
    .WithReference(cache)
    .WaitFor(db)           // Wait for running
    .WaitForHealthy(cache); // Wait for healthy (requires health check)

When to Read Specific Files

Read app-host.md when:

Setting up new AppHost project
Understanding resource lifecycle events
Configuring endpoints and networking
Using parameters and secrets

Read azure-integrations.md when:

Using Azure services (Cosmos, Service Bus, Storage)
Running Azure emulators locally
Using RunAsEmulator() or RunAsContainer()
Customizing Bicep output

Read polyglot-integrations.md when:

Adding Node.js, Python, Go, Rust, or Java apps
Frontend frameworks (Vite, Angular, React)
Container-based polyglot services
Migrating from AddNpmApp to AddJavaScriptApp

Read deployment-cli.md when:

Using aspire deploy, aspire publish, or aspire do
Using aspire init to Aspirify existing projects
Setting up CI/CD pipelines
Understanding manifest format

Read mcp-integration.md when:

Setting up AI assistant integration
Configuring Claude Code, GitHub Copilot, or Cursor
Excluding resources from MCP access

Read vs-code-extension.md when:

Using Aspire in VS Code
Debugging polyglot applications
Creating new Aspire projects in VS Code

Read certificate-config.md when:

Configuring HTTPS for polyglot apps
Custom certificate authorities
Certificate trust issues between services

Read aspire-13-migration.md when:

Upgrading from Aspire 9.x
Seeing deprecated API warnings
Container networking issues after upgrade

Read diagnostics.md when:

Seeing ASPIRE* compiler errors
Debugging service discovery issues
Troubleshooting container startup

FAQ

What does the working-with-aspire skill do?

How do I install working-with-aspire?

Run npx skills add https://github.com/mhagrelius/dotfiles --skill working-with-aspire in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/working-with-aspire/ (personal) or .claude/skills/working-with-aspire/ (project).

Which AI agents can use working-with-aspire?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is working-with-aspire safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains working-with-aspire?

It is published by mhagrelius in mhagrelius/dotfiles. It has 42 recorded installs.

More from mhagrelius/dotfiles

View all →

dotnet-10-csharp-14

mhagrelius/dotfiles

Use when building .NET 10 or C 14 applications; when using minimal APIs, modular monolith patterns, or feature folders; when implementing HTTP resilience, Options pattern, Channels, or validation; when seeing outdated patterns like old extension method syntax

Backend & APIs1.9K installs

developing-gtk-apps

mhagrelius/dotfiles

Use for any change to a GTK 4/libadwaita app, new or existing, whether or not the request mentions GTK. Trigger on the repo rather than the wording — if Cargo.toml depends on gtk4/libadwaita, or sources import gi/Gtk (Python) or use Gtk (Vala), this applies to every change to that app, including requests phrased purely as symptoms ("reordering doesn't work", "pressing enter should continue the list", "the window opens too small"). Covers app boilerplate and new features; behaviour bugs in drag-and-drop, context menus, keyboard and text editing, focus, selection, and window sizing; threading, signals, and lifecycle; gtk-rs calls that fail to compile; GSettings, resources, packaging, and tests. Delegates widget choice, layout, and HIG to designing-gnome-ui.

Frontend & Design120 installs

designing-gnome-ui

mhagrelius/dotfiles

Open the skill to read its SKILL.md instructions.

Frontend & Design100 installs

building-tui-apps

mhagrelius/dotfiles

Use when building interactive terminal dashboards or full-screen terminal applications; when implementing keyboard navigation, live data updates, or multi-panel layouts; when TUI is flickering, slow, or unresponsive; when handling terminal resize events

100 installs

using-typescript-lsp

mhagrelius/dotfiles

Open the skill to read its SKILL.md instructions.

Code Quality & Workflow50 installs

working-with-ms-agent-framework

mhagrelius/dotfiles

Use when building AI agents with Microsoft Agent Framework (Semantic Kernel + AutoGen unified); when implementing memory or context providers; when threads won't deserialize; when workflow checkpointing fails; when migrating from Semantic Kernel or AutoGen; when seeing ChatAgent or AgentThread errors

AI & Agents42 installs

Popular backend & apis skills

View category →

find-skills

vercel-labs/skills

Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.

OfficialBackend & APIs4.1M installs

entra-app-registration

microsoft/azure-skills

Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.

OfficialBackend & APIs566.7K installs

google-agents-cli-adk-code

google/agents-cli

This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).

Backend & APIs514.8K installs

embedded-captions

heygen-com/hyperframes

Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.

Backend & APIs453.3K installs

entra-agent-id

microsoft/azure-skills

Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).

OfficialBackend & APIs336.6K installs

neon

neondatabase/agent-skills

Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.

Backend & APIs237.1K installs

working-with-aspire

Install

Install

Describe the task

Review the result

SKILL.md

Working with .NET Aspire 13

For AI Assistants: Use MCP Tools

Quick Reference

Common Mistakes

❌ Wrong: Using non-existent or deprecated APIs

❌ Wrong: Putting secrets in appsettings.json

Aspire 13 Breaking Changes

JavaScript/Node.js Changes (13.0)

Azure Redis Changes (13.1)

Network Context Changes (13.0)

Publishing API Changes (13.0)

Aspire 13.0+ New Features

Certificate Trust Automation

MCP Integration for AI Assistants

aspire do Pipeline System

aspire init (Aspirify Existing Projects)

Single-File AppHost

Common Patterns

FastAPI + React (Vite) Full Stack

Basic AppHost Structure

Service Discovery Pattern

Health Checks and Wait

When to Read Specific Files

FAQ

More from mhagrelius/dotfiles

Popular backend & apis skills