1. 为什么 .NET 开发者这次该认真看一眼 Agent SkillsAgent Skills for .NET 正式发布这件事表面上是 Microsoft Agent Framework下称 MAF的一个特性从预览转稳定实际影响的是 .NET 团队怎么把领域知识打包给 AI 用。它解决的问题很具体以前你要么把业务规则全塞进系统提示上下文窗口很快被撑爆要么做成 RAG检索质量时好时坏还不好调。Agent Skills 换了个思路用 SKILL.md 加渐进式披露平时只注入 name 和 description 大约 100 tokens 的“广告位”模型判断需要时才调 load_skill 拉完整指令再按需读资源、跑脚本。这套规范不是 .NET 专属它由 Anthropic 发起Claude Code、GitHub Copilot、Cursor、Gemini CLI、JetBrains Junie 等工具都已采用。同一份 SKILL.md 能在这些工具之间复用这对写一次想多端用的团队很实在。而 .NET 侧这次 GA核心包是 Microsoft.Agents.AIMCP 技能源另需 Microsoft.Agents.AI.Mcp接入点就是 AgentSkillsProvider 和 AgentSkillsProviderBuilder。本文不重复官方博客的目录而是把落地链路走通从 TaoToken 拿统一 Key到 config.toml / settings.json 骨架再到 CC Switch、Cline 的配置片段最后验证 AgentSkillsProvider 是否真的把 SKILL.md 加载进来了附一份排错清单。适合正在做企业内部 agent、或者已经在 Semantic Kernel / Autogen 上有积累、准备迁到 MAF 的 .NET 开发者。2. TaoToken 前置统一 Key 与 API 通道怎么准备在写任何 MAF 代码之前先把模型调用通道固定下来。多工具、多项目并行时最烦的是每个工具各配一套 Key、各记一个 base_url换模型要改一堆地方。TaoToken 在这里的角色是统一入口一个 Key 走 API 通道CC Switch、Cline、以及你自己的 .NET 程序都指向同一个地址模型切换只改一处。先到官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并进入控制台在 API Keys 页面创建一个 Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Keys 管理页是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建后立刻复制页面刷新后不再完整显示。API 基地址统一用 https://taotoken.net/api 注意这个地址不带任何查询参数。OpenAI 兼容的客户端一般填到 /v1 这一层也就是 https://taotoken.net/api/v1 具体以你用的客户端要求为准。Key 的形态是 sk- 开头的一串字符别把它写进会提交到 Git 的文件里用环境变量或本地配置文件承载。注意Key 只创建一次就够多个工具共用同一个 Key。如果某个工具需要独立计量再单独建第二个 Key不要为了“隔离”去复制粘贴同一串。拿到 Key 之后建议先做一次最小连通性验证确认通道没问题再往下接 MAF。用 curl 打一次模型列表或对话接口即可export TAOTOKEN_API_KEYsk-你的Key curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ | head -c 500返回里有模型 id 列表就说明 Key 和通道都正常。这一步别跳过后面 MAF 报错时你能快速区分是通道问题还是代码问题。3. 可复制配置config.toml、settings.json 与工具片段配置分三层命令行工具层CC Switch、编辑器插件层Cline、以及 .NET 程序层。三层共用同一个 Key 和 base_url改模型时只动一处。3.1 CC Switch 的 config.toml 骨架CC Switch 用来在多个模型供应商之间切换配置文件通常放在用户目录下的 .cc-switch/config.toml。下面这份骨架可以直接改# ~/.cc-switch/config.toml default_provider taotoken [providers.taotoken] name TaoToken base_url https://taotoken.net/api api_key sk-你的Key # 需要哪个模型就填哪个切换时改这一行 model claude-sonnet-4-5如果你更习惯用环境变量而不是明文写 Key把 api_key 那行换成读取环境变量的写法或者干脆留空、由启动脚本注入 TAOTOKEN_API_KEY。明文写在本地配置文件里可以接受但别提交到仓库。3.2 Cline 的 settings.json 片段Cline 是 VS Code 里的编码 agent 插件配置在 VS Code 的 settings.json 里。它支持 OpenAI 兼容接口所以直接指向 TaoToken{ cline.apiProvider: openai, cline.openAiBaseUrl: https://taotoken.net/api/v1, cline.openAiApiKey: sk-你的Key, cline.openAiModelId: claude-sonnet-4-5, cline.customInstructions: 优先使用项目内 SKILL.md 定义的技能不要臆造命令。 }这里 base_url 填到 /v1因为 Cline 的 OpenAI 兼容实现会在后面拼 /chat/completions。填错这一层是最常见的 404 来源排错时先看这里。3.3 .NET 程序侧的配置MAF 程序里不要把 Key 硬编码。用 appsettings.json 加环境变量覆盖的方式{ TaoToken: { BaseUrl: https://taotoken.net/api/v1, ApiKey: , Model: claude-sonnet-4-5 } }ApiKey 留空运行时从环境变量 TAOTOKEN_API_KEY 读。这样本地开发和 CI 用同一份配置只是环境变量不同。4. 接入 MAFAgentSkillsProvider 加载 SKILL.md 的完整动作配置就绪后进入 .NET 侧。先建项目并装包dotnet new console -n SkillDemo cd SkillDemo dotnet add package Microsoft.Agents.AI dotnet add package Microsoft.Agents.AI.Mcp4.1 准备一个最小 SKILL.md在项目输出目录下建 skills/expense-report/SKILL.md注意 name 必须和父目录名一致全小写加连字符--- 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 metadata: author: contoso-finance version: 2.1 --- # Expense Report Skill 当用户询问报销规则或提交报销时按以下步骤执行 1. 读取 references/policy.md 确认当前限额。 2. 校验金额是否超过单笔上限。 3. 调用 scripts/validate.py 做格式检查。 4. 输出结论附上引用的政策条款编号。frontmatter 之后是正文指令建议不超过 500 行长材料拆到 references/ 里。description 要写清“做什么”和“何时用”因为模型就是靠它判断要不要加载这个技能。4.2 用 AgentSkillsProvider 接进代理最小用法一个路径就够脚本执行需要传一个 runnerusing Microsoft.Agents.AI; using Microsoft.Extensions.AI; using System.ClientModel; var baseUrl Environment.GetEnvironmentVariable(TAOTOKEN_BASE_URL) ?? https://taotoken.net/api/v1; var apiKey Environment.GetEnvironmentVariable(TAOTOKEN_API_KEY) ?? throw new InvalidOperationException(TAOTOKEN_API_KEY 未设置); var skillsProvider new AgentSkillsProvider( Path.Combine(AppContext.BaseDirectory, skills), SubprocessScriptRunner.RunAsync); var client new OpenAIClient( new ApiKeyCredential(apiKey), new OpenAIClientOptions { Endpoint new Uri(baseUrl) }); AIAgent agent client .GetResponsesClient() .AsAIAgent(new ChatClientAgentOptions { Name ExpenseAgent, ChatOptions new() { Instructions You are a helpful assistant. }, AIContextProviders [skillsProvider], }, model: claude-sonnet-4-5); var response await agent.RunAsync(帮我看看 800 元的差旅报销能不能过。); Console.WriteLine(response);如果你要同时挂多个技能源用 AgentSkillsProviderBuilder 链式组合它会自动加聚合、去重、缓存var skillsProvider new AgentSkillsProviderBuilder() .UseFileSkill(Path.Combine(AppContext.BaseDirectory, skills)) .UseSkill(volumeConverterSkill) // AgentInlineSkill .UseSkill(temperatureConverter) // AgentClassSkill .UseFileScriptRunner(SubprocessScriptRunner.RunAsync) .Build();4.3 生产治理的两个开关GA 的重点是生产可用默认三个工具 load_skill、read_skill_resource、run_skill_script 全部需要审批。想对只读操作放宽用 UseToolApproval 中间件var agent client .GetResponsesClient() .AsAIAgent(new ChatClientAgentOptions { Name SkillsAgent, ChatOptions new() { Instructions You are a helpful assistant. }, AIContextProviders [skillsProvider], }, model: claude-sonnet-4-5) .AsBuilder() .UseToolApproval(new ToolApprovalAgentOptions { AutoApprovalRules [AgentSkillsProvider.ReadOnlyToolsAutoApprovalRule], }) .Build();ReadOnlyToolsAutoApprovalRule 自动放行 load 和 read脚本执行仍要人工确认。脚本执行是重点风险文件型脚本走子进程官方明确说 SubprocessScriptRunner 仅供演示生产要自己加容器沙箱、资源限制和审计日志。5. 验证请求与成功结果确认 SKILL.md 真的被加载代码跑起来不等于技能被加载。验证分三步从外到内。第一步确认通道通。用第 2 节的 curl 打一次 /v1/models有返回说明 Key 和 base_url 没问题。第二步确认技能被发现。在程序里加一行诊断把 provider 解析出的技能列表打出来var skills await skillsProvider.GetSkillsAsync( new AgentSkillsSourceContext(agent, session)); foreach (var s in skills) { Console.WriteLine($loaded skill: {s.Frontmatter.Name} - {s.Frontmatter.Description}); }如果这里输出为空说明路径不对或 SKILL.md 的 frontmatter 不合法先查这两处。第三步确认模型真的调了 load_skill。跑一个明确命中 description 的问题比如“800 元差旅报销能不能过”观察日志里是否出现 load_skill 工具调用。成功时你会看到模型先请求 load_skill拿到完整指令后读 references/policy.md最后给出带政策条款编号的结论。如果模型直接凭常识回答、没调工具多半是 description 写得不够具体模型没把它和问题关联上。一个可复现的成功输出长这样[skill] advertise: expense-report (约 100 tokens) [tool] load_skill(nameexpense-report) - 已加载完整指令 [tool] read_skill_resource(pathreferences/policy.md) - 已读取 [answer] 单笔差旅上限 500 元800 元超出需附审批单。依据 policy.md 第 3.2 条。看到这条链路完整走通才算真正接上了。6. 本篇常见错排查清单404 或 model not foundbase_url 层级填错。Cline 和 OpenAI 兼容客户端要填到 /v1MAF 里用 OpenAIClient 时 Endpoint 也指向 /v1。填成 https://taotoken.net/api 会 404。401 未授权Key 没读到或带了多余空格。检查环境变量名是否和代码里一致Key 复制时有没有把换行带进去。技能列表为空三种可能。路径指向了源码目录而不是输出目录用 AppContext.BaseDirectory 拼SKILL.md 的 name 和父目录名不一致frontmatter 的 YAML 缩进错了metadata 下的字段要用空格缩进不能用 Tab。模型不调 load_skilldescription 太泛。把“做什么”和“何时用”都写进去比如明确写“Use when asked about expense submissions, reimbursement rules, or spending limits”命中率会明显提升。脚本执行被拦默认三个工具都要审批这是设计如此。要么在交互里确认要么用 ReadOnlyToolsAutoApprovalRule 放行只读操作脚本执行保持人工确认。改了 SKILL.md 不生效Builder 默认包了 CachingAgentSkillsSource技能列表解析一次后复用。开发期加 DisableCaching() 让改动即时生效生产环境用 RefreshInterval 控制刷新。多租户串技能一个 provider 服务多个租户时用 CacheIsolationKeySelector 按租户 ID 隔离缓存再用 FilteringAgentSkillsSource 或 UseFilter 按上下文决定暴露哪些技能。排错时优先看通道curl 能不能通、再看路径技能列表打不打得出来、最后看模型行为有没有调工具。这三层分开定位比一股脑改代码快得多。如果你在接入过程中卡在 Key 或通道配置直接去 API Keys 页面重新确认一遍https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入细节看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。想先验证模型对话是否正常用模型对话页 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 快速试一次。长期做编码 agent、需要稳定额度的看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。
