agent-skills：模块化技能库让Agent从“能聊天”到“会干活”

1. 项目概述与底层逻辑

1.1 为什么现在做 agent-skills

这两年大模型（LLM）相关的应用越来越多，大家从最初玩提示词，慢慢转向搭建正经的 Agent 应用。但做了一段时间就会发现，真正让 Agent 落地跑通的，不是模型本身多聪明，而是它能不能稳定调用外部工具、执行多步任务、处理各种边界情况。这个项目叫 agent-skills，本质就是把 Agent 需要的能力拆成可复用、可插拔的技能模块，让 Agent 不只是"能聊天"，而是"会干活"。

我最初碰这个方向，是因为团队接了十几个内部自动化需求。本来想着用现成的 Agent 框架去套，结果发现每个业务场景都有一套独特的操作逻辑：有的要走审批流、有的要查数据库、有的要操作文件、有的要调定时任务。如果每个都从零写一遍，那工作量直接爆炸。后来我干脆把高频、通用、可组合的动作全部抽象成"技能"，一个技能解决一类问题，组合多个技能就能跑复杂流程。这套思路用下来；，开发效率至少提了一倍，而且后续维护也轻松很多。

这个项目适合谁来参考？我的判断是：如果你已经在做 Agent 应用开发，或者准备做，会写一点 Python / JS，想摆脱"只会写单轮 Prompt"的阶段，那 agent-skills 这套分拣思路和落地方式会很有价值。哪怕你暂时不用这个具体实现，里面关于技能封装、目录规划、调度机制的设计理念，也能直接迁移到自己的项目里。

1.2 agent-skills 到底是什么

拆开来看，agent-skills 是一套面向 Agent 的能力仓库。它把 Agent 在真实业务中可能用到的能力，归纳成一个个"技能（skill）"。每个技能都有明确的输入输出、执行逻辑、依赖参数和错误处理。Agent 接到任务后，可以理解任务目标，从技能仓库里挑选合适的技能，按顺序执行，甚至根据中间结果动态调整后续动作。

举个例子：现在你让 Agent 做一份"上周销售数据周报"。如果只有模型本身，它能做的也就是编一段话，或者生成一份全是模板的文档。但配上 agent-skills 后，Agent 可以调用"SQL 查询技能"去数据表拉数，然后调用"图表生成技能"把趋势画出来，再调用"PPT 组装技能"把这些内容拼成正式周报。整个过程 Agent 不用重新发明轮子，而是像搭积木一样，把已经验证过的技能模块组合起来。

这套设计解决了几个很痛的问题：

• 重复开发：每个 Agent 项目都要写文件读写、API 调用、数据清洗的代码，有了技能库之后，一套通吃。
• 技能分散：以前各项目各写各的，没有一个统一的标准。技能库把接口约定、参数格式、输出规范全部统一起来。
• 不可组合：单点脚本能做一件事，但组合不起来。技能化之后，可以按业务流程自由编排。
• 维护困难：原来功能分散在业务代码里，改一个接口要满项目找。现在集中在技能目录里，更新升级很直观。

我自己的体会是，"技能化 + 目录化 + 编排化"这三件事，其实比具体某个技能实现更重要。项目标题叫 agent-skills，它承载的就是这套思路的工程化落地。

1.3 整体架构与核心模块

agent-skills 的结构并不复杂，但它把"能力"的位置抬得很高。整个项目按功能域划分为若干核心模块，平时用起来自己心里有数，新同事接入也快。核心模块大致包括：

• 技能定义层：定义技能的数据结构。每个技能有唯一的名字、描述、参数 Schema、执行函数、返回类型、错误处理策略。这层是基础，所有技能都必须实现标准接口。
• 技能注册中心：负责管理技能列表，支持按名称、标签、用途注册和查找。这样 Agent 可以在执行任务时动态发现可用技能。
• 技能执行引擎：负责实际调用技能函数。它处理入参校验、上下文传递、并发控制、超时熔断，避免一个技能卡死拖垮整个任务。
• 任务编排层：支持将多个技能串成流水线（Pipeline），或者按条件分支执行。这一层是面向复杂业务的，通常配合状态机使用。
• 观察与日志：记录技能执行轨迹、耗时、成功失败率、调用参数等。我之前很多线上问题排查，靠的都是这套日志系统，它让我们能回溯 Agent 当时调了什么、传了什么、报了什么错。

这些模块之间相互独立，通过标准接口通信。好处很明显：每个技能更新不影响其他模块；更换模型供应商不影响技能逻辑；甚至可以把部分技能搬出主进程，做成独立服务，给多个 Agent 共享。

