.NET + AI 进阶实战：基于类的技能开发 - 打造可治理的 Agent 能力模块

导语：如果说 Inline Skill 解决了"能不能用"，File-based Skill 解决了"能不能沉淀"，那么今天要聊的 Class-based Skill，解决的就是 "能不能在工程中长期治理" 的问题。它不是另一种炫技的写法，而是面向生产环境、面向复杂业务系统的一套类型驱动的解决方案。

一、回顾：从"接入"到"资产"的演进

我们梳理了 Agent Skill 的两种主要形态：

Inline Skill ：直接在对话上下文中拼凑 Prompt 和代码。定位：先把能力接进来。
File-based Skill ：将 Skill 标准化为目录文件（SKILL.md + 资源）。定位：把能力沉淀为可分发、可复用的资产。

File-based Skill 已经很优雅了，它让 Skill 变成了独立的文件包。但当我们把视角从"个人开发者"切换到"大型业务系统团队"时，新的诉求出现了：

这个物流换算的 Skill 马上要接入订单中心了，能不能写单元测试？
业务规则变了，我要改系数，能不能让 IDE 帮我检查所有引用点？
这个 Skill 需要调用内部 API 和日志组件，怎么优雅地注入 HttpClient 和 ILogger？

这时候，Class-based Skill 登场了。它的载体不再是目录里的 Markdown 文件，而是一个 强类型的 C# 类。

二、初见：把 Skill 写成一个 C# 类是什么体验？

在 Microsoft.Extensions.AI 体系中，AgentClassSkill<T> 提供了一种新的声明方式。我们来看一个物流单位换算的完整示例：

csharp 复制代码

```csharp
#pragma warning disable MAAI001
using System.ComponentModel;
using System.Text.Json;

internal sealed class UnitConverterClassSkill : AgentClassSkill<UnitConverterClassSkill>
{
    // 1. 元数据：清晰、编译期可校验
    public override AgentSkillFrontmatter Frontmatter { get; } = new(
        "unit-converter",
        "Convert between common logistics units.");

    // 2. 指令：与逻辑代码同文件，维护成本低
    protected override string Instructions => """
        当用户询问距离或重量换算时：
        1. 先读取 conversion-table
        2. 再调用 convert
        3. 回复中包含原始值、系数和结果
        """;

    // 3. 资源：通过 Attribute 标记，强类型字符串
    [AgentSkillResource("conversion-table")]
    [Description("距离与重量换算系数表")]
    public string ConversionTable => """
        miles -> kilometers = 1.60934
        kilograms -> pounds = 2.20462
        """;

    // 4. 脚本/动作：纯 C# 方法，享受重构和测试便利
    [AgentSkillScript("convert")]
    [Description("按 value × factor 执行换算")]
    private static string Convert(double value, double factor)
    {
        return JsonSerializer.Serialize(new
        {
            value,
            factor,
            result = Math.Round(value * factor, 4)
        });
    }
}

这种写法的本质变化是什么？

边界收敛：将Frontmatter（描述信息）、Instructions（指令集）、Resource（资源）和Script（动作脚本）全部封装在一个类中，实现功能聚合。

类型安全：采用double类型作为方法参数，避免AI猜测字符串含义。当参数类型不匹配时，编译器会立即报错，确保类型安全性。

三、原理拆解：它是如何跑进 Agent 大脑的？

虽然它采用类形式封装，但底层实现依然基于 Agent Context 的挂载机制。框架会通过 Attribute 扫描自动识别类成员，并将其转换为模型可识别的 Function Calling Schema 和 Resource 上下文。

集成过程非常简单，只需将其作为 AIContextProvider 挂载：

csharp 复制代码

var classSkill = new UnitConverterClassSkill();
var provider = new AgentSkillsProvider(classSkill);

var agentOptions = new ChatClientAgentOptions
{
    Name = "LogisticsAgent",
    AIContextProviders = [provider]
};

这种设计保持了协议的一致性：Class-based Skill 并非创建新协议，而是通过工程化手段自动生成标准协议。模型接收到的仍然是标准 Tool 描述，而开发者维护的则是可调试、可重构的 C# 代码文件。

四、为什么它更适合工程化？

这正是 Class-based Skill 的核心价值所在。当 Skill 采用标准 C# 类实现时，开发者将自动获得诸多 File-based 方案难以提供的优势：

✅ 编译时类型检查

✅ IDE 智能重构

✅ 便捷的单元测试

✅ 无缝的依赖注入

✅ 轻松集成日志、安全等治理组件

换言之，Class-based Skill 的真正优势不在于"分发"，而在于"治理"。它特别适合那些已趋于稳定，但需要长期维护和持续演进的核心业务能力。

从定位角度区分：

File-based Skill 侧重能力的外部化共享

Class-based Skill 强调系统的内部治理

前者注重可移植性，后者专注可维护性。

五、结语

从 Inline 到 File-based 架构，我们实现了 Skill 的结构化与资产化管理；

从 File-based 到 Class-based 架构，我们进一步解决了 Skill 的工程化与治理问题。

AgentClassSkill 的推出，展现了 .NET 社区在 AI 应用开发领域的务实创新：不仅要让 AI 生成代码，更要确保 AI 调用的代码具备健壮性、可维护性和可扩展性。

当您的 Skill 趋于稳定并准备作为核心功能长期使用时，建议将其重构为 Class-based Skill。届时您会发现，它已不再是简单的 Prompt 文件，而是业务系统中一个可靠的核心模块，真正成为系统的"一等公民"。

.NET + AI 进阶实战：基于类的技能开发 - 打造可治理的 Agent 能力模块