[docs] Update aspire agent init docs to reflect bundle-manifest-driven skills catalog

[aspire-repo-bot]

Documents changes from microsoft/aspire#17553 by @IEvangelist.

Targeting release/13.4 — the latest release branch on microsoft/aspire.dev — because release/13.5 (from the source PR milestone 13.5) does not exist there.

Why this PR is needed

Prior to microsoft/aspire#17553, the aspire agent init docs listed only three bundle skills (aspire, aspireify, and implicitly the CLI-local ones). The microsoft/aspire-skills bundle actually ships six skills, so aspire-init, aspire-monitoring, and aspire-orchestration were invisible to users reading the docs and to the --skills option description.

The source PR makes the bundle manifest (skill-manifest.json) the source of truth for bundle-backed skill names, descriptions, and install defaults, so the docs need to reflect the full catalog and explain how bundle resolution works.

What changed

• Updated the Description section to explain that the skills catalog is loaded from the Aspire skills bundle manifest automatically.
• Added a Skills catalog subsection listing the current bundle-provided skills (aspire, aspireify, aspire-init, aspire-monitoring, aspire-orchestration) and CLI-defined skills (playwright-cli, dotnet-inspect), and notes the aspireify default-selection difference between aspire init and aspire new.
• Added a Bundle resolution and remote fetch subsection documenting the new features:aspireSkillsRemoteFetchEnabled feature flag (default off) and the resolution order (cache → GitHub release → embedded snapshot).
• Updated the --skills option description to include the full set of bundle-provided and CLI-defined skill names.
• Added two new examples: installing specific bundle skills non-interactively, and enabling remote bundle fetching.

Files modified

• src/frontend/src/content/docs/reference/cli/commands/aspire-agent-init.mdx — updated (existing page)

Generated by PR Documentation Check for issue #17553 · ● 10.9M · ◷

[Copilot]

Pull request overview

Updates the aspire agent init command reference page to document the new manifest-driven skills catalog from microsoft/aspire#17553. Adds a Skills catalog subsection, a Bundle resolution and remote fetch subsection (introducing the features:aspireSkillsRemoteFetchEnabled feature flag), updates the --skills option description with the expanded set of skill names, and adds two new usage examples.

Changes:

• Replaces the static three-skill list with a description explaining the catalog is loaded from skill-manifest.json, plus an explicit list of bundle-provided and CLI-defined skills.
• Documents the bundle resolution order (cache → GitHub release → embedded snapshot) and the opt-in features:aspireSkillsRemoteFetchEnabled flag.
• Adds two examples covering non-interactive bundle skill installs and enabling remote bundle fetching.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[IEvangelist]

Automated docs-accuracy review

Phase A verified against microsoft/aspire release/13.4 @ 0cbaf82dab7d2dec5cf2fbda7577e7eaca6e86b1.
Phase B exercised live aspire.dev/reference/cli/commands/aspire-agent-init/ (no PR preview available; assessed PR-branch MDX content as new-user-rendered prose).

Phase A — claim verdicts (12 total)

verdict	count
verified	9
verified-with-nuance	2
contradicted	1
unverifiable	0

The single contradicted claim and its companion nuance both stem from the same omission: the doc enumerates 5 bundle-provided skills, but the embedded bundle (src/Aspire.Cli/Agents/AspireSkills/Embedded/aspire-skills-v0.0.1.tgz) actually ships 6. See the inline comments at lines 34 and 62.

Verified claims (9) and verified-with-nuance (2) — click to expand

