dotnet-skills：让AI助手精准理解.NET生态，告别代码生成偏差

1. 项目概述：dotnet-skills，让AI真正懂你的.NET项目

如果你是一位.NET开发者，并且尝试过让Claude、GitHub Copilot这类AI助手帮你写Entity Framework Core的代码，或者让它理解你的Blazor项目结构，你很可能经历过这样的挫败感：AI要么给你生成过时的EF6代码，要么分不清Blazor Server和Blazor WebAssembly的区别，甚至在你使用Minimal API时，还固执地给你生成一个Startup.cs文件。这种“鸡同鸭讲”的体验，根源在于AI模型缺乏对现代.NET生态具体、准确、结构化的知识。它们可能知道C#语法，但对ASP.NET Core的最新实践、Orleans的Grain模型、或是Aspire的编排逻辑，认知是模糊甚至错误的。

dotnet-skills项目就是为了彻底解决这个问题而生的。它不是一个简单的代码片段库，而是一个社区驱动的、持续更新的.NET技能目录。你可以把它理解为一套为AI助手量身定制的“专业词典”和“操作手册”。通过安装这些技能，你实际上是在“教”你的AI助手，让它理解你项目中使用的具体技术栈的边界、最佳实践和常见陷阱。从此，当你对AI说“用Entity Framework Core实现一个分页查询”时，它不会再给你一个包含DbContext构造函数和DbSet属性的过时模板，而是会生成符合.NET 8和EF Core 8规范的、使用了AsNoTracking和PaginatedList的现代化代码。

这个工具的核心价值在于消除认知偏差。它通过结构化的Markdown文档（SKILL.md）和元数据（manifest.json），将分散的、隐性的.NET开发知识，转化为AI可以精确理解和应用的显性规则。无论是基础的Microsoft.Extensions依赖注入配置，还是复杂的Semantic Kernel插件编排，亦或是Orleans的Grain持久化策略，每个技能都聚焦于一个具体的、可操作的领域。对于开发者而言，这意味着更高的代码生成准确率、更少的上下文解释成本，以及一个真正能融入开发生命周期的AI伙伴。

2. 核心设计思路：从“通用聊天”到“领域专家”的范式转变

dotnet-skills的设计哲学，源于一个深刻的洞察：让一个通用大模型直接生成高质量的领域代码，是低效且不可靠的。这就像让一个博学的通才去完成心脏外科手术——他可能知道所有医学名词，但缺乏精准的、肌肉记忆般的操作流程。因此，项目的核心思路是**“路由+精专”**。

2.1 分层路由架构：让对的AI做对的事

整个系统的顶层是一个智能路由层。当你向AI提出一个需求，比如“帮我优化这个Web API的性能”，dotnet-skills背后的路由逻辑（例如dotnet-router这个编排代理）不会让AI直接开始写代码。它会先进行问题分类：

1. 领域识别：这是Web API问题，属于“Web”集合。
2. 技术栈判定：项目使用的是ASP.NET Core Minimal API还是Controller？是否用了EF Core？
3. 问题细化：“性能优化”可能涉及数据库查询、HTTP响应压缩、缓存策略、还是异步编程？

基于这个分类，路由层会将任务精准分发到最专业的技能上。例如，如果判定是数据库查询慢，它会调用entity-framework-core-query-performance技能；如果是内存缓存问题，则调用microsoft-extensions-caching技能。这种设计确保了AI始终在它“最懂”的上下文里工作，避免了跨领域知识混淆带来的错误。

2.2 技能即原子知识单元：结构化的“操作手册”

每个技能（Skill）都是一个自包含的原子知识单元。它的载体是一个SKILL.md文件，其内容结构经过精心设计，远不止是API文档的复制粘贴：

