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直接开始写代码。它会先进行问题分类领域识别这是Web API问题属于“Web”集合。技术栈判定项目使用的是ASP.NET Core Minimal API还是Controller是否用了EF Core问题细化“性能优化”可能涉及数据库查询、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 efdotnet 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和项目类型如OutputTypeExe/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助手平台并为每个平台定义了标准的技能存放路径AI 助手全局安装路径 (--scope global)项目级安装路径 (--scope project)Claude~/.claude/skills/./.claude/skills/GitHub Copilot~/.copilot/skills/./.github/skills/Gemini~/.gemini/skills/./.gemini/skills/Codex$CODEX_HOME/skills/(默认~/.codex/skills/)./.codex/skills/Junie~/.junie/skills/./.junie/skills/默认共享路径~/.agents/skills/./.agents/skills/作用域的选择策略项目级安装这是推荐的首选方式。将技能安装在项目目录下的隐藏文件夹中如.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-ciCI/CD流水线的守门员。这个技能是上述所有工具的集大成者。它指导AI如何在一个典型的GitHub Actions或Azure Pipelines的YAML配置文件中串联起这些质量检查步骤。例如它会生成一个包含以下步骤的CI作业dotnet restoredotnet build --no-restoredotnet format --verify-no-changes --severity info格式检查dotnet test --no-build --verbosity normal运行测试dotnet csharpier --check .如果使用了CSharpier上传代码覆盖率报告通过安装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如何分析并解决性能问题启用日志配置Microsoft.EntityFrameworkCore.Database.Command日志级别为Information让AI能看到生成的SQL。识别N1查询通过日志发现循环内多次查询数据库的模式。提出解决方案建议使用Include进行预加载或使用Select进行显式加载将多个查询合并。使用AsSplitQuery在涉及大量Include的复杂查询中建议使用拆分查询以避免笛卡尔积爆炸。 这个技能让AI从一个代码生成器变成了一个初级性能调优师。dapper回归原始的掌控感。当项目需要极致的性能或复杂的SQL操作时Dapper是首选。这个技能教会AI参数化查询必须使用DynamicParameters来防止SQL注入绝不能拼接字符串。多映射如何处理QueryTFirst, 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关键规则SKILL.md是核心它应专注于路由、工作流、可交付物和验证。不要在里面写version、category等元数据这些属于manifest.json。manifest.json是元数据包级和技能级的manifest.json文件用于存储分类、版本、依赖关系等结构化信息供CLI工具和网站读取。关注点分离AGENT.md负责决策和路由“该用哪个技能”SKILL.md负责具体执行“如何做这件事”。5.3 贡献你的技能社区驱动是dotnet-skills的生命力。如果你维护着一个优秀的.NET开源库或者对某个框架有深刻理解强烈建议你为其贡献一个技能。流程大致如下Fork Clone Fork官方仓库并克隆到本地。确定位置 根据你的库属于平台、框架还是工具在catalog/Type/下创建或找到对应的包目录。创建技能结构 在包目录的skills/下创建新的技能文件夹如my-awesome-library。编写SKILL.md 这是最核心的一步。内容应包含清晰的目标这个技能解决什么问题精确的触发条件USE FORAI在什么场景下应该激活这个技能明确的禁忌DO NOT USE FOR哪些场景不适用详细的工作流一步步指导AI如何完成任务。验证步骤如何确认任务完成正确常见陷阱与解决方案分享你踩过的坑。编写manifest.json 填写技能的名称、描述、版本、所属集合、关联的NuGet包等信息。测试 在本地使用dotnet skills install --local 你的技能路径进行安装和测试。提交PR 发起拉取请求项目维护者会进行审核。贡献的核心价值在于填补AI知识的空白。尤其是那些官方文档语焉不详但实践中又至关重要的“隐性知识”——比如某个库在异步环境下的特殊配置、某个API的性能瓶颈及其规避方法、与另一个流行库集成时的常见冲突——这些正是dotnet-skills技能文档应该详细阐述的。6. 常见问题与故障排查在实际使用和贡献过程中你可能会遇到一些典型问题。以下是我根据经验整理的排查指南。6.1 安装与命令问题问题现象可能原因解决方案运行dotnet skills提示“命令未找到”1. .NET全局工具未正确安装。2. 终端会话未刷新PATH。1. 确认安装dotnet tool list -g。2. 重新打开终端或运行dotnet tool install --global dotnet-skills重装。dotnet skills install --auto未检测到任何技能1. 当前目录没有.csproj文件。2..csproj文件格式异常或无法解析。1. 切换到包含.csproj的项目根目录。2. 检查.csproj是否为有效的MSBuild XML文件。技能已安装但AI助手如Claude无反应1. 技能安装路径错误。2. AI助手未正确加载技能目录。3. 技能文件格式有误。1. 使用dotnet skills where查看技能安装路径确认与AI助手配置一致。2. 查阅AI助手官方文档确认其自定义技能/插件的加载机制。3. 检查SKILL.md的Markdown语法和manifest.json的JSON格式是否正确。更新技能后AI行为未改变AI助手可能缓存了技能内容。重启AI助手的客户端或IDE插件。对于某些云端AI可能需要等待一段时间或手动触发技能重载。6.2 技能内容与效果问题问题现象可能原因解决方案AI生成的代码仍然过时或不符合预期1. 安装的技能版本过旧。2. 多个技能冲突AI选择了错误的技能。3. 用户提示词过于模糊未触发精确技能。1. 运行dotnet skills update更新所有技能到最新目录版本。2. 使用dotnet skills list --local查看已安装技能移除不必要或冲突的技能。3. 在提示词中更明确地指定技术栈例如“使用ASP.NET Core Minimal API和EF Core 8按照aspnetcore-minimal-api技能的规范创建一个...”技能描述很好但AI执行结果有偏差SKILL.md中的工作流可能不够具体或缺少关键的限制条件。这是一个贡献的好机会可以Fork项目修改该技能的SKILL.md在“验证”或“陷阱”部分增加更明确的约束条件然后提交PR。找不到我需要的某个库的技能该库尚未被社区覆盖。参考第5.3节为你熟悉的库贡献一个技能。这是让整个社区受益的最佳方式。6.3 高级配置与调试跳过更新检查如果你处于离线环境或者不想在每次运行命令时检查NuGet更新可以设置环境变量export DOTNET_SKILLS_SKIP_UPDATE_CHECK1 # 然后运行 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解释基础概念和纠正低级错误上的时间几乎降为零可以将更多精力集中在架构设计和业务逻辑这些真正创造价值的部分。