2. 典型应用场景与价值分析

2.1 企业内部自动化流程

企业内部有大量规则明确、重复度高、逻辑固定的流程性工作，非常适合用 agent-skills 处理。比如：自动生成业务报表、定时拉取数据并通知、对账异常自动报警、客户信息自动补全等。

拿"自动生成业务报表"来展开说。正常流程可能这么设计：Agent 接到"每日生成销售概览"的定时任务触发，第一步调用"数据库查询技能"从数仓拉取前一天的销量、毛利、订单量等指标；第二步调用"数据处理技能"，做同环比计算；第三步调用"文档生成技能"，把结果写入线上文档并格式化；第四步调用"消息通知技能"，把文档链接推送到工作群。整个过程无人工参与，稳定跑了一个多月，每天省下的时间估算下来约 15 分钟到半小时。而且因为执行逻辑是可配置的，一旦指标口径调整，改对应的技能参数即可，不影响其他环节。

这种场景下 agent-skills 的典型优势在于逻辑透明。每个步骤做了什么、数据来源是什么、为什么得出这个结论，都能从技能调用记录里查出来。跟业务方对账的时候，我不会说"模型认为"，而是直接给链路：几点几分调了哪个技能，传了什么参数，返回了什么结果。有了存档和溯源，企业内部落地就容易很多。

2.2 个人知识管理与助手

除了企业级场景，agent-skills 在个人助手类应用里也非常顺手。比如做笔记整理、邮件分类、日程归纳、文献解读。技能化最大的收益是"能力沉淀后不断复用"。

我自己的一个日常用法：收集了大量网页文章链接，全靠手动剪藏太慢。我用 agent-skills 做了一个"自动剪藏"流水线。第一个技能负责解析 URL，抓取正文内容并去除广告和无用 HTML；第二个技能做文本清洗，输出纯净的 Markdown；第三个技能按标题关键词自动分类，比如技术、行业、观点、资源等；第四个技能把结果按日期归档到本地仓库目录。整个过程输入只有一堆链接，输出是已经整理好的知识文件。

值得说的是，个人场景和企业场景不同，对容错要求没那么高，但对"轻量、可改、能快速跑通"要求更高。agent-skills 的设计天然契合这点：技能粒度小，可以单独改某一个技能的逻辑而不用动整条链路；也不用引入重量级框架，一个 Python 文件加一个配置就能跑起来。

2.3 复杂任务的分步拆解与执行

复杂任务有一个共同的特征：没法用一个 Prompt 描述清楚，整个任务是多阶段的，并且阶段之间强相关。比如"写一篇行业分析报告"这种任务，如果一次性丢给模型，结果往往很空。而用 agent-skills 拆成：收集资料、整理框架、逐节写正文、统一排版、生成摘要——每一步输出都可以被检查、被修正。

这种拆法还有个好处，一旦某个环节质量不稳定，可以单独优化那个技能。比如发现"数据收集"环节总是找到过时信息，那我只需要替换或者改进这一个技能的实现即可，其他环节完全不受影响。多步任务的可维护性因此大幅提升。

我也试过把这种能力用在一个小规模研究助手上。流程是：用户给一个研究主题，Agent 先调用"关键词生成技能"产生多组检索词；再调用"搜索引擎技能"做多次搜索；然后调用"网页摘要技能"把每个网页压缩成 200 字以内的摘要；接着调用"聚类技能"把摘要按主题合并；最后生成初步研究笔记。一整条链路跑下来，比直接让模型回答问题要扎实得多。

3. 单技能的标准化落地

3.1 技能定义与接口设计

技能要可组合，标准就得先行。我把每个技能视为一个独立可调用单元，统一接口格式是run(input) -> output。这里的 input 和 output 都是 JSON 结构，既方便模型理解，也方便程序处理。一个技能示例的完整定义如下：

{ "name": "fetch_webpage_content", "description": "抓取指定 URL 的网页正文内容，返回干净的文本", "params": { "type": "object", "required": ["url"], "properties": { "url": {"type": "string", "description": "目标网页链接"}, "max_chars": {"type": "integer", "description": "最多抓取字符数，默认5000"} } }, "returns": { "type": "object", "properties": { "title": {"type": "string"}, "content": {"type": "string"}, "success": {"type": "boolean"} } } }

这个定义看起来简单，但背后都藏着经验教训。字段description尤其关键，它是给模型理解的多模态信息，写得好不好直接影响 LLM 能不能正确调用这个技能。我在实践中发现：描述写清"这个技能做什么、适合什么时候用、不适合什么时候用"，比只写"抓取网页"要好用得多。模型真的会读这些描述。边界写清楚了，幻觉性误调用能少一大截。

