aspire-init
WORKFLOW SKILL - First-run flow for adding Aspire to a repo. Picks aspire new (greenfield) or aspire init (existing repo), drops the AppHost skeleton, then hands off to aspireify for resource wiring. USE FOR: aspire init, aspire new, aspire-starter, aspire-ts-starter, aspire-py-starter, add Aspire to existing repo, scaffold Aspire app, bootstrap Aspire, no AppHost detected, install aspireify, apphost.mts, generated .aspire/modules. DO NOT USE FOR: AppHost wiring on an existing AppHost (use aspireify), start/stop/wait (use aspire-orchestration), deploy/publish (use aspire-deployment), logs/traces (use aspire-monitoring), repo that already has an AppHost. INVOKES: aspire CLI (init, new, doctor), aspireify (handoff after skeleton drop). FOR SINGLE OPERATIONS: Run aspire init or aspire new TEMPLATE directly.
- Installs
- 655
- Last 24h
- +26
- Trending rank
- #4768
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/microsoft/aspire-skills --skill aspire-init- 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 aspire-init 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.
Aspire Init
First-run only. This skill owns the skeleton drop and template choice for repositories that do not yet have an Aspire AppHost. Once the skeleton is in place, hand off to
aspireifyfor the actual resource wiring.
Prerequisites
| Requirement | Install |
|---|---|
| .NET 10.0 SDK | https://dotnet.microsoft.com/download |
Node.js ^20.19.0, ^22.13.0, or >=24 (TypeScript AppHost) | https://nodejs.org |
| Aspire CLI (curl installer) | curl -sSL https://aspire.dev/install.sh | bash |
| Aspire CLI (npm) | npm install -g @microsoft/aspire-cli |
| Aspire CLI (NativeAOT global tool) | dotnet tool install -g Aspire.Cli (.NET 10 required) |
| Diagnose missing prerequisites | aspire doctor |
Aspire also supports Nix, Homebrew, WinGet, mise, and the curl/PowerShell installers. Use the installation method already owned by the user's environment.
Detection
Activate only when adding Aspire to a workspace that does not yet have one. Confirm ALL
of the following before running aspire init:
| Signal | How to Detect | Meaning |
|---|---|---|
| No C# AppHost | No .csproj containing Aspire.AppHost.Sdk | OK to init |
| No file-based AppHost | No apphost.cs with #:sdk Aspire.AppHost.Sdk | OK to init |
| No TypeScript AppHost | No current apphost.mts or legacy apphost.ts in the repo | OK to init |
| No Aspire config | No aspire.config.json in repo root | OK to init |
| User intent | Explicit "add Aspire", "scaffold Aspire", "aspire init" | OK to init |
If any AppHost signal is already present, do not run aspire init. Route to
aspireify (re-wire) or
aspire-orchestration (lifecycle).
Decision: aspire new vs aspire init
| Situation | Command | Why |
|---|---|---|
| Empty directory or brand-new project | aspire new <template> | Generates a full starter solution |
| Existing repo with services to model | aspire init | Drops minimal skeleton + aspire.config.json next to existing code |
| User wants a sample to learn from | aspire new aspire-starter | Includes ApiService + Web + ServiceDefaults |
| User wants the smallest possible scaffold | aspire new aspire-empty (C#) or aspire new aspire-ts-empty (TS) | No resources pre-wired |
| User wants Python services | aspire new aspire-py-starter (TypeScript AppHost drives Python) | Not dotnet new — that template was removed in 13.3 |
See references/templates.md for the complete template list and options.
Workflow A — aspire new <template> (new project)
For brand-new projects in an empty or non-existent directory:
- Confirm prerequisites with
aspire doctorif the CLI install is uncertain. - Pick a template from references/templates.md.
- Run the template, append
--non-interactivefor agent flows:aspire new aspire-starter --name MyApp --output ./MyApp --non-interactive - The new directory is fully wired by the template — no aspireify handoff needed.
- Route to
aspire-orchestrationfor first run (aspire start).
Workflow B — aspire init (existing repo)
For repositories that already contain services (Express API, .NET API, Python service, etc.) and need an AppHost added alongside them:
- Verify the Detection table — confirm no AppHost is present.
- Run
aspire init, choosing language explicitly for non-interactive flows:aspire init --language csharp --non-interactive # or aspire init --language typescript --non-interactive aspire initdrops:- The AppHost skeleton (
apphost.cswith#:sdkdirectives, orapphost.mtswith the generated.aspire/modules/folder) - AppHost configuration describing language + AppHost path
- The
aspireifyagent skill into the project's skill directory (same oneaspire agent inituses). In 13.6+, the chained agent setup preselects the recommended skills, includingaspireify, and does not offer Aspire MCP server configuration. If MCP config is missing after a successful init, that is expected and isn't a defect. MCP is a separate opt-in; see theaspirerouter's Skills vs. MCP guidance.
- The AppHost skeleton (
- Hand off to
aspireify—aspire initdoes not wire resources, projects, or integrations on its own. - After
aspireifyfinishes wiring, validate viaaspire start(aspire-orchestration).
In 13.5, a TypeScript init inside a repo that already has a root package.json creates a
nested aspire-apphost/ package and points the root aspire.config.json at
aspire-apphost/apphost.mts. A solution-backed C# repo can receive a project-based AppHost;
new C# AppHosts enable AspireUseCliBundle=true by default. Preserve these generated choices.
See references/init-workflow.md for the full sequence
including what aspire.config.json contains and what to do if aspire init fails partway.
Handoff Rules
After aspire init / aspire new finishes... | Route To |
|---|---|
| Skeleton dropped, resources need wiring | → aspireify skill (in-plugin or project-local) |
| Skeleton dropped, validate it starts | → aspire-orchestration (run aspire start) |
| New project from template, ready to run | → aspire-orchestration |
| User asks to deploy after init | → aspire-deployment |
| User asks for logs/traces after init | → aspire-monitoring |
| Existing AppHost detected — do NOT run init | → aspireify (re-wire) or aspire-orchestration (lifecycle) |
Project-Local Skill Override
If .agents/skills/aspire-init/SKILL.md exists project-locally (legacy install from an
older aspire init run), warn the user and defer to it. The legacy project-local skill
may carry repo-specific guidance that should not be overridden by this in-plugin skill.
The project-local aspireify skill (installed by aspire init) takes precedence
over this plugin's in-plugin aspireify for the same reason — defer to the project-local
copy and warn.
Error Handling
| Symptom | Cause | Action |
|---|---|---|
aspire init reports AppHost already exists | Repo already has an AppHost | Stop. Route to aspireify (re-wire) or aspire-orchestration (lifecycle) |
aspire init fails in non-interactive mode without --language | Multiple language paths available | Re-run with --language csharp or --language typescript |
aspire new rejects --output path | Path exists and is non-empty | Use a different --output or empty the directory |
aspire command not found | CLI not installed | dotnet tool install -g Aspire.Cli (.NET 10) or curl -sSL https://aspire.dev/install.sh | bash |
aspire doctor reports missing .NET 10 | SDK missing | Install .NET 10 SDK before retrying |
aspire init succeeded but no aspireify skill installed | Agent skill directory not detected, or aspireify not selected (13.5 doesn't preselect it) | Run aspire agent init --non-interactive --skills aspireify (append aspireify to any explicit --skills list, keep any --skill-locations, and don't add --mcp), then continue wiring |
aspire init succeeded but no MCP config was written | Expected in 13.6+ — chained agent setup does not offer MCP | Don't repair it. Configure MCP only when the user explicitly asks for it (aspire agent init --mcp on 13.6+) |
| Skeleton dropped but resources not wired | Expected — aspire init does not wire | Hand off to aspireify |
Existing TypeScript AppHost still uses apphost.ts | Legacy entry point and package graph | Hand off to aspire-orchestration, which owns approval and aspire update --migrate --yes --non-interactive; return to aspireify only for later source authoring |
References
- templates.md —
aspire newtemplates and options - init-workflow.md —
aspire initflow,aspire.config.jsonlayout, andaspireifyhandoff - aspire-13-5-breaking-changes.md — 13.5 migrations, CLI-bundle behavior, and fixes for affected releases
FAQ
What does the aspire-init skill do?
WORKFLOW SKILL - First-run flow for adding Aspire to a repo. Picks aspire new (greenfield) or aspire init (existing repo), drops the AppHost skeleton, then hands off to aspireify for resource wiring. USE FOR: aspire init, aspire new, aspire-starter, aspire-ts-starter, aspire-py-starter, add Aspire to existing repo, scaffold Aspire app, bootstrap Aspire, no AppHost detected, install aspireify, apphost.mts, generated .aspire/modules. DO NOT USE FOR: AppHost wiring on an existing AppHost (use aspireify), start/stop/wait (use aspire-orchestration), deploy/publish (use aspire-deployment), logs/traces (use aspire-monitoring), repo that already has an AppHost. INVOKES: aspire CLI (init, new, doctor), aspireify (handoff after skeleton drop). FOR SINGLE OPERATIONS: Run aspire init or aspire new TEMPLATE directly.
How do I install aspire-init?
Run npx skills add https://github.com/microsoft/aspire-skills --skill aspire-init 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/aspire-init/ (personal) or .claude/skills/aspire-init/ (project).
Which AI agents can use aspire-init?
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 aspire-init 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 aspire-init?
It is published by microsoft in microsoft/aspire-skills, and it is an official skill from the maker of the technology it covers. It has 655 recorded installs.
More from microsoft/aspire-skills
aspire
microsoft/aspire-skills
WORKFLOW SKILL - Aspire router. Detects AppHosts, enforces guardrails, and selects the right sub-skill. USE FOR: Aspire AppHost, Aspire CLI, distributed app, cloud-native .NET, aspire start/stop/resource/deploy/destroy/publish/init/new/add/wait/describe/ps/logs/otel, aspire agent init, WithBrowserLogs, WithTerminal, Interaction Service, apphost.mts, TS package managers, Yarn Classic, custom resource commands, .aspire/modules recovery, ProjectResource to DotnetProjectResource migration, or Playwright URL discovery. DO NOT USE FOR: non-Aspire projects or ordinary build/test tasks. INVOKES: aspire-init, aspireify, aspire-project-v2-migration, aspire-orchestration, aspire-deployment, aspire-monitoring. FOR SINGLE OPERATIONS: Route directly to the matching sub-skill.
aspire-orchestration
microsoft/aspire-skills
WORKFLOW SKILL — Manage Aspire lifecycle in VS Code or the CLI. WHEN: "start or stop my Aspire app", "aspireapphoststart", "aspireapphoststop", "notEditorOwned", "ambiguousSession", "aspire start", "aspire stop", "aspire wait", resource restart, file-lock errors (MSB3491 or CS2012), port conflicts, git worktrees, "--isolated", "aspire update --self", "aspire update --migrate", "aspire describe --include-hidden", "aspire stop --force", "aspire terminal", integration discovery, default watch, or hot reload. INVOKES: VS Code lifecycle tools first when exposed; Aspire CLI for readiness, inspection, resource operations, isolated worktree starts, and allowed fallbacks. DO NOT USE FOR: deploy/publish/destroy (aspire-deployment), logs/traces/metrics (aspire-monitoring), or AppHost code and resource wiring (aspireify). FOR SINGLE OPERATIONS: Load the matching editor tool first, then obey the exact-target, worktree-isolation, and stop-result rules below.
aspire-monitoring
microsoft/aspire-skills
ANALYSIS SKILL - Observe Aspire apps: logs, traces, metrics, resource state, telemetry export, browser telemetry, and the standalone dashboard. Routes between local Aspire CLI, AKS workload diagnostics, and deployed Azure resource health. USE FOR: aspire logs, aspire otel logs, aspire otel traces, aspire otel spans, aspire describe, aspire ps, aspire export, aspire dashboard run, describe --include-hidden, browser logs in dashboard, terminal view, DevTunnel URLs, WithBrowserLogs, App Insights query, AKS pod logs, container app logs. DO NOT USE FOR: start/stop/wait (use aspire-orchestration), deploy/publish/destroy (use aspire-deployment), AppHost code edits like WithBrowserLogs() (use aspireify), Azure provisioning (use azure-prepare). INVOKES: aspire CLI, azure-diagnostics (deployed Azure), kubectl + Container Insights. FOR SINGLE OPERATIONS: Run the aspire CLI command directly for quick log or describe lookups.
aspireify
microsoft/aspire-skills
WORKFLOW SKILL - Wire Aspire AppHosts or repair TypeScript AppHost toolchains. Scans the repo, proposes a resource graph, edits C, file-based C, or TypeScript AppHosts, wires ServiceDefaults + OTel, validates with aspire start, then stops. USE FOR: wire/scaffold AppHost, add Postgres/Redis/Rabbit/Mongo, connect frontend to API, after aspire init, AddNextJsApp, AddViteApp, WithBrowserLogs, WithTerminal, Interaction Service, command arguments, apphost.cs, apphost.mts, unified withEnvironment, .aspire/modules refusal, config/secrets, TS dependency restore, pnpm/yarn/bun, or Yarn Classic. DO NOT USE FOR: skeleton drop (aspire-init), lifecycle-only start/stop/wait/restart or aspire update --migrate (aspire-orchestration), publish/deploy/destroy (aspire-deployment), logs/traces (aspire-monitoring). INVOKES: aspire CLI, AppHost source edits, ServiceDefaults wiring. FOR SINGLE OPERATIONS: Run aspire add PACKAGE directly for a one-off integration.
aspire-deployment
microsoft/aspire-skills
WORKFLOW SKILL — Deploy Aspire apps from AppHost models to Docker Compose, Kubernetes, Azure, AWS, or preview Radius. WHEN: "deploy Aspire app", "publish Aspire artifacts", "deploy to Azure Container Apps", "generate Kubernetes artifacts", "deploy to Radius", "tear down Aspire deployment". INVOKES: aspire CLI, Aspire docs, target cloud/container CLIs. FOR SINGLE OPERATIONS: use generic Azure, Kubernetes, Docker, AWS, or Radius tools only when no Aspire AppHost exists.
aspire-project-v2-migration
microsoft/aspire-skills
Open the skill to read its SKILL.md instructions.
Popular devops & cloud skills
microsoft-foundry
microsoft/azure-skills
Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent create, managed harness agent create, GitHub Copilot harness agent, create agent, update agent, add tool to agent, invoke agent, agent insights, evaluate agent, batch eval, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, Agent Optimizer scaffold, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure
azure-diagnostics
microsoft/azure-skills
Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter.
azure-prepare
microsoft/azure-skills
Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure.
azure-ai
microsoft/azure-skills
Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.
azure-deploy
microsoft/azure-skills
Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment", "push to production", "push to cloud", "go live", "ship it", "bicep deploy", "terraform apply", "publish to Azure", "launch on Azure". DO NOT USE WHEN: "create and deploy", "build and deploy", "create a new app", "set up infrastructure", "create and deploy to Azure using Terraform" — use azure-prepare for these.
azure-validate
microsoft/azure-skills
Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment.