Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions src/frontend/config/sidebar/docs.topics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
1 change: 1 addition & 0 deletions src/frontend/scripts/update-github-stats.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ const REPOS = [
'microsoft/aspire-samples',
'CommunityToolkit/Aspire',
'microsoft/aspire.dev',
'microsoft/aspire-skills',
'microsoft/dcp',
] as const;
const OUTPUT_PATH = './src/data/github-stats.json';
Expand Down
7 changes: 7 additions & 0 deletions src/frontend/src/content/docs/community/contributors.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,13 @@ Want to help [improve the aspire.dev site?](/community/contributor-guide/) We're
<ContributorList githubRepo="microsoft/aspire.dev" ignore={ignore} />
<GitHubRepoStats stats={stats} repoName="microsoft/aspire.dev" />

## 🤖 Aspire Skills contributors

Aspire Skills helps AI coding agents follow Aspire workflows consistently, from AppHost setup and orchestration to deployment and diagnostics. Contributions to the skills, plugin metadata, docs, and evals help agents stay aligned with current Aspire guidance and improve the experience for everyone using AI-assisted development with Aspire.

<ContributorList githubRepo="microsoft/aspire-skills" ignore={ignore} />
<GitHubRepoStats stats={stats} repoName="microsoft/aspire-skills" />

## ⚙️ DCP contributors