• 精准的触发条件（USE FOR）：明确界定该技能的适用场景。例如，pinvoke技能的触发条件是“编写新的P/Invoke或LibraryImport声明、审查或调试现有的原生互操作代码”。这防止了AI在不该使用该技能时误用。
• 明确的禁忌（DO NOT USE FOR）：同样重要，它划清了技能边界。继续以pinvoke为例，它会明确指出“不适用于COM互操作、C++/CLI混合模式程序集”。这直接避免了AI生成错误类型的代码。
• 工作流与可交付物：技能会描述一个典型的解决路径。比如entity-framework-core-migrations技能，会引导AI依次完成：1) 检查模型变更，2) 创建迁移，3) 生成SQL脚本预览，4) 应用迁移。并明确最终交付物是一个新的迁移文件和更新后的数据库。
• 验证与陷阱：这是技能的“精华”部分，包含了常规文档不会写的实战经验。例如，在blazor-server技能中，会强调“在OnInitializedAsync中执行长时间操作时要考虑组件渲染状态，避免在预渲染阶段调用JavaScript互操作”。这些内容直接来自社区开发者的踩坑经验。

2.3 集合与捆绑包：逻辑分组与一键部署

为了便于管理，技能被组织成集合（Collections）和捆绑包（Bundles）。

• 集合是按技术领域划分的逻辑分组，如“.NET Foundations”、“Web”、“Data”、“AI & Agents”。它帮助开发者和AI从宏观上理解技能的组织结构。
• 捆绑包则是为了特定工作流或角色设计的一键安装包。例如，bundle quality捆绑包就包含了format、csharpier、roslynator、code-analysis等一系列代码质量相关的技能。如果你是一个团队的技术负责人，想为所有项目统一配置代码质量门禁，直接安装这个捆绑包即可，无需逐个寻找。

这种设计体现了极强的实用性思维：它既提供了细粒度的控制（可以单独安装efcore技能），也提供了面向场景的粗粒度解决方案（一键安装整个质量检查套件）。

3. 实战上手：安装、配置与核心工作流解析

理解了设计理念，我们来看如何将它用起来。整个过程非常“.NET”，主要通过全局工具（Global Tool）来完成。

3.1 环境准备与工具安装

首先，你需要安装.NET 8 SDK或更高版本。然后，通过NuGet安装核心工具：

dotnet tool install --global dotnet-skills

这个命令会安装dotnet skills这个主CLI工具。它负责技能目录的管理：浏览、安装、更新、移除。根据你主要使用的AI助手，你可能还需要安装对应的“代理启动器”。项目提供了两种风格：

• .NET风格：dotnet tool install --global dotnet-agents，之后使用dotnet agents命令。
• 独立风格：dotnet tool install --global agents，之后使用agents命令。

两者功能完全一致，选择你习惯的命令行风格即可。我个人更推荐dotnet-agents，因为它与.NET生态的工具链（如dotnet ef，dotnet run）风格统一，记忆成本低。

3.2 探索与安装技能

安装完成后，最直观的入口是交互式控制中心：

dotnet skills

执行这个命令会打开一个基于终端的TUI界面，你可以在这里按集合浏览所有技能，查看详细描述，并预览安装效果。这对于初次接触的用户来说非常友好。

但对于习惯了命令行的高效开发者，直接使用CLI命令更快捷。首先，列出所有可用的技能和捆绑包：

# 列出所有技能（简洁视图，显示已安装和可用集合摘要） dotnet skills list # 列出所有聚焦的捆绑包 dotnet skills bundle list

假设你正在开发一个ASP.NET Core Web API项目，并使用了Entity Framework Core。你可以手动安装相关技能：

# 安装单个技能 dotnet skills install aspnetcore-webapi entity-framework-core # 或者，安装一个针对Web开发的捆绑包（如果存在） # dotnet skills install bundle web-foundations

但更强大的功能是自动发现。进入你的项目根目录（包含.csproj文件），运行：

dotnet skills install --auto

这个命令会扫描当前目录下的所有.csproj文件，识别出引用的NuGet包（如Microsoft.EntityFrameworkCore.SqlServer）和项目类型（如<OutputType>Exe</OutputType>），然后自动为你安装匹配的技能。例如，检测到Microsoft.AspNetCore.OpenApi包，它会建议安装aspnetcore-openapi技能；检测到NUnit测试框架，它会建议安装testing-nunit技能。

一个重要的实操技巧：项目依赖会变化。当你移除某个NuGet包后，之前自动安装的技能可能就过时了。这时可以使用--prune参数进行清理：

dotnet skills install --auto --prune

这个命令会在安装新技能的同时，移除那些不再与当前项目匹配的“陈旧”技能，保持技能列表的整洁。但请注意，一些诊断性技能（如graphify-dotnet）会被保护，不会被自动移除。

