做 Agent 开发这段时间我最大的感受是真正拉开不同 Agent 体验差距的往往不是模型本身而是你给它装了多少“Skills”。如果你最近在刷 GitHub、翻 Claude 或者 OpenAI 的更新一定会看到 agent skills 这两个词的组合。所谓 skills简单说就是一套给 AI Agent 安装“专项技能”的标准格式一个文件夹、一份说明文档、若干辅助脚本装进指定目录之后Agent 就能在对应场景里自动调用这套流程。Elastic 我前前后后写过几十个 Skill也在几个开源 Agent 框架里做过二次开发这篇文章就把 agent-skills 从概念到实操完整过一遍它到底解决什么问题、目录内部是怎么组织的、如何手写一个能用的 Skill以及我在实际调试中踩过的坑。适合正打算搭 Agent、或者已经把 Agent 跑起来但觉得它“不够强”的开发者。1. 先搞清楚Skills 到底解决什么问题1.1 从“什么都会一点”到“专项能力包”早期 Agent 的使用方式很简单把系统提示词写得足够长告诉它“你是资深前端工程师”“请遵守以下规范”然后祈祷它全能。问题在于一旦任务变复杂这种“全知全能”式提示词就开始失灵。你给它塞了 50 条规则它可能只记得前 10 条你给它配了一堆函数调用它可能不知道该先调哪个再调哪个。Skills 的设计思路完全不同不再追求让 Agent 一次学会所有事而是把每一个“专业能力”拆成独立的、可插拔的技能包。Agent 平时不加载它一旦遇到匹配场景再通过描述信息自动发现并激活。这有点像你桌面上不会同时摊开所有工具书而是在写周报时才翻出模板在画架构图时才打开图例库。我最早接触这个概念是在 Claude 的 Agent Skills 发布之后。官方把它定义为一套预构建的技能集合放在.claude/skills目录下每个技能就是一个文件夹。后来 OpenAI Codex 也做了类似的 skills 机制社区里各种 skills 仓库更是雨后春笋。核心逻辑其实一致把“流程知识”和“工具调用”打包成一个 Agent 可理解、可复用的单元。拿生活场景类比Tools 是工具箱里的一把扳手你告诉 Agent“拧这个螺丝”它直接调扳手函数。Skills 更像是一份带工具的作业指导书“拧螺丝前先检查螺纹、按对角线顺序拧、扭矩达到 15 N·m 停止”。前者是确定性指令后者是带有判断逻辑和步骤流程的完整方案。1.2 Skills、Tools 和 Workflow 的边界很多新手一上来就困惑这仨到底啥区别Tools 是最底层的能力单元通常是确定性的函数调用入参出参固定比如“搜索网页”“读取文件”“发送 HTTP 请求”。Tools 没有流程它只回答“能做什么”。我在实际开发中会把任何可封装的原子操作尽量做成 Tool这部分不受模型版本限制。Workflow 或者叫编排层解决的是“先做什么、后做什么、怎么做分支判断”。比如一个多 Agent 系统里规划 Agent 拆任务执行 Agent 跑工具审查 Agent 校验结果这就是编排层的事。Workflow 关心的是状态流转和数据传递。Skills 正好处在两者之间。它既包含指令性的步骤描述也可以内嵌多个工具调用、脚本和参考资料。Skill 的本质是一份“程序性知识包”告诉模型在特定场景下应该按什么 SOP 处理用哪些工具、按什么顺序、关注哪些风险点。它不需要写死每一步分支因为模型会根据 Skill 里的描述自主决策。我见过一个比较清晰的区分方式Tools 是“能力”Workflow 是“流程”Skills 是“专家经验”。Skills 里描述了专家的做法至于具体执行时用哪个 Tool由模型结合场景决定。这也是 skills 这类机制和传统 RPA 脚本最大的不同——它不是死流程而是有弹性的专家手册。明白了这个边界你再看各种 Agent 框架的设计思路就通了。有些框架把 skills 当成提示词片段管理有些把它当成可加载的模块还有些把 skills 和 tools 混在一起。理解了边界之后你就能判断一个框架的设计是否合理而不是被各种营销词汇带着走。2. 拆开一个 Skill 看看里面装了什么2.1 标准目录结构与核心文件一个标准的 Skill在文件组织上通常长这样.skills/ └── frontend-code-review/ ├── SKILL.md ├── scripts/ │ ├── security_check.py │ └── perf_analyzer.js └── templates/ └── review_report.md核心文件是SKILL.md所有 Agent 框架都会首先读它。它本身是 Markdown 格式但头部通常带一段 YAML 元信息用来声明技能的名称和描述。这段描述至关重要因为它在模型扫描可用技能时决定“会不会选中你的 Skill”。如果是 Claude 的生态项目级技能放.claude/skills/用户级技能放~/.claude/skills/Codex 的路径类似一般在~/.codex/skills/。不同框架的具体路径有差异但设计哲学一致Agent 启动时或会话中按目录扫描读取每个 Skill 的元信息构建一份可用的技能清单。我强烈建议所有 Skill 都放在版本管理仓库里哪怕你只是个人使用。原因很简单一个成熟的 Skill 是你跟 Agent 之间沟通方式的一再迭代你不希望某天误删或改乱之后无法回滚。我用一个私有的 skills 仓库管理所有技能目录名就是技能名内部结构完全统一。2.2 元信息、指令正文与辅助脚本怎么编排SKILL.md的结构可以拆成三块元信息块。YAML frontmatter 里最重要的两个字段是name和description。name 通常用短横线命名法比如frontend-code-review。description 要写得“像搜索引擎的落地页摘要”既要说明适用场景又要给出触发条件。例如“对前端项目代码进行规范审查识别性能隐患、可访问性问题和安全漏洞并输出结构化的审查报告。当用户要求代码审查或 review 前端代码时使用。”这里的关键是给足触发线索但又不过度承诺。指令正文块。这是 SKILL.md 的主体写给模型看的操作手册。我会用编号列表写主流程再用小标题分主题补充细节。不要求写得像严格编程语言那么死板但必须有清晰的步骤顺序、判断条件和输出格式。模型不是照着代码逐行执行而是理解语义后自主推进所以语言要明确避免“视情况而定”这种模糊表达。辅助资源块。脚本和模板放在子目录里正文用相对路径引用。我经常放 Python 脚本做静态扫描放 JavaScript 脚本做运行时分析再放一份报告模板统一输出格式。这样 Skill 既能指导模型思考又能给它实际的工具来干活。我踩过的一个大坑是在 SKILL.md 里直接贴大段代码。这会让技能描述臃肿每加载一次都要浪费大量 token。正确的做法是代码全部放到scripts/或references/里SKILL.md 只保留运行方式、参数说明和预期的输出结构。让模型读文档去调脚本而不是把整个脚本背下来。2.3 主流框架里的 Skills 实现差异Claude 的 Agent Skills 与 OpenAI Codex 的 skills 理念基本一致但细节各有取舍。Claude 更侧重“文档驱动”。它的 Skill 强烈依赖SKILL.md的指令质量辅助脚本可以存在但不强制。官方对 Skill 文件夹里放 Python 脚本、Shell 脚本、参考资料都持开放态度。整个机制像是给模型发了一本“可执行手册”模型按手册操作。Codex 的 skills 机制更像工程化插件。它对文件结构的要求也很清晰但更强调把技能作为一个单元加载到命令行 Agent 中。Codex 的生态里skills 主要用于扩展编码能力比如引入新框架的最佳实践、项目模板等。它的AGENTS.md和 skills 的配合方式也值得研究——前者管项目级约束后者管能力扩展。开源生态里的差距更大。有的框架把 skills 做成 JSON 配置文件有的用 YAML 描述并关联 Python 入口函数。还有基于 Rust 写的 agent 框架把 skills 直接编译进二进制。这类实现更底层但本质没变扫描目录、读取描述、按需加载。我个人的建议是不要被框架差异绑架先吃透SKILL.md这套范式。它在多数主流框架里都是兼容的就算换了框架迁移成本也只是改一下目录路径。我自己在 Claude、Codex 和自研框架里用同一套 skills 仓库只有少数框架需要额外写一点适配层。3. 从零手写一个 Skill以“前端代码审查”为例3.1 场景拆解与需求定义动手写 Skill 之前我会先回答三个问题这个技能处理什么输入、产出什么输出、在什么场景触发。拿“前端代码审查”举例。输入是一个前端项目目录或一组文件的路径输出是一份结构化的审查报告包含严重问题、建议改进、代码示例触发场景是用户说“帮我 review 一下这个项目”或“检查下这段代码有什么问题”。需求定义清楚后再细化审查维度。我通常关注四类问题性能隐患重复渲染、大体积依赖、未缓存的请求、可访问性问题缺 aria 标签、颜色对比度不足、安全漏洞XSS 风险、敏感信息硬编码、依赖版本过旧、可维护性问题死代码、复杂度过高、命名混乱。这里有一个重要原则不要试图让 Skill 一次覆盖所有问题。Skill 的目标是在特定场景下给模型明确的工作框架而不是让它变成万能扫描器。审查维度太多会导致输出浮于表面我宁可做一个聚焦的 Skill也不太想做那种“什么都检查一点”的大杂烩。3.2 编写 SKILL.md 和审查脚本目录结构设计如下.skills/ └── frontend-code-review/ ├── SKILL.md ├── scripts/ │ ├── scan_project.py │ └── analyze_bundle.py └── templates/ └── review_report.mdSKILL.md的元信息部分--- name: frontend-code-review description: 对前端项目进行代码审查覆盖性能、可访问性、安全性和可维护性四个维度输出结构化的审查报告。当用户要求 review 前端代码、检查项目质量或定位性能隐患时使用。 ---正文部分我会这样写# 前端代码审查流程 ## 1. 项目结构梳理 先扫描项目根目录确认使用的框架、构建工具和目录组织方式。读取 package.json记录依赖列表。 ## 2. 分类检查 - 性能检查重复的组件渲染、未使用 memo/useCallback 的热点组件、缺少代码分割的页面。 - 可访问性检查表单控件是否缺少 label图片是否缺少 alt交互元素是否有键盘支持。 - 安全检查 innerHTML 直接插入用户输入、敏感信息硬编码、存在已知漏洞的依赖版本。 - 可维护性检查死代码、过高的函数复杂度、不一致的命名风格。 ## 3. 输出报告 使用 templates/review_report.md 模板生成报告。每个问题必须给出 - 问题位置文件路径 行号 - 严重级别严重/中等/建议 - 问题说明 - 修复示例辅助脚本的作用是帮模型快速获取数据而不是替模型做判断。scan_project.py可以扫描目录并输出文件清单、代码行数、潜在风险模式的位置。模型拿到这些数据后结合自身理解去输出报告。这种分工效率最高。3.3 安装、加载与第一次实测安装步骤很直白。项目级就放到当前项目对应的 skills 目录想全局复用就放到用户级目录。放在~/.claude/skills/或者~/.codex/skills/下之后新建会话就能被发现。第一次实测我建议用一个真实项目但范围控制小一点比如只审查src/components目录。直接对 Agent 说“使用 frontend-code-review 技能审查 src/components 目录下的代码。”如果 Agent 正确加载了技能它会按 SKILL.md 里的流程走而不是自由发挥。实测中最常见的现象是Agent 加载了技能但输出还是不够结构化。这时候别急着改 SKILL.md先检查模型是否真的读到了辅助脚本的输出。我会在指令正文里明确要求“第一步必须先运行 scan_project.py 获取项目概况”确保脚本先跑起来。我也试过在小范围测试时故意用模糊的指令比如只说“帮我看看这个项目怎么样”观察 Agent 能否通过描述自动触发技能。这种测试很有价值因为它验证了 description 的触发线索是否准确。描述写得差技能就会“沉睡”。3.4 调试与迭代节奏一个 Skill 很难一次写到位我基本遵循“写初稿 - 跑真实案例 - 改指令 - 再跑”的循环通常三轮之后才稳定下来。第一轮先跑通整个流程重点看有没有阻塞性问题脚本能不能运行、路径引用对不对、报告模板能不能正常套用。第二轮关注输出质量看报告是否太泛、问题点是否准确、修复建议是否可落地。第三轮微调触发条件优化 description 的措辞让该触发时触发、不该触发时不打扰。调试时我有一个习惯把每次测试的输入和输出都留档。因为 Agent 输出并不完全确定你没法控制模型的随机性但可以记录“在某个 prompt 下它这次表现如何”。多次对比之后你才能判断修改 SKILL.md 到底产生了正向还是负向影响。这个思路其实和做评测时用的 harness 差不多——先定一个固定测试集再跑对比。4. 常见问题与排查技巧实录4.1 技能装了却加载不出来这是问得最多的问题。技能文件正确放在目录里但 Agent 就是“看不见”。排查思路按顺序来先确认目录路径是否匹配当前框架的约定。不同版本、不同工具的默认目录可能不同最直接的办法是让 Agent 自己列出技能清单比如问“你现在装了哪些 skills”。如果清单里没有那就是框架没扫到而不是技能内容有问题。再看文件命名和元信息格式。SKILL.md这个文件名是硬性要求大小写都不能错。YAML frontmatter 里的字段名也要匹配特别要注意 description 不能写成desc或者没有写全。最后检查描述里的触发线索。如果描述写得太窄比如“当用户要求进行 React 项目的性能优化分析且项目使用 Vite 构建时使用”那普通用户根本不会用这样的措辞技能自然触发不了。我建议描述覆盖 3 到 5 种常见表达方式但也不要写成一长段泛泛而谈。4.2 上下文被 SKILL.md 吃光一个典型的失误是把 SKILL.md 写得像百科全书。每次加载技能正文里的内容都会占用上下文窗口让模型处理实际任务的空间变小。这里涉及 token 的分配问题模型能用的上下文总量固定技能描述就是额外的消耗。我的经验是把 SKILL.md 控制在 300 到 600 行以内超过这个量就要怀疑是不是设计有问题。正文里不要贴大段配置文件、不要复制整个函数库、不要罗列几十条“注意”。把代码和参考资料放进子目录需要时按需读取而不是全部塞进主文档。还有一个隐蔽的坑Agent 加载技能时会把描述拼进系统提示如果同时装了几十个技能光是技能清单就能占掉几千 token。这时候需要给每个 Skill 写短摘要让框架在“预览清单”里只看到精简描述真正被选中时才加载完整正文。这一点直接决定了多技能场景下的使用体验。4.3 Skills 的版本管理与多 Agent 共享个人使用还好一旦进入团队或多 Agent 场景Skills 的版本管理就开始变得重要。我遇到过一个实际问题多个 Agent 共享同一份 skills 仓库但不同 Agent 对技能格式的兼容性不同。有的 Agent 能读 Markdown 格式的指令有的一定要求脚本入口。后来我做了个折中仓库里维护统一的SKILL.md再给不同框架写一层薄的适配配置指向同一套脚本和模板。这样主体逻辑只有一份适配层各自独立。版本管理上我给每个 Skill 的 update 记录写在仓库的 changelog 里不要把更新历史塞进 SKILL.md。因为模型每次加载都会看到这些历史信息纯粹是浪费 token。用 Git 的 commit message 记录变更内容人看人懂模型也不需要关心。多 Agent 场景里还有个“技能权限”的问题。某些技能只希望特定的 Agent 使用比如一个面向用户对话的 Agent不该加载内部运维脚本。解决办法是在描述里加入限定语或者在框架层对技能目录做细分。我倾向于按 Agent 角色分目录避免一个 Agent 加载过多无用技能。4.4 常见问题速查表问题表现大概率原因处理办法技能清单里看不到新技能目录路径不对或文件名不匹配核对目录约定确认SKILL.md名称和位置技能能列出但从不自动触发description 触发线索过窄或措辞不当扩展描述覆盖多种用户表达方式加载后上下文明显变短SKILL.md 过长或加载了过多技能精简正文把资源拆到子目录按需读取输出不符合流程要求指令正文缺少明确步骤或输出格式用编号列表写清主流程指定报告模板脚本执行报错路径引用错误或依赖缺失用相对路径在目录内附带 requirements 文件同一 Skill 在不同框架表现不一致框架对 Skill 的加载规则不同确认元信息格式与框架兼容写适配层还有一个很多人都遇到的奇怪现象Agent 突然执行中断报类似agent execution terminated due to error。这通常不是 Skills 本身的问题而是某个子步骤触发了框架的错误处理比如脚本超时或模型输出格式不符合预期。排查时先看错误发生在哪一步是框架报错还是子进程报错再针对性修复。不要一上来就改 SKILL.md。5. 一些值得分享的经验用了大半年 Skills 之后我慢慢摸清了什么场景该用、什么场景不该用。真正适合做成 Skill 的是那些“有稳定流程但需要灵活判断”的任务。比如代码审查、日志分析、报告生成、项目脚手架搭建。这类任务有清晰的步骤框架但每一步都需要模型根据实际情况决策不会像一个普通函数那样固定输入输出。反过来如果任务是纯确定性操作比如“把这张图片转成 PNG”那更应该做成 Tool 而不是 Skill。另一个经验是关于“技能组合”的。单个 Skill 解决单项任务但实际工作中经常需要多个 Skill 协作。比如我先用一个“代码审查”Skill 找出问题再用“修复建议”Skills 生成补丁。设计时可以保持 Skill 间的低耦合让它们通过文件或规范化的中间结果对接而不是硬编码依赖。最后说说学习路线。如果你刚接触 agent skills我建议按这个顺序走先读官方文档了解目录结构和触发机制然后从社区找一个成熟技能包比如 GitHub 上的 superpower skills、nature skills 这类合集跑通安装和触发流程接着挑一个你工作中最常做的任务亲手写一个简单 Skill最后才是研究多 Agent 场景下的 Skills 共享和编排。我在实际使用中发现写 SKILL.md 和写技术文档有点像最容易犯的错误不是内容不够而是重点不突出。模型确实能理解长文本但真正能稳定执行的是那些层级清晰、步骤明确、示例到位的技能描述。所以我后来写技能时会在每个流程节点都给出“预期产出”哪怕是简单的一句“输出一个表格”模型的执行稳定性都会好很多。另一个体会是别急于追求技能数量。我现在主力使用的技能不超过十个但每一个都经过反复打磨。与其装 50 个只能在理想条件下触发的技能不如把 10 个核心技能做成真正可靠的“肌肉记忆”。当你把一个 Skill 调试到“不管用户怎么问它都能稳定完成任务”的时候那种感觉确实像是给 Agent 装上了一个新的器官。这大概就是 skills 这个机制最迷人的地方——它让 Agent 的成长从一个模糊的整体调优变成了一个个具体能力的拼装。