3.2 技能实现与异常处理

接口定了之后，技能实现就相对独立了。以"抓取网页正文"为例，直接用 Python 实现，核心逻辑是请求、解析、清洗、返回：

import requests from bs4 import BeautifulSoup def run(params: dict) -> dict: url = params.get("url") max_chars = params.get("max_chars", 5000) try: resp = requests.get(url, timeout=10, headers={"User-Agent": "Mozilla/5.0"}) resp.raise_for_status() soup = BeautifulSoup(resp.text, "html.parser") for tag in soup(["script", "style", "nav", "footer", "header"]): tag.decompose() content = soup.get_text(separator="\n", strip=True) content = content[:max_chars] return {"title": soup.title.string.strip() if soup.title else "", "content": content, "success": True} except Exception as e: return {"title": "", "content": "", "success": False, "error": str(e)}

这份实现里有几个细节值得注意。第一，必须设置超时，否则某个网页响应慢会卡住整个流水线。第二，User-Agent 必须模拟正常浏览器，部分网站对裸请求直接拒绝。第三，清洗环节先移除 script、style、nav 等标签，不然正文里全是噪音。第四，把异常捕获在函数内而不是抛出去，这样就算某个网页抓取失败，流水线也能继续往下处理，只是把 success 标记为 false。这个"防御性容错"思路在技能化落地时几乎是必须的。

3.3 技能注册与自动发现

技能实现好了，要注册到技能仓库里，Agent 才能找得到。注册逻辑其实很简单，本质上是维护一张技能清单。我在项目里用了一个技能注册函数，按名字去重：

SKILL_REGISTRY = {} def register_skill(skill_def: dict, handler: callable): name = skill_def.get("name") if name in SKILL_REGISTRY: raise KeyError(f"Skill {name} already registered") SKILL_REGISTRY[name] = { "definition": skill_def, "handler": handler, } def list_skills(): return [{"name": name, "definition": info["definition"]} for name, info in SKILL_REGISTRY.items()] def get_skill(name: str): return SKILL_REGISTRY.get(name)

注册中心虽然简单，但它解决了发现的问题。Agent 要干活时，先把用户任务文本和所有技能定义一起丢给模型，模型根据描述选择该调用哪个技能。这种"技能即函数"的映射方式，我实测对大模型的工具调用成功率帮助很大。因为你不需要模型记住所有参数细节，只需要它把"任务文本"和"技能描述"匹配上就行。

4. 多技能组合与任务编排

4.1 流水线编排的设计思路

单一技能能做一件事，但业务永远不止一件事。多技能组合有两种常见模式：一种是顺序流水线，前一个技能的输出，作为后一个技能的输入；另一种是条件分支，根据中间结果决定后续动作。

顺序流水线的代码逻辑其实很直观，但真正让它好用的不是循环本身，而是输出映射的设计。每个技能的输出可能是嵌套 JSON，但下一个技能需要的参数可能是其中的某一个字段。如果每个技能内部各自去猜，那组合管理就乱了。所以我在编排层增加一个字段映射配置，比如这样：

{ "pipeline": "weekly_report", "steps": [ {"skill": "query_sql", "output_map": {"result": "output.data"}}, {"skill": "calc_metric", "input_map": {"raw_data": "output.data"}, "output_map": {"metrics": "output.result"}}, {"skill": "generate_chart", "input_map": {"data": "output.metrics"}}, {"skill": "build_doc", "input_map": {"chart_path": "output.image_path"}} ] }

这段配置的意思很清楚：每一步从指定字段取数据，执行完结果落到特定路径，供后续步骤使用。字段映射可以做到很复杂，也可以很简单。实际业务中大多数时候都不用太复杂，关键是把数据流动显式化，避免"这个技能到底读谁的输出"这种模糊地带。

4.2 基于 LLM 的技能选择机制

虽然手工写死流水线在很多场景足够用，但真正体现 agent-skills 能力的，是让 LLM 自己决定每一步调用哪个技能。

方法是这样的：把技能清单转成模型的 tool schema，直接让模型输出要调用的技能名称和参数。以 OpenAI 格式为例：

{ "role": "assistant", "content": null, "tool_calls": [ {"id": "call_1", "type": "function", "function": {"name": "query_sql", "arguments": "{\"sql\": \"select * from sales where date = '2025-01-01'\", \"db\": \"sales_db\"}"}} ] }

模型返回之后，我先校验参数是否符合技能定义的 JSON Schema，校验通过才真正执行；不通过就回传给模型做修正。这一步至关重要，我在前期吃过不少亏。不校验直接执行，模型偶尔会把字符串类型传成整数，或者漏掉必填参数，技能执行阶段就很难排查。

