Agent Skills实战：从知识到能力的智能体技能化改造

最近在做agent-skills这个项目的时候，我一直被一个问题困扰：为什么同一个大模型，在聊天场景下回答得头头是道，一旦让它去实际操作软件、调用接口、处理文件，就各种失灵？后来我意识到，问题不在模型本身，而在于我们只给了模型“知识”，却没给它“技能”。agent-skills要解决的，正是这件事——把一项项具体操作封装成 Agent 可以理解和调用的技能单元，然后像工具箱一样挂在智能体身上。这篇文章不聊虚的，就讲清楚这个项目里技能设计、路由、构建、集成和踩坑的完整链路，适合那些已经在做 Agent 应用、但觉得现有框架“不够顺手”的人参考。

1. 为什么需要 Agent Skills：从“知识”到“能力”的断层

1.1 模型最缺的不是逻辑，是可执行动作

很多团队在落地智能体时会发现，让模型写一段 SQL 很容易，但让它自动连上数据库、执行查询、把结果整理成报表，就很别扭。原因在于，大模型本质上是一个“文本预测器”，它擅长生成看起来合理的文本，但真正要操作外部系统，需要精确的 API 参数、认证方式、异常处理。这些东西没法靠提示词凭空生成，只能通过预先定义好的技能注入。

我最早做 Agent 时也走过弯路，把大量操作逻辑塞进 system prompt，让模型“自己看着办”。结果是：简单任务还能应付，一旦任务链超过两步，模型就开始自创函数名、编造参数。后来我把这些操作全部拆成agent-skills里的技能模块，每个模块都有明确的输入输出和运行环境，模型的任务从“实现操作”降级成“选择并调用操作”，成功率一下子拉起来了。

1.2 技能不是 Prompt 模板，而是可执行行为单元

很多人会把技能理解成一套话术模板，比如“当用户说订机票时，请调用订票API”。这是很大的误解。Prompt 模板解决的是“怎么说话”，技能解决的是“怎么做事”。一个合格的 Agent 技能，至少包含三部分：自然语言描述、执行代码、参数约束。描述让模型知道这个技能管什么，代码让技能真正落地，参数约束则保证模型不会把异常输入传进来。

打个不严谨的比方：模型就像一个实习生，Prompt 是岗位说明书，技能则是他手里的一套标准化作业清单。没有清单，实习生只能凭感觉发挥；有了清单，他即使遇到没见过的情况，也能按步骤走完大部分流程。agent-skills的核心工作，就是替 Agent 把这些清单编好、编细、编到可以直接执行。

1.3 从单体 Agent 到技能复用：能力的“搭积木”思维

另一个推动我搞agent-skills的现实问题是复用性。之前我给 A 客户做了“网页内容抓取”的功能，给 B 客户做“PDF 信息提取”，代码逻辑高度重复，但因为耦合在各自的业务流里，完全没办法直接搬过去用。技能化之后，抓网页、读 PDF、查数据库这些动作都成了独立技能，新的 Agent 只要声明“我需要哪些技能”，就能像搭积木一样组合出新的能力。这也是为什么现在各大 Agent 框架都在推 Skills 概念的原因——它不是花架子，而是规模化做 Agent 应用的必经之路。

2. agent-skills 项目核心设计：技能如何被表达和路由

2.1 技能描述 Schema：给模型看的“使用说明书”

要让 Agent 正确选技能，必须用模型容易理解的语言写技能元信息。我在agent-skills里做了这样的 Schema：

{ "skill_name": "fetch_web_page", "description": "抓取指定URL的网页内容并提取正文文本。适用于读取公开网页、文章、新闻页面。", "input_schema": { "type": "object", "properties": { "url": { "type": "string", "description": "需要抓取的完整网页地址，必须包含协议头，如 https://example.com/article" }, "max_chars": { "type": "integer", "description": "返回正文的最大字符数，默认10000，避免内容过长", "default": 10000 } }, "required": ["url"] }, "executor": "python", "timeout_seconds": 30, "allowed_environments": ["sandbox", "local"] }

