Document Aspire skills

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',

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:
 
 <Steps>
 

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 <abbr title="Model Context Protocol" data-tooltip-placement="top">MCP</abbr>-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
 
 </Steps>
 
@@ -63,73 +59,41 @@ 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:
-
-<FileTree>
-
-- .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
-
-</FileTree>
-
-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:
-
-<FileTree>
-
-- .agents/skills/dotnet-inspect/
-  - SKILL.md
-- .github/skills/dotnet-inspect/
-  - SKILL.md
-- .claude/skills/dotnet-inspect/
-  - SKILL.md
-- .opencode/skill/dotnet-inspect/
-  - SKILL.md
-
-</FileTree>
-
-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
 
 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.
 
 ## 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.
 
 <Steps>
 
-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.
 
 </Steps>
 
 <Aside type="tip">
-The skill file is more structured than `AGENTS.md` and includes a complete CLI command reference table, workflow patterns, and rules that the agent follows automatically. You can customize it for your project's specific needs.
+Skill files are more structured than `AGENTS.md` and include a complete CLI command reference table, workflow patterns, and rules that the agent follows automatically. You can customize them for your project's specific needs.
 </Aside>
 
 ## 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/)

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 <abbr title="Model Context Protocol" data-tooltip-placement="top">MCP</abbr> 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**.
 
 <LearnMore>
@@ -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/)

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.
+
+<LearnMore>
+  To configure AI coding agents end to end, see [Use AI coding
+  agents](/get-started/ai-coding-agents/).
+</LearnMore>
+
+## 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:
+
+<FileTree>
+
+- .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
+
+</FileTree>
+
+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.
+
+<Steps>
+
+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.
+
+</Steps>
+
+## 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/)