这整套逻辑下来，Agent 干活的路线变成了"感知任务 -> 匹配技能 -> 逐步执行 -> 检查结果 -> 修正计划"。它不是一次性的问答，而是一个动态循环。

4.3 可视化编排

后来我们在内部工具里给流程编排加了一层可视化。把每个技能当成节点，拖拽连接，做一个简单的 DAG。运行时按拓扑序执行，支持人审、暂停、重跑等操作。

说实话，可视化本身不会提升技能的执行质量，但对于沟通价值极大。业务方看到你画的流程图，能立刻理解 Agent 每一步在做什么。对于"信任 AI 系统"这件事，可视化功不可没。每次业务方问"它这个结论怎么来的"，我直接把 DAG 图打开，指着节点说这是查询、这是计算、这是生成，他们很快就对系统建立信任。

4.4 重试、回退与人工介入

组合任务链路长，失败是必然的。所以编排层必须考虑重试、回退与人工介入。我这边的策略是分三层：

• 技能层重试：单个技能失败时，允许重试 2 次；如果参数问题则直接修正后重试。
• 流程层回退：某个步骤连续失败，可以回退到前一个稳定步骤，清理中间产物后重新执行。
• 人工介入：如果关键节点失败且自动修复失败，就挂起任务，把当前上下文发给运维人员处理。

在 agent-skills 项目里，我把这层逻辑封装成"执行器（executor）"。执行器负责调度、重试、状态记录。所有的任务都通过执行器来跑，而不是直接循环调用。这样统一入口，日志、埋点、中断恢复都好集中控制。

5. 避坑指南与实战心得

5.1 技能粒度：拆太大太小都会痛

技能粒度是 agent-skills 设计中最难把握、也是最影响迭代体验的地方。拆太细，比如"打开文件""读取第一行"都做成技能，那调用链会长到不可维护，模型选择技能也容易选错；拆太大，比如"生成完整周报"一个技能搞定，那又退回到普通函数调用，失去了组合价值。

我实践下来的粒度标准是："一个技能能独立完成一个语义完整的动作，并且输出可以被下一个技能直接消费或人直接检查。"举个例子，"抓取网页正文"可以是一个技能，"把文本转成 Markdown"可以是一个技能，但"抓取网页正文并提取其中所有邮箱"就太细了，不值得单独为一个邮箱提取做技能。我发现粒度合理的技能，描述控制在 2 到 4 句话就能说清楚，参数控制在 3 到 5 个。参数超过 7 个，LLM 调用出错的概率会明显升高。

5.2 参数校验：不校验就是给自己埋雷

这个坑我必须重点说。LLM 生成参数天然地有随机性，直接拿着模型输出去执行技能，早晚出事。我们在实际项目里部署技能后的头几周，几乎每天都有因为参数格式问题导致的执行异常，有的 SQL 被改写了，有的日期格式传成"昨天"，有的把必填字段直接漏掉。

后面彻底改成强校验方案：每个技能注册时附带一份 JSON Schema，LLM 选完技能后，先用 jsonschema 库校验参数结构：

import jsonschema def validate_params(skill_name: str, params: dict) -> list: schema = SKILL_REGISTRY[skill_name]["definition"]["params"] errors = [] try: jsonschema.validate(instance=params, schema=schema) except jsonschema.ValidationError as e: errors.append(str(e)) return errors

校验不通过就返回给模型修正，并附上错误原因。这样虽然多了一轮交互，但成功率提升非常明显，基本上首次执行成功率从 60% 提到了 90% 以上。

5.3 日志与可观测性：没有日志等于盲跑

Agent 类应用和普通 API 有个很大区别：普通 API 上线后主要看流量、错误率、延迟，Agent 应用还得看"意图、选择、行为链路"。你不仅要懂代码，还要知道模型为什么选了 A 技能而不是 B 技能。

所以从第一个版本开始，agent-skills 就把结构化日志内置进去了。每个技能调用都会记录：

• 调用时间、耗时、技能名、入参、出参、错误信息
• 触发方式：是 LLM 决策还是人工指定
• 所在流水线 ID、步骤序号
• 重试次数和修正记录

有了这些，我排查问题基本不用猜。有一次定时任务凌晨 3 点失败，我早上调日志，一眼看到是中间步骤传了个空字符串给下一个技能，参数校验拦下来，整个任务就挂了。顺着日志把那个技能的空值处理逻辑补上，问题就解决了。

5.4 让 LLM 选技能，描述决定成败

