Skip to content

Update skill to CLI commands, rework agent init, add aspire mcp tools/call #14837

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mitchdenny merged 2 commits into from
Mar 6, 2026
Merged

Update skill to CLI commands, rework agent init, add aspire mcp tools/call #14837

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ae027ba
Update Aspire skill to use CLI commands, rework agent init, add aspir…
davidfowl Mar 5, 2026
13d0faa
Fix review issues: JSON input validation, extension backchannel comme…
Mar 6, 2026
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
174 changes: 67 additions & 107 deletions src/Aspire.Cli/Agents/CommonAgentApplicators.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ public static bool TryAddSkillFileApplicator(
context.AddApplicator(new AgentEnvironmentApplicator(
$"{description} (update - content has changed)",
ct => UpdateSkillFileAsync(skillFilePath, ct),
promptGroup: McpInitPromptGroup.AdditionalOptions,
promptGroup: McpInitPromptGroup.SkillFiles,
priority: 0));
return true;
}
Expand All @@ -68,7 +68,7 @@ public static bool TryAddSkillFileApplicator(
context.AddApplicator(new AgentEnvironmentApplicator(
description,
ct => CreateSkillFileAsync(skillFilePath, ct),
promptGroup: McpInitPromptGroup.AdditionalOptions,
promptGroup: McpInitPromptGroup.SkillFiles,
priority: 0));

return true;
Expand Down Expand Up @@ -98,9 +98,9 @@ public static void AddPlaywrightCliApplicator(

context.PlaywrightApplicatorAdded = true;
context.AddApplicator(new AgentEnvironmentApplicator(
"Install Playwright CLI for browser automation",
"Install Playwright CLI (Recommended for browser automation)",
ct => installer.InstallAsync(context, ct),
promptGroup: McpInitPromptGroup.AdditionalOptions,
promptGroup: McpInitPromptGroup.Tools,
priority: 1));
}

Expand Down Expand Up @@ -146,136 +146,96 @@ private static string NormalizeLineEndings(string content)
"""
---
name: aspire
description: "**WORKFLOW SKILL** - Orchestrates Aspire applications using the Aspire CLI and MCP tools for running, debugging, and managing distributed apps. USE FOR: aspire run, aspire stop, start aspire app, aspire describe, list aspire integrations, debug aspire issues, view aspire logs, add aspire resource, aspire dashboard, update aspire apphost. DO NOT USE FOR: non-Aspire .NET apps (use dotnet CLI), container-only deployments (use docker/podman), Azure deployment after local testing (use azure-deploy skill). INVOKES: Aspire MCP tools (list_resources, list_integrations, list_structured_logs, get_doc, search_docs), bash for CLI commands. FOR SINGLE OPERATIONS: Use Aspire MCP tools directly for quick resource status or doc lookups."
description: "Orchestrates Aspire distributed applications using the Aspire CLI for running, debugging, and managing distributed apps. USE FOR: aspire start, aspire stop, start aspire app, aspire describe, list aspire integrations, debug aspire issues, view aspire logs, add aspire resource, aspire dashboard, update aspire apphost. DO NOT USE FOR: non-Aspire .NET apps (use dotnet CLI), container-only deployments (use docker/podman), Azure deployment after local testing (use azure-deploy skill). INVOKES: Aspire CLI commands (aspire start, aspire describe, aspire otel logs, aspire docs search, aspire add), bash. FOR SINGLE OPERATIONS: Use Aspire CLI commands directly for quick resource status or doc lookups."
---

# Aspire Skill

This repository is set up to use Aspire. Aspire is an orchestrator for the entire application and will take care of configuring dependencies, building, and running the application. The resources that make up the application are defined in `apphost.cs` including application code and external dependencies.

## General recommendations for working with Aspire

1. Before making any changes always run the apphost using `aspire run` and inspect the state of resources to make sure you are building from a known state.
2. Changes to the _apphost.cs_ file will require a restart of the application to take effect.
3. Make changes incrementally and run the aspire application using the `aspire run` command to validate changes.
4. Use the Aspire MCP tools to check the status of resources and debug issues.

## Running Aspire in agent environments

Agent environments may terminate foreground processes when a command finishes. Use detached mode:
This repository uses Aspire to orchestrate its distributed application. Resources are defined in the AppHost project (`apphost.cs` or `apphost.ts`).

## CLI command reference

| Task | Command |
|---|---|
| Start the app | `aspire start` |
| Start isolated (worktrees) | `aspire start --isolated` |
| Restart the app | `aspire start` (stops previous automatically) |
| Wait for resource healthy | `aspire wait <resource>` |
| Stop the app | `aspire stop` |
| List resources | `aspire describe` or `aspire resources` |
| Run resource command | `aspire resource <resource> <command>` |
| Start/stop/restart resource | `aspire resource <resource> start|stop|restart` |
| View console logs | `aspire logs [resource]` |
| View structured logs | `aspire otel logs [resource]` |
| View traces | `aspire otel traces [resource]` |
| Logs for a trace | `aspire otel logs --trace-id <id>` |
| Add an integration | `aspire add` |
| List running AppHosts | `aspire ps` |
| Update AppHost packages | `aspire update` |
| Search docs | `aspire docs search <query>` |
| Get doc page | `aspire docs get <slug>` |
| List doc pages | `aspire docs list` |
| Environment diagnostics | `aspire doctor` |
| List resource MCP tools | `aspire mcp tools` |
| Call resource MCP tool | `aspire mcp call <resource> <tool> --input <json>` |

Most commands support `--format Json` for machine-readable output. Use `--apphost <path>` to target a specific AppHost.

## Key workflows

### Running in agent environments

Use `aspire start` to run the AppHost in the background. When working in a git worktree, use `--isolated` to avoid port conflicts and to prevent sharing user secrets or other local state with other running instances:

```bash
aspire run --detach
aspire start --isolated
```

This starts the AppHost in the background and returns immediately. The CLI will:
- Automatically stop any existing running instance before starting a new one
- Display a summary with the Dashboard URL and resource endpoints

### Running with isolation

The `--isolated` flag starts the AppHost with randomized port numbers and its own copy of user secrets.
Use `aspire wait <resource>` to block until a resource is healthy before interacting with it:

```bash
aspire run --detach --isolated
aspire start --isolated
aspire wait myapi
```

Isolation should be used when:
- When AppHosts are started by background agents
- When agents are using source code from a work tree
- There are port conflicts when starting the AppHost without isolation
Relaunching is safe — `aspire start` automatically stops any previous instance. Re-run `aspire start` whenever changes are made to the AppHost project.

### Stopping the application
### Debugging issues

To stop a running AppHost:
Before making code changes, inspect the app state:

```bash
aspire stop
```
1. `aspire describe` — check resource status
2. `aspire otel logs <resource>` — view structured logs
3. `aspire logs <resource>` — view console output
4. `aspire otel traces <resource>` — view distributed traces

This will scan for running AppHosts and stop them gracefully.
### Adding integrations

### Relaunch rules
Use `aspire docs search` to find integration documentation, then `aspire docs get` to read the full guide. Use `aspire add` to add the integration package to the AppHost.

- If AppHost code changes, run `aspire run --detach` again to restart with the new code.
- Relaunching is safe: starting a new instance will automatically stop the previous instance.
- Do not attempt to keep multiple instances running.
After adding an integration, restart the app with `aspire start` for the new resource to take effect.

## Running the application
### Using resource MCP tools

To run the application run the following command:
Some resources expose MCP tools (e.g. `WithPostgresMcp()` adds SQL query tools). Discover and call them via CLI:

```bash
aspire run
aspire mcp tools # list available tools
aspire mcp tools --format Json # includes input schemas
aspire mcp call <resource> <tool> --input '{"key":"value"}' # invoke a tool
```

If there is already an instance of the application running it will prompt to stop the existing instance. You only need to restart the application if code in `apphost.cs` is changed, but if you experience problems it can be useful to reset everything to the starting state.

## Checking resources
## Important rules

To check the status of resources defined in the app model use the _list resources_ tool. This will show you the current state of each resource and if there are any issues. If a resource is not running as expected you can use the _execute resource command_ tool to restart it or perform other actions.

## Listing integrations

IMPORTANT! When a user asks you to add a resource to the app model you should first use the _list integrations_ tool to get a list of the current versions of all the available integrations. You should try to use the version of the integration which aligns with the version of the Aspire.AppHost.Sdk. Some integration versions may have a preview suffix. Once you have identified the correct integration you should always use the _get integration docs_ tool to fetch the latest documentation for the integration and follow the links to get additional guidance.

## Debugging issues

IMPORTANT! Aspire is designed to capture rich logs and telemetry for all resources defined in the app model. Use the following diagnostic tools when debugging issues with the application before making changes to make sure you are focusing on the right things.

1. _list structured logs_; use this tool to get details about structured logs.
2. _list console logs_; use this tool to get details about console logs.
3. _list traces_; use this tool to get details about traces.
4. _list trace structured logs_; use this tool to get logs related to a trace

## Other Aspire MCP tools

1. _select apphost_; use this tool if working with multiple app hosts within a workspace.
2. _list apphosts_; use this tool to get details about active app hosts.
- **Always start the app first** (`aspire start`) before making changes to verify the starting state.
- **To restart, just run `aspire start` again** — it automatically stops the previous instance. NEVER use `aspire stop` then `aspire run`. NEVER use `aspire run` at all.
- Use `--isolated` when working in a worktree.
- **Avoid persistent containers** early in development to prevent state management issues.
- **Never install the Aspire workload** — it is obsolete.
- Prefer `aspire.dev` and `learn.microsoft.com/dotnet/aspire` for official documentation.

## Playwright CLI

The Playwright CLI has been installed in this repository for browser automation. Use it to perform functional investigations of the resources defined in the app model as you work on the codebase. To get endpoints that can be used for navigation use the list resources tool. Run `playwright-cli --help` for available commands.

## Updating the app host

The user may request that you update the Aspire apphost. You can do this using the `aspire update` command. This will update the apphost to the latest version and some of the Aspire specific packages in referenced projects, however you may need to manually update other packages in the solution to ensure compatibility. You can consider using the `dotnet-outdated` with the users consent. To install the `dotnet-outdated` tool use the following command:

```bash
dotnet tool install --global dotnet-outdated-tool
```

## Persistent containers

IMPORTANT! Consider avoiding persistent containers early during development to avoid creating state management issues when restarting the app.

## Aspire workload

IMPORTANT! The aspire workload is obsolete. You should never attempt to install or use the Aspire workload.

## Aspire Documentation Tools

IMPORTANT! The Aspire MCP server provides tools to search and retrieve official Aspire documentation directly. Use these tools to find accurate, up-to-date information about Aspire features, APIs, and integrations:

1. **list_docs**: Lists all available documentation pages from aspire.dev. Returns titles, slugs, and summaries. Use this to discover available topics.

2. **search_docs**: Searches the documentation using keywords. Returns ranked results with titles, slugs, and matched content. Use this when looking for specific features, APIs, or concepts.

3. **get_doc**: Retrieves the full content of a documentation page by its slug. After using `list_docs` or `search_docs` to find a relevant page, pass the slug to `get_doc` to retrieve the complete documentation.

### Recommended workflow for documentation

1. Use `search_docs` with relevant keywords to find documentation about a topic
2. Review the search results - each result includes a **Slug** that identifies the page
3. Use `get_doc` with the slug to retrieve the full documentation content
4. Optionally use the `section` parameter with `get_doc` to retrieve only a specific section

## Official documentation

IMPORTANT! Always prefer official documentation when available. The following sites contain the official documentation for Aspire and related components

1. https://aspire.dev
2. https://learn.microsoft.com/dotnet/aspire
3. https://nuget.org (for specific integration package details)
If configured, use Playwright CLI for functional testing of resources. Get endpoints via `aspire describe`. Run `playwright-cli --help` for available commands.
""";
}
18 changes: 14 additions & 4 deletions src/Aspire.Cli/Agents/McpInitPromptGroup.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,19 +9,29 @@ namespace Aspire.Cli.Agents;
internal sealed class McpInitPromptGroup
{
/// <summary>
/// Group for updating deprecated agent configurations (highest priority).
/// Group for updating deprecated agent configurations (applied silently).
/// </summary>
public static readonly McpInitPromptGroup ConfigUpdates = new("ConfigUpdates", priority: -1);

/// <summary>
/// Group for agent environment configurations (VS Code, Copilot CLI, etc.).
/// Group for agent environment MCP server configurations (VS Code, Copilot CLI, etc.).
/// </summary>
public static readonly McpInitPromptGroup AgentEnvironments = new("AgentEnvironments", priority: 0);

/// <summary>
/// Group for additional optional configurations (AGENTS.md, Playwright, etc.).
/// Group for skill file installations.
/// </summary>
public static readonly McpInitPromptGroup AdditionalOptions = new("AdditionalOptions", priority: 1);
public static readonly McpInitPromptGroup SkillFiles = new("SkillFiles", priority: 1);

/// <summary>
/// Group for additional tool installations (Playwright CLI, etc.).
/// </summary>
public static readonly McpInitPromptGroup Tools = new("Tools", priority: 2);

/// <summary>
/// Group for additional optional configurations.
/// </summary>
public static readonly McpInitPromptGroup AdditionalOptions = new("AdditionalOptions", priority: 3);

private McpInitPromptGroup(string name, int priority)
{
Expand Down
Loading
Loading