The [Distributed Component Platform (DCP)](/architecture/overview/#developer-control-plane) is an open-source project that provides a framework for building distributed applications. It is designed to simplify the development of microservices and serverless applications by providing a set of tools and libraries that make it easy to create, deploy, and manage distributed components.
Expand Down
33 changes: 10 additions & 23 deletions src/frontend/src/content/docs/dashboard/ai-coding-agents.mdx
Original file line number Diff line number Diff line change
@@ -1,43 +1,42 @@
---
title: Dashboard and AI coding agents
seoTitle: Aspire dashboard and AI coding agents for distributed apps
description: Learn how AI coding agents use the Aspire CLI and MCP server to read logs and telemetry from the Aspire dashboard, diagnose failures, and propose code changes.
description: Learn how AI coding agents use the Aspire CLI to read dashboard telemetry, diagnose failures, and propose code changes.
---

import { Aside, Steps } from '@astrojs/starlight/components';
import { Steps } from '@astrojs/starlight/components';

AI coding agents can use the [Aspire CLI](/reference/cli/overview/) and [Aspire MCP server](/get-started/aspire-mcp-server/) to fetch logs and telemetry from the Aspire dashboard. This gives agents the same observability data that developers see in the dashboard UI — structured logs, distributed traces, resource status, and console output — so they can diagnose issues, verify fixes, and add new features with full context.
AI coding agents can use the [Aspire CLI](/reference/cli/overview/) to fetch logs and telemetry from the Aspire dashboard. This gives agents the same observability data that developers see in the dashboard UI — structured logs, distributed traces, resource status, and console output — so they can diagnose issues, verify fixes, and add new features with full context.

## How agents use dashboard data

When an Aspire app is running, the dashboard collects OpenTelemetry data from all resources. AI coding agents access this data through two channels:
When an Aspire app is running, the dashboard collects OpenTelemetry data from all resources. AI coding agents access this data through the Aspire CLI:

- **Aspire CLI** — Commands like [`aspire logs`](/reference/cli/commands/aspire-logs/), [`aspire otel logs`](/reference/cli/commands/aspire-otel-logs/), [`aspire otel traces`](/reference/cli/commands/aspire-otel-traces/), and [`aspire describe`](/reference/cli/commands/aspire-describe/) retrieve resource status, console logs, and telemetry directly from the terminal. All commands support `--format Json` for structured output that agents can parse.
- **Aspire MCP server** — The [MCP server](/get-started/aspire-mcp-server/) exposes tools such as `list_resources`, `list_structured_logs`, `list_traces`, and `list_console_logs` that agents call directly through the Model Context Protocol.

Both channels draw from the same underlying dashboard data. Whether an agent reads logs via the CLI or through MCP tools, it sees the same information as the dashboard UI.
The CLI draws from the same underlying dashboard data. Whether an agent reads logs from the terminal or a developer views them in the dashboard UI, they see the same information.

### 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 skill files](/get-started/ai-coding-agents/#aspire-skill-file) and the [Aspire Skills plugin pack](/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>

1. The agent starts the Aspire app with `aspire start` and waits for resources to become healthy with `aspire wait`.
1. The agent runs `aspire describe` to check resource status and identify any unhealthy services.
1. The agent fetches structured logs with `aspire otel logs` or the `list_structured_logs` MCP tool, filtering by resource name to find errors.
1. The agent fetches structured logs with `aspire otel logs`, filtering by resource name to find errors.
1. The agent retrieves distributed traces with `aspire otel traces` to understand cross-service request flow and identify latency issues.
1. Using the collected data, the agent makes code changes, restarts the affected resource, and verifies the fix by checking logs and traces again.

</Steps>

## Get started

The fastest way to set up AI coding agents with Aspire is the `aspire agent init` command. See [Use AI coding agents](/get-started/ai-coding-agents/) for the full setup guide, including skill files, MCP server configuration, and supported AI assistants.
The fastest way to set up AI coding agents with Aspire is the `aspire agent init` command. See [Use AI coding agents](/get-started/ai-coding-agents/) for the full setup guide, including skill files and supported AI assistants. For global plugin installation and included skills, see [Aspire Skills](/get-started/aspire-skills/).

## Standalone mode

The Aspire CLI and MCP server work with the [standalone dashboard](/dashboard/standalone/) — you don't need an Aspire AppHost project. This is useful when monitoring any application that sends OpenTelemetry data to the dashboard.
The Aspire CLI works with the [standalone dashboard](/dashboard/standalone/) — you don't need an Aspire AppHost project. This is useful when monitoring any application that sends OpenTelemetry data to the dashboard.

### Start the standalone dashboard

Expand Down Expand Up @@ -67,18 +66,6 @@ aspire otel traces --dashboard-url "http://localhost:18888"
aspire otel spans --dashboard-url "http://localhost:18888"
```

### Use Aspire MCP with the standalone dashboard

Start the MCP server in dashboard-only mode using `--dashboard-url`:

```bash title="Aspire CLI"
aspire agent mcp --dashboard-url "http://localhost:18888"
```

This exposes the dashboard's telemetry tools (structured logs, traces, and resource data) to any MCP-compatible AI assistant.

Configuration is required in the agent to use the MCP server. For configuration details, see [Aspire MCP server configuration](/get-started/aspire-mcp-server/#configuration). The `--dashboard-url` must be passed as a command line argument when configuring the MCP server for standalone use.

### Sample skill for standalone dashboard

The following is a sample skill file that teaches an AI coding agent how to start the standalone dashboard and query its data. Save it as `.github/skills/aspire-standalone/SKILL.md` (for GitHub Copilot) or `.claude/skills/aspire-standalone/SKILL.md` (for Claude Code):
Expand Down Expand Up @@ -131,6 +118,6 @@ aspire otel spans --dashboard-url http://localhost:18888
## See also

- [Use AI coding agents](/get-started/ai-coding-agents/) — full setup guide with `aspire agent init`
- [Aspire MCP server](/get-started/aspire-mcp-server/) — MCP tools, security, and troubleshooting
- [Aspire Skills](/get-started/aspire-skills/) — plugin installation and included skills
- [Standalone Aspire dashboard](/dashboard/standalone/) — running the dashboard without an AppHost
- [Aspire CLI reference](/reference/cli/overview/)
116 changes: 38 additions & 78 deletions src/frontend/src/content/docs/get-started/ai-coding-agents.mdx
Original file line number Diff line number Diff line change
@@ -1,25 +1,21 @@
---
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, configure agent tooling, 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 AsciinemaPlayer from '@components/AsciinemaPlayer.astro';
import LoopingVideo from '@components/LoopingVideo.astro';
import { Aside, Steps, FileTree } from '@astrojs/starlight/components';
import LearnMore from '@components/LearnMore.astro';
Comment on lines +7 to 8

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.
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 agentic coding tool — can immediately understand, build, debug, and monitor your distributed applications. For global agent-host plugins and the shared Aspire skill pack, see [Aspire Skills](/get-started/aspire-skills/).

## Why Aspire for coding agents

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.
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 available through the [Aspire CLI](/get-started/install-cli/). Whether a person is debugging in the dashboard or an agent is diagnosing from the terminal, 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 skill file (installed by `aspire agent init`) teaches agents all of these patterns automatically. The separate [Aspire Skills](/get-started/aspire-skills/) plugin pack makes the same Aspire-aware routing and guardrails available to supported agent hosts globally.

## Get started

Expand All @@ -37,27 +33,27 @@ When you create a new Aspire project with `aspire new` or `aspire init`, you're

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

</Steps>

<AsciinemaPlayer
src="/casts/agent-init.cast"
poster="npt:0:08"
<AsciinemaPlayer
src="/casts/agent-init.cast"
poster="npt:0:08"
autoPlay={true}
cols={256}
rows={10} />
rows={10}
/>

## What gets configured

Expand All @@ -70,13 +66,13 @@ The skill file teaches your AI coding agent how to work with Aspire. It includes
<FileTree>

- .agents/skills/aspire/
- SKILL.md Standard (VS Code, GitHub Copilot, OpenCode)
- SKILL.md Standard (VS Code, GitHub Copilot, OpenCode)
- .github/skills/aspire/
- SKILL.md GitHub Copilot (legacy location)
- SKILL.md GitHub Copilot (legacy location)
- .claude/skills/aspire/
- SKILL.md Claude Code
- SKILL.md Claude Code
- .opencode/skill/aspire/
- SKILL.md OpenCode
- SKILL.md OpenCode

</FileTree>

Expand All @@ -85,7 +81,7 @@ 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
- Use resource-specific tools for database queries and other operations

### dotnet-inspect skill

Expand All @@ -110,9 +106,14 @@ The skill enables your agent to inspect NuGet package API surfaces, compare API
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
### Aspire Skills plugin pack

The [`microsoft/aspire-skills`](https://github.com/microsoft/aspire-skills) repository packages the Aspire skill, focused sub-skills, plugin metadata, and evals for agent hosts that support plugin or extension installation. Use it when you want Aspire guidance installed globally for tools such as Copilot CLI, Claude Code, Codex CLI, Gemini CLI, Cursor CLI, OpenCode, or Ollama with Copilot CLI.

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.
<LearnMore>
For installation commands, included skills, and evaluation coverage, see
[Aspire Skills](/get-started/aspire-skills/).
</LearnMore>

## Migrate from AGENTS.md

Expand All @@ -129,7 +130,9 @@ If your project has an `AGENTS.md` file from a previous version of Aspire, you c
</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.
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.
</Aside>

## Your first prompts
Expand All @@ -142,64 +145,21 @@ Once configured, start your preferred AI coding environment. Try asking your age

> "Add a Redis cache to my AppHost."

<Tabs>
<TabItem label="VS Code" id="demo-vscode">
<LoopingVideo
aria-label="VS Code with GitHub Copilot using Aspire MCP to list resources"
controls={true}
sources={[
{
src: "/mcp-vscode-list-resources.mp4",
type: "video/mp4",
title: "VS Code demonstrating Aspire MCP integration with GitHub Copilot"
}
]}
/>
</TabItem>
<TabItem label="Claude Code" id="demo-claude">
<AsciinemaPlayer
src="/casts/mcp-claudecode-cli.cast"
poster="npt:0:27"
autoPlay={true}
cols={256}
rows={28} />
</TabItem>
<TabItem label="Copilot CLI" id="demo-copilot">
<AsciinemaPlayer
src="/casts/mcp-copilot-cli.cast"
poster="npt:0:22"
autoPlay={true}
cols={256}
rows={28} />
</TabItem>
<TabItem label="OpenCode" id="demo-opencode">
<AsciinemaPlayer
src="/casts/mcp-opencode-cli.cast"
poster="npt:0:14"
autoPlay={true}
cols={256}
rows={28} />
</TabItem>
</Tabs>

## Supported AI assistants

The `aspire agent init` command supports the following AI assistants:
The `aspire agent init` command supports project-local setup for 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/)
- [VS Code](https://code.visualstudio.com/docs/copilot/overview) with GitHub Copilot
- [Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli)
- [Claude Code](https://docs.claude.com/en/docs/claude-code/overview)
- [OpenCode](https://opencode.ai/docs/)

<Aside type="note">
The Aspire MCP server uses the STDIO transport protocol and may work with other agentic coding environments that support this MCP communication protocol.
</Aside>
The [Aspire Skills plugin pack](/get-started/aspire-skills/#install-as-an-agent-plugin-or-extension) also provides install paths for Copilot CLI, Claude Code, Codex CLI, Gemini CLI, Cursor CLI, OpenCode, and Ollama with Copilot CLI.

## See also

- [Aspire MCP server](/get-started/aspire-mcp-server/) — tools, security, and troubleshooting for the MCP server
- [Aspire Skills](/get-started/aspire-skills/) — plugin installation, included skills, and eval coverage
- [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/)
Loading
Loading