还有一件事，如果没有亲手试过可能感受不深：LLM 选择技能的能力，除了模型本身强弱，很大程度取决于你的技能描述写得好不好。

我试过几种写法，最有用的是结构化描述。比"抓取网页并返回文本"更有效的是：这个技能抓取指定 URL 的正文，去除页头和页脚，并返回标题与纯文本内容。适合用于获取网页资料。不适合用于处理登录后才能访问的网站。这种描述不仅告诉模型"能做什么"，还明确边界，模型在判断矛盾时会优先排除掉不适合的技能。

我还建议给容易混淆的技能加上使用提示。比如"查询数据库"和"写入数据库"两个技能，如果不写清使用时机，模型有时会拿查询技能去做更新操作。有了清晰描述，这种错配大幅减少。

5.5 安全与权限：默认拒绝最小授权

技能可以做任何事，权限边界就必须清晰。这也是我在推进 agent-skills 时特别注意的维度。技能执行往往涉及文件读写、数据库操作、外部网络请求，如果放任不管，LLM 一个幻觉就能把坏事做出来。

我们的策略是"默认拒绝 + 技能白名单 + 环境隔离"。每个技能声明自己的权限类型：只读、写文件、数据库写、网络请求等。流水线执行时，按照技能清单去匹配权限，超出授权范围的技能直接禁止调用。涉及高危险操作比如删除文件、清库、发送外部邮件，一律要求人工审批后才执行。

安全这块没有捷径，凡是能把危险动作封死的，绝不在逻辑里留后门。

5.6 常见错误与快速排查速查表

给自己攒了一个高频问题排查表，大多数团队照着查就能解决：

这张表并不复杂，但在实际项目中帮我省了大量排查时间。很多时候问题不是"技能没实现好"，而是"注册错了、描述偏了、参数没对齐"。这些问题清楚了，整套系统才真正稳。

6. 从 agent-skills 到更广阔的能力图景

6.1 迁移到不同 Agent 框架

如果你留意了前面的代码，会发现 agent-skills 的核心并不绑定某个特定框架。技能定义、注册机制、执行编排，这些概念在 LangChain、LlamaIndex、AutoGen、自研框架里都能复用。

我实际做过一次迁移：把一套 agent-skills 技能库接到另一个 Agent 运行时上，主要工作量是把技能定义转成目标框架的工具格式。注册和执行逻辑基本原样搬过去，因为它们本来就是框架无关的纯函数。由此我也建议，新建技能库时不要把框架 API 写进技能内部，保持技能函数纯净，输入输出只走 JSON。这样未来换框架成本极低。

6.2 与多模型和多模态能力的结合

agent-skills 在功能上不只限文本技能。图像识别、语音转文字、Embedding 匹配、PDF 解析等能力同样可以技能化。一个"多模态会议纪要"技能组合可以是：语音识别 -> 分离说话人 -> 提取关键议题 -> 生成会议纪要 -> 发送归档。每个步骤都是一个独立技能，中间可以随时插入人工审核节点。

我现在在做的一个扩展方向，把 Embedding 检索也变成标准技能。这样 Agent 可以自动从向量库里捞上下文，再结合业务数据做下一步决策。这一块虽然还在迭代，但思路是一致的："把智力留给模型，把稳定留给技能"。

6.3 技能市场与团队协作

技能越来越多之后，沉淀和共享就成了新的问题。我在内部做了一个简单的技能市场页面，按业务域分组，每个技能标注作者、版本、测试状态和适用场景。团队成员新接需求时先翻技能市场，看能不能直接组合出方案，能就不新写。

版本控制也很有用。技能升级时保留旧版本，支持按流水线固定版本，防止"技能升级了，老流程突然变了行为"这种情况。这个教训是从真实事故里得来的，有一次技能改了一行逻辑，没有做版本隔离，导致多个旧流水线行为同步变化，排查了很久。之后我才强制引入版本管理。

6.4 后续迭代方向

我自己后续最想做的三件事：一是把技能推荐做成智能化。根据任务文本直接预测候选技能列表，缩减 LLM 选择范围；二是做技能依赖解析。自动识别某个技能依赖的其他技能、外部服务和权限，并提供依赖图；三是把技能效能评估系统化。通过线上日志计算每个技能的成功率、耗时、修正次数，自动标记低质量技能，反向驱动技能优化。

这些迭代方向并不是空想，而是从实际运营里冒出来的真实需求。只要底层接口标准不变，上面这些能力都能逐步长出来。agent-skills 最关键的价值，就是给了 Agent 能力一个可持续积累、可评估、可演进的组织方式。