How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/microsoft/aspire-skills --skill aspire-initBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
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 `aspireify` for 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-orchestration` for 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-interactiveaspire initdrops:
- The AppHost skeleton (
apphost.cswith#:sdkdirectives, orapphost.mtswith the
generated .aspire/modules/ folder)
- AppHost configuration describing language + AppHost path
- The `aspireify` agent skill into the project's skill directory (same one
aspire agent init uses). In 13.6+, the chained agent setup preselects the recommended skills, including aspireify, 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 the aspire router's Skills vs. MCP guidance.
- Hand off to `aspireify` —
aspire initdoes not wire resources, projects, or
integrations on its own.
- After
aspireifyfinishes wiring, validate viaaspire start
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.json
layout, and aspireify handoff
13.5 migrations, CLI-bundle behavior, and fixes for affected releases