id	claim	evidence
c1	The CLI loads available skills from skill-manifest.json	AspireSkillsBundle.cs:16 ManifestFileName="skill-manifest.json"; GetSkillDefinitions() parses the manifest. ✅
c3	CLI itself defines playwright-cli and dotnet-inspect, separate from the bundle	SkillDefinition.cs:178 CliDefined = [PlaywrightCli, DotnetInspect]; AgentInitCommand.cs:505 adds them after bundle resolution. ✅
c4	CLI-defined skill wins when its name collides with a bundle skill	AgentInitCommand.cs:492 bundle.GetSkillDefinitions().Where(s => !IsCliDefinedSkillName(s.Name)); CLI-defined appended at line 505. ✅
c5	aspire init pre-selects aspireify with the bundle defaults	InitCommand.cs:171-178 calls PromptAndChainAsync without the ExcludeOneTimeSetupSkillsFromDefaults predicate, so IsDefault=true skills (which include aspireify) are pre-selected. ⚠️ See nuance comment on line 36.
c6	aspire new does not pre-select aspireify	NewCommand.cs:533 passes ExcludeOneTimeSetupSkillsFromDefaults; AgentInitCommand.cs:160-172 lists aspireify in s_oneTimeSetupSkillNames. ✅
c7	Feature flag features:aspireSkillsRemoteFetchEnabled exists and defaults to false	KnownFeatures.cs:32 defines the key; lines 86-89 set DefaultValue: false. ✅
c8	Default (flag off) skips the GitHub call entirely	AspireSkillsInstaller.cs:82-105 gates InstallFromGitHubAsync behind the feature flag; embedded fallback runs at line 107. ✅
c9	Resolution order matches the doc (cache → [github] → embedded)	AspireSkillsInstaller.cs:54-122 — cache first (TryLoadCachedBundleAsync), then conditionally GitHub, then embedded. ✅
c10	aspire config set features:<feature> <value> is the correct syntax	ConfigCommand.cs:128 registers the set subcommand; Features.cs:13 builds the key as features:{feature} — colon syntax matches. ✅
c11	--skills accepts the named bundle + CLI skills plus all/none	AgentInitCommand.cs:84-90 (option), :482 ResolveAvailableSkillsAsync. ⚠️ Same omission as c2 — aspire-deployment is a valid --skills value but the doc's enumeration on line 62 omits it. See inline comment.
c12	--skill-locations standard and combining with --skills works	SkillLocation.cs:18-24 defines standard; AgentInitCommand.cs:67-76 both options coexist; named skills (aspire, aspire-monitoring, aspire-orchestration) all exist. ✅

---

Phase B — doc-tester report

Scope: the single PR-affected page, /reference/cli/commands/aspire-agent-init/.
Reachability check: all referenced internal targets resolve (HTTP 200): aspire-init/, aspire-new/, aspire-config/, aspire-config-set/, aspire-agent/, aspire-agent-mcp/, configuration/.

Critical issues

1. The page documents the standalone aspire agent init command, but never tells the reader what pre-selection happens when running it standalone. Step 2 (line 27) says "All skills are pre-selected by default," then the new "Skills catalog" section explains pre-selection rules only for the chained aspire init and aspire new paths. A user landing on this page and running aspire agent init directly cannot determine from the docs whether aspireify, playwright-cli, and dotnet-inspect are pre-selected, partially pre-selected, or excluded. This is the central use-case of the page being silently skipped.

Warnings

1. "because the workspace was just created" is misleading (line 36). aspire init adds an AppHost to an existing repo — only the AppHost is new, not the workspace. Readers familiar with aspire init will be confused. Suggested rewrite mirroring the in-source comment at InitCommand.cs:171: "because aspire init adds a new AppHost to an existing repo, aspireify is the natural follow-up wiring skill."
2. "Versioned cache" is referenced but never defined (line 46). The doc tells users about the resolution order but doesn't say where the cache lives on disk, when it expires, or how to clear it — the first questions a user asks when a stale bundle bites them.
3. Chicken-and-egg in cache wording (line 46). "Cached bundles from a previous successful fetch continue to work in either mode" is useful, but a reader who hears "default never fetches" may conclude the cache is always empty. Worth one sentence on how the cache initially populates (i.e., from a prior run with remote-fetch on).

Passed checks

• Page metadata, headings hierarchy, code-block syntax, and Asciinema embed all valid.
• All linked routes resolve.
• The two new examples are well-formed and copy-pasteable.
• The new "Bundle resolution and remote fetch" section gives a useful mental model.

Knowledge gaps a new user will hit

