Document --skills and --skill-locations flags for init and new commands#1348
Merged
Conversation
Add documentation for the --skills and --skill-locations options on aspire init and aspire new commands. These flags were added in microsoft/aspire#18191 and microsoft/aspire#18192 to support non-interactive mode for controlling which agent skills are installed during initialization.
JamesNK
requested review from
IEvangelist,
aaronpowell,
davidfowl,
eerhardt,
maddymontaquila and
mitchdenny
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the Aspire docs site for the 13.5 release wave, including new/updated CLI reference pages (notably --skills / --skill-locations for aspire init and aspire new), new documentation pages (terminal commands, dashboard troubleshooting, Kubernetes persistent volumes, 13.5 release notes), and introduces a %ASPIRE_VERSION% placeholder system to avoid hard-coded version drift across docs.
Changes:
- Add
%ASPIRE_VERSION%/%ASPIRE_VERSION_MAJOR_MINOR%placeholders with a remark plugin + post-build replacement for Markdown copies, plus unit tests. - Add multiple new docs pages and expand CLI reference (terminal commands, timestamp search qualifier,
aspire init/aspire newskills flags, Nix install guidance, troubleshooting). - Roll forward site banners and “What’s new” navigation to Aspire 13.5 and refresh several docs pages for 13.5 behavior.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| src/frontend/tests/unit/aspire-version-placeholders.vitest.test.ts | Adds unit coverage for placeholder replacement in remark + post-build directory pass. |
| src/frontend/src/content/docs/zh-cn/index.mdx | Updates localized banner to Aspire 13.5. |
| src/frontend/src/content/docs/whats-new/aspire-13-5.mdx | Adds new 13.5 release notes page. |
| src/frontend/src/content/docs/whats-new/aspire-13-4.mdx | Refines persistent lifetime wording and proxy/proxyless defaults. |
| src/frontend/src/content/docs/uk/index.mdx | Updates localized banner to Aspire 13.5. |
| src/frontend/src/content/docs/tr/index.mdx | Updates localized banner to Aspire 13.5. |
| src/frontend/src/content/docs/ru/index.mdx | Updates localized banner to Aspire 13.5. |
| src/frontend/src/content/docs/reference/cli/search-filter.mdx | Documents timestamp qualifier behavior and operators. |
| src/frontend/src/content/docs/reference/cli/microsoft-collected-cli-telemetry.mdx | Documents AI agent skill usage telemetry collection details. |
| src/frontend/src/content/docs/reference/cli/commands/aspire-update.mdx | Documents Nix behavior for aspire update --self. |
| src/frontend/src/content/docs/reference/cli/commands/aspire-terminal.mdx | Adds command reference for aspire terminal. |
| src/frontend/src/content/docs/reference/cli/commands/aspire-terminal-ps.mdx | Adds command reference for aspire terminal ps. |
| src/frontend/src/content/docs/reference/cli/commands/aspire-terminal-attach.mdx | Adds command reference for aspire terminal attach. |
| src/frontend/src/content/docs/reference/cli/commands/aspire-otel-traces.mdx | Adds timestamp comparison qualifier documentation for traces. |
| src/frontend/src/content/docs/reference/cli/commands/aspire-otel-spans.mdx | Adds timestamp comparison qualifier documentation for spans. |
| src/frontend/src/content/docs/reference/cli/commands/aspire-otel-logs.mdx | Adds timestamp comparison qualifier documentation for logs. |
| src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx | Documents --skills / --skill-locations and adds non-interactive examples. |
| src/frontend/src/content/docs/reference/cli/commands/aspire-init.mdx | Documents --skills / --skill-locations and adds non-interactive examples. |
| src/frontend/src/content/docs/reference/cli/commands/aspire-doctor.mdx | Updates aspire doctor docs and replaces hard-coded versions with placeholders. |
| src/frontend/src/content/docs/pt-br/index.mdx | Updates localized banner to Aspire 13.5. |
| src/frontend/src/content/docs/ko/index.mdx | Updates localized banner to Aspire 13.5. |
| src/frontend/src/content/docs/ja/index.mdx | Updates localized banner to Aspire 13.5. |
| src/frontend/src/content/docs/ja/docs.mdx | Updates Japanese docs landing banner to Aspire 13.5. |
| src/frontend/src/content/docs/it/index.mdx | Updates localized banner to Aspire 13.5. |
| src/frontend/src/content/docs/integrations/dotnet/csharp-file-based-apps.mdx | Replaces hard-coded versions with placeholders in file-based app directives. |
| src/frontend/src/content/docs/integrations/databases/efcore/seed-database.mdx | Replaces hard-coded Aspire package versions with placeholders. |
| src/frontend/src/content/docs/integrations/compute/kubernetes.mdx | Adds section linking to persistent volume docs + examples. |
| src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx | Updates Foundry Local lifecycle description to CLI-based behavior. |
| src/frontend/src/content/docs/integrations/ai/github-models/github-models-host.mdx | Adds deprecation caution notice for GitHub Models integration. |
| src/frontend/src/content/docs/integrations/ai/github-models/github-models-get-started.mdx | Adds deprecation caution notice for GitHub Models integration. |
| src/frontend/src/content/docs/integrations/ai/github-models/github-models-connect.mdx | Adds deprecation caution notice for GitHub Models integration. |
| src/frontend/src/content/docs/index.mdx | Updates root banner to Aspire 13.5. |
| src/frontend/src/content/docs/id/index.mdx | Updates localized banner to Aspire 13.5. |
| src/frontend/src/content/docs/hi/index.mdx | Updates localized banner to Aspire 13.5. |
| src/frontend/src/content/docs/get-started/install-cli.mdx | Adds Nix install tab and replaces hard-coded version output with placeholder. |
| src/frontend/src/content/docs/get-started/aspire-sdk.mdx | Replaces hard-coded SDK versions with placeholders. |
| src/frontend/src/content/docs/get-started/add-aspire-existing-app.mdx | Replaces hard-coded file-based app package versions with placeholders. |
| src/frontend/src/content/docs/fundamentals/persist-data-volumes.mdx | Adds link to Kubernetes persistent volumes page. |
| src/frontend/src/content/docs/fundamentals/networking-overview.mdx | Updates proxyless/persistent endpoint defaults + adds dynamic port allocation section. |
| src/frontend/src/content/docs/fundamentals/custom-resource-commands.mdx | Clarifies dashboard icon fallback behavior. |
| src/frontend/src/content/docs/fr/index.mdx | Updates localized banner to Aspire 13.5. |
| src/frontend/src/content/docs/es/index.mdx | Updates localized banner to Aspire 13.5. |
| src/frontend/src/content/docs/docs.mdx | Updates docs landing banner to Aspire 13.5. |
| src/frontend/src/content/docs/deployment/kubernetes/persistent-volumes.mdx | Adds new Kubernetes persistent volumes guide. |
| src/frontend/src/content/docs/deployment/kubernetes/clusters.mdx | Adds link to persistent volumes guide. |
| src/frontend/src/content/docs/deployment/kubernetes.mdx | Adds link card + link to persistent volumes guide. |
| src/frontend/src/content/docs/de/index.mdx | Updates localized banner to Aspire 13.5. |
| src/frontend/src/content/docs/dashboard/troubleshooting.mdx | Adds new dashboard troubleshooting page. |
| src/frontend/src/content/docs/da/index.mdx | Updates localized banner to Aspire 13.5. |
| src/frontend/src/content/docs/community/index.mdx | Updates community landing banner to Aspire 13.5. |
| src/frontend/src/content/docs/app-host/with-terminal.mdx | Adds new WithTerminal documentation page. |
| src/frontend/src/content/docs/app-host/resource-lifetimes.mdx | Updates persistent endpoint behavior text + links to proxyless allocation section. |
| src/frontend/src/content/docs/app-host/configuration.mdx | Clarifies launch profile locations for project-based vs file-based C# AppHosts. |
| src/frontend/config/sidebar/reference.topics.ts | Adds aspire terminal command group to CLI reference sidebar. |
| src/frontend/config/sidebar/docs.topics.ts | Adds Aspire 13.5 “What’s new” entry and WithTerminal docs nav entry. |
| src/frontend/config/sidebar/deployment.topics.ts | Adds persistent volumes page to deployment sidebar. |
| src/frontend/config/sidebar/dashboard.topics.ts | Adds dashboard troubleshooting nav entry (with translations). |
| src/frontend/config/remark-aspire-version-placeholders.mjs | Adds remark plugin to replace Aspire version placeholders in markdown/MDX AST. |
| src/frontend/config/aspire-versions.mjs | Centralizes current Aspire version constants + placeholder map. |
| src/frontend/config/aspire-version-placeholders-integration.mjs | Adds Astro build-done integration to post-process Markdown copies under dist. |
| src/frontend/astro.config.mjs | Wires placeholder remark plugin and build-done integration into Astro build. |
| .github/agents/release-verifier.agent.md | Updates release verifier agent guidance to validate placeholder constants. |
| .agents/skills/doc-pr-reviewer/SKILL.md | Updates doc PR reviewer skill guidance re: version placeholders. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Contributor
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
IEvangelist
approved these changes
Jul 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the
--skillsand--skill-locationsflags that were added toaspire init,aspire new, andaspire agent initcommands in the Aspire CLI. These flags support non-interactive mode, allowing use in scripts and CI environments without interactive prompts.Changes
aspire initcommand reference — added--skill-locationsand--skillsoptions with descriptions and cross-references toaspire agent initfor the full list of values. Added non-interactive usage examples.aspire newcommand reference — added--skill-locationsand--skillsoptions with descriptions and cross-references toaspire agent initfor the full list of values. Added non-interactive usage examples.aspire agent initcommand reference — already had both options documented; no changes needed.Related PRs
--skillsflag toaspire init--skill-locationsand--skillsthroughAgentInitCommand,InitCommand, andNewCommandCommunity contribution by @nanookclaw.