npx skills add ...
npx skills add microsoft/aspire-skills --skill aspire-init
npx skills add microsoft/aspire-skills --skill 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, 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.
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.
| Requirement | Install |
|---|---|
| .NET 10.0 SDK | https://dotnet.microsoft.com/download |
| Aspire CLI (curl installer) | curl -sSL https://aspire.dev/install.sh | bash |
| Aspire CLI (NativeAOT global tool) | dotnet tool install -g Aspire.Cli (.NET 10 required) |
| Diagnose missing prerequisites | aspire doctor |
Aspire ships the CLI as a NativeAOT .NET global tool — instant startup, no JIT warmup. The curl/PowerShell installer remains supported for environments without .NET 10.
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 apphost.ts in repo root | 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).
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.
aspire new <template> (new project)For brand-new projects in an empty or non-existent directory:
aspire doctor if the CLI install is uncertain.--non-interactive for agent flows:
aspire-orchestration for first run
(aspire start).aspire init (existing repo)For repositories that already contain services (Express API, .NET API, Python service, etc.) and need an AppHost added alongside them:
aspire init, choosing language explicitly for non-interactive flows:
aspire init drops:
apphost.cs with #:sdk directives, or apphost.ts with the
generated .aspire/modules/ folder)aspireify agent skill into the project's skill directory (same one
aspire agent init uses)aspireify — aspire init does not wire resources, projects, or
integrations on its own.aspireify finishes wiring, validate via aspire start
(aspire-orchestration).See references/init-workflow.md for the full sequence
including what aspire.config.json contains and what to do if aspire init fails partway.
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) |
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.
| 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 | Run aspire agent init to install aspireify, then continue wiring |
| Skeleton dropped but resources not wired | Expected — aspire init does not wire | Hand off to aspireify |
aspire new templates and optionsaspire init flow, aspire.config.json
layout, and aspireify handoff