From 9378b074bf0fb3066075205455f490f451e50bf8 Mon Sep 17 00:00:00 2001 From: David Fowler Date: Fri, 29 May 2026 23:44:02 -0700 Subject: [PATCH 1/3] Document Aspire skills Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- src/frontend/config/sidebar/docs.topics.ts | 4 + .../docs/dashboard/ai-coding-agents.mdx | 2 +- .../docs/get-started/ai-coding-agents.mdx | 67 +++------ .../docs/get-started/aspire-mcp-server.mdx | 5 + .../docs/get-started/aspire-skills.mdx | 129 ++++++++++++++++++ .../content/docs/get-started/first-app.mdx | 2 +- .../cli/commands/aspire-agent-init.mdx | 6 +- .../reference/cli/commands/aspire-agent.mdx | 4 +- 8 files changed, 161 insertions(+), 58 deletions(-) create mode 100644 src/frontend/src/content/docs/get-started/aspire-skills.mdx diff --git a/src/frontend/config/sidebar/docs.topics.ts b/src/frontend/config/sidebar/docs.topics.ts index 7c644758b..252aad6fe 100644 --- a/src/frontend/config/sidebar/docs.topics.ts +++ b/src/frontend/config/sidebar/docs.topics.ts @@ -432,6 +432,10 @@ export const docsTopics: StarlightSidebarTopicsUserConfig = { label: 'Overview', slug: 'get-started/ai-coding-agents', }, + { + label: 'Aspire skills', + slug: 'get-started/aspire-skills', + }, { label: 'Aspire MCP server', slug: 'get-started/aspire-mcp-server', diff --git a/src/frontend/src/content/docs/dashboard/ai-coding-agents.mdx b/src/frontend/src/content/docs/dashboard/ai-coding-agents.mdx index 57862efee..8124d25a1 100644 --- a/src/frontend/src/content/docs/dashboard/ai-coding-agents.mdx +++ b/src/frontend/src/content/docs/dashboard/ai-coding-agents.mdx @@ -19,7 +19,7 @@ Both channels draw from the same underlying dashboard data. Whether an agent rea ### Typical agent workflow -The following workflow is an example — [Aspire skill files](/get-started/ai-coding-agents/#aspire-skill-file) teach agents the best patterns to run and debug Aspire apps automatically. A typical agent-driven debugging session looks like this: +The following workflow is an example — [Aspire skills](/get-started/aspire-skills/) teach agents the best patterns to run and debug Aspire apps automatically. A typical agent-driven debugging session looks like this: diff --git a/src/frontend/src/content/docs/get-started/ai-coding-agents.mdx b/src/frontend/src/content/docs/get-started/ai-coding-agents.mdx index 357d421bd..bb79b087a 100644 --- a/src/frontend/src/content/docs/get-started/ai-coding-agents.mdx +++ b/src/frontend/src/content/docs/get-started/ai-coding-agents.mdx @@ -4,12 +4,9 @@ seoTitle: Use AI coding agents with Aspire AppHost projects today description: Set up AI coding agents to work with Aspire — install skills, configure the Aspire MCP server, and enable browser automation for distributed-app development workflows. --- -import { LinkCard, CardGrid } from '@astrojs/starlight/components'; -import { Aside, Steps, Tabs, TabItem, FileTree } from '@astrojs/starlight/components'; -import { Image } from 'astro:assets'; +import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components'; import AsciinemaPlayer from '@components/AsciinemaPlayer.astro'; import LoopingVideo from '@components/LoopingVideo.astro'; -import LearnMore from '@components/LearnMore.astro'; Aspire provides a first-class setup experience for AI coding agents. Run `aspire agent init` in your project and your AI assistant — whether it's GitHub Copilot, Claude Code, or another MCP-compatible tool — can immediately understand, build, debug, and monitor your distributed applications. @@ -19,7 +16,7 @@ Aspire gives coding agents the same visibility into your running application tha The Aspire CLI is built for agent-driven workflows — commands support non-interactive execution to avoid blocking on prompts, and many commands support `--format Json` for structured plain text output. Key commands include `aspire start` (background execution), `aspire start --isolated` (parallel worktrees), `aspire wait` (block until healthy), `aspire describe`, `aspire logs`, and `aspire docs search`. -The Aspire skill file (installed by `aspire agent init`) teaches agents all of these patterns automatically. +Aspire skills teach agents these patterns automatically. ## Get started @@ -44,11 +41,10 @@ When you create a new Aspire project with `aspire new` or `aspire init`, you're | **GitHub Skills** | `.github/skills/` | VS Code / GitHub Copilot specific | | **OpenCode** | `.opencode/skill/` | OpenCode specific | -1. Select the **skills and tools** to install into those locations. All options are pre-selected by default: +1. Select the **skills and tools** to install into those locations. Aspire workflow skills are selected by default; optional companion tools can be selected explicitly: - - **Aspire skill** — teaches your AI agent how to use Aspire CLI commands + - **Aspire skills** — teach your AI agent how to operate Aspire apps and complete AppHost wiring for existing codebases - **Playwright CLI** — enables browser automation for testing web resources - - **dotnet-inspect skill** — teaches your AI agent to query .NET API surfaces @@ -63,52 +59,20 @@ When you create a new Aspire project with `aspire new` or `aspire init`, you're The `aspire agent init` command detects your AI development environment and creates the appropriate configuration files: -### Aspire skill file +### Aspire skills -The skill file teaches your AI coding agent how to work with Aspire. It includes a CLI command reference, key workflows (starting apps, debugging issues, adding integrations), and important rules to follow. The file is installed into each selected skill location: - - - -- .agents/skills/aspire/ - - SKILL.md Standard (VS Code, GitHub Copilot, OpenCode) -- .github/skills/aspire/ - - SKILL.md GitHub Copilot (legacy location) -- .claude/skills/aspire/ - - SKILL.md Claude Code -- .opencode/skill/aspire/ - - SKILL.md OpenCode - - - -The skill file guides your agent on how to: +The [Aspire skills](/get-started/aspire-skills/) teach your AI coding agent how to work with Aspire. Aspire ships a set of workflow skills for app operations, initialization, monitoring, deployment, and AppHost wiring. The skills guide your agent on how to: - Start and manage your Aspire application (`aspire start`, `aspire stop`, `aspire describe`) - Debug issues using structured logs and distributed traces - Add integrations with `aspire add` and search documentation with `aspire docs` +- Initialize new and existing codebases, including AppHost resource wiring +- Publish, deploy, and tear down Aspire applications through supported Aspire workflows - Use resource MCP tools for database queries and other resource-specific operations -### dotnet-inspect skill - -The `dotnet-inspect` skill teaches your AI agent to query .NET API surfaces using the [`dotnet-inspect`](https://github.com/richlander/dotnet-inspect) tool. It's installed alongside the Aspire skill in each selected location: - - - -- .agents/skills/dotnet-inspect/ - - SKILL.md -- .github/skills/dotnet-inspect/ - - SKILL.md -- .claude/skills/dotnet-inspect/ - - SKILL.md -- .opencode/skill/dotnet-inspect/ - - SKILL.md - - - -The skill enables your agent to inspect NuGet package API surfaces, compare API changes between package versions, and explore .NET types and members. +### Playwright CLI -:::note[Skill conflict] -The `dotnet-inspect` skill should not be installed alongside the Aspire skill. The Aspire skill already includes support for `aspire docs api` subcommands, providing a powerful way to query Aspire APIs across both C# and TypeScript. -::: +The Playwright CLI option enables browser automation for testing web resources. Use it alongside Aspire skills so the agent can discover the correct frontend endpoint through Aspire first, then automate the browser with Playwright. ### Aspire MCP server @@ -116,20 +80,20 @@ The MCP server gives your AI agent direct runtime access to your running Aspire ## Migrate from AGENTS.md -If your project has an `AGENTS.md` file from a previous version of Aspire, you can migrate to the new skill file format. The skill file provides better structure and is recognized natively by AI coding agents. +If your project has an `AGENTS.md` file from a previous version of Aspire, you can migrate to Aspire skills. Skill files provide better structure and are recognized natively by AI coding agents. -1. Run `aspire agent init` and select **Install Aspire skill file**. +1. Run `aspire agent init` and select **Aspire skills**. -2. The skill files are created at `.github/skills/aspire/SKILL.md` and `.claude/skills/aspire/SKILL.md`. +2. Review the generated `SKILL.md` files in the skill locations you selected. -3. Review and delete the old `AGENTS.md` file — the skill file replaces it. +3. Review and delete the old `AGENTS.md` file after the generated skills cover the same guidance. ## Your first prompts @@ -198,6 +162,7 @@ The Aspire MCP server uses the STDIO transport protocol and may work with other ## See also - [Aspire MCP server](/get-started/aspire-mcp-server/) — tools, security, and troubleshooting for the MCP server +- [Aspire skills](/get-started/aspire-skills/) — skill installation, contents, and migration guidance - [aspire agent command](/reference/cli/commands/aspire-agent/) - [aspire agent init command](/reference/cli/commands/aspire-agent-init/) - [aspire agent mcp command](/reference/cli/commands/aspire-agent-mcp/) diff --git a/src/frontend/src/content/docs/get-started/aspire-mcp-server.mdx b/src/frontend/src/content/docs/get-started/aspire-mcp-server.mdx index 7613e0c94..bb04eda4a 100644 --- a/src/frontend/src/content/docs/get-started/aspire-mcp-server.mdx +++ b/src/frontend/src/content/docs/get-started/aspire-mcp-server.mdx @@ -12,6 +12,10 @@ The MCP server that was previously built into the Aspire dashboard has been remo The Aspire MCP server gives AI coding agents direct runtime access to your running Aspire application. Through the Model Context Protocol (MCP), agents can query resource status, read logs, inspect distributed traces, and execute commands — without you copy-pasting terminal output. +:::tip[Aspire skills are preferred] +For most AI coding-agent workflows, install [Aspire skills](/get-started/aspire-skills/) first. Aspire skills are the preferred way to teach agents Aspire commands, workflows, and AppHost conventions. Add the Aspire MCP server when the agent also needs live runtime data such as resource status, logs, traces, or resource commands. +::: + The MCP server is configured automatically when you run `aspire agent init` and select **Install Aspire MCP server**. @@ -313,5 +317,6 @@ If your AI assistant doesn't detect your AppHost, verify it's running with `aspi ## See also - [Use AI coding agents](/get-started/ai-coding-agents/) — set up your project for AI agents +- [Aspire skills](/get-started/aspire-skills/) — project-local guidance for AI coding agents - [aspire agent mcp command](/reference/cli/commands/aspire-agent-mcp/) - [Dashboard security considerations](/dashboard/security-considerations/) diff --git a/src/frontend/src/content/docs/get-started/aspire-skills.mdx b/src/frontend/src/content/docs/get-started/aspire-skills.mdx new file mode 100644 index 000000000..85b70b87c --- /dev/null +++ b/src/frontend/src/content/docs/get-started/aspire-skills.mdx @@ -0,0 +1,129 @@ +--- +title: Aspire skills +description: Learn how Aspire skills teach AI coding agents to initialize, operate, observe, deploy, and wire Aspire apps. +--- + +import { FileTree, Steps } from '@astrojs/starlight/components'; +import LearnMore from '@components/LearnMore.astro'; + +Aspire skills are Markdown instruction bundles for AI coding agents. Each skill lives in a folder with a `SKILL.md` file that describes when the skill applies and what workflow the agent should follow. Skills don't run services or expose application data; they teach the agent how to use Aspire tools correctly. + +Aspire ships multiple skills for different parts of the app lifecycle. The exact list can vary by Aspire CLI version and project type, but Aspire skills are organized around workflows such as initialization, orchestration, monitoring, deployment, and AppHost wiring. + + + To configure AI coding agents end to end, see [Use AI coding + agents](/get-started/ai-coding-agents/). + + +## Install Aspire guidance + +When you create a new Aspire project with [`aspire new`](/reference/cli/commands/aspire-new/) or add Aspire to an existing codebase with [`aspire init`](/reference/cli/commands/aspire-init/), answer **yes** when the CLI asks whether to configure AI agent environments. Aspire installs the selected skills and MCP configuration as part of that flow. + +To add or update Aspire guidance later, run [`aspire agent init`](/reference/cli/commands/aspire-agent-init/) from your project directory: + +```bash title="Aspire CLI" +aspire agent init +``` + +For non-interactive setup, pass the skill and location options explicitly. To install the available skills and tools into all supported locations, use `all`: + +```bash title="Aspire CLI" +aspire agent init --skills all --skill-locations all +``` + +To install a subset, pass a comma-separated list of skill names: + +```bash title="Aspire CLI" +aspire agent init --skills aspire,aspire-init,aspire-orchestration,aspire-monitoring,aspire-deployment,aspireify,playwright-cli --skill-locations all +``` + +## Available skills + +| Skill | Use it for | What it teaches | +| ---------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `aspire` | Routing Aspire tasks to the right workflow | Detect the AppHost, apply Aspire safety guardrails, and choose the appropriate workflow for the user's request | +| `aspire-init` | Starting a new Aspire app or adding Aspire to an existing repo | Choose `aspire new` or `aspire init`, create the AppHost skeleton, and hand off existing-codebase wiring to `aspireify` | +| `aspire-orchestration` | Managing the local AppHost lifecycle | Start, stop, restart, wait for, and inspect Aspire resources, including recovery from port conflicts and orphaned processes | +| `aspire-monitoring` | Observing running Aspire apps | Inspect resource state, logs, traces, metrics, browser telemetry, and dashboard data before making changes | +| `aspire-deployment` | Publishing, deploying, and tearing down Aspire apps | Use AppHost-modeled deployments for targets such as Docker Compose, Kubernetes, Azure, and AWS | +| `aspireify` | Completing Aspire initialization in an existing codebase after `aspire init` drops an AppHost skeleton | Scan the repo, propose a resource graph, wire projects and containers into the AppHost, connect resources, configure telemetry when appropriate, and validate the wiring | +| `playwright-cli` | Testing running web resources in a browser | Use Playwright CLI for browser automation, including navigation, form interaction, screenshots, and visual checks | + +Use the top-level `aspire` skill when the user request is about an Aspire app and the right workflow isn't obvious. Use a workflow-specific skill directly when the task is clear, such as `aspire-orchestration` for local lifecycle work, `aspire-monitoring` for telemetry investigation, `aspire-deployment` for publish and deploy workflows, or `aspireify` for existing-codebase AppHost wiring. Use `playwright-cli` when an agent needs to test or inspect a running frontend. + +## Playwright handoff + +The `playwright-cli` skill works best alongside the `aspire` skill. The agent should first use Aspire to discover the running app and the correct frontend endpoint, especially when multiple web resources exist. After it has the target URL, it can use Playwright CLI to automate browser testing. + +## Skill locations + +Aspire installs each selected skill into the selected skill locations. For example, a standard location can contain: + + + +- .agents/skills/ + - aspire/ + - SKILL.md + - aspire-init/ + - SKILL.md + - aspire-orchestration/ + - SKILL.md + - aspire-monitoring/ + - SKILL.md + - aspire-deployment/ + - SKILL.md + - aspireify/ + - SKILL.md + - playwright-cli/ + - SKILL.md + + + +Other supported locations use the same skill folder names: + +| Location | Directory | Notes | +| ----------------- | ------------------ | -------------------------------------------------- | +| **Standard** | `.agents/skills/` | Supported by VS Code, GitHub Copilot, and OpenCode | +| **Claude Code** | `.claude/skills/` | Claude Code specific | +| **GitHub Skills** | `.github/skills/` | VS Code / GitHub Copilot specific | +| **OpenCode** | `.opencode/skill/` | OpenCode specific | + +## Prefer skills for workflow guidance + +Aspire skills and the [Aspire MCP server](/get-started/aspire-mcp-server/) solve different parts of the AI agent workflow: + +| Capability | Purpose | +| ------------------------ | --------------------------------------------------------------------------------------------------------- | +| **Aspire skills** | Teach the agent which Aspire workflows, commands, and AppHost conventions to follow | +| **Aspire MCP server** | Gives the agent direct runtime access to resource status, logs, traces, commands, and documentation tools | +| **Resource MCP servers** | Expose resource-specific tools, such as database query tools, through Aspire resources | + +Start with Aspire skills for workflow guidance. Add the Aspire MCP server when the agent also needs live application data to act on. + +## Migrate from AGENTS.md + +If your project has an `AGENTS.md` file from a previous version of Aspire, migrate to Aspire skills. Skill files are structured for AI coding tools and can be installed into the locations those tools read automatically. + + + +1. Run `aspire agent init` and select the Aspire skills. + +1. Review the generated `SKILL.md` files in the skill locations you selected. + +1. Move any project-specific instructions from `AGENTS.md` into the appropriate generated skill file or another agent instruction file used by your team. + +1. Delete `AGENTS.md` after the new skill-based instructions cover the same guidance. + + + +## Customize skills + +Generated skill files can be customized for project-specific conventions, such as preferred resource names, deployment targets, testing commands, or local environment setup. Review custom changes when rerunning `aspire agent init`, `aspire init`, or `aspire new`, because those commands may update generated skill content as Aspire evolves. + +## See also + +- [Use AI coding agents](/get-started/ai-coding-agents/) — set up your project for AI agents +- [Aspire MCP server](/get-started/aspire-mcp-server/) — runtime tools, security, and troubleshooting for MCP +- [Resource MCP servers](/get-started/resource-mcp-servers/) — expose MCP tools from Aspire resources +- [aspire agent init command](/reference/cli/commands/aspire-agent-init/) +- [aspire init command](/reference/cli/commands/aspire-init/) diff --git a/src/frontend/src/content/docs/get-started/first-app.mdx b/src/frontend/src/content/docs/get-started/first-app.mdx index cf1fb8333..7151dcf39 100644 --- a/src/frontend/src/content/docs/get-started/first-app.mdx +++ b/src/frontend/src/content/docs/get-started/first-app.mdx @@ -126,7 +126,7 @@ To create your first Aspire application, use the [Aspire CLI](/get-started/insta If prompted for additional selections, use the and keys to navigate the options. Press to confirm your selection. :::note[AI agent environments] - When prompted "Would you like to configure AI agent environments for this project?", select `y`. This sets up workspace configurations (such as the Aspire skill file and MCP server settings) for your project, enabling a richer experience with AI coding assistants. For more information, see [Use AI coding agents](/get-started/ai-coding-agents/) and the [`aspire agent init`](/reference/cli/commands/aspire-agent-init/) reference. + When prompted "Would you like to configure AI agent environments for this project?", select `y`. This sets up workspace configurations (such as Aspire skills and MCP server settings) for your project, enabling a richer experience with AI coding assistants. For more information, see [Use AI coding agents](/get-started/ai-coding-agents/) and the [`aspire agent init`](/reference/cli/commands/aspire-agent-init/) reference. ::: diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-agent-init.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-agent-init.mdx index 2b89972ec..613fbed71 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-agent-init.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-agent-init.mdx @@ -21,10 +21,10 @@ aspire agent init [options] ## Description -The `aspire agent init` command initializes skill files and MCP (Model Context Protocol) server configuration for your development environment. It presents an interactive multi-step flow to configure AI coding agent support: +The `aspire agent init` command initializes Aspire skills, companion tools, and MCP (Model Context Protocol) server configuration for your development environment. It presents an interactive multi-step flow to configure AI coding agent support: 1. **Select skill locations** — choose where skill files are installed (Standard `.agents/skills/`, Claude Code `.claude/skills/`, GitHub Skills `.github/skills/`, OpenCode `.opencode/skill/`). The **Standard** location is the only option that defaults as pre-selected. -2. **Select skills and tools** — choose which skills to install (Aspire skill, Playwright CLI, dotnet-inspect skill). All options are pre-selected by default. +2. **Select skills and tools** — choose which skills and companion tools to install, such as Aspire skills and Playwright CLI. Aspire workflow skills are selected by default; optional companion tools can be selected explicitly. 3. **Apply selections** — installs the chosen skills into each selected location and sets up the MCP server connection. The command also removes skill files from any locations that were deselected, keeping your workspace clean. @@ -43,7 +43,7 @@ The following options are available: - **`--skills `** - Comma-separated list of skills to enable, such as `aspire`, `aspireify`, `playwright-cli`, or `dotnet-inspect`. Use `all` to enable all available skills or `none` to skip skill installation. When not specified, the command prompts interactively. + Comma-separated list of skills to enable, such as `aspire`, `aspire-init`, `aspire-orchestration`, `aspire-monitoring`, `aspire-deployment`, `aspireify`, or `playwright-cli`. The available list can vary by Aspire CLI version and project type. Use `all` to enable all available skills or `none` to skip skill installation. When not specified, the command prompts interactively. - diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-agent.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-agent.mdx index 2f843ab59..741009d82 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-agent.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-agent.mdx @@ -1,7 +1,7 @@ --- title: aspire agent command seoTitle: aspire agent command reference for the Aspire CLI -description: Learn about the aspire agent command and its usage. This command driver manages AI agent integrations, Aspire skill files, and MCP (Model Context Protocol) server operations. +description: Learn about the aspire agent command and its usage. This command driver manages AI agent integrations, Aspire skills, and MCP (Model Context Protocol) server operations. --- import AsciinemaPlayer from '@components/AsciinemaPlayer.astro'; @@ -22,7 +22,7 @@ aspire agent [command] [options] ## Description -The `aspire agent` command manages AI agent integrations for Aspire. This includes initializing agent environment configuration, installing Aspire skill files, and starting the MCP server. The MCP server enables AI assistants and development tools to interact with your Aspire AppHost, providing capabilities such as resource management, diagnostics, and observability. +The `aspire agent` command manages AI agent integrations for Aspire. This includes initializing agent environment configuration, installing Aspire skills, and starting the MCP server. The MCP server enables AI assistants and development tools to interact with your Aspire AppHost, providing capabilities such as resource management, diagnostics, and observability. ## Options From ca31514f936e70c1d9abcc168f5970d443833b2e Mon Sep 17 00:00:00 2001 From: David Fowler Date: Sat, 30 May 2026 07:14:55 -0700 Subject: [PATCH 2/3] Refine Aspire agent docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../docs/get-started/ai-coding-agents.mdx | 91 +++---------- .../docs/get-started/aspire-mcp-server.mdx | 8 +- .../docs/get-started/aspire-skills.mdx | 122 ++++++++++++------ 3 files changed, 103 insertions(+), 118 deletions(-) diff --git a/src/frontend/src/content/docs/get-started/ai-coding-agents.mdx b/src/frontend/src/content/docs/get-started/ai-coding-agents.mdx index bb79b087a..4453f937e 100644 --- a/src/frontend/src/content/docs/get-started/ai-coding-agents.mdx +++ b/src/frontend/src/content/docs/get-started/ai-coding-agents.mdx @@ -1,22 +1,18 @@ --- title: Use AI coding agents seoTitle: Use AI coding agents with Aspire AppHost projects today -description: Set up AI coding agents to work with Aspire — install skills, configure the Aspire MCP server, and enable browser automation for distributed-app development workflows. +description: Set up AI coding agents to work with Aspire — install skills, add optional tools, and guide agents through distributed-app workflows. --- -import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components'; +import { Steps, Tabs, TabItem } from '@astrojs/starlight/components'; import AsciinemaPlayer from '@components/AsciinemaPlayer.astro'; import LoopingVideo from '@components/LoopingVideo.astro'; -Aspire provides a first-class setup experience for AI coding agents. Run `aspire agent init` in your project and your AI assistant — whether it's GitHub Copilot, Claude Code, or another MCP-compatible tool — can immediately understand, build, debug, and monitor your distributed applications. +## Why Aspire works well for coding agents -## Why Aspire for coding agents +Distributed apps are hard for agents when the app shape is spread across projects, ports, processes, and terminal output. Aspire turns that into one AppHost model and one set of CLI workflows. Agents can read the graph, start the app, wait for resources to become healthy, inspect failures, and make AppHost changes with compiler feedback. -Aspire gives coding agents the same visibility into your running application that a developer has. The resource data, structured logs, and distributed traces you see in the [Aspire Dashboard](/dashboard/overview/) are exposed to agents through the [Aspire MCP server](/get-started/aspire-mcp-server/) and the [Aspire CLI](/get-started/install-cli/). Whether a person is debugging in the dashboard or an agent is diagnosing through MCP, they see the same picture. - -The Aspire CLI is built for agent-driven workflows — commands support non-interactive execution to avoid blocking on prompts, and many commands support `--format Json` for structured plain text output. Key commands include `aspire start` (background execution), `aspire start --isolated` (parallel worktrees), `aspire wait` (block until healthy), `aspire describe`, `aspire logs`, and `aspire docs search`. - -Aspire skills teach agents these patterns automatically. +Start with Aspire skills. They give coding agents Aspire-specific guidance for everyday tasks such as app startup, AppHost wiring, debugging, and deployment. If an agent also needs live data from a running app, Aspire includes an optional MCP server for resource status, logs, traces, and resource commands. ## Get started @@ -32,19 +28,7 @@ When you create a new Aspire project with `aspire new` or `aspire init`, you're aspire agent init ``` -1. Select the **skill locations** where you want files installed. The **Standard** location is pre-selected by default: - - | Location | Directory | Notes | - |---|---|---| - | **Standard** | `.agents/skills/` | Supported by VS Code, GitHub Copilot, and OpenCode | - | **Claude Code** | `.claude/skills/` | Claude Code specific | - | **GitHub Skills** | `.github/skills/` | VS Code / GitHub Copilot specific | - | **OpenCode** | `.opencode/skill/` | OpenCode specific | - -1. Select the **skills and tools** to install into those locations. Aspire workflow skills are selected by default; optional companion tools can be selected explicitly: - - - **Aspire skills** — teach your AI agent how to operate Aspire apps and complete AppHost wiring for existing codebases - - **Playwright CLI** — enables browser automation for testing web resources +1. Select the agent guidance locations and options for your environment. Keep Aspire skills selected. Add Playwright CLI for browser checks, or select **Install Aspire MCP server** if the agent needs live data from a running Aspire app. @@ -55,46 +39,15 @@ When you create a new Aspire project with `aspire new` or `aspire init`, you're cols={256} rows={10} /> -## What gets configured - -The `aspire agent init` command detects your AI development environment and creates the appropriate configuration files: - -### Aspire skills - -The [Aspire skills](/get-started/aspire-skills/) teach your AI coding agent how to work with Aspire. Aspire ships a set of workflow skills for app operations, initialization, monitoring, deployment, and AppHost wiring. The skills guide your agent on how to: - -- Start and manage your Aspire application (`aspire start`, `aspire stop`, `aspire describe`) -- Debug issues using structured logs and distributed traces -- Add integrations with `aspire add` and search documentation with `aspire docs` -- Initialize new and existing codebases, including AppHost resource wiring -- Publish, deploy, and tear down Aspire applications through supported Aspire workflows -- Use resource MCP tools for database queries and other resource-specific operations - -### Playwright CLI - -The Playwright CLI option enables browser automation for testing web resources. Use it alongside Aspire skills so the agent can discover the correct frontend endpoint through Aspire first, then automate the browser with Playwright. - -### Aspire MCP server - -The MCP server gives your AI agent direct runtime access to your running Aspire application — resource status, logs, traces, and commands. See [Aspire MCP server](/get-started/aspire-mcp-server/) for configuration details, available tools, and the security model. +## Configuration details -## Migrate from AGENTS.md +Keep this page focused on setup. Use the dedicated pages when you need the details behind each option: -If your project has an `AGENTS.md` file from a previous version of Aspire, you can migrate to Aspire skills. Skill files provide better structure and are recognized natively by AI coding agents. - - - -1. Run `aspire agent init` and select **Aspire skills**. - -2. Review the generated `SKILL.md` files in the skill locations you selected. - -3. Review and delete the old `AGENTS.md` file after the generated skills cover the same guidance. - - - - +| Capability | Details | +|---|---| +| **Aspire skills** | [Install skills and review available skills](/get-started/aspire-skills/). Start here for most agent workflows. | +| **Aspire MCP server** | [Configure the Aspire MCP server](/get-started/aspire-mcp-server/) when an agent needs resource status, logs, traces, or resource commands from a running app. | +| **Resource MCP servers** | [Expose resource-specific MCP tools from Aspire resources](/get-started/resource-mcp-servers/) when you need deeper access to a particular resource. | ## Your first prompts @@ -146,25 +99,13 @@ Once configured, start your preferred AI coding environment. Try asking your age -## Supported AI assistants - -The `aspire agent init` command supports the following AI assistants: - -- [VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) with GitHub Copilot -- [Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli#add-an-mcp-server) -- [Claude Code](https://docs.claude.com/en/docs/claude-code/mcp) -- [OpenCode](https://opencode.ai/docs/mcp-servers/) - - - ## See also -- [Aspire MCP server](/get-started/aspire-mcp-server/) — tools, security, and troubleshooting for the MCP server -- [Aspire skills](/get-started/aspire-skills/) — skill installation, contents, and migration guidance +- [Aspire skills](/get-started/aspire-skills/) — skill installation and contents +- [Aspire MCP server](/get-started/aspire-mcp-server/) — optional access to live resource status, logs, and traces - [aspire agent command](/reference/cli/commands/aspire-agent/) - [aspire agent init command](/reference/cli/commands/aspire-agent-init/) - [aspire agent mcp command](/reference/cli/commands/aspire-agent-mcp/) - [Dashboard security considerations](/dashboard/security-considerations/) - [Dashboard and AI coding agents](/dashboard/ai-coding-agents/) +- [Agentic dev aspirations](https://devblogs.microsoft.com/aspire/agentic-dev-aspirations/) — background on Aspire's agent-friendly development model diff --git a/src/frontend/src/content/docs/get-started/aspire-mcp-server.mdx b/src/frontend/src/content/docs/get-started/aspire-mcp-server.mdx index bb04eda4a..865eab60b 100644 --- a/src/frontend/src/content/docs/get-started/aspire-mcp-server.mdx +++ b/src/frontend/src/content/docs/get-started/aspire-mcp-server.mdx @@ -16,15 +16,13 @@ The Aspire MCP For most AI coding-agent workflows, install [Aspire skills](/get-started/aspire-skills/) first. Aspire skills are the preferred way to teach agents Aspire commands, workflows, and AppHost conventions. Add the Aspire MCP server when the agent also needs live runtime data such as resource status, logs, traces, or resource commands. ::: -The MCP server is configured automatically when you run `aspire agent init` and select **Install Aspire MCP server**. - To set up your project for AI coding agents, see [Use AI coding agents](/get-started/ai-coding-agents/). ## Configuration -The `aspire agent init` command creates MCP server configuration files for your detected AI environment: +When you select **Install Aspire MCP server**, the `aspire agent init` command creates MCP server configuration files for your detected AI environment: @@ -300,7 +298,7 @@ If your AI assistant doesn't detect your AppHost, verify it's running with `aspi If it starts without errors, the issue is in your AI assistant's configuration. -1. Regenerate configuration: +1. Regenerate configuration and select **Install Aspire MCP server**: ```bash title="Aspire CLI" aspire agent init @@ -310,7 +308,7 @@ If your AI assistant doesn't detect your AppHost, verify it's running with `aspi ### Claude Code issues -- Ensure `.mcp.json` exists in your project root — run `aspire agent init` to regenerate +- Ensure `.mcp.json` exists in your project root — run `aspire agent init` and select **Install Aspire MCP server** to regenerate - On Windows, commands like `npx` require a `cmd.exe /c` prefix - Restart Claude Code to re-establish stale MCP connections diff --git a/src/frontend/src/content/docs/get-started/aspire-skills.mdx b/src/frontend/src/content/docs/get-started/aspire-skills.mdx index 85b70b87c..a7d8011a8 100644 --- a/src/frontend/src/content/docs/get-started/aspire-skills.mdx +++ b/src/frontend/src/content/docs/get-started/aspire-skills.mdx @@ -1,9 +1,10 @@ --- title: Aspire skills +seoTitle: Aspire skills for AI coding agents and AppHost projects description: Learn how Aspire skills teach AI coding agents to initialize, operate, observe, deploy, and wire Aspire apps. --- -import { FileTree, Steps } from '@astrojs/starlight/components'; +import { FileTree, TabItem, Tabs } from '@astrojs/starlight/components'; import LearnMore from '@components/LearnMore.astro'; Aspire skills are Markdown instruction bundles for AI coding agents. Each skill lives in a folder with a `SKILL.md` file that describes when the skill applies and what workflow the agent should follow. Skills don't run services or expose application data; they teach the agent how to use Aspire tools correctly. @@ -17,15 +18,24 @@ Aspire ships multiple skills for different parts of the app lifecycle. The exact ## Install Aspire guidance -When you create a new Aspire project with [`aspire new`](/reference/cli/commands/aspire-new/) or add Aspire to an existing codebase with [`aspire init`](/reference/cli/commands/aspire-init/), answer **yes** when the CLI asks whether to configure AI agent environments. Aspire installs the selected skills and MCP configuration as part of that flow. +Choose the tab that matches your coding agent or installer path. The Aspire CLI path is recommended for project-local setup because it installs Aspire skill files into detected agent environments. -To add or update Aspire guidance later, run [`aspire agent init`](/reference/cli/commands/aspire-agent-init/) from your project directory: + + + +Use Aspire's first-party agent setup when creating a new app, adding Aspire to an existing repo, or refreshing agent guidance later. ```bash title="Aspire CLI" +aspire new +# select y when prompted to configure AI agent environments + +aspire init +# select y when prompted to install Aspire agent guidance + aspire agent init ``` -For non-interactive setup, pass the skill and location options explicitly. To install the available skills and tools into all supported locations, use `all`: +For non-interactive setup, pass the skill and location options explicitly. To install the available skills into all supported locations, use `all`: ```bash title="Aspire CLI" aspire agent init --skills all --skill-locations all @@ -37,6 +47,76 @@ To install a subset, pass a comma-separated list of skill names: aspire agent init --skills aspire,aspire-init,aspire-orchestration,aspire-monitoring,aspire-deployment,aspireify,playwright-cli --skill-locations all ``` + + + +Add the Aspire skills marketplace once, then install the Aspire plugin by name. + +```bash title="GitHub Copilot CLI" +copilot plugin marketplace add microsoft/aspire-skills +copilot plugin install aspire@aspire-skills +``` + +Use this path for terminal workflows where GitHub Copilot needs Aspire-specific guidance for AppHost, lifecycle, deployment, and diagnostics tasks. + + + + +Start Claude Code in your terminal, add the Aspire marketplace, then install the Aspire plugin. + +```bash title="Claude Code CLI" +claude +/plugin marketplace add microsoft/aspire-skills +/plugin install aspire@aspire-skills +``` + +Run the slash commands inside the Claude Code CLI session. + + + + +Add the Aspire marketplace, then install Aspire from the Codex plugins UI. + +```bash title="Codex CLI" +codex plugin marketplace add microsoft/aspire-skills +# then open /plugins and install aspire +``` + +Use this path for terminal-first Codex work that needs repeatable Aspire setup, orchestration, and diagnostics guidance. + + + + +Use APM to install Aspire skills into agent hosts that support OpenCode-compatible skill locations. + +```bash title="OpenCode" +apm install microsoft/aspire-skills +opencode +``` + +Use this path when APM is your preferred way to manage agent skills. + + + + +Use the Skills-compatible installer when your agent host supports skills.sh-managed skill locations. + +```bash title="skills.sh NPX" +npx skills add microsoft/aspire-skills +``` + +For hosts that need an explicit skills directory and target agent, install from the `skills/` folder: + +```bash title="skills.sh NPX with explicit target" +npx skills add https://github.com/microsoft/aspire-skills/tree/main/skills \ + -a github-copilot -g -y +``` + +In that command, `-a github-copilot` selects the target agent, `-g` installs globally, and `-y` accepts prompts. + + + + ## Available skills | Skill | Use it for | What it teaches | @@ -88,42 +168,8 @@ Other supported locations use the same skill folder names: | **GitHub Skills** | `.github/skills/` | VS Code / GitHub Copilot specific | | **OpenCode** | `.opencode/skill/` | OpenCode specific | -## Prefer skills for workflow guidance - -Aspire skills and the [Aspire MCP server](/get-started/aspire-mcp-server/) solve different parts of the AI agent workflow: - -| Capability | Purpose | -| ------------------------ | --------------------------------------------------------------------------------------------------------- | -| **Aspire skills** | Teach the agent which Aspire workflows, commands, and AppHost conventions to follow | -| **Aspire MCP server** | Gives the agent direct runtime access to resource status, logs, traces, commands, and documentation tools | -| **Resource MCP servers** | Expose resource-specific tools, such as database query tools, through Aspire resources | - -Start with Aspire skills for workflow guidance. Add the Aspire MCP server when the agent also needs live application data to act on. - -## Migrate from AGENTS.md - -If your project has an `AGENTS.md` file from a previous version of Aspire, migrate to Aspire skills. Skill files are structured for AI coding tools and can be installed into the locations those tools read automatically. - - - -1. Run `aspire agent init` and select the Aspire skills. - -1. Review the generated `SKILL.md` files in the skill locations you selected. - -1. Move any project-specific instructions from `AGENTS.md` into the appropriate generated skill file or another agent instruction file used by your team. - -1. Delete `AGENTS.md` after the new skill-based instructions cover the same guidance. - - - -## Customize skills - -Generated skill files can be customized for project-specific conventions, such as preferred resource names, deployment targets, testing commands, or local environment setup. Review custom changes when rerunning `aspire agent init`, `aspire init`, or `aspire new`, because those commands may update generated skill content as Aspire evolves. - ## See also - [Use AI coding agents](/get-started/ai-coding-agents/) — set up your project for AI agents -- [Aspire MCP server](/get-started/aspire-mcp-server/) — runtime tools, security, and troubleshooting for MCP -- [Resource MCP servers](/get-started/resource-mcp-servers/) — expose MCP tools from Aspire resources - [aspire agent init command](/reference/cli/commands/aspire-agent-init/) - [aspire init command](/reference/cli/commands/aspire-init/) From 87e0a0a30e19098e40b19f4a8d44b79b8e11f4b8 Mon Sep 17 00:00:00 2001 From: David Fowler Date: Sat, 30 May 2026 18:39:30 -0700 Subject: [PATCH 3/3] Address Aspire agent docs feedback Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../content/docs/get-started/ai-coding-agents.mdx | 15 +++------------ .../content/docs/get-started/aspire-skills.mdx | 4 ++-- 2 files changed, 5 insertions(+), 14 deletions(-) diff --git a/src/frontend/src/content/docs/get-started/ai-coding-agents.mdx b/src/frontend/src/content/docs/get-started/ai-coding-agents.mdx index 4453f937e..4699643f0 100644 --- a/src/frontend/src/content/docs/get-started/ai-coding-agents.mdx +++ b/src/frontend/src/content/docs/get-started/ai-coding-agents.mdx @@ -10,9 +10,9 @@ import LoopingVideo from '@components/LoopingVideo.astro'; ## Why Aspire works well for coding agents -Distributed apps are hard for agents when the app shape is spread across projects, ports, processes, and terminal output. Aspire turns that into one AppHost model and one set of CLI workflows. Agents can read the graph, start the app, wait for resources to become healthy, inspect failures, and make AppHost changes with compiler feedback. +Distributed apps are hard for agents when the app shape is spread across projects, ports, processes, and terminal output. Aspire turns that into one AppHost model and one set of CLI workflows. Agents can read resource graphs, start apps, wait for resources to become healthy, inspect failures, and make AppHost changes with compiler feedback. -Start with Aspire skills. They give coding agents Aspire-specific guidance for everyday tasks such as app startup, AppHost wiring, debugging, and deployment. If an agent also needs live data from a running app, Aspire includes an optional MCP server for resource status, logs, traces, and resource commands. +The Aspire skills give coding agents Aspire-specific guidance for everyday tasks such as app startup, AppHost wiring, debugging, and deployment. If an agent needs live data from a running app, Aspire includes an optional MCP server for resource status, logs, traces, and resource commands. ## Get started @@ -39,16 +39,6 @@ When you create a new Aspire project with `aspire new` or `aspire init`, you're cols={256} rows={10} /> -## Configuration details - -Keep this page focused on setup. Use the dedicated pages when you need the details behind each option: - -| Capability | Details | -|---|---| -| **Aspire skills** | [Install skills and review available skills](/get-started/aspire-skills/). Start here for most agent workflows. | -| **Aspire MCP server** | [Configure the Aspire MCP server](/get-started/aspire-mcp-server/) when an agent needs resource status, logs, traces, or resource commands from a running app. | -| **Resource MCP servers** | [Expose resource-specific MCP tools from Aspire resources](/get-started/resource-mcp-servers/) when you need deeper access to a particular resource. | - ## Your first prompts Once configured, start your preferred AI coding environment. Try asking your agent: @@ -103,6 +93,7 @@ Once configured, start your preferred AI coding environment. Try asking your age - [Aspire skills](/get-started/aspire-skills/) — skill installation and contents - [Aspire MCP server](/get-started/aspire-mcp-server/) — optional access to live resource status, logs, and traces +- [Resource MCP servers](/get-started/resource-mcp-servers/) — optional resource-specific tools - [aspire agent command](/reference/cli/commands/aspire-agent/) - [aspire agent init command](/reference/cli/commands/aspire-agent-init/) - [aspire agent mcp command](/reference/cli/commands/aspire-agent-mcp/) diff --git a/src/frontend/src/content/docs/get-started/aspire-skills.mdx b/src/frontend/src/content/docs/get-started/aspire-skills.mdx index a7d8011a8..562e4fba3 100644 --- a/src/frontend/src/content/docs/get-started/aspire-skills.mdx +++ b/src/frontend/src/content/docs/get-started/aspire-skills.mdx @@ -129,11 +129,11 @@ In that command, `-a github-copilot` selects the target agent, `-g` installs glo | `aspireify` | Completing Aspire initialization in an existing codebase after `aspire init` drops an AppHost skeleton | Scan the repo, propose a resource graph, wire projects and containers into the AppHost, connect resources, configure telemetry when appropriate, and validate the wiring | | `playwright-cli` | Testing running web resources in a browser | Use Playwright CLI for browser automation, including navigation, form interaction, screenshots, and visual checks | -Use the top-level `aspire` skill when the user request is about an Aspire app and the right workflow isn't obvious. Use a workflow-specific skill directly when the task is clear, such as `aspire-orchestration` for local lifecycle work, `aspire-monitoring` for telemetry investigation, `aspire-deployment` for publish and deploy workflows, or `aspireify` for existing-codebase AppHost wiring. Use `playwright-cli` when an agent needs to test or inspect a running frontend. +Use the top-level `aspire` skill when the request is about an Aspire app and the right workflow isn't obvious. Use a workflow-specific skill directly when the task is clear, such as `aspire-orchestration` for local lifecycle work, `aspire-monitoring` for telemetry investigation, `aspire-deployment` for publish and deploy workflows, or `aspireify` for existing-codebase AppHost wiring. Use `playwright-cli` when an agent needs to test or inspect a running frontend. ## Playwright handoff -The `playwright-cli` skill works best alongside the `aspire` skill. The agent should first use Aspire to discover the running app and the correct frontend endpoint, especially when multiple web resources exist. After it has the target URL, it can use Playwright CLI to automate browser testing. +The `playwright-cli` skill works best alongside the `aspire` skill. The agent will first use Aspire to discover the running app and the correct frontend endpoint, especially when multiple web resources exist. After it has the target URL, it can use the Playwright CLI to automate browser testing. ## Skill locations