[docs] docs: document Aspire workflow skills external bundle migration

[aspire-repo-bot]

Summary

This PR updates the Aspire documentation to reflect the migration of workflow skills (aspire, aspireify, aspire-deployment) from being embedded directly in the CLI binary to loading from an external npm bundle (@microsoft/aspire-skills).

Corresponding source PR: microsoft/aspire#17323 — Migrate Aspire skills to external bundle

What changed

Starting with Aspire 13.4, the aspire agent init command loads GitHub Copilot workflow skills from an external npm package (@microsoft/aspire-skills) rather than shipping them as embedded resources in the CLI binary. This means:

• Network access is required the first time the skills are fetched
• Skills are cached locally so subsequent runs work offline:
  • Windows: %LOCALAPPDATA%\Microsoft\Aspire\skills-cache
  • Linux/macOS: ~/.local/share/aspire/skills-cache
• Three skills are now surfaced: aspire, aspireify, and aspire-deployment

Files changed

src/frontend/src/content/docs/reference/cli/commands/aspire-agent-init.mdx

• Added aspireify and aspire-deployment to the documented skill list
• Added a note explaining the npm bundle requirement and local cache paths
• Updated the --skills option description to include the new skills
• Added an example command showing how to install all three workflow skills

src/frontend/src/content/docs/get-started/ai-coding-agents.mdx

• Added aspireify and aspire-deployment to the skill list
• Added a callout explaining the one-time network access requirement and cache location

src/frontend/src/content/docs/whats-new/aspire-13-4.mdx

• Updated CLI bullet point to mention skills bundle migration
• Added a new "Aspire workflow skills from external bundle" subsection under CLI enhancements with full explanation, platform-specific cache paths, an example command, and learn-more links

Triggered signals

Signal	Evidence
cli_command_file_changed	src/Aspire.Cli/Commands/AgentCommand.cs modified — aspireify and aspire-deployment skills added
cli_resource_strings_changed	src/Aspire.Cli/Resources/AgentCommandStrings.resx modified — new skill names and descriptions added
pr_body_has_user_facing_section	PR body contains ## Usage section describing the external bundle behavior
pr_body_has_cli_flag_mention	PR body mentions --skills flag usage

Source PR details

• Source PR: Migrate Aspire skills to external bundle aspire#17323
• Author: @IEvangelist
• Milestone: Aspire 13.4
• Merged: 2026-05-26

Generated by PR Documentation Check for issue #17323 · ● 95.4M · ◷

[Copilot]

Pull request overview

Updates Aspire 13.4 documentation to reflect that GitHub Copilot workflow skills (aspire, aspireify, aspire-deployment) are now fetched from an external npm bundle (@microsoft/aspire-skills) and cached locally when running aspire agent init.

Changes:

• Expanded documented skill list to include aspireify and aspire-deployment.
• Added notes/callouts about one-time network access and local caching behavior.
• Added a “what’s new” subsection describing the external bundle migration and an example install command.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
src/frontend/src/content/docs/whats-new/aspire-13-4.mdx	Adds release note bullet + new subsection explaining external bundle migration and cache paths.
src/frontend/src/content/docs/reference/cli/commands/aspire-agent-init.mdx	Updates command reference to include new skills, adds network/cache note, updates --skills docs and examples.
src/frontend/src/content/docs/get-started/ai-coding-agents.mdx	Updates skill list and adds a note about bundle download + cache location.

---

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

[IEvangelist]

Docs accuracy review

Source of truth: microsoft/aspire@cc4b7eaf (release/13.4, fetched 2026-05-29)
PR head: 3f6d1fa7570b1f97a6e240c5eb0f498b91e92121

Verdict	Count
verified	8
verified-with-nuance	2
unverifiable	0
contradicted	7

Verdict: REQUEST_CHANGES — the PR repeatedly describes the Aspire skills bundle as an @microsoft/aspire-skills npm package verified via npm provenance, but the actual implementation in Aspire.Cli downloads a release asset from the microsoft/aspire-skills GitHub repo and verifies it via GitHub artifact attestation (Sigstore-backed SLSA provenance issued by the publishing GitHub Actions workflow). There is no npm in the picture for these skills.

Worth noting: the npm-flavored description (npm provenance, tarball integrity, SHA-512 SRI) is exactly what the separate PlaywrightCliInstaller does — so the PR appears to have merged the two skill-acquisition flows.

There are also two other contradictions: the Linux/macOS cache path in whats-new/aspire-13-4.mdx is written with a trailing backslash (~/.aspire/cache/aspire-skills\), and the playwright-cli skill is documented as installing without network access when it actually downloads from the npm registry on every install.

Source of truth pointers

• src/Aspire.Cli/Agents/AspireSkills/AspireSkillsInstaller.cs:33 — internal const string GitHubRepository = "microsoft/aspire-skills";
• :104-175 InstallFromGitHubAsync — fetches a release asset via api.github.com/repos/microsoft/aspire-skills/releases/tags/{tag} and verifies with IGitHubArtifactAttestationVerifier.VerifyAsync(...) against ExpectedSourceRepository, ExpectedWorkflowPath, ExpectedBuildType.
• :391-401 asset name pattern is aspire-skills-{version}.{zip|tar.gz|tgz} (not an npm package tarball).
• :542-545 cache root is Path.Combine(executionContext.CacheDirectory.FullName, "aspire-skills") → <aspire-home>/cache/aspire-skills, default home <UserProfile>/.aspire.
• src/Aspire.Cli/Agents/AspireSkills/AspireSkillsBundle.cs:159-188,280-303 — per-file SHA-256 manifest verification + relative-path safety check (no .., no absolute paths). These two specific claims in whats-new are correct.
• src/Aspire.Cli/Agents/Playwright/PlaywrightCliInstaller.cs:46,118-242 — Playwright CLI requires npm on PATH, resolves the package from the npm registry, verifies Sigstore npm provenance, then npm packs and SHA-512-SRI verifies the tarball. This is the flow the docs describe.
• src/Aspire.Cli/Agents/SkillDefinition.cs:19-72,182 — the five skills, of which only aspire/aspireify/aspire-deployment have isDefault: true.