• What does the features: prefix mean in aspire config set features:...? Is it a namespace, a required token, or a convention? No link to aspire config set configuration docs.
• Where is the bundle cache stored on disk and how do I purge it?
• What happens if a remote fetch fails (network down, GitHub rate-limited) — silent fallback or surfaced error?
• The third skills example (--skills aspire,aspire-monitoring,aspire-orchestration) picks three skills with no commentary; readers may wonder why those three and not aspireify / aspire-init.

Recommendations

• After fixing the c2 omission, add one explicit sentence to Step 2 (or to the Skills catalog section) about what standalone aspire agent init pre-selects.
• Define "versioned cache" inline (path + clearing hint) the first time it appears.
• Cross-link the features:aspireSkillsRemoteFetchEnabled example to the aspire config set page.

---

Verdict

REQUEST_CHANGES — one Phase A contradicted claim (missing aspire-deployment in the bundle enumeration, repeated on line 34 and line 62) and one Phase B critical issue (no documented behavior for standalone aspire agent init skill pre-selection).

_{Generated by the hourly docs-from-code PR review workflow. Phase A SHA: 0cbaf82da. Reviewer SHA: 28a6770e.}

[IEvangelist]

Contradicted (Phase A — c2) — verified against microsoft/aspire release/13.4 @ 0cbaf82da.

The enumeration omits aspire-deployment. The embedded bundle (src/Aspire.Cli/Agents/AspireSkills/Embedded/aspire-skills-v0.0.1.tgz) ships six bundle skills — extracting the tarball confirms skills/{aspire,aspire-deployment,aspire-init,aspire-monitoring,aspire-orchestration,aspireify}/SKILL.md, and the manifest agrees.

Please update this sentence to include aspire-deployment:

Bundle-provided skills currently include aspire, aspire-deployment, aspire-init, aspire-monitoring, aspire-orchestration, and aspireify.

(Note: aspire-deployment is a real, useful skill — it covers the deployment workflow — so a doc that promises a complete list while omitting it actively misleads readers.

[IEvangelist]

Verified-with-nuance (Phase A — c11) — same omission as line 34. The --skills option does accept aspire-deployment as a value (resolved dynamically at runtime via AgentInitCommand.ResolveAvailableSkillsAsync), so listing it here keeps the docs self-consistent with the runtime catalog and with the corrected Skills catalog section.

[IEvangelist]

Verified-with-nuance (Phase A — c5) — the behavior claim (aspire init pre-selects aspireify) is correct, confirmed at InitCommand.cs:171-178 (no ExcludeOneTimeSetupSkillsFromDefaults predicate passed). But the justification — because the workspace was just created — is misleading. aspire init adds an AppHost to an existing repo; only the AppHost is new.

The in-source comment at InitCommand.cs:171 reads:

aspire init creates an AppHost in an existing repo, so pre-select every bundle skill (which includes aspireify as the natural follow-up wiring skill).

Consider mirroring that wording so the reader doesn't conclude that aspire init creates the workspace.

[IEvangelist]

Phase B — critical issue (clarity for the page's primary command). This line says All skills are pre-selected by default, and the new Skills catalog section just below carves out exceptions — but only for the chained aspire init and aspire new paths. This page documents the standalone aspire agent init command, and there is no sentence telling the reader what the default pre-selection is when running aspire agent init directly. A user reading this page in isolation cannot resolve the contradiction between All skills are pre-selected and the per-entry-point rules in the next section. Please add one sentence covering the standalone case so the page's primary use case isn't silently skipped.

[IEvangelist]

Phase B — warnings (knowledge gaps a new user will hit).

1. Versioned cache is mentioned twice but never defined: a new user can't tell where it lives on disk, when it expires, or how to clear it — those are the first questions when a stale bundle causes a problem.
2. Cached bundles from a previous successful fetch continue to work in either mode is useful, but the reader who just absorbed By default ... no network call is made won't intuit how the cache populates in the first place. One sentence on how the cache is initially filled (i.e., from a prior run with remote-fetch on) closes the loop.