很多人一提到 Agent，第一反应就是：

• LangChain
• LangGraph
• 多工具编排
• 工作流
• 复杂状态机

但如果只是想真正理解：

Agent Skills 到底是什么？

其实不需要一上来就上复杂框架。
我最近专门写了一套最小可运行版 Agent Skills Demo，只做一件事：

让 Agent 调用一个“查询天气”的 skill

而且这个项目故意做得非常克制：

• 不接真实天气 API
• 不用任何 Agent 框架
• 天气数据直接写死在 markdown 文件里
• 只保留 Agent Skills 最核心的执行逻辑

这套代码本质上就是一个最小版技能调用系统。
项目里只有：

• SKILL.md
• weather.md
• app.py

其中 SKILL.md 定义 skill 的用途、触发条件、输入输出和约束，weather.md 存放实际天气内容，主程序负责让模型先决定要不要调用 skill，再去执行。

---

Agent Skills 的核心原理，到底是什么？🧠

我觉得可以用一句话概括：

模型做决策，Skill 做执行，外部文件做知识承载

很多人会把 Agent 理解成“工具调用系统”，这没错。
但如果再往下拆，Agent Skills 的最小本质其实就是三层：

1. Skill 描述层

告诉模型：

• 这个 skill 叫什么
• 它是干什么的
• 什么时候应该使用
• 需要什么输入
• 输出时要遵守什么约束

在我的这个项目里，这部分就是 SKILL.md。
比如这里定义了 skill 名字叫 weather-query，并明确规定：当用户询问某个城市天气、温度、是否下雨、是否适合出行时使用这个 skill，而且只能基于本地 weather.md 回答，不能联网，也不能编造。

---

2. Skill 数据层

这层负责存真正要被 skill 使用的数据。

在这个 demo 里，就是 weather.md。
里面写死了几个城市的天气内容，比如：

• 西安
• 北京
• 上海
• 广州

也就是说，这里没有真实天气查询接口，只有一个本地 markdown 文件作为数据源。

---

3. Skill 执行层

这一层是主程序，也就是 app.py。
它的职责不是“自己回答问题”，而是：

• 先判断用户是不是在问天气
• 如果是，决定要不要调用 weather-query
• 调用后再提取参数，比如城市名
• 最后读取 weather.md 返回结果

也就是说，这个项目不是“直接让大模型读所有内容然后回答”，而是让模型只做决策和提参，真正的内容返回还是由 skill 执行逻辑完成。

---

这套代码最核心的点：渐进式披露 🚨

我觉得这也是 Agent Skills 很值得讲的一点。

很多人现在做 Agent，喜欢把：

• 所有技能说明
• 所有工具描述
• 所有数据
• 所有规则

一次性全塞进 prompt。

这样当然也能跑，但问题很明显：

• token 浪费
• 规则互相打架
• 模型注意力分散
• 所有信息一次性暴露，不够可控
• skill 一多就会迅速膨胀

所以这个项目专门演示了一种更合理的方式：

渐进式披露

什么意思？

就是：

第一步：先只暴露 skill 摘要

主程序启动时，先读取 SKILL.md 里的 name 和 description。
这一步不会把完整 skill 说明和天气数据全给模型，只给最少信息，让模型做第一轮判断。代码里 _load_skill() 会从 SKILL.md 的 front matter 里解析出这两个字段。

---

第二步：如果命中 skill，再加载完整 SKILL.md

如果模型判断用户确实是在问天气，就会进入第二阶段。
这时程序会把完整 SKILL.md 提供给模型，让它在技能规则约束下提取参数，比如 city。代码里这一步对应 _plan()，注释里写得很清楚：命中后再读取完整 SKILL.md 做参数提取。

这一步特别关键，因为这时候模型看到的已经不是简单摘要了，而是完整技能说明，包括：

• Purpose
• When to use
• Inputs
• Data source
• Output requirements
• Constraints

这样提参会更稳，也更符合 skill 定义。

---

第三步：最后再读取 weather.md

只有当城市参数提取成功之后，程序才会真正去读 weather.md，然后通过标题匹配找到对应城市的小节，把那段天气文本返回出来。代码里 _weather() 使用正则去匹配 ## 城市名 对应的 section。

所以这一整套逻辑不是“一次性全给模型”，而是：

先给摘要 → 再给完整技能说明 → 最后再给资源文件

这就是一个非常典型的渐进式披露思路。
README 里其实也把这三阶段写得很清楚：先技能摘要路由，命中后再加载完整技能说明做参数提取，最后读取资源文件执行返回。

