早两年聊 AI Agent大家张口闭口都是“规划、记忆、工具调用”三件套。今年再看风向已经变了工具调用只是地基真正让 Agent 拉开差距的是“skills”的厚度和复用度。我最近密集做了一个叫 agent-skills 的组件化项目翻了不少框架和开源仓库自己也复刻了一版给内部业务用。今天就借这个主题把 agent、skills、工具调度、适配层、评测以及几个高频踩坑点串起来讲透。1. 理解 Agent 与 Skills 的关系从单体大脑到可插拔能力1.1 Agent 的本质是什么Agent 不是一个聊天框。它的核心是“自主决策 多步执行”你给它一个目标它能自己拆解成子任务、选择工具、调用外部系统、观察结果、再决定下一步。这里面的自主性靠的是大模型的推理能力但真正的执行力靠的是外部工具和环境接口。我习惯用一个生活化类比来解释 Agent 的组成把 Agent 想象成一家餐厅的主厨。大模型是主厨的脑子负责点菜、判断火候、协调出餐顺序工具是灶台和厨具负责切、炒、炸、烤而 skills 呢是主厨收录在册的“拿手菜标准操作流程”。一道菜怎么做才地道、需要哪口锅、酱汁比例多少主厨不需要每次重新想直接从 SOP 里调。这个类比能解释一个非常关键的细节skills 不是给用户看的说明书而是给 Agent 自己看和执行的“程序化经验”。它以结构化文本或脚本的形式预置在上下文里Agent 碰到对应场景就直接引用和套用。1.2 Skills 解决的问题是什么没有 skills 的 Agent就像没有菜谱的新手厨师——每次炒菜都靠临场发挥。大模型哪怕再有知识面对具体流程也会出现三类典型问题步骤不稳定。同样一个需求今天走 A 流程明天走 B 流程结果参差不齐。隐性经验丢失。怎么封装 HTTP 请求、怎么避坑文件编码、哪条 SQL 容易触发死锁这些经验只存在于某个人的脑子里。多场景不可复用。一个 Agent 如果同时支撑数据分析、前端开发、客服问答三个场景Prompts 全塞进系统提示词只会互相干扰。Skills 的核心价值就是把“单次对话里临时想出来的方法”沉淀成“可复用的、可插拔的标准化能力模块”。每个 skill 有明确的触发条件、输入格式、执行步骤、输出约定。Agent 拿到任务时先判断“这属于哪个 skill”再按 skill 的预案去执行。1.3 从代码层面看 Agent Skills 的结构一个标准的 agent skill通常包含以下部分metadata技能名、描述、适用场景、版本。trigger什么时候激活这个技能通常由模型基于描述自行判断。execution plan分步指令模型照此执行。context templates用来填充任务信息的模板。validation如何检查执行结果是否正确。这里的关键是整个 skills 文件要以“足够的细节、明确的边界、可检验的输出”呈现。写得太笼统等于没写写得太死板又会把模型的灵活性限制死。这是一门平衡的艺术。2. 方案设计为什么技能化拆分比大而全的 Prompt 更靠谱2.1 单一 Prompt 方案的致命伤做 Agent 开发最容易犯的一个错就是“一个系统提示词包打天下”。想象一下你让一个 Agent 同时会调数据库、会写前端、会做竞品分析、会处理合同审核你就把所有规则、范例、工具说明全部灌进 system prompt。带来的直接后果有两个上下文窗口被无谓占用有效信息密度下降而且各领域指令互相干扰模型在长对话里经常“串台”。我实测过一个场景把前端样式规范写进系统提示词后Agent 回答数据分析问题时居然还在提醒“注意颜色体系”。这并非模型蠢而是提示词里的冗余上下文影响了它的注意力分配。问题不在模型在于我塞进去的东西没有边界。2.2 按功能垂直切分技能项目 agent-skills 的核心设计思路就是“垂直切分 动态加载”。每个技能是一个独立目录只负责一个领域内的操作闭环。举个例子code-reviewer-skill专门做代码审查有明文的规则清单、常见反模式列表、输出模板。sql-optimizer-skill专门做 SQL 分析与优化有 explain 解读方法论。frontend-fixer-skill专门修复前端页面样式问题有 CSS/JS 的诊断流程。research-report-skill专门做资料检索和报告生成有搜索、摘要、引用链路。这样做的好处非常直接。第一上下文只加载当前任务相关的技能描述其他技能不占用 tokens。第二技能可以独立迭代、独立测试、独立交付某一个技能版本升级不会影响其他。第三任何一个新场景不需要重写 Agent只需要新加一个 skills 目录Agent 的能力边界就扩展了。2.3 技能与工具/框架的区别问对了很多初学者把“技能”“工具”“Agent 框架”三个词混为一谈。实际上它们分层非常清晰工具tool是一个具体的功能接口比如“发送 HTTP 请求”“执行 SQL”“调用某个 API”。技能skill是“在什么场景下、按什么步骤、用哪些工具、产出什么结果”的完整方案。框架framework是承载 Agent 运行时的底座负责模型调度、工具注册、上下文管理、循环控制等。一句话总结工具是哑元件技能是工艺方案框架是车间。项目里它们仨必须解耦。早期版本里我把技能逻辑写死在框架里结果每次调技能都要动框架代码维护成本飙升。后期改成“框架只负责加载技能只负责描述”接新的技能从改代码变成写文档效率提升非常明显。2.4 Skills 与 Agent 的绑定关系设计在设计时还要考虑一个问题技能是绑定特定 Agent 还是全局共享我个人的经验是分成两层基础技能层跨 Agent 通用比如“代码搜索”“错误定位”“日志分析”所有 Agent 都可以调用。专属技能层仅为特定角色服务比如“前端美化技能”只在前端 Agent 里注册“合同风险技能”只在合同 Agent 里注册。这种按需注册的好处是避免 Agent 在错误场景下误触发不合适的技能。小白写技能时容易把所有东西都挂到同一个 Agent 上最后出现“做数据清洗时把表单按钮调整了色号”这种事。看似好笑实则是技能边界没划分清楚。3. 实操环节手把手实现一个前端代码审查技能3.1 技能目录设计与元信息编写这一节我直接以项目里的一个典型技能做例子。假设我们要做一个“前端代码审查技能”frontend-reviewer目标是对一个 React 组件进行代码质量与安全检查。在 agent-skills 的目录结构里我会这样组织skills/ ├── frontend-reviewer/ │ ├── SKILL.md │ ├── rules/ │ │ └── react-patterns.md │ ├── templates/ │ │ ├── review-report.md │ │ └── severity-matrix.md │ └── scripts/ │ └── extract-props.py这里的 SKILL.md 是入口元信息部分长这样--- name: frontend-reviewer version: 1.4.0 description: 审查 React/TypeScript 组件的代码质量、可维护性与安全隐患。 tags: [react, security, code-review, typescript] trigger: 当用户要求审查前端代码、检查组件质量或定位前端代码缺陷时使用。 ---这段元信息非常重要。description 要写得清晰且便于模型理解。模型判断是否启用这个技能主要依据就是 name 和 description 是否与用户意图匹配。写得模糊模型就会在需要激活时漏掉写得过于宽泛又会在不该激活时误触发。3.2 执行计划与分步指令的写法SKILL.md 的主体部分是执行计划。我把前端审查拆成四步## 执行流程 ### 步骤1收集上下文 - 读取指定组件文件及其依赖文件。 - 明确组件用途、props 接口、状态管理方式。 - 如果文件缺失或无法访问停止执行并向用户说明。 ### 步骤2静态规则扫描 - 调用 rules/react-patterns.md 中的检查清单。 - 重点检查hooks 调用顺序、useEffect 依赖数组、非受控组件警告、key 属性唯一性。 - 对每一项检查给出 ✅ 通过或 ⚠️ 风险标记。 ### 步骤3安全检查 - 检查 dangerouslySetInnerHTML 的使用场景。 - 检查 URL 拼接有没有引入 XSS 风险。 - 检查状态更新是否存在竞态条件。 - 对高危问题标红并给出具体修复建议。 ### 步骤4输出报告 - 按照 templates/review-report.md 的格式生成报告。 - 报告含总体评分、问题清单、修复建议、优先级四部分。 - 评分标准必须引用 severity-matrix.md。每一条指令都包含两个要素动作做什么和判定标准怎么算完成。我写技能踩过最大的坑就是只有动作、没有判定模型执行到一半不知道怎么叫“做完”要么提前收工要么反复穷举。加上判定标准后执行质量马上稳定下来。比如“检查 hooks 调用顺序”没有判定的时候模型只会说“看起来不错”加了判定标准“检查 useCallback、useMemo 是否在条件分支内调用检查 useEffect 内是否引用了组件外且未声明的变量”模型就有了具体的检查对象输出自然踏实。3.3 技能如何与工具调用联动Skills 和工具是两层概念但实操时它们是配合关系。同样以这个审查技能为例执行“收集上下文”这一步技能本身没有能力读文件它必须调用 Agent 框架提供的 read_file 工具。所以在 skill 编写中不应该写“直接调用 read_file”这种和框架绑死的话而应该写抽象的意图“读取目标组件文件的完整内容包含 import 语句和样式定义”。至于底层是走 read_file 还是走代码检索工具由框架层的工具调度逻辑去决定。这样设计能保持技能的“框架无关性”。我目前内部项目同时跑了基于 Python 的自研调度器和基于 TypeScript 的开源运行时同一套 SKILL.md 可以两处复用没有任何改动。这就是把工具与技能解耦的最大回报。顺便说一句工具返回结果往往很长Agent 一次读不完。我处理的方式是在技能里约定“如果文件超过 200 行优先提取关键代码片段再按需分段读取”。这个细节极大缓解了上下文溢出问题。3.4 让技能可以被测试验证与回退机制Agent Skills 不能只写出来就完事还得能测。我在技能里加了一个“self-check”设计## 自检清单 执行完上述步骤后必须确认 1. 是否覆盖了 rules/react-patterns.md 中全部必检项 2. 报告中是否包含至少一个具体修复示例 3. 是否对每个风险点标注了严重程度有了自检清单再配合自动化测试脚本就可以对技能效果做回归验证。每次改技能描述都拿同一个测试文件跑一遍看看输出有没有劣化。这个习惯帮我拦截过好几次“描述优化后反而把关键规则丢了”的回归事故。如果没有自建测试集也可以退而求其次用“固定案例多人盲测”的方式做验证同一个任务分别扔给开启技能与关闭技能的 Agent对比输出的专业度差异。这个对比能直观告诉你这个技能到底有没有价值。4. 融合 Rust 与多 Agent 场景一套可扩展的架构实践4.1 用 Rust 做技能引擎的优势项目里有相当一部分底层的技能调度逻辑我选择了 Rust。选择它的理由有三点并发能力强。Agent 经常要同时发起多个工具调用并行搜索、并行读文件、并行请求 APIRust 的 async 模型处理这种场景很从容。内存可控。Agent 常驻服务在长会话里会出现内存缓慢上涨的问题。Rust 的内存占用曲线比 Python 平缓得多跑长任务不慌。分发简单。编译成单一二进制交付不需要在目标机器上装整套 Python 环境。这对部署运维特别友好。当然 Rust 也有代价开发效率不如 Python。所以我采取的是混合架构Rust 做调度与执行引擎Python 做数据分析类技能的附加工具。这个思路我觉得比“纯 Rust 重写一切”务实得多。4.2 多 Agent 场景下技能注册中心的设计多 Agent 系统里最怕的就是技能管理混乱。A Agent 用了技能 v1B Agent 用了技能 v3最后问题复现时两边表现不一样查了半天查不到最后发现在技能版本上。我在项目里做了一件很笨但非常有效的事建一个技能注册表记录每个技能的 ID、版本、适用 Agent、依赖工具链。技能注册表样例技能ID版本适用Agent依赖工具上次验证时间frontend-reviewer1.4.0前端修复Agentread_file, code_search2025-05-12sql-optimizer2.1.3数据开发Agentquery_explain, db_connect2025-05-08research-report0.9.2通用研究Agentweb_search, fetch_page2025-04-30每次技能发布必须走“注册—测试—灰度—全量”的流程。这套流程让多 Agent 系统的行为可预测了很多。很多人做多 Agent 只把注意力放在“怎么让多个 Agent 对话”上忽略了底层的技能版本一致性结果对话越热闹干活越不靠谱。机制比热闹重要。4.3 Agent 编排与技能加载的配合Agent 框架有几个重要概念任务队列、工具映射、上下文构建、循环终止条件。技能加载发生在“上下文构建”阶段。流程大致是这样的用户下发任务文本。框架做意图识别从注册表中选出候选技能。框架把候选技能的 SKILL.md 相关模板注入模型上下文。模型依据技能描述规划步骤并执行。若执行需要工具技能步骤描述里的动作被翻译为工具调用。工具调用结果回填模型继续决策直到执行结束。这里有一个值得说的细节技能描述本身是要计入 token 的。一个技能平均占 800 到 1500 tokens如果意图识别不准把所有技能全塞进上下文光技能描述就有上万 tokens成本翻了倍效果却不升反降。所以我一开始就给意图识别模块加了一个硬指标单次任务最多载入两个技能。宁可多跑一次“技能选不到再扩大搜索”的兜底也不要一口气加载五个技能让模型左右为难。这个设计让我在成本控制上省了不少。5. 常见问题与排查技巧实录5.1 Agent 执行中途报 execution terminated due to error这个错误极其常见。很多初学者第一反应是去查网络或者 API Key但我遇到的大部分情况根源其实在于技能执行计划里某一步返回了结构完全不符合预期的数据模型试图按原计划继续结果在工具层直接崩掉。排查思路是三步走打开 Agent 日志定位到底是在哪一次工具调用时终止的。看那次调用的输入是否和技能设计时预期的输入格式一致。如果不一致问题通常出在“技能步骤里缺少输入校验”。解决方法是在技能里增加“输入异常时的备用路径”。比如“若接口返回的不是数组而是一个错误对象则提取 error 字段内容将其作为下一步的输入”。类似这种把异常处理写指令里的方式能显著降低执行中断率。5.2 Token 消耗爆炸到底出了什么问题场景是同一个任务手写 Prompt 只要 3K tokens启用技能后却花了 12K。这不是技能没用而是上下文管理没做好。常见的元凶有三个技能文件太长全部注入。解决只注入 SKILL.md 的精简版规则细节按需读取。工具返回结果太大。解决在技能步骤里约定“截断摘要”而不是全量回填。回顾循环失控。Agent 反复重新分析同一段历史把旧结果一遍遍粘贴进新上下文。解决在框架层设置“关键结果固定保存推理过程不重复输出”。我后来给技能设计加了一个 token 预算字段每个技能标注“推荐单次占用 token 量”超了就要做精简。有了这个红线上下文里面的“无效膨胀”降了一半以上。5.3 同一个技能在 A 场景很牛在 B 场景变成智障这是技能的过拟合问题。技能里面用了太多特定项目的术语和假设换到另一个项目触发条件匹配不上执行步骤里引用的判断标准又不成立模型只好硬着头皮套结果自然稀烂。解决这个问题我在每个技能里加了“适用前提”一栏明确写清楚“本技能仅适用于基于 React 18 以上的项目若项目使用 Vue 或 Angular 则停止执行并提示用户切换技能”。看似只是加了一行字实际效果立竿见影——技能被误用的概率直线下降。5.4 技能和 Agent 框架内置功能重叠先调谁实际开发中会遇到一个棘手问题Agent 框架本身就自带了一些能力比如代码解释器、文件读写、搜索这时候你的技能要不要重复实现一遍我的经验是三层处理框架已有能力不要重复造轮子在技能里直接引用框架的工具标识。框架能力太粗技能里补充“增强指令”约束框架工具的使用方式。框架没有能力技能里定义新的操作步骤并附上可能的脚本或调用方案。重点要防止的是“技能把框架能力再包一层”。比如框架已经能读写文件技能里又写了“调用 read_file 工具读取文件内容”这就是纯粹的冗余。编写技能时应该把精力放在决策逻辑上而不是重复封装已有的工具执行能力。6. 进阶玩法如何高质量设计一套前端开发 skills 清单6.1 前端领域里的 skills 分层思路前端这个领域其实非常适合用 skills 来拆解因为它的任务边界非常清晰。我把前端 skills 拆成六个方向UI 还原技能从 Figma 设计稿到高还原度组件代码。样式修复技能定位样式错位、间距异常、色值偏差问题。性能检测技能分析首屏加载、构建体积、渲染瓶颈。兼容性审查技能排查不同浏览器下的行为差异。代码规范校验技能统一团队编码规范与提交规范。组件测试生成技能为组件自动生成单元测试与交互测试。六个方向彼此独立前端 Agent 可以按需加载一个也可以组合多个。比如“修好这个样式并且给组件补个测试”就是样式修复技能和组件测试生成技能组合工作。技能组合时我会格外注意接口的一致性两个技能不能对同一个组件状态产生互相矛盾的要求。6.2 官方市场与开源渠道的取舍现在很多平台都有 skills 市场和开源仓库。我的使用感受是官方市场的优势在于质量校验、版本兼容好拿来能用开源仓库则是种类多、奇技淫巧多但质量参差不齐下载前必须看星数和最近维护记录。下载的 skill 不是装完就完事的一定要做三件事改写定制的触发描述让它可以匹配你的任务范式清理掉技能里与你的 Agent 不兼容的工具名称跑一遍你自己的回归测试集。很多在网上被吹上天的 skill直接装了根本不能跑原因就是写 skill 的人环境和你完全不一样。6.3 写技能的三个进阶心法最后分享一下我自己写 skills 的几个进阶心法心法一让技能“越具体越通用”。听起来矛盾其实不矛盾。所谓具体是操作的颗粒度要细所谓通用是适用场景的表述不要绑死在某一个具体项目上。比如写“接口出错时重试最多3次”是具体写“只适用于用户中心接口”就太窄了。心法二输出结构先于执行步骤写好。技能里先定义好输出报告的模板再写步骤Agent 执行时会更倾向于照模板输出而不是输出一堆没结构的内容。心法三每个技能都要有一个“反例清单”。告诉大家“什么情况不要用这个技能”和“什么情况用”同样重要。反例带来的是边界约束边界越清晰的技能被模型误触发的概率越低。我最近在改一个数据分析技能时就靠反例清单拦截住了一场悲剧。技能描述里原本写“当用户提到性能问题时使用”结果数据分析 Agent 接到一个“页面加载性能优化”的需求差点把监督学习模型调起来。我加了一行“性能问题指数据库查询、报告生成、特征计算不包含前端渲染”误触发当场消失。7. 写在最后的一些经验碎片这个项目做了几轮迭代之后我最大的感受是写 agent 真正难的不是让模型聪明而是让模型的“每次执行都稳定地聪明”。而 skills 就是通往稳定聪明的关键载体。如果你想在自己项目里落地 agent-skills 这套思路我建议从一个小场景切入选一个你每天重复做的任务把它写成一个最朴素的技能然后在真实 Agent 里跑一周。哪怕这个技能最初很粗糙也不怕先用起来再不停迭代。技能这东西最大的特点是越跑越准——因为你每次踩的坑都可以沉淀成一个新的判断规则写回去。最后再分享一个技巧技能文件里一定会用到 Markdown但别把技能文件当普通文档写把它当成“给大模型看的程序代码”来写。有类型、有边界、有异常处理、有版本记录。把技能当成一等公民的团队和把技能当成临时提示词的团队跑三个月后差距会大到肉眼可见。