Aspire Init

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 | | 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.

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 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).

Decision: aspire new vs aspire init

| Situation | Command | Why | |-----------|---------|-----| | Empty directory or brand-new project | aspire new | 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](references/templates.md) for the complete template list and options.

Workflow A — aspire new (new project)

For brand-new projects in an empty or non-existent directory:

1. Confirm prerequisites with aspire doctor if the CLI install is uncertain.
2. Pick a template from [references/templates.md](references/templates.md).
3. Run the template, append --non-interactive for agent flows:

``bash aspire new aspire-starter --name MyApp --output ./MyApp --non-interactive ``

1. The new directory is fully wired by the template — no aspireify handoff needed.
2. 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:

1. Verify the [Detection](#detection) table — confirm no AppHost is present.
2. Run aspire init, choosing language explicitly for non-interactive flows:

``bash aspire init --language csharp --non-interactive # or aspire init --language typescript --non-interactive ``

1. aspire init drops:

• The AppHost skeleton (apphost.cs with #:sdk directives, or apphost.ts 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)

1. Hand off to aspireify — aspire init does not wire resources, projects, or

integrations on its own.

1. After aspireify finishes wiring, validate via aspire start

(aspire-orchestration).

See [references/init-workflow.md](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 |

References

• [templates.md](references/templates.md) — aspire new templates and options
• [init-workflow.md](references/init-workflow.md) — aspire init flow, aspire.config.json

layout, and aspireify handoff

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: microsoft
• Source: microsoft/aspire-skills
• License: MIT
• Homepage: https://aspire.dev/get-started/aspire-skills/

Install and usage instructions live in the source repository linked above.