Doc-tester (UX) notes

Reading the PR's three docs end-to-end as a first-time reader, then trying to reconcile claims with what the source actually does:

• The "external @microsoft/aspire-skills npm bundle" claim led me to look for the package on npmjs.com. It does not exist there as a CLI-consumed package — the only thing that exists at that name/scope is the publishing pipeline. A new user clicking through npmjs.com/package/@microsoft/aspire-skills would not find what the docs are pointing at.
• whats-new/aspire-13-4.mdx line 181 correctly links the GitHub repo (https://github.com/microsoft/aspire-skills) and then in the same sentence calls it an @microsoft/aspire-skills npm bundle. From a reader's standpoint these point to two different things; one of them is wrong.
• The trailing backslash on the Linux/macOS path in whats-new (line 186) is reproducible: a user copying it into a shell would get cache/aspire-skills\ (with a literal backslash) which won't resolve.
• "All options are pre-selected by default" in aspire-agent-init.mdx line 28 is a pre-existing claim that this PR enlarges (now applies to five items). In the implementation, only three of those five are actually pre-selected. The PR doesn't introduce the wrong assertion, but it now applies to two more skills.
• The example command aspire agent init --skill-locations standard --skills aspire,aspireify,aspire-deployment is correct and uses valid identifiers from CommonAgentApplicators/SkillDefinition.

Verified claims

ID	Claim	Evidence
p2	aspire-deployment description in selection list.	AgentCommandStrings.resx:129-131 — "Aspire deployment target selection, preflight, publish, and deploy workflows".
p4/p8/p15	Cache paths: ~/.aspire/cache/aspire-skills/ and %USERPROFILE%\.aspire\cache\aspire-skills\.	AspireSkillsInstaller.cs:542-545 + Program.cs:616-621 + CliPathHelper.cs:51-61.
p9	Subsequent installs reuse the cache without network.	AspireSkillsInstaller.cs:66-71 — TryLoadCachedBundleAsync returns before any HTTP call.
p11	--skills accepts aspire, aspireify, aspire-deployment, playwright-cli, dotnet-inspect, all, none.	CommonAgentApplicators.cs:16-31 + SkillDefinition.cs:42.
p12	Example aspire agent init --skill-locations standard --skills aspire,aspireify,aspire-deployment.	All names resolve to real SkillDefinition entries.
p17	microsoft/aspire-skills GitHub repo link.	AspireSkillsInstaller.cs:33 declares GitHubRepository = "microsoft/aspire-skills".

Verified-with-nuance

ID	Claim	Nuance
p1	aspireify — teaches your AI agent to bootstrap Aspire into existing projects	Description in AgentCommandStrings.resx:138-140 is "One-time setup: wire up AppHost with discovered projects". Paraphrase is fair; loses the "one-time" framing.
p5	Step 2 lists five skills; "All options are pre-selected by default."	Only aspire/aspireify/aspire-deployment are isDefault: true (SkillDefinition.cs:25,36,72). playwright-cli (:47) and dotnet-inspect (:59) are isDefault: false. The "pre-selected" claim is pre-existing and not introduced by this PR, but the PR now extends the list it applies to.

Contradicted

ID	Claim	Source-of-truth contradiction
p3	@microsoft/aspire-skills npm bundle (in ai-coding-agents.mdx).	Bundle is a GitHub release asset from microsoft/aspire-skills (no npm).
p6	@microsoft/aspire-skills npm bundle (in aspire-agent-init.mdx).	Same as p3.
p7	First install checks "npm provenance and tarball integrity".	Verification is GitHub artifact attestation via IGitHubArtifactAttestationVerifier.VerifyAsync(...). The npm-provenance / SHA-512 SRI flow belongs to the separate PlaywrightCliInstaller.
p10	"playwright-cli and dotnet-inspect skills ... are installed without network access."	True for dotnet-inspect (SkillSourceKind.Static). False for playwright-cli — it requires npm on PATH, resolves from the npm registry, and downloads + verifies on every install.
p13	@microsoft/aspire-skills npm bundle (in whats-new/aspire-13-4.mdx).	Same as p3.
p14	"checking npm provenance and tarball integrity, validating manifest file hashes, and rejecting unsafe paths".	"npm provenance and tarball integrity" → wrong (see p7). "Manifest file hashes" ✓ (AspireSkillsBundle.cs:159-188). "Rejecting unsafe paths" ✓ (AspireSkillsBundle.cs:280-303).
p16	Linux/macOS path shown as ~/.aspire/cache/aspire-skills\ (trailing backslash).	POSIX paths use /; the sibling doc renders it correctly.

[IEvangelist]

Addressed the review-level docs accuracy feedback in 28bb230.

Verified against microsoft/aspire@565af53 on release/13.4 and edited per the doc-writer skill.