3.3 技能安装路径与AI助手集成

安装的技能文件最终去了哪里？这取决于你安装时指定的目标（--agent）和作用域（--scope）。

dotnet-skills支持主流的AI助手平台，并为每个平台定义了标准的技能存放路径：

作用域的选择策略：

• 项目级安装：这是推荐的首选方式。将技能安装在项目目录下的隐藏文件夹中（如.claude/skills）。这样做的好处是技能配置可以随项目代码一起纳入版本控制（如Git）。任何克隆该项目的团队成员，都能立即获得完全一致的AI技能环境，保证了协作的一致性。这对于强制执行代码规范（通过quality捆绑包）或确保特定框架（如Orleans）使用方式统一至关重要。
• 全局安装：适合安装那些你在所有项目中都会用到的基础、通用技能，例如dotnet（主路由技能）、modern-csharp（现代C#规范）、project-setup（项目结构）。这些技能不依赖于特定项目技术栈，属于开发者个人工作环境的一部分。

如果你不指定--agent参数，工具会按照Codex -> Claude -> Copilot -> Gemini -> Junie的顺序，自动检测系统中已存在的AI助手配置目录，并将技能安装到所有检测到的平台。只有在所有平台目录都不存在时，才会使用默认的共享路径（~/.agents/skills/）。

3.4 编排代理：更高阶的AI工作流管理

除了技能，dotnet-skills还引入了编排代理的概念。如果说技能是让AI懂得“如何做一件事”，那么代理就是告诉AI“何时以及如何调用一系列技能来完成一个复杂任务”。

例如，dotnet-router是一个顶层的路由代理。它的AGENT.md文件里定义了复杂的路由逻辑：当用户提出一个模糊的需求时，它负责分析问题，决定应该调用dotnet-build（构建问题）、dotnet-data（数据问题）还是dotnet-frontend（前端问题）等更具体的代理。

这些代理的安装和管理与技能类似，但有独立的命令集（通过dotnet agents或agents）：

# 列出可用的编排代理 dotnet agents list # 安装代理（例如，智能路由器） dotnet agents install router # 更推荐：自动安装到所有检测到的AI助手平台 dotnet agents install router --auto

--auto参数在这里非常有用，它会遍历所有已知的AI助手目录（如~/.claude/agents/），并将代理文件安装到每一个已存在的平台中，实现一键多平台部署。

4. 技能目录深度解析：以“质量保障”和“数据访问”为例

为了更具体地理解dotnet-skills的价值，我们深入看两个核心集合：.NET Quality和Data。

4.1 .NET Quality 集合：打造坚如磐石的代码基线

这个集合的目标不是简单地让AI格式化代码，而是让AI理解并帮助实施一整套可重复、可强制执行的代码质量体系。它包含的技能各有侧重，形成了互补的防线。

• format与csharpier：格式化之争。format技能基于官方的dotnet format工具，高度可配置，能与.editorconfig深度集成，适合需要精细控制编码风格的大型团队。而csharpier则是一个“固执己见”的格式化工具，它提供一种统一的、不可配置的代码风格，适合追求绝对一致性和减少风格争论的团队。AI在应用这两个技能时，会生成不同的建议：使用format时，它可能会提示“根据.editorconfig第X行规则，建议将换行符改为LF”；而使用csharpier时，它的建议会更绝对：“运行dotnet csharpier .以应用不可变的格式化规则”。

• code-analysis与roslynator/meziantou-analyzer：分析器的层次。code-analysis技能专注于配置.NET SDK内置的分析器（Microsoft.CodeAnalysis.NetAnalyzers），通过设置AnalysisLevel和EnableNETAnalyzers来开启或关闭规则。这是第一道，也是最轻量级的防线。而roslynator和meziantou-analyzer则是强大的第三方分析器包，提供了数百个额外的规则，涵盖代码风格、性能、安全、设计等方方面面。AI在应用这些技能时，能给出更具体的代码改进建议，例如“Roslynator规则RCS1090建议在此处调用ConfigureAwait(false)以提高非UI上下文的性能”。

