# .NET开发技能插件

`dotnet` `Claude Code` `插件` `C#` `Akka.NET`

# Claude Code 的 .NET 技能插件

一个功能全面的 Claude Code 插件，包含 **30 个技能** 和 **5 个专业智能体**，专为专业 .NET 开发而设计。涵盖 C#、Akka.NET、Aspire、EF Core、测试和性能优化等领域，均为来自生产系统的经过实战验证的模式。

## 安装

本插件支持多种支持技能/智能体功能的 AI 编程助手。

### Claude Code（CLI）

[官方文档](https://code.claude.com/docs/en/discover-plugins)

在 Claude Code CLI（终端应用，非 VSCode 扩展）中运行以下命令：

```
/plugin marketplace add Aaronontheweb/dotnet-skills
/plugin install dotnet-skills
```

更新方式：
```
/plugin marketplace update
```

### GitHub Copilot

[官方文档](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)

将技能克隆或复制到项目或全局配置中：

**项目级别**（推荐）：
```bash
# 克隆到项目的 .github/skills/ 目录
git clone https://github.com/Aaronontheweb/dotnet-skills.git /tmp/dotnet-skills
cp -r /tmp/dotnet-skills/skills/* .github/skills/
```

**全局**（适用所有项目）：
```bash
mkdir -p ~/.copilot/skills
cp -r /tmp/dotnet-skills/skills/* ~/.copilot/skills/
```

### OpenCode

[官方文档](https://opencode.ai/docs/skills)

```bash
git clone https://github.com/Aaronontheweb/dotnet-skills.git /tmp/dotnet-skills

# 全局安装（目录名必须与 frontmatter 的 'name' 字段匹配）
mkdir -p ~/.config/opencode/skills ~/.config/opencode/agents
for skill_file in /tmp/dotnet-skills/skills/*/SKILL.md; do
  skill_name=$(grep -m1 "^name:" "$skill_file" | sed 's/name: *//')
  mkdir -p ~/.config/opencode/skills/$skill_name
  cp "$skill_file" ~/.config/opencode/skills/$skill_name/SKILL.md
done
cp /tmp/dotnet-skills/agents/*.md ~/.config/opencode/agents/
```

---

## 推荐的 AGENTS.md / CLAUDE.md 片段

以下片段放置于**项目根目录**（代码库根目录，紧邻 `.git` 文件夹）：
- Claude Code：`CLAUDE.md`
- OpenCode：`AGENTS.md`

前提条件：在助手运行时（Claude Code 或 OpenCode）中安装/同步 dotnet-skills 插件，以便下方的技能 ID 能够正常解析。

在下游仓库的 `AGENTS.md`（OpenCode）或 `CLAUDE.md`（Claude Code）中添加一小段路由片段，可确保技能被一致调用。这些片段告诉助手在常见任务中应使用哪些技能。

### 可读片段（可直接复制粘贴）

```markdown
# 智能体指南：dotnet-skills

重要提示：对于任何 .NET 工作，优先使用检索引导的推理，而非预训练知识。
工作流：浏览仓库模式 -> 按名称查询 dotnet-skills -> 实现最小变更 -> 记录冲突。

路由（按名称调用）
- C# / 代码质量：modern-csharp-coding-standards、csharp-concurrency-patterns、api-design、type-design-performance
- ASP.NET Core / Web（含 Aspire）：aspire-service-defaults、aspire-integration-testing、transactional-emails
- 数据：efcore-patterns、database-performance
- DI / 配置：dependency-injection-patterns、microsoft-extensions-configuration
- 测试：testcontainers-integration-tests、playwright-blazor-testing、snapshot-testing

质量关卡（适用时使用）
- dotnet-slopwatch：在大量新增/重构/LLM 生成代码之后
- crap-analysis：在复杂代码中新增/修改测试之后

专业智能体
- dotnet-concurrency-specialist、dotnet-performance-analyst、dotnet-benchmark-designer、akka-net-specialist、docfx-specialist
```

### 压缩片段（自动生成）

运行 `./scripts/generate-skill-index-snippets.sh --update-readme` 可刷新下方代码块。

<!-- BEGIN DOTNET-SKILLS COMPRESSED INDEX -->
```markdown
[dotnet-skills]|重要提示：对于任何 .NET 工作，优先使用检索引导的推理，而非预训练知识。
|flow:{浏览仓库模式 -> 按名称查询 dotnet-skills -> 实现最小变更 -> 记录冲突}
|route:
|akka:{akka-net-best-practices,akka-net-testing-patterns,akka-hosting-actor-patterns,akka-net-aspire-configuration,akka-net-management}
|csharp:{modern-csharp-coding-standards,csharp-concurrency-patterns,api-design,type-design-performance}
|aspnetcore-web:{aspire-integration-testing,aspire-configuration,aspire-service-defaults,mailpit-integration,mjml-email-templates}
|data:{efcore-patterns,database-performance}
|di-config:{microsoft-extensions-configuration,dependency-injection-patterns}
|testing:{testcontainers-integration-tests,playwright-blazor-testing,snapshot-testing,verify-email-snapshots,playwright-ci-caching}
|dotnet:{dotnet-project-structure,dotnet-local-tools,package-management,serialization,dotnet-devcert-trust}
|quality-gates:{dotnet-slopwatch,crap-analysis}
|meta:{marketplace-publishing,skills-index-snippets}
|agents:{akka-net-specialist,docfx-specialist,dotnet-benchmark-designer,dotnet-concurrency-specialist,dotnet-performance-analyst,roslyn-incremental-generator-specialist}
```
<!-- END DOTNET-SKILLS COMPRESSED INDEX -->

## 专业智能体

智能体是具有深度领域专长的 AI 角色，当 Claude Code 检测到相关任务时会自动调用。

| 智能体 | 专业领域 |
| --- | --- |
| **akka-net-specialist** | Actor 系统、集群、持久化、Akka.Streams、消息模式 |
| **dotnet-concurrency-specialist** | 线程、async/await、竞态条件、死锁分析 |
| **dotnet-benchmark-designer** | BenchmarkDotNet 设置、自定义基准测试、测量策略 |
| **dotnet-performance-analyst** | 性能分析器分析、基准测试结果解读、回归检测 |
| **docfx-specialist** | DocFX 构建、API 文档、Markdown 检查 |

---

## 技能库

### Akka.NET

使用 Akka.NET 构建分布式系统的生产级模式。

| 技能 | 学习内容 |
| --- | --- |
| **best-practices** | EventStream vs DistributedPubSub、监督策略、Actor 层次结构 |
| **testing-patterns** | Akka.Hosting.TestKit、异步断言、TestProbe 模式 |
| **hosting-actor-patterns** | Props 工厂、`IRequiredActor<T>`、Actor 中的 DI 作用域管理 |
| **aspire-configuration** | Akka.NET + .NET Aspire 集成、HOCON 与 IConfiguration |
| **management** | Akka.Management、健康检查、集群引导 |

### C# 语言

适用于简洁、高性能代码的现代 C# 模式。

| 技能 | 学习内容 |
| --- | --- |
| **coding-standards** | Records、模式匹配、可空类型、值对象、禁用 AutoMapper |
| **concurrency-patterns** | 何时使用 Task vs Channel vs lock vs actors |
| **api-design** | 仅扩展设计、API/线路兼容性、版本控制策略 |
| **type-design-performance** | 密封类、只读结构体、静态纯函数、Span&lt;T&gt; |

### 数据访问

可扩展的数据库模式。

| 技能 | 学习内容 |
| --- | --- |
| **efcore-patterns** | 实体配置、迁移、查询优化 |
| **database-performance** | 读写分离、防止 N+1 问题、AsNoTracking、行数限制 |

### .NET Aspire

云原生应用编排。

| 技能 | 学习内容 |
| --- | --- |
| **integration-testing** | DistributedApplicationTestingBuilder、Aspire.Hosting.Testing |
| **service-defaults** | OpenTelemetry、健康检查、弹性、服务发现 |
| **mailpit-integration** | 使用 Mailpit 容器进行邮件测试、SMTP 配置、测试断言 |

### ASP.NET Core

Web 应用程序模式。

| 技能 | 学习内容 |
| --- | --- |
| **mjml-email-templates** | MJML 语法、响应式布局、模板渲染器、组合器模式 |

### .NET 生态系统

核心 .NET 开发实践。

| 技能 | 学习内容 |
| --- | --- |
| **project-structure** | 解决方案布局、Directory.Build.props、分层架构 |
| **package-management** | 中央包管理（CPM）、共享版本变量、dotnet CLI |
| **serialization** | Protobuf、MessagePack、System.Text.Json 源生成器、AOT |
| **local-tools** | dotnet 工具清单、团队共享工具 |
| **slopwatch** | 检测代码库中 LLM 生成的反模式 |

### Microsoft.Extensions

依赖注入与配置模式。

| 技能 | 学习内容 |
| --- | --- |
| **configuration** | IOptions 模式、环境特定配置、密钥管理 |
| **dependency-injection** | IServiceCollection 扩展、作用域管理、键控服务 |

### 测试

全面的测试策略。

| 技能 | 学习内容 |
| --- | --- |
| **testcontainers** | 基于 Docker 的集成测试、PostgreSQL、Redis、RabbitMQ |
| **playwright-blazor** | Blazor 应用的端到端测试、页面对象、异步断言 |
| **crap-analysis** | CRAP 分数、覆盖率阈值、ReportGenerator 集成 |
| **snapshot-testing** | Verify 库、审批测试、API 响应校验 |
| **verify-email-snapshots** | 对邮件模板进行快照测试，捕获渲染回归 |

---

## 核心原则

这些技能强调在生产环境中有效的模式：

- **默认不可变** —— Records、只读结构体、值对象
- **类型安全** —— 可空引用类型、强类型 ID
- **组合优于继承** —— 无抽象基类，默认密封
- **性能意识** —— Span&lt;T&gt;、对象池、延迟枚举
- **可测试性** —— 处处使用 DI、纯函数、显式依赖
- **无黑魔法** —— 不用 AutoMapper，不用重反射框架

---

## 仓库结构

```
dotnet-skills/
├── .claude-plugin/
│   └── plugin.json         # 插件清单
├── agents/                 # 5 个专业智能体
│   ├── akka-net-specialist.md
│   ├── docfx-specialist.md
│   ├── dotnet-benchmark-designer.md
│   ├── dotnet-concurrency-specialist.md
│   └── dotnet-performance-analyst.md
└── skills/                 # 扁平结构（30 个技能）
    ├── akka-best-practices/SKILL.md
    ├── akka-hosting-actor-patterns/SKILL.md
    ├── akka-net-aspire-configuration/SKILL.md
    ├── aspire-configuration/SKILL.md
    ├── aspire-integration-testing/SKILL.md
    ├── csharp-concurrency-patterns/SKILL.md
    ├── testcontainers-integration-tests/SKILL.md
    └── ...                 # （按类别添加前缀）
```

---

## 贡献指南

想要添加技能或智能体？欢迎提交 PR！

1. 创建 `skills/<skill-name>/SKILL.md`（使用 `akka-`、`aspire-`、`csharp-` 等前缀标注类别）
2. 将路径添加到 `.claude-plugin/plugin.json`
3. 提交 PR

技能文档应为包含具体示例和反模式的完整参考文档（10-40KB）。

---

## 作者

由 [Aaron Stannard](https://aaronstannard.com/)（[@Aaronontheweb](https://github.com/Aaronontheweb)）创建

模式来源于生产系统，包括 [Akka.NET](https://getakka.net/)、[Petabridge](https://petabridge.com/) 和 [Sdkbin](https://sdkbin.com/)。

## 许可证

MIT 许可证 - 版权所有 © 2025 Aaron Stannard

详情见 [LICENSE](LICENSE) 文件。