这里最关键的是description字段。它不写“可以抓网页”这种笼统话，而是写清楚适用场景、边界条件、常见坑。比如我会补一句“如果页面是 JS 动态渲染的，此技能可能返回空，请使用 fetch_web_page_rendered 技能”，这样模型在选技能时能少犯错。input_schema是给模型看的参数规范，也是给执行器的数据契约，两者必须完全对应。

2.2 发现与匹配：让 Agent 知道“我有哪些工具可用”

技能多了之后，最大的问题不是写技能，而是做路由。如果一次对话把 50 个技能全部塞进上下文，模型的注意力会被稀释，反而不知道该用哪个。我在项目里做了两层处理。

第一层是技能索引。每个技能注册时，会根据description生成向量索引，当任务进来时，先用 embedding 检索 Top 5 候选技能，只把这 5 个候选的技能描述放入模型上下文。这一步能大幅压减 token 占用，同时提升选择准确率。第二层是模型决策。系统会把候选技能描述和当前任务一起交给大模型，让它用 JSON 格式输出“打算调用的技能名 + 参数”。如果模型认为所有技能都不合适，它可以输出空，我不强制它硬调。

实测下来，这种“先检索，后决策”的路由方式，比把全部技能堆给模型要稳定得多。

2.3 执行器设计：为什么用 Python 而不是 JSON

有的 Agent 框架把技能定义成纯 JSON 配置，执行时让模型自己生成代码。我试过这种方案，效果很不稳定。模型生成的代码经常少 import、漏异常处理，甚至写出不存在的方法。agent-skills的执行器方案是：每个技能对应一个 Python 函数，函数内部逻辑由人写死，模型只负责填参数。这样就把“模型自由的创造力”限制在安全范围内，执行逻辑保持确定性。

下面是我项目里的技能函数示例：

# skills/web_fetch.py import requests from bs4 import BeautifulSoup def fetch_web_page(url: str, max_chars: int = 10000) -> str: headers = {"User-Agent": "Mozilla/5.0"} try: resp = requests.get(url, headers=headers, timeout=15) resp.raise_for_status() except Exception as e: return f"抓取失败: {str(e)}" soup = BeautifulSoup(resp.text, "html.parser") for tag in soup(["script", "style", "nav", "footer"]): tag.decompose() text = soup.get_text(separator="\n", strip=True) if len(text) > max_chars: text = text[:max_chars] + "..." return text

模型的职责就是判断“用户想做的是不是抓网页”，然后把符合规范的url传进来。至于页面能不能抓到、要不要处理反爬，那是函数内部的事，模型不需要也不应该操心。

3. 从零构建技能库的实操步骤

3.1 拆解业务动作：技能的粒度怎么定

建技能库最容易踩的坑是“粒度过粗”或“粒度过细”。粒度过粗，比如“处理所有文件操作”，模型根本不知道该怎么传参；粒度过细，比如“读取 txt 文件第一行”“读取 txt 文件第二行”，技能数量爆炸，检索成本上升，模型也容易选错。

我在项目中总结的判断标准是：一个技能应该对应一个完整的用户意图。比如“读取 pdf 内容”“将文本写入 txt 文件”“对列表去重”都是合理粒度；而“字符串转大写”“字符串转小写”这种原子操作，除非是给开发人员专用 Agent 用，否则没有必要单独做技能。因为它们太底层，模型完全可以自己在代码里完成，用技能反而浪费上下文。

3.2 编写技能清单、参数约束与验证逻辑

每个技能模块我固定分为四个文件，放在同一目录下：

• skill.md：写给人看的设计文档，说明技能背景、适用场景、不适用场景。
• schema.json：机器可读的技能描述，也就是上面那个 Schema。
• execute.py：实际的 Python 实现。
• tests.py：验证脚本，包含至少 5 个典型输入用例和 2 个边界用例。

