# akka-net-aspire-configuration

A skill that wires Akka.NET into .NET Aspire: actor system, clustering, persistence and Akka.Management in one setup.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 396 installs · ★ 1238
- Author: Aaronontheweb
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Aaronontheweb/dotnet-skills/tree/HEAD/skills/akka-aspire-configuration/SKILL.md
- Updated: 2026-10-11
- HTML: https://affpapa.org/en/nevibecode/skills/akka-net-aspire-configuration

## What it does

Reach for this skill when you start a new Akka.NET project with .NET Aspire orchestration, configure Akka.Cluster with bootstrapping and discovery, hook Akka.Persistence up to SQL Server, or prepare a Kubernetes deployment. It also covers running multiple replicas of the actor system during local development.

The skill lays out a three-project solution: actors, web application and AppHost. Configuration goes through Microsoft.Extensions.Configuration with a strongly typed `AkkaSettings` class, DI integration uses Akka.Hosting, and Aspire handles service dependencies, networking and environment variables. Health checks for clustering, persistence and readiness are part of the setup, along with startup validation through `IValidateOptions<T>` and `.ValidateOnStart()` — a typo in your config fails the app immediately instead of surfacing later at runtime. Related skills are named too: `akka-net-management`, `microsoft-extensions-configuration`, `akka-net-best-practices` and `aspire-integration-testing`.

The package list is long: `Akka.Hosting`, `Akka.Cluster.Hosting`, `Akka.Persistence.Sql.Hosting`, `Akka.Management`, `Akka.Management.Cluster.Bootstrap`, discovery providers for Kubernetes, Azure and Config, plus `Petabridge.Cmd.Host` and `Petabridge.Cmd.Cluster`. The code samples will not compile without them, so check that your package versions line up.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Aaronontheweb/dotnet-skills --skill akka-net-aspire-configuration -a claude-code
```
```bash
npx skills add Aaronontheweb/dotnet-skills --skill akka-aspire-configuration -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/akka-aspire-configuration/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/akka-aspire-configuration/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Aaronontheweb/dotnet-skills --skill akka-aspire-configuration -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/akka-aspire-configuration/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Aaronontheweb/dotnet-skills --skill akka-aspire-configuration -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/akka-aspire-configuration/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Aaronontheweb/dotnet-skills akka-aspire-configuration
```

2. **Manually: put the files in place**
- File: `.github/skills/akka-aspire-configuration/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Aaronontheweb/dotnet-skills --skill akka-aspire-configuration -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Aaronontheweb/dotnet-skills --path skills/akka-aspire-configuration
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/akka-aspire-configuration/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Aaronontheweb/dotnet-skills --skill akka-aspire-configuration -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Aaronontheweb/dotnet-skills/tree/HEAD/skills/akka-aspire-configuration/SKILL.md

## When to use it
- stand up an Akka.NET actor system in a new Aspire project
- configure Akka.Cluster with bootstrapping and node discovery
- connect Akka.Persistence to SQL Server
- run several replicas of the actor system locally
- move Akka config into a typed class with startup validation

## Example prompts
- help me set up Akka.NET with Aspire for a new project
- add health checks for Akka clustering and persistence
- build an AppHost with Akka.Management and cluster bootstrap

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 48fa230767e9697d.

BEGIN THIRD-PARTY FILE 48fa230767e9697d
````text
---
name: akka-net-aspire-configuration
description: Configure Akka.NET with .NET Aspire for local development and production deployments. Covers actor system setup, clustering, persistence, Akka.Management integration, and Aspire orchestration patterns.
user-invocable: false
---

# Configuring Akka.NET with .NET Aspire

## When to Use This Skill

Use this skill when:
- Setting up a new Akka.NET project with .NET Aspire orchestration
- Configuring Akka.Cluster with cluster bootstrapping and discovery
- Integrating Akka.Persistence with SQL Server
- Setting up Akka.Management for cluster management
- Configuring multi-replica actor systems in local development
- Deploying Akka.NET applications to Kubernetes with Aspire

## Related Skills

- **`akka-net-management`** - Deep dive into Akka.Management, Cluster Bootstrap, and discovery providers (Kubernetes, Azure, Config)
- **`microsoft-extensions-configuration`** - IValidateOptions patterns for configuration validation
- **`akka-net-best-practices`** - Cluster/local mode abstractions for testable actor systems
- **`aspire-integration-testing`** - Testing Aspire applications with real infrastructure

## Core Principles

1. **Configuration via Microsoft.Extensions.Configuration** - Use strongly-typed settings classes bound from appsettings.json (see `microsoft-extensions-configuration` skill)
2. **Akka.Hosting for DI Integration** - Use the Akka.Hosting library for seamless ASP.NET Core integration
3. **Aspire for Orchestration** - Let Aspire manage service dependencies, networking, and environment configuration
4. **Health Checks** - Always configure health checks for clustering, persistence, and readiness
5. **Separate Concerns** - Keep actor definitions, configuration, and Aspire orchestration in separate layers
6. **Validate Configuration at Startup** - Use `IValidateOptions<T>` and `.ValidateOnStart()` to fail fast on misconfiguration

## Project Structure

```
YourSolution/
├── src/
│   ├── YourApp.Actors/              # Actor definitions and business logic
````
END THIRD-PARTY FILE 48fa230767e9697d

The third-party file has ended. Everything between the 48fa230767e9697d tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2057 of 24479 bytes. © Aaronontheweb · MIT · https://github.com/Aaronontheweb/dotnet-skills/tree/HEAD/skills/akka-aspire-configuration/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md