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 doctor if the CLI install is uncertain.
- Pick a template from references/templates.md.
- Run the template, append
--non-interactive for 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-interactive
aspire init drops:
- The AppHost skeleton (
apphost.cs with #:sdk directives, or apphost.mts with 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)
- Hand off to
aspireify — aspire init does not wire resources, projects, or
integrations on its own.
- After
aspireify finishes wiring, validate via aspire 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 |
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 |
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 new templates and options
- init-workflow.md —
aspire init flow, aspire.config.json
layout, and aspireify handoff
- aspire-13-5-breaking-changes.md —
13.5.3 versions, migrations, and CLI-bundle behavior
1---
2name: aspire-init
3description: >-
4 **WORKFLOW SKILL** - First-run flow for adding Aspire to a repo. Picks `aspire new`
5 (greenfield) or `aspire init` (existing repo), drops the AppHost skeleton, then hands
6 off to `aspireify` for resource wiring.
7 USE FOR: aspire init, aspire new, aspire-starter, aspire-ts-starter, aspire-py-starter,
8 add Aspire to existing repo, scaffold Aspire app, bootstrap Aspire, no AppHost detected,
9 install aspireify, apphost.mts, generated .aspire/modules.
10 DO NOT USE FOR: AppHost wiring on an existing AppHost (use aspireify), start/stop/wait
11 (use aspire-orchestration), deploy/publish (use aspire-deployment), logs/traces (use
12 aspire-monitoring), repo that already has an AppHost.
13 INVOKES: aspire CLI (init, new, doctor), aspireify (handoff after skeleton drop).
14 FOR SINGLE OPERATIONS: Run `aspire init` or `aspire new TEMPLATE` directly.
15license: MIT
16metadata:
17 source: https://skillmd.com/skills/microsoft/aspire-init
18 author: Microsoft
19 version: "0.0.2"
20---
21
22# Aspire Init
23
24> **First-run only.** This skill owns the skeleton drop and template choice for repositories
25> that do not yet have an Aspire AppHost. Once the skeleton is in place, hand off to
26> [`aspireify`](https://github.com/microsoft/aspire-skills/blob/main/skills/aspireify/SKILL.md) for the actual resource wiring.
27
28## Prerequisites
29
30| Requirement | Install |
31|-------------|---------|
32| .NET 10.0 SDK | https://dotnet.microsoft.com/download |
33| Node.js `^20.19.0`, `^22.13.0`, or `>=24` (TypeScript AppHost) | https://nodejs.org |
34| Aspire CLI (curl installer) | `curl -sSL https://aspire.dev/install.sh \| bash` |
35| Aspire CLI (npm) | `npm install -g @microsoft/aspire-cli` |
36| Aspire CLI (NativeAOT global tool) | `dotnet tool install -g Aspire.Cli` (.NET 10 required) |
37| Diagnose missing prerequisites | `aspire doctor` |
38
39> Aspire also supports Nix, Homebrew, WinGet, mise, and the curl/PowerShell installers.
40> Use the installation method already owned by the user's environment.
41
42## Detection
43
44Activate **only** when adding Aspire to a workspace that does not yet have one. Confirm ALL
45of the following before running `aspire init`:
46
47| Signal | How to Detect | Meaning |
48|--------|---------------|---------|
49| No C# AppHost | No `.csproj` containing `Aspire.AppHost.Sdk` | OK to init |
50| No file-based AppHost | No `apphost.cs` with `#:sdk Aspire.AppHost.Sdk` | OK to init |
51| No TypeScript AppHost | No current `apphost.mts` or legacy `apphost.ts` in the repo | OK to init |
52| No Aspire config | No `aspire.config.json` in repo root | OK to init |
53| User intent | Explicit "add Aspire", "scaffold Aspire", "aspire init" | OK to init |
54
55If **any** AppHost signal is already present, **do not run `aspire init`**. Route to
56[`aspireify`](https://github.com/microsoft/aspire-skills/blob/main/skills/aspireify/SKILL.md) (re-wire) or
57[`aspire-orchestration`](https://github.com/microsoft/aspire-skills/blob/main/skills/aspire-orchestration/SKILL.md) (lifecycle).
58
59## Decision: `aspire new` vs `aspire init`
60
61| Situation | Command | Why |
62|-----------|---------|-----|
63| Empty directory or brand-new project | `aspire new <template>` | Generates a full starter solution |
64| Existing repo with services to model | `aspire init` | Drops minimal skeleton + `aspire.config.json` next to existing code |
65| User wants a sample to learn from | `aspire new aspire-starter` | Includes ApiService + Web + ServiceDefaults |
66| User wants the smallest possible scaffold | `aspire new aspire-empty` (C#) or `aspire new aspire-ts-empty` (TS) | No resources pre-wired |
67| User wants Python services | `aspire new aspire-py-starter` (TypeScript AppHost drives Python) | **Not** `dotnet new` — that template was removed in 13.3 |
68
69See [references/templates.md](references/templates.md) for the complete template list and
70options.
71
72## Workflow A — `aspire new <template>` (new project)
73
74For brand-new projects in an empty or non-existent directory:
75
761. Confirm prerequisites with `aspire doctor` if the CLI install is uncertain.
772. Pick a template from [references/templates.md](references/templates.md).
783. Run the template, append `--non-interactive` for agent flows:
79 ```bash
80 aspire new aspire-starter --name MyApp --output ./MyApp --non-interactive
81 ```
824. The new directory is fully wired by the template — **no aspireify handoff needed**.
835. Route to [`aspire-orchestration`](https://github.com/microsoft/aspire-skills/blob/main/skills/aspire-orchestration/SKILL.md) for first run
84 (`aspire start`).
85
86## Workflow B — `aspire init` (existing repo)
87
88For repositories that already contain services (Express API, .NET API, Python service, etc.)
89and need an AppHost added alongside them:
90
911. Verify the [Detection](#detection) table — confirm **no** AppHost is present.
922. Run `aspire init`, choosing language explicitly for non-interactive flows:
93 ```bash
94 aspire init --language csharp --non-interactive
95 # or
96 aspire init --language typescript --non-interactive
97 ```
983. `aspire init` drops:
99 - The AppHost skeleton (`apphost.cs` with `#:sdk` directives, **or** `apphost.mts` with the
100 generated `.aspire/modules/` folder)
101 - AppHost configuration describing language + AppHost path
102 - The **`aspireify`** agent skill into the project's skill directory (same one
103 `aspire agent init` uses)
1044. **Hand off to `aspireify`** — `aspire init` does **not** wire resources, projects, or
105 integrations on its own.
1065. After `aspireify` finishes wiring, validate via `aspire start`
107 ([`aspire-orchestration`](https://github.com/microsoft/aspire-skills/blob/main/skills/aspire-orchestration/SKILL.md)).
108
109In 13.5, a TypeScript init inside a repo that already has a root `package.json` creates a
110nested `aspire-apphost/` package and points the root `aspire.config.json` at
111`aspire-apphost/apphost.mts`. A solution-backed C# repo can receive a project-based AppHost;
112new C# AppHosts enable `AspireUseCliBundle=true` by default. Preserve these generated choices.
113
114See [references/init-workflow.md](references/init-workflow.md) for the full sequence
115including what `aspire.config.json` contains and what to do if `aspire init` fails partway.
116
117## Handoff Rules
118
119| After `aspire init` / `aspire new` finishes... | Route To |
120|------------------------------------------------|----------|
121| Skeleton dropped, resources need wiring | → `aspireify` skill (in-plugin or project-local) |
122| Skeleton dropped, validate it starts | → `aspire-orchestration` (run `aspire start`) |
123| New project from template, ready to run | → `aspire-orchestration` |
124| User asks to deploy after init | → `aspire-deployment` |
125| User asks for logs/traces after init | → `aspire-monitoring` |
126| Existing AppHost detected — do NOT run init | → `aspireify` (re-wire) or `aspire-orchestration` (lifecycle) |
127
128## Project-Local Skill Override
129
130If `.agents/skills/aspire-init/SKILL.md` exists project-locally (legacy install from an
131older `aspire init` run), **warn the user and defer to it**. The legacy project-local skill
132may carry repo-specific guidance that should not be overridden by this in-plugin skill.
133
134The project-local `aspireify` skill (installed by `aspire init`) takes precedence
135over this plugin's in-plugin `aspireify` for the same reason — defer to the project-local
136copy and warn.
137
138## Error Handling
139
140| Symptom | Cause | Action |
141|---------|-------|--------|
142| `aspire init` reports AppHost already exists | Repo already has an AppHost | Stop. Route to `aspireify` (re-wire) or `aspire-orchestration` (lifecycle) |
143| `aspire init` fails in non-interactive mode without `--language` | Multiple language paths available | Re-run with `--language csharp` or `--language typescript` |
144| `aspire new` rejects `--output` path | Path exists and is non-empty | Use a different `--output` or empty the directory |
145| `aspire` command not found | CLI not installed | `dotnet tool install -g Aspire.Cli` (.NET 10) or `curl -sSL https://aspire.dev/install.sh \| bash` |
146| `aspire doctor` reports missing .NET 10 | SDK missing | Install .NET 10 SDK before retrying |
147| `aspire init` succeeded but no `aspireify` skill installed | Agent skill directory not detected | Run `aspire agent init` to install `aspireify`, then continue wiring |
148| Skeleton dropped but resources not wired | Expected — `aspire init` does not wire | Hand off to `aspireify` |
149| 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 |
150
151## References
152
153- [templates.md](references/templates.md) — `aspire new` templates and options
154- [init-workflow.md](references/init-workflow.md) — `aspire init` flow, `aspire.config.json`
155 layout, and `aspireify` handoff
156- [aspire-13-5-breaking-changes.md](https://github.com/microsoft/aspire-skills/blob/main/skills/aspire/references/aspire-13-5-breaking-changes.md) —
157 13.5.3 versions, migrations, and CLI-bundle behavior