先别急着往 agent 项目里堆代码。如果你已经在用 Claude Code、Codex 这类 AI 编程工具你一定遇到过这种场景让 Agent 生成一个图表它给你画了个四不像让它读一遍项目代码再重构它答非所问同一个任务换个人来提需求产出的质量天差地别。问题不一定出在模型能力上更可能出在你没有给它一套“干这种事的标准动作”。“agent-skills”这个概念解决的就是这件事——把碎片化的提示词、工具调用、操作规范打包成可复用的技能模块让 Agent 在特定场景下直接加载调用而不是每次从零摸索。这篇文章我会结合自己跑通的经验把 agent 和 skills 到底是什么关系、怎么做 skills 开发、哪里有现成好用的 skills、评测和排坑怎么做一次聊透。1. 先搞清楚概念agent 和 skills 到底谁依赖谁很多刚接触 AI 编程生态的人看到 surface 上飘着“agent”“skills”两词容易混成一谈。我自己最开始也绕了一阵子后来用一句话就理顺了Agent 是执行中枢Skills 是能力包。以自动驾驶类比。Agent 是那位司机负责看路、决定什么时候转弯、什么时候刹车Skills 则像是“侧方停车”“高架并线”这类专项能力。司机可以不掌握某个 Skill 硬着头皮开但有了 Skill相同场景下的表现会稳定得多。没有 AgentSkills 只是一堆文档没有 SkillsAgent 能干活但干得糙、干得飘。从技术上拆开看Agent 的核心能力是“推理 规划 工具调用”它知道自己有几个工具能调然后根据用户的一句话目标拆解出一堆子任务循环执行直到完成。但“知道有工具”和“用得对”中间差着一大截。模型再怎么聪明也不会天然知道“画架构图应该用 plantuml不要用 mermaid”“这个项目的前端代码在 src/front 目录别去根目录乱翻”“跑测试之前必须先把 mock 数据初始化好”。这些信息通过普通对话让 Agent 记住并严格遵循非常不可靠。Skills 就是把这个“经验层”固化成文件。一个 skill 的本质是一组指令文本通常包含三个部分元信息技能名称、描述、适用场景、详细的操作指引步骤、约束、格式要求、有时候还附带上示例片段或脚本。Agent 在启动后会扫描可用的 skills 列表根据当前任务的语义自动选择合适的 skill 加载进上下文。也就是说模型本身没变但它在特定任务上的“临时知识”变多了行为也会从“自由发挥”变成“按规范执行”。这也就回答了一个高频疑问skill 和 prompt 有什么区别Prompt 是一次性的、嵌套在对话里的Skill 是可复用的、独立存放的。你可以在十几二十个项目里反复加载同一份 skill而不必每次把一大段话复制粘贴进对话框。你可以把 skill 想象成插入式组件而普通 prompt 是一次性的手写纸条。2. 主流生态盘点Claude Code Skills、Superpower Skills、Codex Skills 三者各有什么门道当前阶段做 agent skills基本绕不开这三大生态。它们底层逻辑相似但入口、兼容性、和各自 Agent 的整合深度有明显差异。我逐个说下我的实际感受。Claude Code Skills基本上是这个领域的标杆。Claude Code 作为 Anthropic 官方 CLI 编程工具天然就有 skills 插槽。它的结构非常清晰在某个目录通常是~/.claude/skills或者项目内的.claude/skills下每个 skill 单独建一个子目录里面放一个SKILL.md文件这就是全部的核心。SKILL.md 开头有 YAML frontmatter写name、description正文写操作步骤、规则、示例。Claude Code 启动时自动扫描根据 description 做语义匹配触发了就把这个文件内容注入上下文。很多人第一次看到这结构会愣一下就一个 Markdown 文件对就这么简单。但这个“简单”正是它强大的地方——任何会写 Markdown 的人都可以创建 skill不需要重新编译、不需要装运行时、不需要处理依赖。门槛极低。Superpower Skills是社区里一个非常出名的 skill 集合项目GitHub 上的 star 涨得飞快。它不是官方出品而是第三方把日常高频开发场景打包成几十个 skill从写提交信息、Code Review、重构建议、到架构分析、正则生成、SEO 写作全都有覆盖。它解决的痛点是官方框架有了但默认仓库里空空的不知道该写啥 skillSuperpower 直接给你提供了大量开箱即用的模板。不过我建议你谨慎地把它当“参考素材库”而不是“全家桶”。逐个把它的 skill 读一遍你会发现有些质量参差不齐部分 skill 的指令过于泛化放进自己的项目里未必贴合你的技术栈。但作为脚手架和灵感来源它非常有用。把项目 clone 下来对照它每个 skill 的结构慢慢替换成自己团队的内容是最高效的上手路径。Codex Skills这边的情况稍有不同。Codex 如果指的是 OpenAI 的 Codex CLI / Codex Agent那么对 skills 的原生支持并不像 Claude Code 那样有一等公民的地位。很多 Codex 用户是依赖外部方案来模拟 skills比如通过加载 AI 知识库文件、通过配置文件注入 system prompt、或者用 opencode 这类在 Codex 基础上拓展的社区客户端。这里面有个容易被忽略的点skills 不应该是某个商业产品专属的封闭格式。因为本质上是 Markdown 文本完全可以做到跨工具迁移。我在 Claude Code 下写的 skill手动调整几个环境变量的写法后也能在 opencode 里用换到 Codex 环境只需把SKILL.md的加载机制改成 CLI 的指令拼接就行。所以不要被“某某平台 skills”锁死要把它看成一套通用的内容规范。顺便提一句热词里出现的“harness 和 agent 的区别”。Harness 在 Agent 语境里通常指“围着模型搭起来的那圈脚手架”包括工具注册、记忆存取、循环终止条件、安全限制。Skills 属于 harness 层的一部分是 harness 提供给 Agent 的“预置经验库”。所以你可以说 skills 是 harness 的插件机制而 agent 是这个机制的消费方。搞懂这层关系后面理解 agent 架构图也会有帮助。3. 实战安装流程以 Claude Code Skills 为例从零装一个能用的 skill理论说多了容易飘我直接拿一个我自己跑过的例子带你走完整流程。目标是在 Claude Code 里安装一个“结构化图表生成”技能让 Agent 在画架构图、流程图、时序图时自动选择正确的画图工具和风格。第一步确定技能存放目录。Claude Code 支持用户级 skills 目录和项目级 skills 目录。用户级目录在~/.claude/skills所有项目通用项目级目录在.claude/skills跟着 Git 仓库走适合团队共享。我一般把通用技能放用户级把业务相关、涉及项目私有路径或特定目录结构的技能放项目级。这一步看似简单后面扯皮最多的就是“为什么加载不到”九成是因为放错了层级。第二步创建技能目录和文件。建一个create-structure-diagram文件夹在里面放一个SKILL.md。初始内容长这样--- name: create-structure-diagram description: Generate architecture diagram / flow diagram / sequence diagram using PlantUML or Mermaid. Use this skill when the user asks for diagrams, charts, flow visualization, or system architecture. --- # Structure Diagram Skill ## When to use - User asks for an architecture diagram - User asks for a sequence diagram or flow chart - User wants to visualize module relationships ## Tool selection - Default to PlantUML for complex architecture diagrams with many nodes. - Use Mermaid only for simple linear flows. - Do not mix diagram syntax in one response. ## Output requirements - Wrap all diagram code in a fenced code block with the correct language tag. - After generating, briefly describe the diagram content in plain text. - If the diagram needs layout adjustment, explain the proposed change before regenerating.看懂这个例子的重点了吗description字段是 Claude Code 做语义匹配的依据写得好不好直接决定 Agent 能不能在合适的时机把这个 skill 加载出来。“Use this skill when the user asks for diagrams, charts...”这种显式触发词非常管用。正文部分我故意强调了“Default to PlantUML”“Do not mix diagram syntax”这就是在约束 Agent 的行为偏好。没有这些规则ChatGPT 和 Claude 可能默认用 Mermaid画出的复杂架构图不仅难看还经常语法报错。第三步让 Claude Code 加载。保存文件后重启会话然后直接问一句“帮我画一个订单系统的架构图包含前端、网关、服务层、数据库”。这个时候 Claude Code 应该自动选中create-structure-diagram并按里面的规则给你输出 PlantUML 代码。如果它没触发有两种可能一是 description 的关键词和你的提问方式不匹配二是 skill 目录位置不对。可以先在对话里问一句“你现在加载了哪些 skills”让它打印出当前可用的技能列表再逐步排查。第四步做一个带示例的 skill。文本指令能约束行为但示例更能统一输出质量。我强烈建议在 SKILL.md 里直接附上“高质量输出示例”。比如在文档里加一段## Good example plantuml startuml !include C4/C4_Container Person(user, User, Browser user) System(web, Web App, Frontend) ContainerDb(db, Database, PostgreSQL) Rel(user, web, HTTPS) Rel(web, db, SQL) enduml就这么一段代码效果比你写十句“请使用 C4 模型”都好。模型有样学样有了参照就不会乱画。这也是 skill 和普通 prompt 拉开差距的核心不仅仅是“告诉它规则”而是“给它看最好的结果长什么样”。 ### 4. 从零开发 skill一个完整案例如“前端代码审查技能” 装现成的 skill 只是第一步真正让 agent 生产力上台阶的是把自己的项目经验沉淀成技能。我拿自己在团队里推广过的“前端代码审查 skill”当案例拆给你看开发过程。 **第一步倒推“我在这个场景下希望 Agent 绝对不犯的错”。** 我的团队前端是 React TypeScript最常见的问题是组件拆分不合理、useEffect 依赖数组遗漏、样式类名命名混乱、大面积 inline style。这些不是模型不知道而是它不知道该按什么标准去查。所以我需要把标准写清楚而不是空泛地说“请认真审查代码”。 **第二步设计 SKILL.md 的结构。** 我会分成四段适用场景、审查清单、输出格式、严重性分级。审查清单部分用列表把 10 条规则列出来包括“禁止在 render 函数内部直接 new 对象或数组”“useEffect 中涉及 props 的必须在依赖数组中体现”“样式必须使用 CSS Modules禁止裸写全局 class 名”等。输出格式要求按严重程度排序每条都要给出文件名、行号、修改建议。 **第三步加入“反例”来防止模型犯蠢。** 这是我最想强调的一点。光有“正确规则”不够模型经常会把不合理的代码改成另一种不合理的写法。所以我会在 skill 里加一段“常见错误修复示例”把一套有明显毛病、但 AI 经常觉得“没问题”的代码放进去然后再放一段修复后的代码对比着让它学习。实测下来加了反例之后审查结果的质量提升非常明显。 **第四步反复测试迭代。** Skill 不是写完就结束的。我会拿一段故意埋入 5 个问题的代码去测看 Agent 能找出几个误报率多高。再把实际项目里的一段提交给它看反馈是否符合团队规范。每次测完把暴露出问题的地方在 SKILL.md 里补充约束条件。代词要精确比如不要写“保持代码整洁”而要写“函数体不要超过 60 行超过必须拆分”。 开发 skill 这件事本质上是在给 Agent 建立一个针对特定领域的“岗位说明书”。你写得越具体它干得越像你团队里的资深工程师你写得越抽象它就越像那个“什么都懂但什么都做不细致”的新人。 ### 5. 有哪些现成的好用 skills我筛过一轮之后留下的名单 GitHub 上的 awesome-claude-skills、superpower-skills 这类项目我基本都翻过一遍挑几个我用了之后真实有效、不是花瓶的分享给你。 **代码回看与提交信息生成**这个几乎所有团队都该常备。它规定提交信息的格式是 Conventional Commits限制单次提交范围不超过一个逻辑变更并在生成提交信息前强制 diff 检查。以前我让 AI 写提交信息它经常写出一堆“fix bugs”“update files”这种毫无价值的内容有了 skill 约束之后提交记录质量直线上升。 **项目结构分析**这个适合接手陌生项目。它要求 Agent 先读取 package.json、README、目录树再逐层分析依赖关系最后以“入口 - 模块 - 基础设施”的结构化分层输出脑图文本。配合“结构图 skills”一起用第一次看项目代码的效率提升明显。 **数学建模辅助**别看偏学术实际工作中做数据分析和算法设计非常有用。它约束 Agent 先明确假设条件、再列公式符号表、然后推导、最后做敏感性分析。没有这个约束模型在数学推导里特别喜欢跳步你根本不知道结果是怎么来的。 **AI 逆向分析**这个听着玄乎其实是分析别人项目里的 prompts 或 agent 配置。社区里有人做了识别 prompt 注入模式、逆向提取 system prompt 的 skill。做安全评估或研究开源 Agent 项目的机制时挺有用。 我建议的筛选标准有三个第一instructions 里有明确的“什么时候触发”和“什么时候不触发”而不是万能药第二有示例输出而不是一堆空泛原则第三该 skill 在你所在的行业场景下有具体的字段、命令或配置可循。凡是满足不了这三条的基本可以丢进垃圾桶。 ### 6. skill 的评测与调优光看“能用”是远远不够的 做完 skill 不做评测等于盲人摸象。现在 GItHub 上已经有人在做 systematic evals 了热词里的 agent evals、skills 怎么测评指的就是这事但普通人没必要一开始就上复杂框架有个轻量评测法足够用。 我的做法是准备三个固定测试集第一个是不相关查询用来测“误触发率”就是那些不该调用该 skill 的请求会不会被错误匹配第二个是边界查询测“触发率”稍微沾边的请求能不能成功触发第三个是标准查询测“输出质量”给同一个输入跑三次看结果是否稳定、是否满足规范。 每次修改 SKILL.md 之后我都重跑一遍这三个测试集把每次的结果记录在一个表格里。这样改了几轮之后你能清楚地看到哪个改动提升了触发率哪个改动引入了误报。我有一次为了提升触发率在 description 里多塞了几个同义关键词结果误触发率从 8% 飙到 40%就是在评测表里看出来的。 评测这件事还有一个价值它会逼你把 skill 的边界想清楚。很多 skill 写得太宽什么都想覆盖结果在特定问题上反倒不如不加载。好的 skill 应该是“窄而深”的只解决一类问题把它解决透。 ### 7. 避坑清单我在开发和使用 skills 过程中踩过的雷 分享点实打实的教训都是文档里不会写的。 **第一description 是灵魂不是摆设。** 加载机制依赖语义匹配description 里写“帮我做前端代码审查”和写“Review React/TypeScript code for common anti-patterns such as missing dependency arrays, inline styles, oversized components”完全是两种触发率。前者会被大量无关请求撞到后者精准且极少误触发。但注意也别写太长的 description上下文容量是有限的又长又啰嗦会稀释 Agent 判断的准确度。 **第二SKILL.md 里能不写代码就不写代码写代码一定带语言标记。** Skill 文件本身会被注入到对话上下文中如果里面粘贴了大段没有语法标注的代码模型会混淆哪些是它该执行的哪些是示例。正确做法是始终使用带语言标识的 code fence并且在代码块前后加说明性文字“下面是示例不要直接执行仅供格式参考。”这一点在 calc 类、browser 操作类 skill 里尤其重要。 **第三权限问题。** 如果你的 skill 要触发 Bash 命令或读写文件务必在 skill 里写清楚“哪些命令可以运行、哪些不允许”。很多第三方 skill 一上来就是“允许 Agent 执行任意命令”这就很危险。我的建议是每个 skill 里显式加一个 ## Permissions 小节比如“允许执行npm lint、jest 测试禁止执行git push、rm -rf、curl 外部接口”。Agent 会读取这些约束比自己口头叮嘱有效得多。 **第四目录别太深。** Claude Code 扫描 skills 目录时是递归搜索 SKILL.md 文件的。但如果你把文件层级叠得太深偶尔会有加载不出来的情况也容易让别人看不懂。保持每个 skill 一个平铺目录里面就放 SKILL.md 和少量辅助文件是最稳妥的结构。 **第五不要贪多。** 一次加载 50 个 skills 的后果是Agent 在匹配阶段会频繁误判而且大量无关指令挤占上下文窗口导致核心任务执行质量下降。我的经验是每个项目常驻 skills 控制在 3-5 个其他按需手动触发。这个度要自己试不同模型对上下文拥挤的敏感度不一样。 ### 8. 学习路线与未来方向从 skills 出发去理解整个 agent 架构 如果你是想系统学习 agent 开发的新手我的建议是从 skills 切入不要一上来就啃大而全的 agent 框架文档。因为 skill 是 agent 体系里最直观、最轻量、最接近“可交付成果”的部分。你花一下午写一个 skill它能实际提升工作流这个正反馈会驱动你继续深入。 热词里反复出现的 agent 开发学习路线我会这么排第一步做一个 skill比如说“自动化 Code Review”跑通安装、触发、评测全流程第二步理解 agent 的 tool calling 和 memory 机制搞明白技能是怎么被调用的、状态是怎么保存的第三步尝试改造 harness 层比如在开源 agent 框架里自己注册一个工具、改一改执行循环第四步思考 eval 问题做一套你自己的 agent 评测集最后才是去看那些大而全的 agent 架构图和论文——到了这一步你已经能自己画出 architecture 了。 Hot words 里提到的 pi agent desktop、hermes agent、codebuddy skills 这些本质都是这条学习路线上的不同工具和脚手架。工具会一直换代但“把经验标准化成可复用模块”这件事不会过时。 最后说一个我目前很看好的方向**多 skill 协作**。单个 skill 解决单点问题但如果能把“代码审查”“单元测试生成”“性能分析”三个 skill 串成一个流水线Agent 就能在一轮交互里完成完整的多阶段任务。现在很多框架在往这个方向走比如支持 skill 依赖声明、skill 之间的输入输出对接。这个趋势继续发展下去skills 会从“指令文本”变成真正意义上的“可编排工作流”那才是 agent 开发走向工程化的关键转折点。现在学着写 skill、积累自己的技能库是在为这套新范式提前储备弹药。
