去年聊 AI Agent大家还在比谁的框架记忆模块更强、工具调用更顺到了今年你再打开任何一个 Agent 项目十有八九都会看到同一个目录skills。我最近在整理手头的 agent-skills 仓库时明显感觉到这个原本藏在角落里的概念正在变成 Agent 生态里的基础设施。所谓 Agent Skills简单说就是把一类高频任务封装成可复用、可分享、可组合的技能包让智能体在遇到相似需求时直接调用而不是每次重新理解一遍需求。它解决的是 Agent 的“即战力”问题不是让模型背更多知识而是让它在正确的时候拿出正确的操作流程。这篇内容适合三类人正在做 Agent 开发的工程师想用 Agent 替代重复劳动的效率爱好者以及刚入门大模型应用的新手。如果你已经写过很多 Prompt却总觉得不够稳定、不够通用那 Skills 大概率就是你缺的那一层封装。我不打算讲太虚的概念直接从“为什么要用”“内部结构是什么”“哪些技能值得收藏”“怎么动手写一个”四件事展开最后再把踩过的坑一股脑倒给你。1. Agent Skills 到底解决了什么问题1.1 从 Prompt 到 Skills为什么今年突然火了过去两年我们做 Agent大多是在写 Prompt。需求一变就改 Prompt模型一更新就重新调 Prompt换个平台又要复制粘贴改一遍。这种做法的最大问题不是“写不出来”而是“不可累积”。你花三天调出来的一套写代码规范换个 Agent 框架完全用不上换个任务类型又要从头来。Prompt 本质上是一次性的配方而 Skills 是把这个配方连同使用说明、示例、校验规则、甚至配套代码一起打包成可以反复调用的模块。为什么是今年因为底层模型的指令跟随能力已经足够强大家发现只要给模型一个清晰的操作手册它就能稳定完成“拆步骤、走流程、出结果”这一类任务。与其每次对话里塞一大段夹带私货的指令不如把指令拆成独立技能让 Agent 按需加载。另一个推手是各大框架和工具开始原生支持 Skills 目录你把写好的技能包丢进约定好的文件夹Agent 会自动发现并在合适的时候调用它。这种“即插即用”的体验直接把 Skills 从“概念”推成了“标准动作”。1.2 Skill、Agent、Harness、Memory 之间的关系热词里很多人搜 harness 和 agent 的区别其实还要再加上 skill 和 memory这几个词经常混在一起说但职责完全不同。我习惯用一句话概括Agent 是司机Harness 是车Skills 是驾驶技巧Memory 是行车记录仪。司机负责判断去哪儿、什么时候打方向盘车提供油门刹车、仪表盘和安全气囊驾驶技巧让司机知道怎么侧方停车行车记录仪保留之前走过的路线和乘客偏好。具体到技术实现上Agent 是决策中枢负责理解用户请求、拆解子目标、决定下一步调用谁Harness 是 Agent 运行的外部环境负责工具调用循环、权限控制、上下文窗口管理和错误处理Skills 是被 Agent 调用的能力模块里面装着完整的操作指令和示例Memory 则保存对话历史、用户偏好、项目状态这些跨任务信息。很多人混淆 Skill 和 Memory是因为它们都能影响 Agent 的行为但 Skills 回答的是“怎么做这件事”Memory 回答的是“我记得什么和你喜欢什么”。没有 MemoryAgent 是失忆的没有 SkillsAgent 是空有蛮力却不会干活的。1.3 和 Prompt、Plugin 有什么本质区别有人觉得 Skills 不就是强化版 Prompt 吗这句话对了一半。Skills 的内核确实是 Prompt但它在三个方向上做了升级可发现、可验证、可组合。可发现是指 Skill 自带 description 和触发条件Agent 能在需要时自动找到它可验证是指 Skill 可以定义输出格式和校验规则比如要求模型返回 JSON并对 JSON 结构和字段做检查失败了就自动重试可组合是指多个 Skill 可以串联成一个更大的流程比如“文章排版 Skill”加“配图生成 Skill”再加“标题优化 Skill”组合成一整条内容生产线。Plugin 和 Skills 也容易混淆。Plugin 通常是外部工具或 API 的包装器比如带鉴权的数据库查询插件、商品搜索插件Skills 则侧重内化的工作流它甚至可以不调用任何外部工具纯粹靠模型的知识和推理完成任务。更直白的区分是Plugin 给 Agent 一双新“手脚”Skills 给 Agent 一套新“操作手册”。很多成熟项目里两者会配合使用Skill 描述完流程后让 Agent 在特定步骤调 Plugin 去查实时数据。2. 深度拆解一个 Skill 的内部结构2.1 一个 Skill 的最小组成我在自己写的 agent-skills 仓库里把每个技能都固定成五个字段name、description、instructions、examples、validator。name 是技能的唯一标识要和代码风格一致比如generate-echarts-optiondescription 是一段面向模型的可搜索描述用来告诉 Agent“我这个技能是干什么用的适合什么场景不适合什么场景”instructions 是核心它是一份分步骤的操作指引告诉模型应该先做什么、再做什么、每一步要遵守什么规则examples 是少量完整的输入输出样例用来让模型快速理解格式通常放 2 到 4 个就好validator 是可选的一段校验逻辑比如用正则或 JSON Schema 检查输出是否符合要求。这五个字段缺一不可最容易出错的是 description。很多新手把 description 写成“一个生成图表的技能”结果 Agent 在判断要不要调用时根本不知道这个技能擅长柱状图还是雷达图、支持什么数据格式、输出的是代码还是图片。description 写得好不好直接决定了技能会不会被正确“唤醒”。我后来遵循的规律是描述里一定要包含“当用户想要……时使用当用户……时不建议使用”把触发边界写清楚误触发率能下降一大半。2.2 如何设计触发条件与元数据设计 Skill 时我建议大家先写元数据再写 instructions。原因是元数据决定了这个技能的“名义边界”边界越清晰后续维护越省心。以一个“结构图 Skill”为例name 可以是mermaid-structure-diagramdescription 要写成“把文字描述的层级关系、组织架构或流程步骤转换为 Mermaid 结构图语法适合给文档、PPT、公众号配图。仅处理静态结构不适合需要实时数据渲染的场景”。这里放了两个关键信息适合什么不适合什么。再往下是输入输出的约定。输入要说明字段名和类型比如“input: 一段层级列表可以用 - 表示同级缩进表示层级output: Mermaid 代码块”。如果技能有固定格式最好在 instructions 里给出模板。我习惯在指令中写“你必须输出 Markdown 代码块语言标记为 mermaid不要在代码块外加多余解释”。因为模型一旦自由发挥输出的内容就无法直接复制使用。元数据不该只给模型看也要给人看建议在 SKILL.md 顶部用 YAML 格式写一份人机共读的配置包括版本号、作者、依赖环境、最后更新时间。这样技能在团队里传播时别人扫一眼就知道能不能直接用。2.3 从好 Prompt 到好 Skill 的三道坎第一道坎是上下文管理。Skill 被加载时会占据上下文窗口如果指令写得太长留给实际任务的空间就少了。所以 instructions 里要尽量用短句和列表把“背景知识”这类高信息量内容放进 examples让模型通过例子领悟而不是通过大段理论讲解。第二道坎是错误处理。模型不会每次都能顺利走完流程Skill 里必须写明“如果第一步返回的结果不符合预期你应该尝试……”。比如生成图表数据时如果发现数值列全是字符串就提示模型先做类型转换如果代码运行报错就模块化重试。没有错误回退路径的技能跟没有备胎的汽车一样爆胎就只能停车。第三道坎是边界约束。Skill 要明确“绝不能做什么”比如内容生成类技能要说明“不要生成违法、歧视性内容”数据分析类技能要说明“不要猜测缺失值必须明确告知用户”。边界约束不是限制模型而是保护使用者。3. 值得收藏的 Skills 实战推荐3.1 前端开发与编码类 Skills最近 GitHub 上最活跃的 Skills 基本都集中在开发领域。如果你的 Agent 用来写前端至少应该收藏四类组件生成、样式调整、代码审查、重构迁移。组件生成 Skill 侧重“根据需求生成 React/Vue 组件并用 Tailwind 或 CSS Module 输出完整代码”样式调整 Skill 则要包含“识别设计稿里的色值、间距、圆角并转换成可执行的 class”。编码类 Skills 的通用套路是先让模型理解需求再写伪代码最后产出可运行的完整文件。我在 agent-skills 里常用一个叫code-review-safe的技能它的 instructions 要求模型先总结代码逻辑、再逐条列风险、最后给出修改建议每个建议都必须标注所在行号和影响范围。这让 review 结果从“一段看起来很厉害的废话”变成了可以直接贴进工单的清单。做 Agent 开发的朋友不妨也从 review 类技能入手它不涉及外部 API风险低又能快速检验 Skill 的可用性。3.2 结构图、画图与可视化类 Skills画图是 Agent 的高频需求但很多人生成的图表惨不忍睹。问题不在模型能力而在缺少一套“绘图规范 Skill”。结构图 Skill 应该包含几个要点选图指导、层级描述、配色建议、输出格式。选图指导是最容易被忽略的很多人一上来就画流程图实际可能更适合思维导图或架构图。我在 description 里会写清楚“当内容呈现父子关系时用思维导图当表示时间线时用流程图当描述依赖关系时用有向图”。可视化类技能还要注意输出格式的一致性。比如要求模型输出 Mermaid 语法就一定要在示例中给出完整的代码块。如果允许 draw.io 或 Excalidraw 格式也要分别给出模板。另一个实用小技巧是让 Skill 先复述一遍自己的绘图方案“用文字描述你打算用哪种图、节点有哪几个、连接关系是什么”确认后再输出正式结果。这个方法能避免模型绕了一大圈画出的图根本不是用户想要的。3.3 数学建模类 Skills数学建模是热词里相当有辨识度的一类 Skills。这类技能不是让模型做数学题而是帮用户把一个实际问题拆解成“模型选择—假设说明—公式推导—代码实现—灵敏度分析”五段式。我见过做得好的建模 Skill甚至会把线性规划、整数规划、回归分析、时间序列等常见模型的适用条件列成一张表让 Agent 先匹配模型再输出代码。编写数学建模 Skills 时最需要注意的是“中间过程不能跳步”。模型在数学推导时特别容易“一步到位”直接给最终公式结果一旦出错很难排查。所以指令里应该强制要求每一步都要写清变量定义、单位、约束条件并在代码注释里标出与公式的对应关系。对于参加数学建模比赛的同学建议再配一个“论文排版”子技能统一 LaTeX 或 Word 模板把结果表转成三线表格式能省下大量后期修改时间。3.4 微信公众号文章与内容创作类 Skills公众号文章相关的技能包最近很火原因是很多人用 Agent 做自媒体内容工厂但产出质量两极分化。一套合格的内容 Skill 至少应该包含主题分析、标题生成、大纲规划、正文撰写、金句提炼五个模块。标题生成要区分“信息型”和“情绪型”“信息型”标题适合干货教程“情绪型”标题适合观点文正文撰写则要规定分段长度、小标题密度、案例数量和口语化程度。我更推荐的做法是“人机共创”模式Skill 负责在初稿里插入占位符比如“这里放一个亲历案例”“这里补一组行业数据”定义好每个占位符的上下文要求再交给作者填充。这比让模型一次性输出“完美初稿”更可控。顺带提醒一句内容创作类 Skills 里不要写“模仿某位作家风格”这种既模糊又可能涉及侵权的要求应改为“用生活化类比解释复杂概念多用短句避免学术化表达”这种可执行、可判断的风格约束。3.5 数据处理与日常效率类 Skills除了上面几类数据处理类 Skills 的使用频率也很高。比如“CSV 清洗与统计”技能输入一份带脏数据的表格输出完整的清洗报告和统计结果“Markdown 表格格式化”技能可以把任意文本表格转换成对齐规范、可读性高的 MD 表格“会议纪要结构化”技能要求模型按结论、待办、负责人、截止日期四个板块输出纪要。这类技能特征是输入输出非常明确最容易写出稳定版本。日常效率类 Skills 我建议从“邮件回复”“周报总结”“PPT 大纲”这几个刚需场景入手。以周报总结为例Skill 的 instructions 可以要求模型先把碎片记录去重归类再按“做了什么—遇到什么问题—下步计划”三段重组最后压缩成不超过 300 字。这类技能本质上是把团队内部的思考框架固化成模板让 Agent 替代最耗时的“从流水账到结论”这一步。4. 手把手编写一个可复用的 Agent Skill4.1 先选场景再写代码需求拆解的四个问题动手写 Skill 之前我会强制自己回答四个问题这个技能解决什么任务任务的输入通常是怎样的输出长什么样算合格用户最不能接受的失败模式是什么这四个问题回答不完整写出来的 Skill 大概率会跑偏。以“前端组件生成”为例如果任务定义是“生成 React 组件”那输入可能是“用户需求描述”也可能是一张设计稿图片输出可能是“单文件组件”也可能是“组件代码加测试用例”。不同答案对应完全不同的实现方式。特别建议把“失败模式”前置思考。比如生成公众号文章时最不能接受的是“标题党”还是“语言像 AI”如果你禁用“像 AI 写的东西”就要在 instructions 里写清楚具体可检测的特征比如“避免使用‘综上所述’‘由此可见’‘促进发展’这类套话每段必须有一个具体案例或个人口吻的句子”。描述得越可检测模型就越不容易理解偏差。4.2 五个步骤从零搓一个 Skills 包第一步创建目录和 SKILL.md。目录名就是技能名用小写中划线连接比如react-component-generator。SKILL.md 里放元数据和 instructions。第二步写 description 和触发条件。先写 3 个“何时用”和 3 个“何时不用”的例子再回填描述文本。第三步写 instructions。我推荐用编号列表把流程固定下来每一条都尽量以动词开头例如“提取输入中的关键需求”“判断是否需要外部依赖”“生成符合 TypeScript 规范的组件代码”。指令的粒度控制在“一个步骤执行一个动作”。第四步添加 examples。这一步最考验功力好的 example 不只是输出样例还要包含“为什么这么做”的简短说明。你可以在示例里加注释比如“这里把按钮尺寸提取为 prop 是因为业务侧经常需要调整”。第五步加 validator。对于一些格式敏感型 Skill比如 Mermaid 语法、JSON 数据、SQL 语句validator 能自动检查输出是否可解析。最简单的做法是在 Skill 的配套脚本里写一个函数把模型输出喂进去解析失败就返回“请按指定格式重新输出”。4.3 测试与发布怎么判断 Skill 是合格的Skill 写完一定要测试尤其是“垃圾输入”测试。我会准备一组边界输入输入为空、格式不符合说明、语义模糊、包含与任务无关的闲聊。好的 Skill 应该在这些情况下给出友好提示而不是硬着头皮生成错误结果。测试时还要注意不同模型的兼容性。同一个 Skill 在 Claude 上表现良好换到开源模型上可能就崩了因为指令跟随能力和弱模型对格式的理解差异很大。如果目标用户可能用多种模型建议在 Skill 里增加“最低模型能力要求”并在描述里标注。发布到社区时一份清晰的 README 比代码更重要。我会固定写几个栏目技能简介、安装方法、输入输出示例、版本记录、已知限制。版本记录尤其重要模型能力更新后原来有效的指令可能失效你需要记录每次改动的原因和效果。这个习惯不仅让别人好跟进也方便你自己三个月后回来维护。5. Agent Skills 踩坑实录与排查技巧5.1 常见翻车现场与根本原因我最早写的“文章摘要 Skill”翻过一个大车无论输入什么文章它都只输出第一段的内容因为我在 instructions 里写了“保留开头信息”模型误以为摘要必须从第一段提取。后来我把指令改成“通读全文后用不超过三句话概括核心观点禁止直接引述首段”问题才解决。这个案例说明Skill 的指令语义必须非常精确特别是“可以”这类委婉词模型往往会过度解读。另一个高频翻车是上下文污染。当一个 Skill 被反复调用时前一轮的输出会残留到后一轮导致第二次生成立即出错。比如画图 Skill 第一次生成了 ECharts 配置第二次让它改颜色结果模型把整个配置重生成了一遍。解决办法是在 instructions 里明确“只输出需要修改的片段不要输出完整文件除非用户要求”。第三个翻车点是输出格式漂移同一个 Skill 今天输出 JSON 明天输出 Markdown。这种情况通常是因为示例不够强或者 validator 缺失模型没有必须遵守格式的强制约束。5.2 问题排查速查表如果 Agent 调用了 Skill 但效果不对先不要急着改 prompt按照下面这张表快速定位症状可能原因处理办法模型完全不调用 Skilldescription 与用户意图不匹配重写 description加入触发词和反触发条件调用了但是输出不符合要求instructions 粒度太粗拆成编号步骤每步只做一件事同样的输入输出结果每次都不一样缺少示例或 validator增加固定格式示例加入输出校验第一次成功第二次开始出错上下文残留在指令末尾增加“只输出本次需求对应内容”换一个模型就失效指令依赖了特定模型的表达习惯去掉只有某模型才懂的词汇改为通用描述技能执行太慢占用大量 token指令冗余、上下文过长精简背景描述把信息密度移到 examples这张表我打印出来贴在工位旁边每次技能出问题就按“症状—原因—方案”排查比自己瞎试快得多。很多人遇到 Skill 失效第一反应是“模型变笨了”但大多数情况下是你的 Skill 没有给模型足够的确定性。5.3 提高 Skill 鲁棒性的五个技巧第一用“必须/禁止”这类强约束词替代“尽量/可以”。模型的概率采样对强制词的响应明显更强比如“你必须输出 JSON”比“最好输出 JSON”稳定得多。第二给每个步骤设定“检查点”。比如写完伪代码后要求模型自己检查一遍是否覆盖了所有需求点再把最终代码写出来。这种 self-check 能让最终结果质量提升不少。第三让 validator 真正生效。如果平台支持在后处理里跑脚本就尽量在 Skill 目录里放一个validate.js而不是只靠模型自觉。第四从第三方仓库下载 Skills 时要特别小心。Skill 本质上是一段有权限的指令来源不明的技能可能诱导模型输出敏感数据或执行危险操作尽量使用活跃度高、更新频繁、作者信息可查的技能包。第五给 Skill 设置版本约束。模型一升级有些原先能跑的指令就失效了建议在 Skill 元数据里注明“已验证模型版本”升级大版本后重新跑一遍回归测试。最后再分享一个小技巧我把 agent-skills 仓库里每个 Skill 都配了一个SMOKE_TEST.md记录一个最简单的输入和一个期望输出。改完任何底层模型或框架先跑一遍 smoke test基本能在五分钟内判断哪些技能受影响。这个小动作看似多余却帮我避免了好几次线上事故。如果你也维护了不少 Skills强烈建议从今天开始补上这层保险。 
长河君 · 2026/9/18 0:52:40 · 阅读 1.2k Agent Skills 实战指南：从 Prompt 到可复用技能包的完整进化路径
去年聊 AI Agent大家还在比谁的框架记忆模块更强、工具调用更顺到了今年你再打开任何一个 Agent 项目十有八九都会看到同一个目录skills。我最近在整理手头的 agent-skills 仓库时明显感觉到这个原本藏在角落里的概念正在变成 Agent 生态里的基础设施。所谓 Agent Skills简单说就是把一类高频任务封装成可复用、可分享、可组合的技能包让智能体在遇到相似需求时直接调用而不是每次重新理解一遍需求。它解决的是 Agent 的“即战力”问题不是让模型背更多知识而是让它在正确的时候拿出正确的操作流程。这篇内容适合三类人正在做 Agent 开发的工程师想用 Agent 替代重复劳动的效率爱好者以及刚入门大模型应用的新手。如果你已经写过很多 Prompt却总觉得不够稳定、不够通用那 Skills 大概率就是你缺的那一层封装。我不打算讲太虚的概念直接从“为什么要用”“内部结构是什么”“哪些技能值得收藏”“怎么动手写一个”四件事展开最后再把踩过的坑一股脑倒给你。1. Agent Skills 到底解决了什么问题1.1 从 Prompt 到 Skills为什么今年突然火了过去两年我们做 Agent大多是在写 Prompt。需求一变就改 Prompt模型一更新就重新调 Prompt换个平台又要复制粘贴改一遍。这种做法的最大问题不是“写不出来”而是“不可累积”。你花三天调出来的一套写代码规范换个 Agent 框架完全用不上换个任务类型又要从头来。Prompt 本质上是一次性的配方而 Skills 是把这个配方连同使用说明、示例、校验规则、甚至配套代码一起打包成可以反复调用的模块。为什么是今年因为底层模型的指令跟随能力已经足够强大家发现只要给模型一个清晰的操作手册它就能稳定完成“拆步骤、走流程、出结果”这一类任务。与其每次对话里塞一大段夹带私货的指令不如把指令拆成独立技能让 Agent 按需加载。另一个推手是各大框架和工具开始原生支持 Skills 目录你把写好的技能包丢进约定好的文件夹Agent 会自动发现并在合适的时候调用它。这种“即插即用”的体验直接把 Skills 从“概念”推成了“标准动作”。1.2 Skill、Agent、Harness、Memory 之间的关系热词里很多人搜 harness 和 agent 的区别其实还要再加上 skill 和 memory这几个词经常混在一起说但职责完全不同。我习惯用一句话概括Agent 是司机Harness 是车Skills 是驾驶技巧Memory 是行车记录仪。司机负责判断去哪儿、什么时候打方向盘车提供油门刹车、仪表盘和安全气囊驾驶技巧让司机知道怎么侧方停车行车记录仪保留之前走过的路线和乘客偏好。具体到技术实现上Agent 是决策中枢负责理解用户请求、拆解子目标、决定下一步调用谁Harness 是 Agent 运行的外部环境负责工具调用循环、权限控制、上下文窗口管理和错误处理Skills 是被 Agent 调用的能力模块里面装着完整的操作指令和示例Memory 则保存对话历史、用户偏好、项目状态这些跨任务信息。很多人混淆 Skill 和 Memory是因为它们都能影响 Agent 的行为但 Skills 回答的是“怎么做这件事”Memory 回答的是“我记得什么和你喜欢什么”。没有 MemoryAgent 是失忆的没有 SkillsAgent 是空有蛮力却不会干活的。1.3 和 Prompt、Plugin 有什么本质区别有人觉得 Skills 不就是强化版 Prompt 吗这句话对了一半。Skills 的内核确实是 Prompt但它在三个方向上做了升级可发现、可验证、可组合。可发现是指 Skill 自带 description 和触发条件Agent 能在需要时自动找到它可验证是指 Skill 可以定义输出格式和校验规则比如要求模型返回 JSON并对 JSON 结构和字段做检查失败了就自动重试可组合是指多个 Skill 可以串联成一个更大的流程比如“文章排版 Skill”加“配图生成 Skill”再加“标题优化 Skill”组合成一整条内容生产线。Plugin 和 Skills 也容易混淆。Plugin 通常是外部工具或 API 的包装器比如带鉴权的数据库查询插件、商品搜索插件Skills 则侧重内化的工作流它甚至可以不调用任何外部工具纯粹靠模型的知识和推理完成任务。更直白的区分是Plugin 给 Agent 一双新“手脚”Skills 给 Agent 一套新“操作手册”。很多成熟项目里两者会配合使用Skill 描述完流程后让 Agent 在特定步骤调 Plugin 去查实时数据。2. 深度拆解一个 Skill 的内部结构2.1 一个 Skill 的最小组成我在自己写的 agent-skills 仓库里把每个技能都固定成五个字段name、description、instructions、examples、validator。name 是技能的唯一标识要和代码风格一致比如generate-echarts-optiondescription 是一段面向模型的可搜索描述用来告诉 Agent“我这个技能是干什么用的适合什么场景不适合什么场景”instructions 是核心它是一份分步骤的操作指引告诉模型应该先做什么、再做什么、每一步要遵守什么规则examples 是少量完整的输入输出样例用来让模型快速理解格式通常放 2 到 4 个就好validator 是可选的一段校验逻辑比如用正则或 JSON Schema 检查输出是否符合要求。这五个字段缺一不可最容易出错的是 description。很多新手把 description 写成“一个生成图表的技能”结果 Agent 在判断要不要调用时根本不知道这个技能擅长柱状图还是雷达图、支持什么数据格式、输出的是代码还是图片。description 写得好不好直接决定了技能会不会被正确“唤醒”。我后来遵循的规律是描述里一定要包含“当用户想要……时使用当用户……时不建议使用”把触发边界写清楚误触发率能下降一大半。2.2 如何设计触发条件与元数据设计 Skill 时我建议大家先写元数据再写 instructions。原因是元数据决定了这个技能的“名义边界”边界越清晰后续维护越省心。以一个“结构图 Skill”为例name 可以是mermaid-structure-diagramdescription 要写成“把文字描述的层级关系、组织架构或流程步骤转换为 Mermaid 结构图语法适合给文档、PPT、公众号配图。仅处理静态结构不适合需要实时数据渲染的场景”。这里放了两个关键信息适合什么不适合什么。再往下是输入输出的约定。输入要说明字段名和类型比如“input: 一段层级列表可以用 - 表示同级缩进表示层级output: Mermaid 代码块”。如果技能有固定格式最好在 instructions 里给出模板。我习惯在指令中写“你必须输出 Markdown 代码块语言标记为 mermaid不要在代码块外加多余解释”。因为模型一旦自由发挥输出的内容就无法直接复制使用。元数据不该只给模型看也要给人看建议在 SKILL.md 顶部用 YAML 格式写一份人机共读的配置包括版本号、作者、依赖环境、最后更新时间。这样技能在团队里传播时别人扫一眼就知道能不能直接用。2.3 从好 Prompt 到好 Skill 的三道坎第一道坎是上下文管理。Skill 被加载时会占据上下文窗口如果指令写得太长留给实际任务的空间就少了。所以 instructions 里要尽量用短句和列表把“背景知识”这类高信息量内容放进 examples让模型通过例子领悟而不是通过大段理论讲解。第二道坎是错误处理。模型不会每次都能顺利走完流程Skill 里必须写明“如果第一步返回的结果不符合预期你应该尝试……”。比如生成图表数据时如果发现数值列全是字符串就提示模型先做类型转换如果代码运行报错就模块化重试。没有错误回退路径的技能跟没有备胎的汽车一样爆胎就只能停车。第三道坎是边界约束。Skill 要明确“绝不能做什么”比如内容生成类技能要说明“不要生成违法、歧视性内容”数据分析类技能要说明“不要猜测缺失值必须明确告知用户”。边界约束不是限制模型而是保护使用者。3. 值得收藏的 Skills 实战推荐3.1 前端开发与编码类 Skills最近 GitHub 上最活跃的 Skills 基本都集中在开发领域。如果你的 Agent 用来写前端至少应该收藏四类组件生成、样式调整、代码审查、重构迁移。组件生成 Skill 侧重“根据需求生成 React/Vue 组件并用 Tailwind 或 CSS Module 输出完整代码”样式调整 Skill 则要包含“识别设计稿里的色值、间距、圆角并转换成可执行的 class”。编码类 Skills 的通用套路是先让模型理解需求再写伪代码最后产出可运行的完整文件。我在 agent-skills 里常用一个叫code-review-safe的技能它的 instructions 要求模型先总结代码逻辑、再逐条列风险、最后给出修改建议每个建议都必须标注所在行号和影响范围。这让 review 结果从“一段看起来很厉害的废话”变成了可以直接贴进工单的清单。做 Agent 开发的朋友不妨也从 review 类技能入手它不涉及外部 API风险低又能快速检验 Skill 的可用性。3.2 结构图、画图与可视化类 Skills画图是 Agent 的高频需求但很多人生成的图表惨不忍睹。问题不在模型能力而在缺少一套“绘图规范 Skill”。结构图 Skill 应该包含几个要点选图指导、层级描述、配色建议、输出格式。选图指导是最容易被忽略的很多人一上来就画流程图实际可能更适合思维导图或架构图。我在 description 里会写清楚“当内容呈现父子关系时用思维导图当表示时间线时用流程图当描述依赖关系时用有向图”。可视化类技能还要注意输出格式的一致性。比如要求模型输出 Mermaid 语法就一定要在示例中给出完整的代码块。如果允许 draw.io 或 Excalidraw 格式也要分别给出模板。另一个实用小技巧是让 Skill 先复述一遍自己的绘图方案“用文字描述你打算用哪种图、节点有哪几个、连接关系是什么”确认后再输出正式结果。这个方法能避免模型绕了一大圈画出的图根本不是用户想要的。3.3 数学建模类 Skills数学建模是热词里相当有辨识度的一类 Skills。这类技能不是让模型做数学题而是帮用户把一个实际问题拆解成“模型选择—假设说明—公式推导—代码实现—灵敏度分析”五段式。我见过做得好的建模 Skill甚至会把线性规划、整数规划、回归分析、时间序列等常见模型的适用条件列成一张表让 Agent 先匹配模型再输出代码。编写数学建模 Skills 时最需要注意的是“中间过程不能跳步”。模型在数学推导时特别容易“一步到位”直接给最终公式结果一旦出错很难排查。所以指令里应该强制要求每一步都要写清变量定义、单位、约束条件并在代码注释里标出与公式的对应关系。对于参加数学建模比赛的同学建议再配一个“论文排版”子技能统一 LaTeX 或 Word 模板把结果表转成三线表格式能省下大量后期修改时间。3.4 微信公众号文章与内容创作类 Skills公众号文章相关的技能包最近很火原因是很多人用 Agent 做自媒体内容工厂但产出质量两极分化。一套合格的内容 Skill 至少应该包含主题分析、标题生成、大纲规划、正文撰写、金句提炼五个模块。标题生成要区分“信息型”和“情绪型”“信息型”标题适合干货教程“情绪型”标题适合观点文正文撰写则要规定分段长度、小标题密度、案例数量和口语化程度。我更推荐的做法是“人机共创”模式Skill 负责在初稿里插入占位符比如“这里放一个亲历案例”“这里补一组行业数据”定义好每个占位符的上下文要求再交给作者填充。这比让模型一次性输出“完美初稿”更可控。顺带提醒一句内容创作类 Skills 里不要写“模仿某位作家风格”这种既模糊又可能涉及侵权的要求应改为“用生活化类比解释复杂概念多用短句避免学术化表达”这种可执行、可判断的风格约束。3.5 数据处理与日常效率类 Skills除了上面几类数据处理类 Skills 的使用频率也很高。比如“CSV 清洗与统计”技能输入一份带脏数据的表格输出完整的清洗报告和统计结果“Markdown 表格格式化”技能可以把任意文本表格转换成对齐规范、可读性高的 MD 表格“会议纪要结构化”技能要求模型按结论、待办、负责人、截止日期四个板块输出纪要。这类技能特征是输入输出非常明确最容易写出稳定版本。日常效率类 Skills 我建议从“邮件回复”“周报总结”“PPT 大纲”这几个刚需场景入手。以周报总结为例Skill 的 instructions 可以要求模型先把碎片记录去重归类再按“做了什么—遇到什么问题—下步计划”三段重组最后压缩成不超过 300 字。这类技能本质上是把团队内部的思考框架固化成模板让 Agent 替代最耗时的“从流水账到结论”这一步。4. 手把手编写一个可复用的 Agent Skill4.1 先选场景再写代码需求拆解的四个问题动手写 Skill 之前我会强制自己回答四个问题这个技能解决什么任务任务的输入通常是怎样的输出长什么样算合格用户最不能接受的失败模式是什么这四个问题回答不完整写出来的 Skill 大概率会跑偏。以“前端组件生成”为例如果任务定义是“生成 React 组件”那输入可能是“用户需求描述”也可能是一张设计稿图片输出可能是“单文件组件”也可能是“组件代码加测试用例”。不同答案对应完全不同的实现方式。特别建议把“失败模式”前置思考。比如生成公众号文章时最不能接受的是“标题党”还是“语言像 AI”如果你禁用“像 AI 写的东西”就要在 instructions 里写清楚具体可检测的特征比如“避免使用‘综上所述’‘由此可见’‘促进发展’这类套话每段必须有一个具体案例或个人口吻的句子”。描述得越可检测模型就越不容易理解偏差。4.2 五个步骤从零搓一个 Skills 包第一步创建目录和 SKILL.md。目录名就是技能名用小写中划线连接比如react-component-generator。SKILL.md 里放元数据和 instructions。第二步写 description 和触发条件。先写 3 个“何时用”和 3 个“何时不用”的例子再回填描述文本。第三步写 instructions。我推荐用编号列表把流程固定下来每一条都尽量以动词开头例如“提取输入中的关键需求”“判断是否需要外部依赖”“生成符合 TypeScript 规范的组件代码”。指令的粒度控制在“一个步骤执行一个动作”。第四步添加 examples。这一步最考验功力好的 example 不只是输出样例还要包含“为什么这么做”的简短说明。你可以在示例里加注释比如“这里把按钮尺寸提取为 prop 是因为业务侧经常需要调整”。第五步加 validator。对于一些格式敏感型 Skill比如 Mermaid 语法、JSON 数据、SQL 语句validator 能自动检查输出是否可解析。最简单的做法是在 Skill 的配套脚本里写一个函数把模型输出喂进去解析失败就返回“请按指定格式重新输出”。4.3 测试与发布怎么判断 Skill 是合格的Skill 写完一定要测试尤其是“垃圾输入”测试。我会准备一组边界输入输入为空、格式不符合说明、语义模糊、包含与任务无关的闲聊。好的 Skill 应该在这些情况下给出友好提示而不是硬着头皮生成错误结果。测试时还要注意不同模型的兼容性。同一个 Skill 在 Claude 上表现良好换到开源模型上可能就崩了因为指令跟随能力和弱模型对格式的理解差异很大。如果目标用户可能用多种模型建议在 Skill 里增加“最低模型能力要求”并在描述里标注。发布到社区时一份清晰的 README 比代码更重要。我会固定写几个栏目技能简介、安装方法、输入输出示例、版本记录、已知限制。版本记录尤其重要模型能力更新后原来有效的指令可能失效你需要记录每次改动的原因和效果。这个习惯不仅让别人好跟进也方便你自己三个月后回来维护。5. Agent Skills 踩坑实录与排查技巧5.1 常见翻车现场与根本原因我最早写的“文章摘要 Skill”翻过一个大车无论输入什么文章它都只输出第一段的内容因为我在 instructions 里写了“保留开头信息”模型误以为摘要必须从第一段提取。后来我把指令改成“通读全文后用不超过三句话概括核心观点禁止直接引述首段”问题才解决。这个案例说明Skill 的指令语义必须非常精确特别是“可以”这类委婉词模型往往会过度解读。另一个高频翻车是上下文污染。当一个 Skill 被反复调用时前一轮的输出会残留到后一轮导致第二次生成立即出错。比如画图 Skill 第一次生成了 ECharts 配置第二次让它改颜色结果模型把整个配置重生成了一遍。解决办法是在 instructions 里明确“只输出需要修改的片段不要输出完整文件除非用户要求”。第三个翻车点是输出格式漂移同一个 Skill 今天输出 JSON 明天输出 Markdown。这种情况通常是因为示例不够强或者 validator 缺失模型没有必须遵守格式的强制约束。5.2 问题排查速查表如果 Agent 调用了 Skill 但效果不对先不要急着改 prompt按照下面这张表快速定位症状可能原因处理办法模型完全不调用 Skilldescription 与用户意图不匹配重写 description加入触发词和反触发条件调用了但是输出不符合要求instructions 粒度太粗拆成编号步骤每步只做一件事同样的输入输出结果每次都不一样缺少示例或 validator增加固定格式示例加入输出校验第一次成功第二次开始出错上下文残留在指令末尾增加“只输出本次需求对应内容”换一个模型就失效指令依赖了特定模型的表达习惯去掉只有某模型才懂的词汇改为通用描述技能执行太慢占用大量 token指令冗余、上下文过长精简背景描述把信息密度移到 examples这张表我打印出来贴在工位旁边每次技能出问题就按“症状—原因—方案”排查比自己瞎试快得多。很多人遇到 Skill 失效第一反应是“模型变笨了”但大多数情况下是你的 Skill 没有给模型足够的确定性。5.3 提高 Skill 鲁棒性的五个技巧第一用“必须/禁止”这类强约束词替代“尽量/可以”。模型的概率采样对强制词的响应明显更强比如“你必须输出 JSON”比“最好输出 JSON”稳定得多。第二给每个步骤设定“检查点”。比如写完伪代码后要求模型自己检查一遍是否覆盖了所有需求点再把最终代码写出来。这种 self-check 能让最终结果质量提升不少。第三让 validator 真正生效。如果平台支持在后处理里跑脚本就尽量在 Skill 目录里放一个validate.js而不是只靠模型自觉。第四从第三方仓库下载 Skills 时要特别小心。Skill 本质上是一段有权限的指令来源不明的技能可能诱导模型输出敏感数据或执行危险操作尽量使用活跃度高、更新频繁、作者信息可查的技能包。第五给 Skill 设置版本约束。模型一升级有些原先能跑的指令就失效了建议在 Skill 元数据里注明“已验证模型版本”升级大版本后重新跑一遍回归测试。最后再分享一个小技巧我把 agent-skills 仓库里每个 Skill 都配了一个SMOKE_TEST.md记录一个最简单的输入和一个期望输出。改完任何底层模型或框架先跑一遍 smoke test基本能在五分钟内判断哪些技能受影响。这个小动作看似多余却帮我避免了好几次线上事故。如果你也维护了不少 Skills强烈建议从今天开始补上这层保险。