以下内容选自我精心打造的《.NET+AI | 智能体开发进阶》课程，如需系统学习，不妨阅读原文了解详情。

上一篇我们聊了 Inline Skill。

它最大的优点是轻：写得快、调得快、验证也快，非常适合作为 Agent Skills 的第一站。

但问题也很明显：一旦 Skill 不再只是临时能力，而是需要长期维护、共享复用，甚至交给不同角色协作，Inline Skill 就开始不够用了。

这时候，File-based Skill 的价值就出来了。

它解决的核心问题，不是“怎么写一个 Skill”，而是“怎么把 Skill 做成一个可以沉淀、共享、分发的能力资产”。

一、为什么 Skill 要从代码里走向文件结构？

Inline Skill 更像“当前代码里的能力”。

它适合快速试验，但不适合长期沉淀。因为一旦 Skill 越来越多，说明、资源、动作都混在代码上下文里，维护成本会迅速上升。

而 File-based Skill 的思路是：把 Skill 从代码片段，提升为一个有组织的文件单元。

这样做最大的意义，不是拆文件本身，而是让 Skill 开始具备资产属性：

• • 可以单独维护
• • 可以跨项目复用
• • 可以被打包和分发
• • 可以让非开发人员也参与部分内容维护

所以，如果说 Inline Skill 解决的是“先把能力接进来”，那么 File-based Skill 解决的就是“怎么把能力沉淀下来”。

二、File-based Skill 的核心，其实是分层

一个 File-based Skill，通常至少会包含三类内容：

• • SKILL.md：描述 Skill 是什么、怎么用
• • 资源文件：提供知识、规则、背景信息
• • 脚本文件：提供可执行动作

比如一个物流报价 Skill，目录就可以直接长这样：

shipping-rate-skill/
├── SKILL.md
├── resources/
│   └── rate-table.md
└── scripts/
    └── quote-rate.csx

其中 SKILL.md 可以负责声明这个 Skill 的身份和使用方式：

---
name: shipping-rate
summary: Quote shipping cost by destination and weight.
---

当用户询问运费时：
1. 先读取 rate-table 资源
2. 再调用 quote-rate 脚本
3. 回复中包含目的地、重量、费率和总价

而 scripts/quote-rate.csx 则专注动作本身：

var destination = Args["destination"].GetString();
var weight = Args["weightKg"].GetDouble();
var rate = destination == "US" ? 8.5 : 10.0;

return new
{
    destination,
    weightKg = weight,
    rate,
    total = Math.Round(weight * rate, 2)
};

这类结构的价值，在于一眼就能看出：说明在哪里、知识在哪里、动作在哪里。

SKILL.md 负责“身份和说明”，资源文件负责“知识”，脚本文件负责“动作”。

这意味着，File-based Skill 本质上不是“把代码拆成几个文件”，而是在做一件更重要的事：把说明、知识、动作分层管理。

一旦完成这一步，Skill 就不再只是一个零散能力，而开始变成一个结构化单元。

三、为什么它特别适合共享和分发？

这正是 File-based Skill 最有价值的地方。

因为它是文件化的，所以天然比 Inline Skill 更容易搬运。你可以把一个 Skill 目录交给另一个项目，也可以把它放进仓库、模板或团队共享目录里复用。

更重要的是，它让 Skill 的维护不再只属于开发者。

比如：

• • 产品同学可以参与 SKILL.md 的说明完善
• • 运营同学可以维护部分资源内容
• • 开发同学只需要聚焦脚本逻辑和装载机制

这就让 File-based Skill 天然更适合团队协作。

从这个角度看，File-based Skill 的核心优势并不只是技术上的，而是协作上的。

它让 Skill 从“写给当前程序看的代码”，变成“团队可以共同维护的能力资产”。

四、它是怎么进入 Agent 运行链路的？

虽然叫 File-based，但它并不是让模型直接去读某个目录。

它的本质仍然是：先把文件结构解析成 Skill，再通过 Provider 装配到 Agent 的上下文链路里。

例如：

var provider = new AgentSkillsProvider("./skills/shipping-rate-skill");

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

也就是说，模型真正消费的，不是磁盘上的文件本身，而是这些文件被组织后形成的 Skill 语义。

你可以把这个过程理解成：

文件结构负责定义 Skill，Provider 负责把 Skill 接进 Agent。

所以从运行机制上看，File-based Skill 和其他 Skill 写法并不是割裂的；真正不同的，是它对能力的组织方式。

五、它和 Inline Skill 的本质差异是什么？

一句话概括：

Inline Skill 偏“快速接入”，File-based Skill 偏“能力沉淀”。

前者适合先验证一个能力能不能跑通，后者适合把已经验证过的能力做成可以共享、可以复用、可以持续演进的资产。

所以它们不是谁替代谁，而是分别对应两个不同阶段：

• • Inline：先跑通
• • File-based：再沉淀

当你开始关心“这个 Skill 要不要长期存在”，File-based 就会比 Inline 更合适。

六、总结

File-based Skill 最重要的价值，不是把 Skill 拆成若干文件，而是把 Skill 从临时代码提升为可组织、可共享、可分发的能力资产。

它补上的，是 Agent Skills 从“能用”走向“可沉淀”的这一层。

下一篇，我们继续聊 Class-based Skill：为什么当一个 Skill 不只是要共享，还要进入系统内部治理时，强类型结构就开始变得重要。