不是又一个 Skill 框架：Agent Skills for .NET 正式发布 目录01 MAF 是什么Semantic Kernel 和 Autogen 的继任者02 Agent Skills 是什么SKILL.md 加渐进式披露03 四种技能源博客说三种文档有四种File-basedSKILL.md 目录Code-definedAgentInlineSkillClass-basedAgentClassSkillMCP-basedskill:// URI04 Provider 架构Provider、Sources、BuilderProviderAgentSkillsProviderSources叶子源 装饰器BuilderAgentSkillsProviderBuilder05 生产治理审批、沙箱、缓存、过滤三个工具默认全部需要审批脚本执行是重点风险缓存和过滤解决规模问题06 Skills vs WorkflowsAI 决定怎么做还是你定义做什么对 .NET 开发者意味着什么第一技能资产可跨工具复用第二分发通道就绪第三生产治理不是事后补丁2026 年 7 月 7 日Microsoft Agent Framework 团队的 Principal Software Engineer Sergey Menshykh 在官方博客宣布Agent Skills for .NET 正式发布从实验性预览转为稳定版本可以在生产环境使用。这条消息表面看是“某 SDK 的某个特性 GA 了”。但它的分量不止于 .NET 生态内部。Agent Skills 不是 .NET 专属的概念。它是一套开放规范规范由 Anthropic 发起仓库 agentskills/agentskills 在 GitHub 上已有两万多名开发者标星。已经采用这套规范的工具一长串Claude Code、GitHub CopilotVS Code / CLI / cloud agent、Cursor、Gemini CLI、JetBrains 的 Junie、OpenCode、OpenHands、Mux、Autohand Code CLI。同一份 C1 技能文件能在这些工具之间复用。而 .NET直到这次 GA才正式被接进这个生态。01 MAF 是什么Semantic Kernel 和 Autogen 的继任者先说载体。Agent Skills 是 Microsoft Agent Framework下称 MAF的一个能力。MAF 的定位和 .NET 开发者直接相关它的官方文档源码仓库是 MicrosoftDocs/semantic-kernel-pr文档站挂着“从 Semantic Kernel 迁移”和“从 Autogen 迁移”两份指南。换句话说MAF 是 Semantic Kernel 和 Autogen 的统一继任者不是又一个平行的新框架。在 SK 上有积累的团队这是它的演进方向不是另起炉灶。MAF 同时提供 .NET 和 Python 两个 SDK。本文聚焦 .NET 侧核心包是 Microsoft.Agents.AIMCP 技能源另需 Microsoft.Agents.AI.Mcp。02 Agent Skills 是什么SKILL.md 加渐进式披露一个技能就是一个目录里面至少有一个 SKILL.md可选地附带 scripts、references、assets 子目录expense-report/ ├── SKILL.md # 必需frontmatter 指令 ├── scripts/ # 可选可执行脚本 ├── references/ # 可选参考文档 └── assets/ # 可选模板等静态资源SKILL.md 头部是 YAML frontmatter--- name: expense-report description: File and validate employee expense reports according to company policy. Use when asked about expense submissions, reimbursement rules, or spending limits. license: Apache-2.0 compatibility: Requires python3 metadata: author: contoso-finance version: 2.1 ---name 和 description 必填。name 限 64 字符以内、小写字母数字加连字符、必须和父目录名一致。description 最多 1024 字符要写清“做什么”和“何时用”因为它是代理判断要不要加载这个技能的依据。frontmatter 之后是 markdown 正文写具体指令建议不超过 500 行长参考材料拆到 references/ 里。格式本身不复杂。关键在它怎么被代理使用渐进式披露progressive disclosure分四个阶段Advertise · 约 100 tokens/skill只有 name 和 description 注入系统提示代理知道有哪些技能可用。Load · 建议 5000 tokens任务匹配某个技能时代理调用 load_skill 工具拉取完整 SKILL.md 正文。Read resources · 按需代理调用 read_skill_resource读取 references、assets 里的补充文件。Run scripts · 按需代理调用 run_skill_script执行技能自带脚本。这个设计的核心是 token 经济学。把领域知识塞进代理传统做法要么写进系统提示撑爆上下文窗口要么做成 RAG检索质量不可控。Agent Skills 的做法是按需加载平时只付 100 tokens 的“广告费”真正要用时才付完整指令的代价而且由模型自己判断什么时候需要。一个细节load_skill 永远会被广播read_skill_resource 只在至少一个技能有 resources 时才广播run_skill_script 同理。工具列表是动态的不会平白多出用不到的工具占位置。03 四种技能源博客说三种文档有四种技能从哪来.NET 实现支持四种技能源。这里有个差异官方博客只提了三种文件型、类、代码定义但 Learn 文档实际描述了四种多出来的是 MCP-based目前还是实验性。File-basedSKILL.md 目录从文件系统的 SKILL.md 目录发现。适合放在共享仓库、由非开发人员维护的技能。脚本执行要传一个 SubprocessScriptRunner.RunAsync。Code-definedAgentInlineSkill用 AgentInlineSkill 在代码里直接定义。适合技能内容需要动态生成比如从数据库读或要捕获调用点上下文的场景。资源用 .AddResource()脚本用 .AddScript()脚本在进程内执行不需要 runner。var unitConverterSkill new AgentInlineSkill( name: unit-converter, description: Convert between common units using a conversion factor, instructions: Use this skill when the user asks to convert between units. 1. Review the conversion-table resource to find the correct factor. 2. Use the convert script, passing the value and factor from the table. ) .AddResource(conversion-table, # Conversion Tables Formula: **result value × factor** | From | To | Factor | |------------|------------|----------| | miles | kilometers | 1.60934 | | kilometers | miles | 0.621371 | ) .AddScript(convert, (double value, double factor) { double result Math.Round(value * factor, 4); return JsonSerializer.Serialize(new { value, factor, result }); });Class-basedAgentClassSkill继承 AgentClassSkillT用 [AgentSkillResource] 和 [AgentSkillScript] 特性标注属性和方法。关键好处是可以打包成 NuGet 分发——团队独立编写技能消费者 dotnet add package 加一行 .UseSkill() 就用上。internal sealed class UnitConverterSkill : AgentClassSkillUnitConverterSkill { public override AgentSkillFrontmatter Frontmatter { get; } new( unit-converter, Convert between common units using a multiplication factor. Use when asked to convert miles, kilometers, pounds, or kilograms.); protected override string Instructions Use this skill when the user asks to convert between units. 1. Review the conversion-table resource to find the correct factor. 2. Use the convert script, passing the value and factor from the table. ; [AgentSkillResource(conversion-table)] [Description(Lookup table of multiplication factors for common unit conversions.)] public string ConversionTable # Conversion Tables Formula: **result value × factor** | From | To | Factor | |------------|------------|----------| | miles | kilometers | 1.60934 | | kilometers | miles | 0.621371 | ; [AgentSkillScript(convert)] [Description(Multiplies a value by a conversion factor and returns the result as JSON.)] private static string ConvertUnits(double value, double factor) { double result Math.Round(value * factor, 4); return JsonSerializer.Serialize(new { value, factor, result }); } }MCP-basedskill:// URI从 MCPModel Context Protocol服务器发现技能用 skill:// URI scheme需要 Microsoft.Agents.AI.Mcp 包目前实验性。支持两种索引类型skill-md 按需从 MCP 服务器拉取 SKILL.md 和资源archive 把整个技能打包成 ZIP/TAR 下载到本地解压。出于安全考虑archive 型技能里的脚本永远不会被执行。四种源各管一段文件型给非开发人员类给 NuGet 分发代码定义给运行时动态场景MCP 给跨进程、跨服务的技能分发。04 Provider 架构Provider、Sources、Builder把技能接进代理靠三个构建块。ProviderAgentSkillsProvider上下文提供程序负责把技能广播进系统提示并注册 load_skill、read_skill_resource、run_skill_script三个工具。Sources叶子源 装饰器叶子源直接产出技能AgentFileSkillsSource 从磁盘读AgentInMemorySkillsSource 包代码定义和类的技能装饰器包装别的源做变换AggregatingAgentSkillsSource 聚合、DeduplicatingAgentSkillsSource 去重、CachingAgentSkillsSource 缓存、FilteringAgentSkillsSource 过滤。装饰器能链式套用组成管道。每个源的 GetSkillsAsync 都拿到 AgentSkillsSourceContext里面有当前请求的 Agent 和 Session过滤逻辑可以据此按代理或租户做决策。BuilderAgentSkillsProviderBuilder链式组合多个源自动加聚合、去重、缓存var skillsProvider new AgentSkillsProviderBuilder() .UseFileSkill(Path.Combine(AppContext.BaseDirectory, skills)) .UseSkill(volumeConverterSkill) // AgentInlineSkill .UseSkill(temperatureConverter) // AgentClassSkill .UseMcpSkills(mcpClient) // MCP-based .UseFileScriptRunner(SubprocessScriptRunner.RunAsync) .Build();最小用法更简单一个文件路径就够var skillsProvider new AgentSkillsProvider( Path.Combine(AppContext.BaseDirectory, skills), SubprocessScriptRunner.RunAsync); AIAgent agent new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential()) .GetResponsesClient() .AsAIAgent(new ChatClientAgentOptions { Name MyAgent, ChatOptions new() { Instructions You are a helpful assistant. }, AIContextProviders [skillsProvider], }, model: deploymentName);05 生产治理审批、沙箱、缓存、过滤GA 的重点是“生产可用”。生产可用不是 API 稳定就够关键在治理。三个工具默认全部需要审批load_skill、read_skill_resource、run_skill_script 在默认配置下代理调用时都会暂停返回 ToolApprovalRequestContent等人确认后才执行。默认即安全。可以用 UseToolApproval 中间件配自动审批规则对受信任的操作放宽AIAgent agent new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential()) .GetResponsesClient() .AsAIAgent(new ChatClientAgentOptions { Name SkillsAgent, ChatOptions new() { Instructions You are a helpful assistant. }, AIContextProviders [skillsProvider], }, model: deploymentName) .AsBuilder() .UseToolApproval(new ToolApprovalAgentOptions { // 自动批准只读的 load_skill / read_skill_resource // run_skill_script 仍需人工确认 AutoApprovalRules [AgentSkillsProvider.ReadOnlyToolsAutoApprovalRule], }) .Build();框架内置两条规则ReadOnlyToolsAutoApprovalRule 自动放行 load 和 read但脚本执行仍要人确认AllToolsAutoApprovalRule 全放行。也可以用 AgentSkillsProviderOptions 单独禁用某个工具的审批。脚本执行是重点风险文件型脚本通过 SubprocessScriptRunner.RunAsync 以子进程方式执行但官方文档明确写了这个 runner仅供演示。生产环境要自己加沙箱容器、资源限制CPU、内存、超时、输入校验和白名单、结构化日志和审计。代码定义和类技能的脚本在进程内执行不需要 runner但同样要审。MCP archive 型技能的脚本直接不执行这是刻意的安全措施——远程可执行内容必须显式信任。缓存和过滤解决规模问题Builder 默认包一层 CachingAgentSkillsSource技能列表解析一次后复用。RefreshInterval 控制过期刷新CacheIsolationKeySelector按上下文比如租户 ID隔离缓存一个 provider 能给不同租户提供不同技能集。过滤用 FilteringAgentSkillsSource 或 Builder 的 UseFilter谓词拿到技能和上下文按代理或租户决定暴露哪些。开发期可以 DisableCaching() 让技能改动即时生效。06 Skills vs WorkflowsAI 决定怎么做还是你定义做什么MAF 里还有一个容易和 Skills 混的概念Workflows。两者都扩展代理能力底层逻辑不同。SkillAI 决定怎么执行单 agent turn 内跑。适合幂等、低风险操作单领域任务。失败整体重试。Workflow你定义执行路径支持 checkpoint失败可从上一步恢复。有副作用发邮件、扣款的步骤该走这里。想让 AI 自己想清楚“怎么做”用 Skill要保证“做什么步骤、什么顺序”用 Workflow。两者不互斥可以组合。对 .NET 开发者意味着什么把这几块拼起来这次 GA 对 .NET 开发者意味着三件事。第一技能资产可跨工具复用为 .NET agent 写的 SKILL.md同一份文件能被 Claude Code、GitHub Copilot、Cursor 识别。领域知识写一次多端通用这比绑死在某个框架的插件格式上值钱。第二分发通道就绪Class-based 技能走 NuGet团队独立发布消费者一行 dotnet add package 加 .UseSkill() 就用上。这和 .NET 生态既有的协作方式一致不需要另起一套。第三生产治理不是事后补丁三个工具默认审批、缓存隔离、过滤管道、脚本沙箱警示这些是企业落地要过的坎框架在 GA 阶段就给到了。剩下的沙箱实现是用户自己的工程责任框架不替你兜底但也不挡路。在 SK 或 Autogen 上有积累的团队MAF 是明确的演进方向。在做企业内部 agent 的团队Agent Skills 的“领域知识打包加按需加载加跨工具复用”值得放进技术选型。从官方文档和示例仓库起步即可。参考资源官方博客https://devblogs.microsoft.com/agent-framework/agent-skills-for-net-is-now-released/Learn 文档https://learn.microsoft.com/en-us/agent-framework/agents/skillsAgent Skills 规范https://agentskills.io.NET 示例https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/02-agents/AgentSkills引入地址