1. Agent Skills 到底是什么先搞清楚概念再动手这两年 AI Agent 相关的概念一个接一个往外冒MCP、Tools、Skills、Planner、Memory、多 Agent 编排很多人还没搞懂上一个下一个又来了。我接到不少朋友私信问同一个问题天天听人说 agent skills这玩意儿和 Tools 到底有什么区别为什么有人说它是 Agent 能力的下一站有人却说就是个 Markdown 文件先说结论Agent Skills 本质上是一种可复用的能力封装单元它把完成某一类任务所需要的指令、流程、上下文知识、示例代码、约束规则打包成一个独立模块让 Agent 在遇到对应场景时能够按图索骥式地调取使用。我最早接触 Skills 是从 Claude 的 Agent Skills 功能开始的。当时官方的定义就一句话Skills 是能增强 Agent 能力的指令集合学习过后Agent 就能更好地处理文档、生成视频或完成任何你能写进规则里的任务。这句话看着轻飘飘的但拆开来看信息量很大——它强调的是学习和增强而不是调用和执行。1.1 Skills 与传统工具Tools的本质区别很多刚入门的同学会把 Skills 和 Tools 划等号这是最常见的误区。为了讲清楚这个区别我做一个通俗类比Tools 就像你家里工具箱里的螺丝刀、扳手、电钻。每件工具只做一件事你要拧螺丝就拿螺丝刀要钻孔就换电钻。对应到 Agent 上一个 Tool 就是一个原子化的函数调用比如搜索网页读取文件发送邮件输入输出标准明确不支持复杂的多步骤推理。Skills 更像是老师傅的操作手册。它不只告诉你用什么工具还告诉你整套操作的流程先观察工件材质再决定用哪种钻头钻孔时转速调多少遇到木头开裂要怎么补救。也就是说Skills 是在 Tools 之上的一层抽象它封装的是怎么做事的完整套路而不仅是做什么的单点能力。这个区别直接决定了使用方式维度ToolsSkills粒度原子操作完整工作流触发方式显式调用按场景自动匹配内容形态函数/接口指令流程示例约束维护成本低较高需持续迭代扩展性单点能力可组合、可叠加典型代表WebSearch、FileRead写周报、做竞品分析、修 Bug理解了这层区别再回看市面上的各种 Agent 平台就不难发现凡是主打WorkflowAutomationTemplate的本质上都是在做 Skills 层面的事情凡是提供Function CallingPlugin API的更多是在做 Tools 层面的集成。1.2 一个 Skill 的典型组成结构官方给出的 Skill 标准结构其实非常朴素核心就是一个文件夹里面装着让它跑起来的全部家当。我当时第一次看到这个结构时心想就这但实际用了几个之后才发现恰恰是这种朴素让它具备了极强的通用性——不绑定任何特定框架纯文本可读任何 Agent 系统都能消化。一个标准的 Skill 目录大致长这样skill-name/ ├── SKILL.md # 核心指令文件Agent 首先读取它 ├── scripts/ # 可执行的辅助脚本 │ ├── run.py │ └── utils.py ├── assets/ # 静态资源如模板、样例数据 │ └── template.docx ├── examples/ # 示例输入输出帮助 Agent 理解使用场景 │ └── demo.pdf └── requirements.txt # 依赖声明如有需要KILL.md 是这个结构的灵魂。它不是代码而是写给 Agent 看的说明书通常包含这几个板块能力描述这个 Skill 能做什么、不能做什么边界划清楚适用场景什么情况下使用它什么情况下不适用执行流程一步步怎么做最好有编号步骤调用规范需要什么输入、产出什么格式注意事项边界情况、错误处理、安全约束我看过很多失败的 Skill 案例几乎都是栽在同一个地方写 SKILL.md 的时候把它当成了给自己看的开发笔记满篇都是代码片段和技术细节却忘了 Agent 需要的是动作指令。写 Skill 和写 API 文档有本质区别API 文档是给人看的Skill 指令是给模型看的模型的阅读理解能力决定了你必须用清晰的流程化语言而非零散的技术片段。2. 设计 Agent Skill 的核心思路与方法搞清楚 Skills 是什么之后更大的问题来了怎么设计一个真正好用的 Skill我见过太多人一上来就闷头写指令写完一测发现 Agent 根本不按预期执行要么答非所问要么输出一堆废话。问题出在设计 Skills 的核心不是写指令而是建模任务。2.1 从真实需求出发什么任务适合做成 Skill不是所有任务都适合封装成 Skill。我用一个筛选标准来判断分享给大家参考第一高频且有固定套路。如果一个任务你每周都要让 Agent 做一次每次的操作步骤几乎一样那它就是 Skill 的绝佳候选。比如生成本周项目周报对竞品官网做功能梳理把会议纪要整理成待办清单。这类任务指令稳定、产出确定Agent 学会一次就能反复用。第二流程可以显式化。Skills 强在把隐性经验变成显式步骤。如果你自己都说不清做这件事有几个步骤、每一步怎么判断那你也没办法教会 Agent。我有个用户想做一个电商详情页文案优化的 Skill但他自己写文案的过程是凭感觉的根本提炼不出步骤。这种任务现阶段不太适合做成 Skill更适合先用几次少样本提示词等流程固化下来再封装。第三有清晰的验收标准。这个点很多人忽略。你做出来的 Skill 到底有没有效必须有一个可量化的判断方式——输出的字数、格式、是否符合模板、关键字段是否齐全。如果验收标准模糊Agent 每次输出的结果都会看起来差不多但总差点意思你也没法迭代。不适合做成 Skill 的典型反例需要实时联网决策的复杂推理任务、高度依赖人工审美判断的任务、涉及多轮人机交互的开放式任务。这些更适合直接对话或做成独立 Agent硬塞进 Skill 结构里只会两头不讨好。2.2 Skill 设计的三个关键维度想清楚做什么之后就要开始设计 Skill 的内部结构。我把它拆成三个维度触发条件When、执行流程How、产出规范What。三者缺一不可而且顺序不能乱。先看触发条件。Agent 面对一个请求时会先判断这活儿我能不能干能的话用哪个 Skill。所以 SKILL.md 的第一段必须是清晰的能力声明包括触发关键词、适用对象、边界排除。我习惯这样写# Skill: WeeklyReportGenerator ## Capability 生成研发团队每周项目周报支持多项目合并、进度汇总、风险标注。 输入本周 commits 列表、任务看板快照、成员备注可选。 输出结构化周报 Markdown 文档。 ## Do Not Use This Skill When - 需要生成的是月度或季度报告此时应使用 PeriodReportGenerator - 需要实时抓取线上数据应配合 Database Query 工具 - 用户仅需要简单的文字总结直接对话即可注意最后一条主动声明不适用场景和声明适用场景同样重要。Agent 的选型判断是概率性的你给它明确的负例它就越不容易误触发。再看执行流程。这是 Skill 的骨架我强烈建议用编号步骤列出每个步骤都尽量包含可操作的判断条件。比如生成周报的流程可能是收集素材检查输入完整性按项目维度归并 commits 记录对照看板快照提取任务状态识别风险项有阻塞标记或逾期记录按模板生成报告填充各板块自检输出是否包含全部必填字段每一个步骤都对应 Agent 的一次推理-行动循环。步骤越细不确定性越小执行越稳定。最后是产出规范。这里最容易犯的毛病是只写输出周报四个字导致 Agent 自由发挥。正确做法是给出模板骨架、字段说明、示例输出## Output Format 必须包含以下板块 - 本期概览3-5 条要点 - 项目进度明细项目名 / 状态 / 本周工作 / 下周计划 - 风险与阻塞无风险则写无 - 附录raw commit 列表如果你有理想的标准输出文件直接放到 examples/ 目录里比写一百字描述都管用。Agent 对从样例中模仿的能力远超从文字描述中理解。2.3 编写高质量 SKILL.md 的实操要点写 SKILL.md 这东西文字越少越好、指令越具体越好。我踩过坑之后总结出几条硬规则第一用祈使句别用描述句。写检查输入是否包含 commits 列表若缺失则要求用户补充而不是该 Skill 需要检查输入的完整性。前者是命令后者是陈述模型对命令的遵循度高一个量级。第二给足负面样例。告诉 Agent不要做什么往往比要做什么更有效。比如不要在周报中直接粘贴完整 commit 详情应归纳为 3-5 条要点不要使用 etc. 这类含糊表述所有状态必须明确标注为正常/阻塞/有风险。第三约束输出长度和粒度。模型对简洁详细这类模糊词的理解很不稳定但你对长度的约束是相对稳定的。与其写周报要简洁不如写每项目进度描述不超过 50 字整份报告不超过 800 字。第四把依赖声明清楚。如果 Skill 需要调用其他能力比如读取某个文件、访问某个数据库必须在 SKILL.md 里写清楚调用什么工具、按什么顺序调用。Agent 不是一个全知全能的大脑它更像一个看到说明书就会照着做的实习生——你写得越清楚它执行得越靠谱。3. Skill 开发实操从零到一完整流程理论讲完了下面进入真正的动手环节。我用一个完整的例子带大家走一遍开发一个代码评审报告生成的 Skill。这个场景足够典型——有输入 (代码 diff)、有流程 (分析-分类-打分-生成报告)、有产出 (结构化报告)而且几乎所有研发团队都用得上。3.1 环境准备与基础框架选择开发 Skills 本身不依赖任何特定框架你需要的只是一个支持 Agent 运行的环境比如 Claude API、Codex CLI、或者自建的 Agent 框架以及一个存放 Skill 的目录。为了演示我以最通用的方式为例用的是一个简单的 Python 脚本配合 API 调用的模式。在选择框架时有几个判断依据供参考可移植性优先优先选择符合标准目录结构 (SKILL.md scripts assets) 的封装方式这样未来换平台时迁移成本低轻量优先Skills 的核心是指令和流程不是代码框架。如果动不动就引入依赖、搞复杂抽象那就违背了 Skills 的初衷测试友好优先选择能快速单独运行、单独测试 Skill 的框架方便迭代我自己实际开发时最常用的组合是一个简单的 Python 脚本作为 Skill 的可执行载体SKILL.md 负责指令一个 test 脚本用于验证输出。不引入任何重型框架开发效率和调试效率反而最高。3.2 第一个 Skill 的完整实现我们来写这个代码评审报告生成Skill。先建目录结构code-review-skill/ ├── SKILL.md ├── scripts/ │ ├── analyze_diff.py │ └── formatter.py └── examples/ └── sample_report.md然后写 SKILL.md这是核心我尽量写得给 Agent 看而不是给人看# Skill: CodeReviewReporter ## Capability 分析代码 diff识别潜在问题bug 风险、性能问题、安全漏洞、代码风格生成结构化评审报告。 ## Input - diff_text代码变更内容必须包含 diff 格式 - context可选的 PR 描述、相关需求背景 ## Execution Steps 1. 通读 diff理解变更目的和影响范围 2. 按以下维度逐条分析每个变更点 - Correctness是否有逻辑错误、边界遗漏 - Performance是否有性能隐患循环嵌套、未索引查询等 - Security是否有安全风险注入、敏感信息泄露等 - Maintainability是否可读可维护命名、重复代码、魔法值 3. 对每个问题标注严重级别S1 必须修复 / S2 建议修复 / S3 可选优化 4. 按模板生成报告 ## Output Format markdown ## 评审总结 - 变更范围... - 风险等级... - 问题数量S1 x 个 / S2 x 个 / S3 x 个 ## 问题明细 ### [S1] 问题描述 - 位置... - 原因... - 修复建议... ## 优化建议 - ... ## 备注 ...Constraints只评审 diff 中实际变更的内容不评论未变更代码不输出代码风格统一建议这类空泛意见必须有具体位置和原因若 diff 为空或无法解析输出错误信息不要伪造评审结果实际的代码文件我就不全部放上来了核心逻辑就是解析 diff、提取变更内容、然后通过 API 让模型按照 SKILL.md 的流程执行最后格式化输出。这样的结构好处是**模型负责推理判断代码负责格式化和稳定性**各司其职。 ### 3.3 测试与迭代让 Skill 真正好用 开发完一个 Skill最重要的环节其实是测试。我见过太多人写完就上线然后被实际效果教育被迫回炉。我的测试方法分三层 **第一层单元测试。** 准备几组典型的输入包括正常用例、边界用例空 diff、超大 diff、异常用例非 diff 格式的文本逐个跑一遍看输出是否符合预期格式。这层主要验证流程跑通、输出结构稳定。 **第二层对抗测试。** 故意给 Skill 一些意料之外的输入比如带有很多注释的 diff、包含删除大量代码的 diff、跨多个文件的 diff。目的是暴露 SKILL.md 中的盲区——Agent 会怎么处理没写清楚的情况。我做过一次实验输入全是删除代码的 diff结果模型差点输出本次变更无风险——因为删除操作确实不容易引入 bug但从职责角度看删除大量代码本身就值得关注。于是我在 SKILL.md 里加了一条删除代码超 30% 时必须提示大规模删除操作需确认是否误删。 **第三层回归测试。** 每次修改 SKILL.md 或代码后把之前跑过的用例重新执行一遍确保没有引入新的问题。这一点很像软件开发的 CI 流程但很多人做 Skill 时嫌麻烦不搞结果改一处、崩三处。 这三层测试跑完基本可以保证一个 Skill 在常规场景下稳定可用。之后就是持续收集实际使用中的失败案例定期迭代 SKILL.md。**Skill 不是一次性交付物它是一份随着使用不断完善的活文档**——这可能是开发 Skill 和开发传统软件最大的思维差异。 ## 4. 踩坑实录与排查技巧 用了大半年 Skills踩过的坑没有二十个也有十五个。我把最典型的几个整理成速查表附上排查思路希望对大家有帮助。 ### 4.1 常见错误速查表 | 现象 | 可能原因 | 排查方向 | |------|----------|----------| | Agent 不触发 Skill | SKILL.md 的能力描述与用户请求不匹配 | 检查 Capability 描述关键词是否覆盖常见表述检查不适用场景是否过于宽泛导致误排除 | | 触发了但执行到一半中断 | 某个步骤指令空洞模型不知道如何继续 | 检查执行步骤是否有判断条件步骤之间是否有逻辑断档 | | 输出格式混乱 | 产出规范写得不够具体 | 增加字段级要求在 examples 目录放完整理想输出示例 | | 结果泛泛而谈、没有干货 | SKILL.md 缺少禁止空话类约束 | 增加负面样例要求每个结论必须有依据 | | 同一个输入多次运行结果差异大 | SKILL.md 中歧义表述过多 | 把模糊词改为明确数量/范围用编号步骤收敛自由度 | | Skill 调用依赖的工具时失败 | 依赖声明缺失或调用顺序不对 | 检查 SKILL.md 中是否写清工具调用顺序和参数要求 | 我遇到最多的问题是第一种**Agent 明明有对应的 Skill却绕过去直接回答**。排查了很久发现问题出在 SKILL.md 的 Capability 描述用了太多内部黑话。比如我写的是生成代码变更评审报告但用户的表述是帮我看看这段代码改得怎么样帮我 review 一下这个 PR。Agent 没把review看看改得怎么样和CodeReviewReporter关联起来。后来我在 Capability 里加了一行触发示例用户请求 review 代码、检查 PR、评估代码改动时使用效果立竿见影。 ### 4.2 排查思路与调优经验 分享几个定位问题的经验。 **第一个经验看 Agent 的中间推理过程。** 大多数 Agent 平台都支持查看模型的中间步骤也就是它看到了什么、在想什么、打算怎么做。Skill 执行出问题时第一步永远是回看推理过程判断模型到底有没有正确理解 SKILL.md 的指令。很多时候你以为的执行失败了实际上是理解偏了——它在第一步就走错了方向后面自然满盘皆输。 **第二个经验做减法优先于做加法。** 一次调优时发现失败率很高我第一反应是往 SKILL.md 里加更多说明。加了两轮之后发现情况没有好转反而更混乱。后来我把 SKILL.md 整个重写砍掉了一半内容把每个步骤改成更直接的短句效果反而上来了。模型处理指令的能力是有限的指令越多越容易迷失重点。**优先删减冗余而不是堆叠规则。** **第三个经验建立自己的失败用例库。** 每次实际使用中发现 Skill 输出不理想我都把输入和错误输出存下来标注失败原因然后针对性修改 SKILL.md。这个库既是测试集也是迭代依据。用了两个多月后我的几个核心 Skill 的失败率已经降到很低就是靠这个笨办法一点点磨出来的。 **第四个经验区分模型能力不足和Skill 设计缺陷。** 有些问题怎么优化 Skill 都解决不了那不是 Skill 的锅是所依赖的模型本身不具备那个能力。比如需要强推理的复杂数学题、需要实时知识的事件判断这类问题应该考虑换更强的模型或者拆分成更小的子任务而不是死磕 SKILL.md。分清问题归属能少走很多弯路。 ## 5. 生态对比与进阶方向 Skills 的玩法远不止写一个 SKILL.md 让 Agent 执行这么简单。到 2025 年主流 AI 厂商和开源社区基本形成了各自的 Skills 生态理解这些生态之间的差异对做技术选型和职业发展都很有帮助。 ### 5.1 主流平台的 Skills 实现方式对比 目前市面上能见到的Skills实现大致可以分成四类各自的思路和侧重点都不同 | 平台/生态 | 实现方式 | 核心特点 | 适用人群 | |-----------|----------|----------|----------| | Claude Agent Skills | SKILL.md 资源目录纯文本驱动 | 轻量、直观、模型理解门槛低 | 个人开发者、快速原型 | | OpenAI Codex Skills | 命令行环境内的技能包 | 强调编码任务、与 CLI 工作流深度绑定 | 开发者、DevOps | | 开源框架LangChain、CrewAI 等 | Plugin/Tool 封装 | 灵活可编程、支持复杂编排 | 需要定制化逻辑的团队 | | 无代码平台 | 可视化流程模板 | 低门槛拖拽配置 | 业务人员、中小企业 | 选择哪个生态核心看你的场景。如果你重度使用 Claude 做文本处理类任务官方 Skills 几乎零成本上手如果你每天都在命令行里写代码Codex 这种绑定 CLI 的方式效率最高如果你需要把 Skills 嵌入复杂的业务系统那还是老老实实用框架手写逻辑。 我在生产环境里的实际经验是**混合使用**。核心流程用框架手写以保证可控性外围能力文档处理、数据整理、报告生成用 Skills 快速拼装。这样既有框架的稳定性又有 Skills 的快速迭代优势。 另外提一嘴开源社区。现在 GitHub 上有大量社区维护的 Skills 仓库覆盖面从写周报到自动修 Bug、从数据分析到视频分镜非常丰富。使用社区 Skills 有两个注意事项一是务必审核其内部指令的安全性和准确性不要盲目跑陌生代码二是注意许可证有的仓库明确不允许商用。安全审核这一步千万别省曾经有社区 Skill 被植入恶意提示词的案例会让 Agent 在某些场景下输出钓鱼链接或者泄露上下文信息技术圈很多朋友都中过招。 ### 5.2 从单个 Skill 到多 Agent 协作的进阶路径 Skill 开发到一定阶段你会发现一个有意思的现象**当你的 Skills 数量足够多、覆盖足够广你就有了组合拳的资本**。多 Agent 协作本质上就是不同 Skill 在不同上下文中的排列组合。 我举个自己的例子。我的团队有一个内容生产系统里面跑着十几个 Skills大致分三层 - **采集层**素材抓取、网页解析、竞品监控 - **处理层**信息分类、要点提炼、去重合并 - **输出层**文章初稿、SEO 优化、多平台适配 早期的做法是让一个 Agent 依次调用所有 Skills结果效果很差——上下文窗口根本装不下这么多指令Agent 在高密度指令下频繁选择性失明。后来我改为多 Agent 架构三个 Agent 各负责一层每层只加载本层需要的 Skills通过结构化数据接口传递中间结果。这一改动让整个系统的成功率和质量都上了一个大台阶。 **这个过程中最大的收获是Skills 的粒度设计直接决定了多 Agent 系统的复杂度。** 如果你的 Skill 设计得很大里面塞了太多职责那么 Agent 之间的交接就会很笨重如果你的 Skill 设计得足够小、职责单一那么组合起来就像乐高积木一样灵活。我个人更偏向把 Skill 拆小宁可多几个文件也不要把复杂流程塞进一个 Skill 里。 另一个进阶方向是给 Skills 加自我评估能力——在 SKILL.md 里写上输出自检规则让 Agent 在完成产出后先自查一遍再交付。这一步看似简单实际效果极其显著尤其对长文本生成类任务质量问题能减少一半以上。 ## 最后分享一点个人体会 做了这么久 Skills 相关的工作我最大的感触是**Skills 看似是个技术概念本质上却是经验编码的实践**。它逼迫你把脑子里的隐性知识显式化——你到底是怎么做周报的、怎么评审代码的、怎么分析竞品的当你把这些过程一步步抽出来、写成 Agent 能理解的指令时你对自己工作方法的理解也会比之前深一个层次。 很多人纠结于选什么框架、用什么平台我的建议是别纠结先从最小的场景开始挑一个你每周都在做的重复性任务花两小时写成第一个 Skill跑通一次再逐步迭代。框架和平台都是次要的真正让你成长的是这个把经验翻译成指令的过程。 后续如果想继续深入可以从这几个方向着手给 Skill 设计完善的测试集、把多个 Skill 编排成自动化流水线、甚至尝试让 Skill 之间互相调用比如竞品分析Skill 调用网页抓取Skill 再调用周报生成Skill。这条路很长但每一步都实实在在能提升你的研发效率——毕竟让工具去干活、让自己去思考这才是我们折腾 Agent 的初衷。