• quality-ci：CI/CD流水线的守门员。这个技能是上述所有工具的集大成者。它指导AI如何在一个典型的GitHub Actions或Azure Pipelines的YAML配置文件中，串联起这些质量检查步骤。例如，它会生成一个包含以下步骤的CI作业：

  1. dotnet restore
  2. dotnet build --no-restore
  3. dotnet format --verify-no-changes --severity info（格式检查）
  4. dotnet test --no-build --verbosity normal（运行测试）
  5. dotnet csharpier --check .（如果使用了CSharpier）
  6. 上传代码覆盖率报告

通过安装bundle quality，你实际上是为AI配备了一个全栈代码质量顾问，它能在你编写代码、提交前、乃至CI流程中，提供贯穿始终的质量保障建议。

4.2 Data 集合：让AI成为你的数据架构伙伴

数据访问是现代应用的核心，也是AI最容易出错的地方之一。Data集合的技能旨在让AI精确理解从ORM到SQL的每一层。

• entity-framework-core：不仅仅是CRUD。这个技能的核心是教会AI区分EF Core的不同使用模式。它会强调：

  • DbContext生命周期：在ASP.NET Core中，推荐使用作用域生命周期；在Worker Service中，可能需要考虑使用池化或瞬态。
  • 查询优化：何时使用AsNoTracking？如何通过Select投影避免SELECT *？IncludevsThenInclude的陷阱是什么？
  • 迁移管理：如何生成幂等的SQL脚本（--idempotent）以用于生产部署？如何在多个DbContext共用一个数据库时处理迁移？ AI在应用此技能后，生成的代码会自带这些“最佳实践”的印记，而不是简单的context.Users.ToList()。

• entity-framework-core-query-performance：深入执行计划。这是EF Core技能的深化。它指导AI如何分析并解决性能问题：

  1. 启用日志：配置Microsoft.EntityFrameworkCore.Database.Command日志级别为Information，让AI能看到生成的SQL。
  2. 识别N+1查询：通过日志发现循环内多次查询数据库的模式。
  3. 提出解决方案：建议使用Include进行预加载，或使用Select进行显式加载，将多个查询合并。
  4. 使用AsSplitQuery：在涉及大量Include的复杂查询中，建议使用拆分查询以避免笛卡尔积爆炸。 这个技能让AI从一个代码生成器，变成了一个初级性能调优师。

• dapper：回归原始的掌控感。当项目需要极致的性能或复杂的SQL操作时，Dapper是首选。这个技能教会AI：

  • 参数化查询：必须使用DynamicParameters来防止SQL注入，绝不能拼接字符串。
  • 多映射：如何处理Query<TFirst, TSecond, TReturn>这种一对多、多对多的复杂结果集映射。
  • 与EF Core混合使用：在同一个项目中，何时该用Dapper执行复杂报表查询，何时该用EF Core处理事务性操作。 有了这个技能，AI就不会再试图用EF Core的LINQ去生成一个需要WITH RECURSIVE的复杂层级查询，而是会正确地建议：“此处查询涉及多重递归和大量计算，建议使用Dapper编写原生SQL，并在数据库层面优化。”

一个关键的实操心得：不要一次性安装所有Data集合的技能。根据你的项目技术栈按需安装。如果你只用EF Core，安装entity-framework-core及其相关的性能、迁移子技能即可。混合使用EF Core和Dapper的项目，则需要同时安装两者。AI会根据上下文（如项目文件中的NuGet包引用）自动选择最相关的技能进行响应。

5. 高级用法与社区贡献

5.1 本地开发与目录预览

如果你是项目的贡献者，或者想深入了解技能目录的构建过程，可以克隆仓库并进行本地开发。

git clone https://github.com/managedcode/dotnet-skills.git cd dotnet-skills

项目使用Python脚本进行目录生成和静态站点构建：

# 生成目录数据（更新 README.md 中的技能表格） python3 scripts/generate_catalog.py # 生成GitHub Pages静态站点 python3 scripts/generate_pages.py

生成的站点会输出到artifacts/github-pages/目录，其导航结构与CLI工具和官方网站保持一致（Packages, Bundles, Collections, Skills, Agents, About），方便本地预览和调试。

5.2 技能与代理的仓库结构

理解仓库布局对贡献至关重要。所有内容都组织在catalog/目录下，按类型和包进行分层：

