AI coding agents 的能力边界正从通用代码生成向领域专业化演进。微软.NET 团队开源的 dotnet/skills 项目，为 C# 生态提供了一套完整的技能库参考实现，涵盖从基础.NET 开发到 MSBuild 诊断、NuGet 包管理、ASP.NET Core 等 12 个专业领域。本文基于该项目的架构设计，探讨如何构建面向 AI agents 的结构化 C# 技能库，重点解析工具契约定义、Roslyn 代码分析接口集成以及 MSBuild 工作流嵌入策略。
技能库架构：从单体到插件化
dotnet/skills 采用插件化架构，每个插件（plugin）对应一个独立的功能域。当前包含 12 个核心插件：dotnet（基础.NET 技能）、dotnet-data（数据访问与 EF）、dotnet-diag（性能诊断）、dotnet-msbuild（构建分析）、dotnet-nuget（包管理）、dotnet-upgrade（版本迁移）、dotnet-maui（跨平台开发）、dotnet-ai（AI/ML 集成）、dotnet-template-engine（模板引擎）、dotnet-test（测试执行）、dotnet-aspnet（Web 开发）以及 dotnet11（.NET 11 新特性）。
这种模块化设计的核心优势在于渐进式能力加载。AI agent 无需一次性加载全部知识，而是根据任务上下文动态激活相关技能。每个插件遵循 agentskills.io 开放标准，通过SKILL.md文件声明元数据（名称、描述）与执行指令，形成标准化的工具契约。
SKILL.md 契约：工具能力的声明式定义
Agent Skills 规范将技能定义为轻量级文件夹结构，核心文件SKILL.md包含三个关键部分：
my-skill/
├── SKILL.md # 必需：元数据+指令
├── scripts/ # 可选：可执行脚本
├── references/ # 可选：参考文档
└── assets/ # 可选：模板资源
这种契约设计实现了能力声明与实现分离。元数据（name/description）在 agent 启动时加载，用于技能发现（Discovery）；完整指令仅在任务匹配时激活（Activation）；执行阶段（Execution）按需调用脚本或加载引用文件。这种 "渐进式披露" 机制确保 agent 在保持大量技能可用的同时，维持较小的上下文占用。
对于 C# 技能库，契约设计需特别关注类型安全边界。技能指令应明确约束输入参数（如项目路径、目标框架版本）与输出格式（如 JSON 诊断报告），避免 agent 在代码分析任务中产生歧义。
Roslyn 集成：代码分析的语义接口
C# 技能库的核心差异化能力在于与 Roslyn 编译器平台的深度集成。Roslyn 提供开放的 API 接口，使 AI agent 能够执行超越文本匹配的语义级代码分析：
语法树遍历：通过CSharpSyntaxTree解析源代码，技能可以精确定位类型声明、方法调用、属性访问等语法节点。这在重构任务中尤为重要 ——agent 需要理解代码的语法结构才能生成正确的修改建议。
符号解析：利用Compilation对象进行语义分析，技能可以解析类型层次、接口实现、泛型约束等编译期信息。例如，在 "现代化.NET 项目" 任务中，技能可以识别使用了过时 API 的代码位置，并建议替换方案。
诊断分析器：通过DiagnosticAnalyzer接口，技能可以复用现有的 Roslyn 分析器规则库，或定义自定义诊断规则。这使得 AI agent 能够集成团队现有的代码质量检查流程。
实践中，技能脚本通常以dotnet CLI 工具形式封装 Roslyn 分析逻辑，通过标准输入输出与 agent 交互，保持接口的简洁性。
MSBuild 集成策略：构建工作流的嵌入
dotnet-msbuild 插件展示了如何将 AI 能力嵌入.NET 构建工作流。该插件覆盖构建失败诊断、性能优化、代码质量检查与项目现代化四个维度。
构建诊断技能通过解析 MSBuild 二进制日志（.binlog）定位编译错误与警告。相比文本日志，二进制日志包含完整的结构化构建事件，使 agent 能够追溯依赖冲突、目标框架不匹配等深层问题。
性能优化技能利用 MSBuild 的/profile开关收集目标执行时间数据，识别构建瓶颈。agent 可以据此建议并行化策略、条件编译优化或 PackageReference 精简方案。
集成策略的关键在于工具链解耦。技能不直接操作 MSBuild API，而是通过封装好的 CLI 命令（如dotnet build -bl）获取构建数据，再通过 JSON 或结构化文本返回分析结果。这种设计确保技能在不同.NET SDK 版本间保持兼容。
跨客户端兼容：多平台部署考量
dotnet/skills 的设计目标之一是跨 AI 客户端兼容。项目明确支持 Copilot CLI、Claude Code、VS Code（预览）、Cursor 以及 OpenAI Codex CLI 等多种运行时环境。
实现跨客户端兼容的核心在于标准接口优先。技能遵循 agentskills.io 规范，避免依赖特定客户端的扩展 API。安装方式也保持统一：通过/plugin marketplace add dotnet/skills添加市场源，再安装具体插件。
对于企业场景，技能库支持本地开发模式。开发者可以将技能仓库克隆到~/.cursor/plugins/local/目录（以 Cursor 为例），实现未发布技能的本地测试与迭代。
需要注意的是，VS Code 的插件支持目前标记为预览功能，配置项chat.plugins.enabled可能在后续版本中调整。生产环境部署前应验证目标客户端的技能规范版本兼容性。
自定义技能开发：从参考实现到内部知识库
dotnet/skills 的架构设计为企业构建内部技能库提供了清晰路径。基于该项目的参考实现，自定义技能开发可遵循以下步骤：
第一步：领域边界划分。参照 dotnet/skills 的插件划分逻辑，按技术域（如微服务治理、内部框架使用规范）或团队职能拆分技能边界，避免单一技能职责过载。
第二步：契约定义。为每个技能编写SKILL.md，明确触发条件（如 "当用户询问 API 性能问题时激活"）、输入参数规范与输出格式约束。契约的精确度直接影响 agent 调用技能的准确率。
第三步：工具封装。将现有 CLI 工具、Roslyn 分析器或 MSBuild 任务封装为技能脚本，确保返回格式符合契约定义。对于复杂分析任务，考虑将逻辑拆分为多个原子技能，通过组合实现复杂工作流。
第四步：验证与迭代。利用 dotnet/skills 提供的 skill-validator 工具（位于eng/skill-validator/src/）对技能进行自动化测试，验证指令清晰度与执行可靠性。
结语
dotnet/skills 项目展示了 AI coding agents 从 "通用助手" 向 "专业协作者" 演进的技术路径。通过结构化的 SKILL.md 契约、Roslyn 语义分析接口与 MSBuild 工作流集成，C# 技能库为.NET 开发者提供了可复用、可扩展的 AI 能力基础设施。对于正在构建内部 AI 开发工具的团队，该项目的插件化架构与渐进式加载机制提供了值得参考的工程范式。
资料来源
内容声明：本文无广告投放、无付费植入。
如有事实性问题，欢迎发送勘误至 i@hotdrydog.com。