[docs] Update aspire agent init docs for bundle-derived skill catalog (13.4)

[aspire-repo-bot]

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

Targeting release/13.4 based on the source PR milestone 13.4.

Why this PR is needed

In Aspire 13.4, aspire agent init was fixed to load the available skill catalog from the Aspire skills bundle manifest instead of a hardcoded list. The previous docs described only the CLI-defined skills (aspire, aspireify, playwright-cli, dotnet-inspect) but the catalog now also includes bundle-provided skills such as aspire-init, aspire-monitoring, and aspire-orchestration.

Additionally, a new feature flag aspireSkillsRemoteFetchEnabled (default: false) was introduced to control remote GitHub download of the skills bundle.

Documentation changes

• Updated the Description step 2 to explain that the skill catalog is now loaded from the bundle manifest, lists example bundle skills, and clarifies that one-time setup skills (like aspireify) are not pre-selected by default in standalone runs.
• Updated the --skills option description to reflect that bundle skills are dynamic and CLI-defined skills are static, and added a note about the aspireSkillsRemoteFetchEnabled feature flag.
• Added an example showing how to install specific bundle skills by name.

Files changed

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

Generated by PR Documentation Check for issue #17673 · ● 11.6M · ◷

[Copilot]

Pull request overview

Updates the aspire agent init CLI reference documentation to reflect the 13.4 behavior where the available skill catalog is derived from the Aspire skills bundle manifest (and includes bundle-provided skills), and adds guidance for enabling remote bundle fetching.

Changes:

• Updated the command description to explain manifest-derived skill catalogs and updated default selection behavior.
• Refreshed --skills option documentation and added a note about the new remote-fetch feature flag.
• Added an example for installing specific bundle skills by name.

---

💡 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 @ e258349fd49dd0fdf08f92468d79f0cfaaf13012.
Phase B exercised live aspire.dev/reference/cli/commands/aspire-agent-init/ plus the related aspire init page; live pages reflect pre-PR docs so the PR's MDX was evaluated as a blind reader.

Phase A — claim verdicts (10 total)

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

This PR is a careful, scoped rewrite of the same surface PR #1125 changes. By using such as ... phrasing instead of enumerating the bundle, it avoids the bundle-enumeration contradiction that PR #1125 introduced. Bundle names cited (aspire-init, aspire-monitoring, aspire-orchestration) all exist in release/13.4's embedded aspire-skills-v0.0.1.tgz. The aspireSkillsRemoteFetchEnabled flag name and 13.4 default (false) match src/Aspire.Cli/KnownFeatures.cs:32,86-89 exactly — the source description even literally calls it "the 13.4 default". The recipe for --skills aspire-monitoring,aspire-orchestration is valid.

The only Phase A nuance is the aspireify defaulting explanation in step 2 — accurate for the standalone command documented here but not a universal rule. See inline comment on line 27.

Per-claim catalog — click to expand

id	claim	verdict	evidence
c1	"the available skill catalog is loaded from the Aspire skills bundle manifest" (L27)	✅ verified	AspireSkillsBundle.cs:16 ManifestFileName = "skill-manifest.json"; GetSkillDefinitions() parses the bundle from this manifest at runtime.
c2	"all bundle-provided skills (such as aspire-init, aspire-monitoring, and aspire-orchestration)" (L27)	✅ verified	Extracted aspire-skills-v0.0.1.tgz contains: aspire, aspire-deployment, aspire-init, aspire-monitoring, aspire-orchestration, aspireify. All three names cited exist. such as phrasing is illustrative, not exhaustive — no contradiction.
c3	"CLI-defined skills (playwright-cli, dotnet-inspect)" (L27)	✅ verified	SkillDefinition.cs:178 CliDefined = [PlaywrightCli, DotnetInspect].
c4	"All catalog skills are pre-selected by default, except one-time workspace-wiring skills (such as aspireify) that are omitted from the defaults when running against an existing project" (L27)	⚠️ verified-with-nuance	AgentInitCommand.cs:141-143 comment: "Standalone aspire agent init is typically run against an existing project, so don't pre-select the one-time aspireify wiring skill even though every other bundle skill is default-on." — matches the doc's wording for the standalone case. But the rule does NOT generalize: InitCommand.cs:171-173 deliberately calls PromptAndChainAsync without the predicate (comment: "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)."). See inline comment on L27.
c5	"Bundle skills are loaded dynamically from the Aspire skills bundle manifest and include skills such as aspire-init, aspire-monitoring, and aspire-orchestration" (L46)	✅ verified	AgentInitCommand.cs:482 ResolveAvailableSkillsAsync loads dynamically; names cited all exist in the bundle.
c6	"CLI-provided skills include playwright-cli and dotnet-inspect" (L46)	✅ verified	Same as c3.
c7	"The full list of available bundle skills depends on the Aspire skills bundle cached or embedded in the CLI" (L49)	✅ verified	AspireSkillsInstaller.cs:54-122 InstallCoreAsync runs cache-first then GitHub (if feature on) then embedded snapshot.
c8	"To enable remote fetch of the latest bundle from GitHub, set the aspireSkillsRemoteFetchEnabled feature flag to true" (L49)	✅ verified	KnownFeatures.cs:32 AspireSkillsRemoteFetchEnabled => "aspireSkillsRemoteFetchEnabled"; AspireSkillsInstaller.cs:82-84 gates InstallFromGitHubAsync on this flag. Feature-key name matches exactly.
c9	"(disabled by default in 13.4)" (L49)	✅ verified	KnownFeatures.cs:86-89 on release/13.4 @ e258349fd: DefaultValue: false. Description text in source literally calls it "the 13.4 default".
c10	aspire agent init --skills aspire-monitoring,aspire-orchestration example (L81)	✅ verified	Both skill names exist in the bundle; AgentInitCommand.cs:84-90 registers --skills option; ResolveAvailableSkillsAsync resolves these names.