catalog/ └── <Type>/ # 类型：如 Platform, Frameworks, Tools, Libraries └── <Package>/ # 包名：如 DotNet, Entity-Framework-Core, CSharpier ├── manifest.json # 包级元数据（标题、描述、图标、链接） ├── skills/ │ └── <skill-name>/ # 技能文件夹 │ ├── SKILL.md # 核心技能文档（内容） │ ├── manifest.json # 技能级元数据 │ └── ... # 可选的脚本、引用、资源 └── agents/ # 代理文件夹（可选） └── <agent-name>/ ├── AGENT.md # 核心代理文档（路由逻辑） └── manifest.json

关键规则：

1. SKILL.md是核心：它应专注于路由、工作流、可交付物和验证。不要在里面写version、category等元数据，这些属于manifest.json。
2. manifest.json是元数据：包级和技能级的manifest.json文件用于存储分类、版本、依赖关系等结构化信息，供CLI工具和网站读取。
3. 关注点分离：AGENT.md负责决策和路由（“该用哪个技能”），SKILL.md负责具体执行（“如何做这件事”）。

5.3 贡献你的技能

社区驱动是dotnet-skills的生命力。如果你维护着一个优秀的.NET开源库，或者对某个框架有深刻理解，强烈建议你为其贡献一个技能。流程大致如下：

1. Fork & Clone： Fork官方仓库并克隆到本地。
2. 确定位置： 根据你的库属于平台、框架还是工具，在catalog/<Type>/下创建或找到对应的包目录。
3. 创建技能结构： 在包目录的skills/下创建新的技能文件夹（如my-awesome-library）。
4. 编写SKILL.md： 这是最核心的一步。内容应包含：
   • 清晰的目标：这个技能解决什么问题？
   • 精确的触发条件（USE FOR）：AI在什么场景下应该激活这个技能？
   • 明确的禁忌（DO NOT USE FOR）：哪些场景不适用？
   • 详细的工作流：一步步指导AI如何完成任务。
   • 验证步骤：如何确认任务完成正确？
   • 常见陷阱与解决方案：分享你踩过的坑。
5. 编写manifest.json： 填写技能的名称、描述、版本、所属集合、关联的NuGet包等信息。
6. 测试： 在本地使用dotnet skills install --local <你的技能路径>进行安装和测试。
7. 提交PR： 发起拉取请求，项目维护者会进行审核。

贡献的核心价值在于填补AI知识的空白。尤其是那些官方文档语焉不详，但实践中又至关重要的“隐性知识”——比如某个库在异步环境下的特殊配置、某个API的性能瓶颈及其规避方法、与另一个流行库集成时的常见冲突——这些正是dotnet-skills技能文档应该详细阐述的。

6. 常见问题与故障排查

在实际使用和贡献过程中，你可能会遇到一些典型问题。以下是我根据经验整理的排查指南。

6.1 安装与命令问题

6.2 技能内容与效果问题

6.3 高级配置与调试

• 跳过更新检查：如果你处于离线环境，或者不想在每次运行命令时检查NuGet更新，可以设置环境变量：

  export DOTNET_SKILLS_SKIP_UPDATE_CHECK=1 # 然后运行 dotnet skills list 等命令

  对于dotnet-agents和agents工具，对应的变量是DOTNET_AGENTS_SKIP_UPDATE_CHECK和AGENTS_SKIP_UPDATE_CHECK。

• 指定目录版本：默认情况下，工具使用最新的目录版本。如果你想锁定到一个特定版本（例如为了稳定性），可以使用--catalog-version参数：

  dotnet skills install aspnetcore-webapi --catalog-version 2024.10.25.0

• 查看令牌数：每个技能文档（SKILL.md）都有其Token数量，这关系到AI模型的上下文窗口占用。你可以导出JSON报告来查看：

  dotnet skills catalog tokens --catalog-root .

  这对于优化技能内容的长度，确保其能被AI有效处理很有帮助。

从我近半年的使用经验来看，dotnet-skills最大的价值在于它将AI从“聪明的实习生”变成了“专业的副驾驶”。它不会取代开发者，而是通过提供精准的领域知识，极大地提升了AI辅助编程的可靠性和效率。最初的设置和学习曲线是值得的，一旦你将技能集成到日常 workflow 中，你会发现你花在向AI解释基础概念和纠正低级错误上的时间几乎降为零，可以将更多精力集中在架构设计和业务逻辑这些真正创造价值的部分。