参数约束里最容易忽略的是description内的约束说明。比如一个“发送邮件”技能，收件人字段必须说明格式，是支持逗号分隔还是必须传数组。如果不说清楚，模型就会用自己的理解猜，猜错的概率很高。我在 schema 里会写类似“recipients: 必填，数组格式，每一项是一个完整邮箱地址”这种话。

3.3 注册进项目并跑通端到端调用

写完技能函数后，不是放进去就完了。我在agent-skills里做了一个注册机制，启动时会扫描skills目录下的所有子文件夹，读取schema.json，将其注册进技能路由表。伪代码如下：

# registry.py import importlib, json, pathlib def discover_skills(skills_dir="skills"): registry = {} for path in pathlib.Path(skills_dir).iterdir(): if not path.is_dir(): continue schema_path = path / "schema.json" if not schema_path.exists(): continue schema = json.loads(schema_path.read_text()) module = importlib.import_module(f"{skills_dir}.{path.name}.execute") registry[schema["skill_name"]] = { "schema": schema, "func": module } return registry

注册之后，我会先用一段固定测试文本跑通整体链路：输入一个模拟任务，比如“请抓取 https://example.com 的正文内容”，看 Agent 能否检索到fetch_web_page、给出正确参数、执行并返回结果。这一步通过后，才算真正的“技能可用”。

3.4 给技能做一个“考官”：自动化回归测试

技能库会随着业务增长不断新增，老技能很可能被新技能影响。比如两个技能都支持“获取网页内容”，但描述类似，模型可能路由错。所以我在项目里加入了一个“考官”脚本：对每个技能预置若干条用户话术，每次技能库更新后，自动跑一遍全量话术，检查模型的技能选择准确率，低于 90% 就报警。

测试用例不只是正向的，还必须包含“不该调用”的用例。比如用户问“今天天气怎么样”，技能库里有“按城市查询天气”，但没有输入城市，模型应该追问而不是乱传一个城市参数。这类“负样本”特别重要，能有效防止模型乱用技能。

4. 集成到主流 Agent 运行时：接口、上下文与权限控制

4.1 技能与模型上下文的预算博弈

集成到 Agent 运行时时，最现实的问题是“塞不下”。一个技能描述平均 200 到 300 token，如果一次让模型看到 10 个技能，就是 3000 token，再加上对话历史和工具返回结果，很容易把 8K 上下文窗口撑爆。我用两个办法缓解：一是技能检索后只保留 Top 3 候选，缩小上下文；二是把技能描述压缩成“一句话摘要 + 可展开详情”的形式，模型需要深入了解时再通过“查看技能详情”动作获取完整信息。

这套机制有点像一个搜索引擎：摘要页放最核心的信息，用户感兴趣了再点进详情页。目前我用普通 32K 窗口的模型跑agent-skills，日常能稳定控制在 12K token 以内。

4.2 权限白名单与危险操作熔断

技能一旦能执行真实操作，权限就必须认真对待。我在agent-skills里给每个技能打了一个权限标签，比如“无副作用”“只读操作”“可写操作”“高风险操作”。执行前，Agent 编排层会检查当前环境是否允许该权限。规则如下：

比如用户在端侧配置了“禁止所有 L2 及以上操作”，那么即便是 Agent 完成了邮件内容撰写，发送动作也会被熔断，返回给用户一条提示信息，等用户手动确认后再执行。这个设计虽然看起来简单，但真的能拦住很多事故。

4.3 从单 Agent 到多 Agent 技能复用

技能化的另一个好处是天然支持多 Agent 协作。agent-skills里技能是全局注册的，任何子 Agent 都能按需加载。我给一个客服场景搭了三个子 Agent：一个负责查订单，一个负责生成回复，一个负责执行拦截操作。它们共享同一套技能库，但每个子 Agent 只加载自己需要的技能描述。这样既避免了重复开发，又防止了权限越界。

这里要特别提醒：多 Agent 场景下，技能调用最好加上“调用来源”字段，方便追踪是哪个 Agent 触发了该技能。在日志里打上 agent_id，排查问题的时候能省下一半时间。