---

代码内部到底是怎么处理的？⚙️

我把这份最小项目拆成 4 个关键步骤来理解。

---

① 启动时先加载 skill

主程序初始化 WeatherAgent 的时候，会先做几件事：

• 读取 .env
• 初始化 OpenAI 兼容客户端
• 定位 skill 目录
• 读取 SKILL.md
• 解析 skill 的 name 和 description

这一点其实就已经说明了：
skill 不是写死在 prompt 里的，而是一个外部可加载的能力包。模型配置也是从 .env 里读取的，README 里给了 .env 的配置方式。

---

② 第一阶段：路由

当用户输入一句话后，程序先调用 _route()。
这里不会直接上完整 skill，也不会读天气数据，而是只把：

• skill 的 name
• skill 的 description

发给模型，让模型判断：

• 这句话是不是该走 weather-query
• 要不要用这个 skill

这一步对应的是最轻量的 skill 发现机制。

---

③ 第二阶段：参数提取

如果第一阶段命中了 weather-query，程序再调用 _plan()。
这一步会把完整 SKILL.md 和用户原始输入一起发给模型，要求它只输出 JSON，并提取 city。如果用户没有明确给城市，就返回“请告诉我你想查询哪个城市的天气”。这个要求在代码和 SKILL.md 里都写得很明确。

---

④ 第三阶段：执行 skill

当城市参数有了之后，程序才真正执行 skill，也就是去读取 weather.md，根据标题匹配找到对应 section，然后返回天气文本。
比如用户问“西安今天天气怎么样”，程序最终命中的其实是：

## 西安
今天天气晴，温度 28°C，微风，适合出行。

这一步完全是本地文件查找，不联网，不调用外部天气接口。

---

为什么我觉得这种写法很适合入门理解 Agent Skills？📌

因为它把很多复杂框架里的东西，压缩成了最小核心流程：

不是先讲工作流

而是先讲：

• skill 是什么
• skill 为什么要有说明文件
• skill 为什么要有数据文件
• skill 为什么不能一次性把所有东西都扔给模型

不是先讲多工具编排

而是先讲：

• 模型负责路由
• 模型负责提参
• skill 自己执行
• 数据由外部文件承载

我觉得这对于理解 Agent Skills 非常重要。
因为很多人一开始就把 Agent 当成“复杂工作流系统”，最后其实没看清最小本质。

---

这套最小项目的意义是什么？💡

我觉得它不是为了做一个真正可上线的天气系统。
它更像是一个教学级别的 Agent Skills 骨架。

通过这套代码，你可以很清楚地看到：

• Skill 怎么定义
• 模型怎么知道什么时候该用这个 skill
• 参数怎么在技能说明约束下提取
• 数据怎么从资源文件里读取
• 渐进式披露到底是怎么落到代码里的

而且这套项目依赖非常少，只需要：

• openai
• python-dotenv

requirements.txt 里也就这两个依赖。

---

最后总结一句

如果让我用一句话总结这套最小版 Agent Skills 项目，我会这么说：

它不是在演示复杂框架，而是在演示 Agent Skills 最核心的结构：技能描述、渐进式披露、参数提取、资源执行。

很多人做 Agent，最先学的是流程编排。
但我越来越觉得，真正值得先搞明白的，是：

一个 skill 到底应该怎么被定义、怎么被发现、怎么被调用、怎么被执行。

这才是后面所有复杂系统的基础。

---

结尾引流文案

如果大家想要我这套完整的最小版 Agent Skills 项目文档，
包括：

• 完整代码
• 目录结构
• 配置说明
• 如何填写 .env
• 如何安装依赖
• 怎么一步一步跑通项目

可以直接私信我。

我会把完整文档发给你，
也会告诉你怎么配置环境，怎么把项目完整跑通。

---

可选标题

你可以挑一个发：

标题1

用一个天气技能，讲清楚Agent Skills原理

标题2

我用最小代码，拆清楚了Agent Skills

标题3

Agent Skills 到底是什么？这版代码讲透了

标题4

别一上来就 LangGraph，先搞懂 Agent Skills

标题5

一个最小项目，讲清 Agent Skills 和渐进式披露

---

如果大家想看我继续往下拆，
我后面也可以继续把这套项目从：

• 最小版天气 skill
• 扩展到多 skill
• 再扩展到企业级 Agent 技能体系

想要这套完整文档 + 跑通说明的朋友，
直接私信我就行。
我会把完整资料发给你，也会告诉你怎么配置和跑通。