---

Phase B — doc-tester report

Scope: /reference/cli/commands/aspire-agent-init/ (the PR's only changed file); cross-checked /reference/cli/commands/aspire-init/ for cross-page consistency.

Page rendering check: existing page uses H2-only sections (Name, Synopsis, Description, Options, Examples, See also). PR additions integrate cleanly: new MDX is a single bulleted Examples item plus a :::note admonition inside the --skills option list. No new top-level structure is added. ✅

Critical issues

None.

Warnings

1. Step 2's "existing project" defaulting rule reads as universal (line 27). The aspire init page advertises that aspire init will install aspireify ("aspire init has an option to install the aspireify skill"). A reader who hops between the two pages will see (a) aspire agent init says aspireify is omitted "when running against an existing project" and (b) aspire init (which by definition runs against an existing repo) offers aspireify by default. Both are correct; the explanation just makes it sound like a global rule when it's only the standalone-command rule. Suggest scoping the sentence to this command (e.g., "In this standalone command, ..." or simply "By default in this command, aspireify is not pre-selected; install it from the aspire init flow instead.").

Knowledge gaps a new user will hit

1. "Aspire skills bundle manifest" undefined and unlinked. First-time readers won't know what the bundle is, where it lives, or why it exists. A one-line gloss ("a versioned collection of skill definitions shipped with the CLI and updatable via GitHub") and a link to a concept page (if one exists) would close the loop.
2. "one-time workspace-wiring skills" — what makes a skill "one-time"? Term is introduced inline without definition. Reader can't tell if there's a list, a marker on each skill, or a category they'll see elsewhere.
3. No way to enumerate the full bundle skill set from this page. Every mention uses "such as". A reader trying to pick skill names for --skills has no canonical list and no pointer to one. A bullet list or a "see the skills overview" link would address this.
4. "cached or embedded in the CLI" — no path to inspect either. Where does the cache live? How is "embedded" different from "cached"? Even just "the CLI ships with an embedded snapshot at install time; the cache is populated on first run when remote fetch is enabled" would orient the reader.
5. aspireSkillsRemoteFetchEnabled has no setting instructions. "Set it in your Aspire CLI configuration" doesn't tell users where the configuration file is, what the JSON schema looks like, or whether there's a CLI command (e.g., aspire config set features.aspireSkillsRemoteFetchEnabled true). A one-line example would make this actionable.

Passed checks

• MDX renders cleanly; admonition (:::note) and code fences are well-formed.
• All factual code identifiers in the PR (aspire-init, aspire-monitoring, aspire-orchestration, aspireify, playwright-cli, dotnet-inspect, aspireSkillsRemoteFetchEnabled) match the CLI.
• New example aspire agent init --skills aspire-monitoring,aspire-orchestration is valid as written.
• :::note text reads naturally for a 13.4 reader.
• Cross-page consistency is preserved (no rename of existing terminology elsewhere).

Recommendations

• Scope the aspireify defaulting sentence in step 2 to this command, or add one clause acknowledging that aspire init defaults differ.
• Add a one-sentence definition of "Aspire skills bundle" and link to a concept/overview page (if one exists).
• Make the feature-flag note actionable with a concrete config example for aspireSkillsRemoteFetchEnabled.

---

Verdict

COMMENT — no Phase A contradictions, no Phase B critical issues. The PR is a substantive improvement over the prior surface state and avoids the enumeration bug from PR #1125. The single substantive issue is the misleading "existing project" generalization in step 2 (line 27), plus several knowledge gaps that would benefit a new reader.

_{Generated by the hourly docs-from-code PR review workflow. Phase A SHA: e258349fd. Reviewer SHA: 6c15214f24.}

[IEvangelist]

Phase A nuance + Phase B warning (line 27): the sentence "All catalog skills are pre-selected by default, except one-time workspace-wiring skills (such as aspireify) that are omitted from the defaults when running against an existing project." reads as a universal rule but only applies to the standalone aspire agent init command documented here.

In microsoft/aspire release/13.4 @ e258349fd:

• AgentInitCommand.cs:141-143 — standalone agent init excludes aspireify by default (matches this doc).
• InitCommand.cs:171-173 — aspire init (which also runs against an existing repo) deliberately calls PromptAndChainAsync without the exclusion predicate, so aspireify IS pre-selected there. The source comment: "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)."

The aspire init docs page advertises this behavior too — it has a dedicated "The aspireify skill" section. A reader hopping between pages will see two different defaulting behaviors for the same "existing project" scenario.

Suggested wording: "In this standalone command, one-time workspace-wiring skills (such as aspireify) are not pre-selected. Use aspire init to install the AppHost and pre-select aspireify together as part of that flow."