我差不多是从半年前开始真正重度折腾 agent-skills 这玩意的。起因特别朴素手上同时维护三四个 agent 项目每个项目的系统提示词越写越长最后长到连我自己都懒得读完更别说让模型稳定按套路执行了。后来我搞明白了 skills 的玩法才意识到之前那种“把逻辑全塞进提示词”的做法有多蠢。这篇我想把 agent-skills 从原理到落地完整聊一遍重点讲清楚三件事skills 到底是什么级别的抽象它跟 agent、harness 这些概念怎么区分以及一套能直接上手的 skills 编写与调试流程。整个内容适合两类人一类是刚开始学 agent 开发、被各种新名词绕晕的入门者另一类是已经在写 agent 但总觉得提示词一复杂就跑不对的进阶玩家。看完你至少能动手搭出自己领域内的第一个 skill 包并且知道遇到报错时该往哪个方向排查。1. 先理清楚 Skills 在整个 Agent 体系里的位置1.1 Skills 的本质给 Agent 一份“标准操作手册”我习惯把大模型 Agent 比作一个刚入职但学习能力极强的实习生。这个实习生的思维方式很灵活但有个致命弱点没有你的行业经验。你直接跟他唠产品方案他能回答个大概可你要他按公司规范完成一份带固定字段的周报他十有八九会按照自己脑补的格式来而不是按公司模板来。Skills 解决的就是这个“公司规范”的问题。它把某一类任务的执行经验、步骤约束、判断规则和兜底策略预先封装成一份结构化的操作手册。Agent 在执行任务的时候如果需要用到这个能力就把手册读进来照着里面的流程一步步走。这里有个关键点Skill 不是一段普通的提示词补丁而是一个自带边界的“能力单元”。打个比方提示词相当于你跟实习生口头交代“记得用公司模板”Skill 则相当于你直接把公司模板、填表规范、历史样例、常见错误避坑说明打包成册递给他。前者靠临场发挥后者靠固化流程——稳定性和可复用性完全不是一个量级。从工程角度看一个标准 Skill 通常包含三部分说明文件SKILL.md 这类用来描述何时用、怎么用、辅助脚本Python/Shell 等用来处理模型不擅长的确定性计算、参考材料示例输出、表格、代码片段等用来约束输出格式与质量。三者配合让 Agent 在“思考”之外还能“动手”和“对照”。1.2 Skill、Agent、Harness 三者到底有什么区别热词榜上同时挂着“skill 和 agent 的区别”和“harness 和 agent 区别”说明这事确实容易搞混。我直接用职场比喻拆开讲。Agent 是决策大脑它负责理解目标、规划步骤、调用工具、检查结果。Skill 是能力包提供的是“怎么做某类具体事情”的标准流程。Harness 则是运行环境相当于给 Agent 提供的工作台负责配置模型参数、管理上下文窗口、注入系统提示词、执行工具调用循环、处理错误重试等。用做饭来类比Harness 是厨房定义了灶台、燃气、锅铲这些基础设施怎么配合Agent 是厨师负责根据菜谱和现场情况决定先炒哪个菜、火大水小Skill 就是菜谱本身告诉你宫保鸡丁的糖醋比例是多少、什么时候下花生米。厨师可以不看菜谱自由发挥但结果不稳定厨房再豪华没有好菜谱也做不出稳定的味道。三者的管理方式也不同。Harness 通常由框架层统一处理比如各类 agent 框架内置的 runnerAgent 逻辑散落在代码和提示词里Skill 则是一堆可被单独增删、版本化、分享的文件目录。我之前在项目里把 Agent 写成一坨巨型 prompt导致换一个 harness 就得整体重写后来把知识类和流程类逻辑下沉成 skills迁移的时候只需要保留目录结构Agent 的 prompt 瘦身到原来的四分之一维护成本瞬间下来了。2. 为什么非要用 Skills从 Prompt 膨胀到项目失控2.1 提示词越写越长模型反而越来越笨先说一个我踩了很多次的坑早期做 agent 的时候遇到“模型输出格式不对”“某个步骤老是漏掉”“判断逻辑不够细致”等问题我的第一反应是往系统提示词里加描述。写着写着系统提示词突破了 5000 字里面包含七八个任务的完整说明、十几条输出规范、四五段样例。这种做法表面看是“我把要求说得很细”实际效果却是灾难性的。大模型对长上下文的注意力容易分散越是埋在长文里的规则越容易被忽略。我实测过同一个 agent系统提示词从 800 字涨到 4000 字后关键规则遵守率从 95% 掉到 70% 左右。更要命的是提示词里的规则往往是隐式的、捆绑在一起的——你想单改一个任务的输出格式可能影响其他任务的判断整个提示词变得极其脆弱。Skills 的出现就是用来打破这种“提示词绑架”局面的。每个 Skill 只负责一个具体领域Agent 只有在遇到相关任务时才会把它加载进上下文。这样单一 Skill 的文档通常控制在几百到一千字以内模型执行时看到的信息密度极高不会被无关规则干扰。2.2 Skills 带来的三个核心收益解耦、复用、可调试第一个收益是解耦。Agent 的主流程只关心“先规划再执行”具体的领域操作完全交给 Skill。以后想调整某个任务的处理规范只需要改对应的 Skill 目录不需要动主提示词。我现在管项目的方式基本变成了Agent 负责编排Skills 负责领域Harness 负责环境改哪块动哪块互不污染。第二个收益是复用。写好的 Skill 完全可以跨项目、跨团队复制。我在一个项目里做的“前端编码 skill”换个项目照样能用社区里别人分享的“微信公众号排版 skill”拿回来稍微改改模板就能接入自己的 agent。这相当于把经验从“隐性知识”变成了“显性资产”价值随积累线性增长。第三个收益是可调试。提示词时代调 bug 是玄学你只能反复改文字碰运气。Skills 时代不一样每个 Skill 都是独立目录里面用的是标准 Markdown 和可执行脚本。哪个步骤出问题直接把该 Skill 单独喂给模型跑一遍或者手动执行其中的脚本很快就能定位是“描述不清”“脚本报错”还是“样例误导”。这种精细粒度的调试能力是 monolith 式提示词永远给不了的。2.3 Skill 和 Prompt 的分界线在哪什么时候该写成 Skill讲了这么多并不是说所有提示词都要改造成 Skill。我自己的划分标准是这样的通用人格、对话风格、安全边界这类全局约束留在系统提示词里就行一个具体的、流程固定的、可封装的任务处理套路就值得做成 Skill。举例来说“你是前端工程师”这句话属于全局设定不适合做成 Skill“给一个 React 组件写测试用例要求覆盖交互逻辑并生成测试报告”这种带步骤和输出规范的任务就很适合封装成 Skill。判断标准很简单如果这个任务你希望它在任何项目里都能被稳定复现、复用、迭代那就值得 Skill 化。如果只是一次性指令直接写在 prompt 里反而更快。3. 手把手写一个 Skill结构、描述、步骤、兜底3.1 Skill 目录的标准结构与每个文件的职责市面上各家框架对 Skill 的目录结构定义大同小异核心思路是一致的。我一般推荐这样组织my-skill/ ├── SKILL.md ├── scripts/ │ ├── parse_input.py │ └── generate_report.py └── references/ ├── example_output.md └── template.mdSKILL.md 是整个 Skill 的灵魂模型主要通过它来理解“该不该用我、怎么用我”。scripts 目录放 Python/Shell 脚本专门处理模型不擅长的确定性操作比如格式转换、数据清洗、文件读写。references 目录放参考材料包括示例输出、模板文件、完整案例用来约束生成的格式和质量。这里有个容易忽略的点Skill 的目录名和 SKILL.md 里的 name 字段最好用英文小写加连字符因为很多 agent 框架是按文件名做索引的。中文描述可以放在 description 里但目录名和 name 用英文更稳妥。我之前曾在目录名里用了中文结果某个框架加载时直接乱码找不到文件排查了大半天。3.2 SKILL.md 的完整编写模板与关键字段解析SKILL.md 的格式是决定 Skill 好不好用的重中之重。我总结了一套模板现在写任何新 Skill 基本都按这个套路来--- name: skill-name description: 在什么场景使用本技能能完成什么任务需要什么前置条件。 --- # Skill: Skill Name ## 使用场景 描述该类任务的特征帮助 Agent 判断是否需要加载本 Skill ## 执行步骤 1. 第一步的具体操作 2. 第二步的具体操作 3. ... ## 关键规则 - 必须遵守的硬性约束 - 输出格式要求 ## 兜底策略 当执行遇到意外情况时如何处理防止 Agent 卡死 ## 示例 给出一段输入与相应输出的对照案例让模型有参照description 字段是整个 Skill 里最重要的部分。Agent 的“路由判断”基本上就靠它。description 写得越具体、越限定场景Agent 误调用的概率越低。我见过很多人把这个字段写成“用于处理常见任务”这种描述约等于没写Agent 在遇到完全无关的任务时也可能会加载它白白浪费上下文窗口。执行步骤要写成可操作的动词短语不要写“理解需求”这种模型无法明确执行的废话。每一步要像菜谱里的“大火烧至八成热下葱姜蒜爆香”一样具体。模型是按字面执行指令的步骤越具体行为越可控。关键规则部分要列硬约束比如“禁止修改用户输入原文”“所有输出必须包含参数说明”“脚本执行前必须先检查输入文件是否存在”。兜底策略容易被新手忽略但其实是实战中最救命的。模型执行任务时一旦遇到分支关联复杂、输入缺失等情况没有兜底策略就可能死循环或者直接报错有兜底策略则能平滑降级到“告诉你缺什么请求补充信息”。3.3 实操演示写一个前端编码类 Skill我用一个实际在用的“前端编码 skill”举例。这个 Skill 的作用是让 Agent 按团队规范生成符合风格的前端组件代码。SKILL.md 的核心部分大致长这样--- name: frontend-coding description: 用于生成 Vue 3 TypeScript 前端组件代码。当用户要求创建新组件、修改已有组件样式、补充交互逻辑时使用。需要用户提供组件功能描述或设计稿。 --- # Skill: Frontend Coding ## 使用场景 用户期望产出前端代码且项目技术栈为 Vue 3 TypeScript 时使用。 ## 执行步骤 1. 提取用户需求中的组件功能点列出 props 和 events 清单 2. 根据组件复杂度决定是否拆分子组件 3. 按项目模板脚手架生成组件代码 4. 输出时必须附带 props / events 使用说明 ## 关键规则 - 样式中禁止使用 px 以外单位设计稿按 750 宽切 - 所有交互必须有对应的 TypeScript 类型声明 - 组件文件必须包含默认导出的 defineComponent 块 ## 兜底策略 如果用户未提供设计稿或现有代码默认按项目基础模板生成标准结构并在说明中标注“按基础模板生成”。 ## 示例 输入需要一个可搜索的下拉选择框 输出查看 references/select-component.md这里有个细节点Skill 里的每一步并非都要模型自己想出来而是应当把合理的小决策迁移进脚本或模板。比如“按项目模板生成脚手架代码”我直接在 references 里放了一个标准模板文件模型只需要照着模板填空而不是从零构思代码。这也印证了我前面说的“Skill 是标准操作手册”的定位——它不追求创造力追求稳定。3.4 面向不同领域的 Skills 扩展数学建模、公众号文章、结构图Skills 不局限于写代码。按照同样的“何时用、怎么用、注意什么”结构任何有固定套路的知识型任务都能 Skill 化。数学建模类 Skill 是最近社区里讨论比较多的方向。比如“数模论文排版 skill”它的 SKILL.md 会把数学建模论文的标准结构摘要、问题重述、模型假设、符号说明、模型建立与求解、模型检验、优缺点评价、参考文献写清楚并提供 LaTeX 模板和摘要写作要求。模型拿到题目后按这个 Skill 产出论文骨架比直接让它“写一篇数模论文”规范得多。公众号文章技能包我最近也在用。运营类需求的特点是输出格式极其固定——标题要多少字、摘要怎么写、正文分几段、配图位置留哪、结尾引导语长什么样全部是可以模板化的。做一个“微信公众号文章排版 skill”把公众号后台的排版规范、字号行距要求、配图建议、引导关注话术整理成参考模板Agent 产出的文章能直接粘贴进后台省掉大量人工调整。结构图类是可视化需求多的人绕不开的。比如“架构图绘制 skill”它的核心不是让模型画图而是让模型先以标准结构化文本描述节点与连线关系再由脚本转换成图片。步骤很固定分析需求得到结构清单 → 按模板生成文本描述 → 执行脚本渲染 → 校验节点数量与连线完整性。模型只负责逻辑梳理绘图这种确定性操作交给代码出错率远低于直接让模型生成 SVG。4. Skills 的加载机制、向量检索与上下文管理4.1 模型如何决定“该用哪个 Skill”路由机制的底层逻辑要说清 Skills 路由我先打个比方。如果把 Agent 比作一家餐厅各类 Skills 就是后厨备好的预制菜包。模型拿到用户需求时相当于客人点单后厨需要快速决定调用哪一份菜包、跳过哪些不需要的菜包。具体到实现层大部分 agent 框架的做法分三步。第一步把当前所有可用 Skills 的名称加一句简短 description 汇总成一个索引清单放在系统提示词里或者与用户消息一起送进上下文。第二步模型根据用户输入的内容从索引清单中判断哪些 Skill 与当前任务相关然后把对应 Skill 的完整内容注入到上下文里。第三步模型在后续推理过程中按 Skill 里的步骤执行。所以 Skill 的 description 写得好不好直接决定了路由准不准。我跟同事做过一次对比实验一个 description 写的是“生成前端代码”另一个写的是“当用户要求创建 Vue 3 TypeScript 组件时使用需要设计稿或功能描述”后者的命中率明显更高误触发率也低得多。因为前者涵盖范围太大用户在讨论后端接口时模型也可能会误认为要写前端代码。4.2 Skills 数量变多之后索引膨胀与上下文压缩策略Skills 少的时候问题不大一旦 Skills 数量增长到两位数索引清单本身就会占据上下文空间。假设每个 Skill 的 description 平均 80 字20 个 Skill 就是 1600 字40 个就是 3200 字。再算上系统提示词、任务描述、历史记录上下文窗口一下子就紧张了。我目前的处理思路是分组。把 Skills 分成“核心技能”和“扩展技能”两层核心技能数量控制在 5 个以内走“全量加载”扩展技能数量不限但只保留 description 进入索引等模型判定需要时再加载完整内容。如果某个 Skill 有 2000 行参考材料全部塞进上下文显然是浪费直接让它按需读取 references 目录下的具体文件就行。另一种方案是引入向量检索。把所有 Skill 的描述和内容片段离线向量化用户请求到来时先做一次语义相似度检索选出 top 3 到 top 5 的候选 Skill再把这几个完整内容注入上下文。这个方案的好处是 Skills 数量可以做到上百个坏处是需要额外搭建向量数据库技术复杂度比纯索引方案高不少。团队里如果有同学熟悉 RAG可以直接套用现有工具链如果只是个人项目我建议先从分组方案起步够用就行。4.3 System Prompt、Skill 与用户消息的拼接顺序拼接顺序这事看着不起眼实际对执行效果影响很大。我对比过三种顺序Skill 放最前面 / 中间 / 最后总结出的最稳定方案如下先把系统提示词Agent 基础人格与行为边界放在最前面紧跟着放本次任务最相关的 1 到 3 个 Skill 完整内容最后才是用户消息。这样模型在读到用户消息时脑子里已经装进了“本次任务所需的操作手册”推理路径天然被约束在正确范围内。反过来如果先读用户消息再加载 Skill模型可能先产生了自认为合理的执行方案之后加载的 Skill 反而变成了需要“和已有思路对齐”的附加约束容易产生偏差。如果你用的是带“System / Assistant / User”消息类型的 API直接把 Skill 塞进 System 消息即可。如果用的是 PEP 模板拼单条 prompt顺序按我上面说的来。我见过有人把 Skill 内容放进了历史消息里结果模型在长对话轮次中把 Skill 内容当成了历史数据执行效果大打折扣这个坑要避开。5. 常见报错、排查流程与生态现状5.1 集中处理两个高频报错信息热词列表里出现两条高频报错“agent execution terminated due to error.” 和 “agent couldnt generate a response. please try again.”。这两条我实际项目里碰到过很多次说一下排查路径。“agent execution terminated due to error” 这个报错的本质是“执行链断裂”。最常见的原因是 Skill 引用的脚本抛了异常比如输入文件不存在、路径写错、依赖包没装、权限不足。排查思路是先把执行链路拆开单独跑脚本验证如果脚本能跑通再检查 SKILL.md 里的调用描述是否和实际脚本参数一致。我遇到过一个特别典型的坑Skill 描述里写“运行 scripts/generate.py”但那个脚本其实依赖一个不在默认环境里的 Python 包而 Agent 的执行环境是干净容器运行时就炸了。解决办法是把依赖声明写进 SKILL.md 并让 harness 自动安装或者把脚本改成无外部依赖的标准库实现。“agent couldnt generate a response” 这个报错通常意味着模型没有产生有效输出。可能原因有三类。第一类上下文被 Skill 内容撑爆模型在超长上下文里迷失方向第二类Skill 的 description 与其他 Skill 冲突模型同时加载了两个互相矛盾的 Skill推理时卡死第三类模型被要求执行一个完全没有给出正确输入或前置条件的任务无法生成合理响应。遇到这类报错我一般先做减法把所有 Skill 卸载只保留一个最小系统提示词确认模型能正常响应再一个一个加回来直到定位是哪个 Skill 或者哪段描述导致的问题。5.2 Skills 执行环境的权限与安全问题先声明一下这里说的“agent 安全”指的是工程安全也就是权限最小化、资源隔离、数据不落地这些跟其他乱七八糟的解读无关。我整理一份可控的权限清单脚本代码尽可能静态分析后再执行不要直接调 eval 或 exec 执行模型生成的代码Skill 里的脚本运行时给予独立临时目录禁止写入系统目录外部数据接口的密钥不要硬编码在 Skill 文件里走环境变量或密钥管理服务如果 Skill 会执行浏览器操作比如生成长图后截图建议用无头浏览器并在隔离容器里跑对 Skill 输出的文件大小、网络请求做限制防止模型误触发高消耗操作有同学可能觉得这些都是“大厂才需要操心的”但我在个人项目里也遭遇过 Skill 脚本把当前目录下的文件误删的情况教训是就算你自己用也要给脚本加上路径白名单校验这是个好习惯。5.3 当前生态里值得看的框架与社区工具目前各大热词里的生态已经比较热闹了我按使用场景给它们分了个类。偏通用型的 agent 框架大多原生支持 Skills适合从零搭建项目的开发者。这类框架内置了 Skill 加载、路由、上下文管理等基础能力你需要做的只是按目录结构往里放 Skill 文件。偏编码型的工具则内置了大量代码类 Skills适合程序员直接日常使用省去自己写各种编码 Skill 的功夫。偏研究演示型的框架更强调可视化和多 Agent 协作对 Skill 机制的实验性支持比较多适合跑 demo 和验证想法。社区里的开源 Skills 集合也在快速膨胀从自动化运维、代码审查、写作润色到简历优化、SQL 生成、PPT 排版应有尽有。我个人的习惯是“先用社区现成的再改造成自己的”。直接白嫖一套写好的 Skill比自己从零写速度快很多等用熟了再把不够贴合自己流程的部分逐步替换。有一点要提醒社区 Skill 质量参差不齐拿回来第一件事不是直接用而是把 SKILL.md 通读一遍看看描述是否准确脚本是否有危险调用。坑品好的 Skill 目录清晰、描述具体坑品差的连 name 和对不上跑起来能气到你脑壳疼。5.4 关于 Skill 流程设计的一些争议与反思社区里对 Skills 的讨论不全是吹捧也有批评的声音。一个比较有代表性的质疑是过度标准化的 Skill 会不会削弱模型的自主性把任务步骤写得太死模型遇到边界案例时是否反而失去灵活处理能力我自己的体会是这个质疑有一定道理但前提是“把 Skill 当成铁律而不是参照”。Skill 的定位应该是“给一个经验不足的实习生一份成熟的工作流程”而不是“给一个专家上枷锁”。所以我现在写 Skill 的时候会在“兜底策略”里留一句“如果遇到本手册未覆盖的情况基于你的判断处理并在输出中注明偏离原因”。这样既保留了 Skill 的规范性又给模型留了灵活应变的口子。另一个值得思考的问题是 Skills 与 Agent 之间的关系会不会被重新定义。现在大家普遍把 Skills 当作 Agent 的可插拔组件但如果未来某个 Agent 能自己编写、调试、组装新的 Skills那这个边界就会变得模糊。热词里有“rethinking skills and prompts”的说法底层的信号是随着任务复杂度上升大家越来越意识到“把知识写在提示词里”不如“把知识组织成可操作、可迭代、可分发的 Skill”来得可靠。6. 一套实测有效的 Skill 调试流程与上手建议6.1 从零到能跑新建 Skill 的推荐步骤写 Skill 的过程其实很像写单元测试驱动的业务代码先定输入输出再写实现最后反复调优。我按顺序推荐下面几个步骤确定这个 Skill 要解决的任务类型写下三组预期输入和对应输出搭目录结构先只写 SKILL.md用纯文本描述步骤不加脚本把 Skill 挂到 agent 上跑一条最简单的用例看看执行效果逐步加脚本和参考材料每加一项重新跑一遍回归用例收集模型执行时暴露的问题哪一步没描述清楚、哪个模板不符合预期逐一修改跑完整测试集确认没有回归后再交给团队使用中间最容易忽略的是第二步和第三步。很多人一上来就写脚本结果模型连调用脚本的参数都传不对。先只用文字版 SKILL.md 跑通流程能确定“模型理解了什么时候该用、步骤是否可执行”再上脚本调试成本会低很多。6.2 维护多个 Skill 时的版本控制与回归测试当你的 Skills 数量超过 5 个就一定得上回归测试的意识。我给每个 Skill 维护一份简单的测试清单内容就是 2 到 5 条典型输入和期望输出。每次改完某个 Skill就用这份清单跑一遍确认不要求自动化人工过一遍也行。别小看这一步我见过太多人改完一个 Skill另一个完全不相关的 Skill 因为 description 重叠而开始误触发结果线上跑了好几天才被发现。版本控制上Skills 目录我用 Git 单独管理每个 Skill 一个子目录SKILL.md 更新时提交信息写清楚改了什么规则。这样做还有个额外好处当团队里多个人同时维护 Skills 时可以像 review 代码一样 review Skill 的改动。这个体验比改提示词好太多了提示词的 diff 根本看不出意图Skill 的 diff 就像看文档变更一目了然。6.3 我的最后一个建议从自己重复过三次以上的任务开始如果你正准备尝试写第一个 Skill我强烈建议不要选那些“看起来很酷”的任务也不要一上来就做那种复杂度极高的任务。选一个你工作中已经重复过至少三次、每次都需要相同步骤的任务。这个“重复三次”的条件很关键它说明这个任务已经有稳定的执行套路适合沉淀成文档和流程而不是你一时兴起想出来的伪需求。我做第一个 Skill 选的就是“生成周报”这个任务拉取本周代码提交记录、统计任务进度、按照固定模板输出。这套流程我手动干了几个月所以写起 SKILL.md 来毫不费力全是经验沉淀。第一次跑通的时候那种“以后这活儿再也不用脑子记”的感觉只有做过的人才能体会。Skills 这套思路本质上是在回答一个问题当大模型越来越强我们还需要给 Ta 写手册吗我的答案是需要而且比任何时候都需要。因为模型的能力提升解决的是“怎么想”的问题而 Skills 解决的是“怎么做才符合你的预期”的问题。这两者叠加起来才是一个真正能在生产环境里稳定交付的 agent。