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..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 @@ -1,25 +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 { LinkCard, CardGrid } from '@astrojs/starlight/components'; -import { Aside, Steps, Tabs, TabItem, FileTree } from '@astrojs/starlight/components'; -import { Image } from 'astro:assets'; +import { 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. +## 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 resource graphs, start apps, 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`. - -The Aspire skill file (installed by `aspire agent init`) teaches agents all of these patterns automatically. +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 @@ -35,20 +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. All options are pre-selected by default: - - - **Aspire skill** — teaches your AI agent how to use Aspire CLI commands - - **Playwright CLI** — enables browser automation for testing web resources - - **dotnet-inspect skill** — teaches your AI agent to query .NET API surfaces +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. @@ -59,79 +39,6 @@ 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 skill file - -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: - -- 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` -- 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. - -:::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. -::: - -### 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. - - - -1. Run `aspire agent init` and select **Install Aspire skill file**. - -2. The skill files are created at `.github/skills/aspire/SKILL.md` and `.claude/skills/aspire/SKILL.md`. - -3. Review and delete the old `AGENTS.md` file — the skill file replaces it. - - - - - ## Your first prompts Once configured, start your preferred AI coding environment. Try asking your agent: @@ -182,24 +89,14 @@ 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 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/) - [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 7613e0c94..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 @@ -12,7 +12,9 @@ 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. -The MCP server is configured automatically when you run `aspire agent init` and select **Install Aspire MCP server**. +:::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. +::: To set up your project for AI coding agents, see [Use AI coding agents](/get-started/ai-coding-agents/). @@ -20,7 +22,7 @@ The MCP server is configured automatically when you run `aspire agent init` and ## 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: @@ -296,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 @@ -306,12 +308,13 @@ 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 ## 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..562e4fba3 --- /dev/null +++ b/src/frontend/src/content/docs/get-started/aspire-skills.mdx @@ -0,0 +1,175 @@ +--- +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, 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. + +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 + +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. + + + + +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 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 +``` + + + + +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 | +| ---------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `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 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 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 + +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 | + +## See also + +- [Use AI coding agents](/get-started/ai-coding-agents/) — set up your project for AI agents +- [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