5. 我在 agent-skills 项目上踩过的坑与优化细节

5.1 技能描述太长，模型反而不敢用

第一次写技能描述时时追求“详尽”，把各种边界条件全写进去，一段描述 800 字。结果模型在决策时经常犹豫，甚至直接回复“无法确认调用哪个技能”。后来我把描述精炼成“功能一句话 + 常用场景 + 禁忌”，长度控制在 150 字以内，路由准确率显著回升。说明模型不是读得越多越好，核心信息要放在最前面。

比如同样是“发送企业微信消息”技能，我最终定稿的描述是：

发送普通文本消息到指定的企业微信群。适用于向群内推送通知、告警、日报。不要在用户未授权的情况下群发；如果消息需要 @所有人，请先与用户确认。

简短、直白，模型一眼就知道该不该用。

5.2 并发调用时共享状态的坑

我一开始用模块级全局变量保存技能执行状态，比如“当前用户的上一次搜索结果”。后来多个请求并发进来，状态互相覆盖，出现了严重的串数据问题。修复方案是：所有技能执行器改为无状态纯函数，需要暂存数据时显式传入context对象，请求结束后释放。

如果确实需要跨技能传递数据，比如先查订单再发通知，那么把临时结果放到context.setdefault("order_no", ...)里，而不是写进全局变量。这一点在异步高并发场景尤其重要，我因为这个 bug 还被测试同事追着改了两版。

5.3 让模型学会“拒绝调用”而不是强行使用

很多 Agent 框架默认“模型选了技能就必须执行”，这会让模型为了避免失败而瞎选。我在agent-skills的编排逻辑里给了模型一个出口：输出skill_name=null并附带 reason。这样当用户问的是纯知识问题，或者当前技能库确实没有合适能力时，模型可以直接拒绝。从数据看，加入了“可拒绝”选项后，技能调用的整体准确率反而提升了，因为不必要的误调用变少了。

我还进一步要求：如果模型决定不调用技能，它必须以普通聊天的方式继续回答用户。这样就解决了“一问就失灵”“只会接技能不会聊天”的尴尬局面。

5.4 实测对照：有技能库的 Agent 成功率差异

为了验证agent-skills的实际价值，我在一个内部知识库问答 + 报表生成的场景里做了对照实验。同样使用同一款基础模型，一组用纯 Prompt 让模型自己调用 API，另一组接入技能库。任务包括：查询最近 7 天订单数、按渠道汇总销售额、解析上传的 Excel 并生成汇总表。每组各跑 100 次，结果如下：

纯 Prompt 组失败的原因分散在“伪造参数”“SQL 语法错误”“Excel 解析字段不对”等；技能库组失败则主要集中在外围异常，比如超时、网络波动。这说明把能力沉淀为技能，确实是把 Agent 从“会聊天”推向“会干活”的关键环节。

5.5 技能版本管理：老版本技能的兼容策略

最后提一个容易被忽略的细节：技能也会迭代。让我比较头疼的是，新技能往往不兼容旧参数。后来我在 Schema 里加了一个deprecated_since字段，老版本的技能不会被立即删除，而是标记为“已废弃”，但依然可以调用。模型路由时会优先选择未废弃版本，如果因为业务需要必须使用旧版，可以在技能描述里明确标注“仅当用户要求使用旧格式时使用”。这个平滑迁移策略让我不用频繁中断线上服务，也给了技能使用者适应的时间。

根据自己的实际体验，agent-skills这类技能化改造最值得投入的阶段，是当你发现 Agent 的聪明只体现在“说”而不是“做”的时候。技能库本身不神秘，难的是克制地设计技能边界、严谨地约束输入输出、耐心地做回归测试。做完这些事情之后，你再回头看 Agent，会发现它终于从一个“嘴强王者”变成了一个“靠谱执行者”。如果这篇文章能帮你少走几个弯路，那就值了。