做 AI agent 开发这段时间我越来越觉得agent-skills是被大多数人低估的东西。Claude Code、Codex、opencode 这些工具台前唱戏的是 agent 本体真正决定产出质量上限的却是用户自己塞进去的那些 skills。所谓 skills就是给 agent 配的一本本“岗位操作手册”它告诉 agent 遇到某种任务时该按什么流程做、用哪些参考文件、输出什么格式、最后怎么自查。没有 skills 的 agent 像一个记忆力好但毫无经验的新人什么都能聊一上手就飘配好 skills 之后它才真正像一个干过几年的老手。这篇文章我会从概念、平台生态、自定义 skill 开发一路讲到 agent 技术栈全景全程用实操视角适合正在用 AI 编程工具做自动化、想搭自己工作流的开发者也适合刚入门的同学把“skills”这个词彻底搞懂。1. agent-skills 到底在解决什么问题1.1 skills 的本质可复用的操作手册而不是一个插件先给 skills 下一个我最认可的定义它是一个“目录 描述文件 参考资料”的组合。目录里可以放脚本、模板、代码片段、规范文档描述文件通常是 SKILL.md用自然语言写清楚这个技能什么时候该用、怎么用、输出什么参考资料则是 agent 干活时要翻阅的“字典”和“样例”。很多朋友第一次接触 skills 时会下意识把它类比成插件或者 MCP server这个理解方向偏了。插件是给 agent 接上“手脚”让它能操作外部系统MCP 是标准化了“手脚”的接口协议而 skills 更像是给 agent 灌进脑子里的“操作流程”。举个例子写一篇技术博客MCP 负责帮 agent 去查询资料、调用图片生成服务skills 则负责约束 agent 先写大纲、再按小标题展开、最后补代码示例和避坑提示。一个管“能做什么”一个管“怎么做好”。我在实际使用中的体会是skills 真正解决的是“跨会话、跨项目的经验固化”。你把自己沉淀下来的工作流写进一个 skill 文件之后任何项目、任何 agent 只要加载它就能复现你原来的高质量输出。这比每次在对话里长篇大论地描述需求要省太多事也比把规则塞进系统提示词要干净得多——system prompt 是全局的塞多了会影响 agent 的基础能力skills 是“按需加载”用的时候才占上下文。1.2 skill、agent、harness 和 MCP一张表说清边界这组概念是 agent 开发社区近期讨论最多、也最容易混的。我先用一句话概括agent 是“大脑 循环”harness 是“跑 agent 的车架”MCP 是“外接器官的标准插口”skill 是“大脑里的操作手册”。你不需要把它们分得比这更细但面试、写方案、选型时能说清这四个东西的关系基本就证明你对 agent 体系有一个整体认知了。名词本质生活类比典型代表Skill可复用的操作流程封装给新人的岗位 SOPClaude Code skills、codex skillsAgent拥有推理循环的自主程序一个有决策能力的员工Claude Code、Codex CLI、自研 agentHarnessagent 的运行时框架负责上下文管理、工具调度、重试员工坐的工位和办公系统Claude Code harness、Codex harnessMCP工具调用的标准化协议标准电源插座MCP server、MCP client重点说一下 harness 和 agent 的区别。Harness 管的是“agent 怎么跑起来”模型请求怎么发、工具结果怎么回填、上下文超限怎么裁剪、失败怎么重试。Agent 本身则是“能思考的那一层”它根据用户目标拆解步骤、选择工具、判断结果。很多团队纠结要不要自研 harness我的建议是除非你有特殊需求否则直接站在 Claude Code、Codex 这些成熟产物上做业务别重复造轮子。原因后面第 4 节会展开。skill 和 agent 的区别就更直接了agent 是一个独立的执行主体skill 是 agent 可以挑选使用的“技能包”。同一个 agent装上“latex-typesetter”skill 就会排版装上“frontend-coder”skill 就会写组件agent 本体不动能力边界完全由 skil 集合决定。这也是我把agent-skills当成一个整体研究的原因——在生态层面技能包才是真正可复制、可交易、可积累的资产。1.3 为什么是现在从 prompt 到 skills 的三层推力“为什么 skills 突然这么火”是很多人的疑问。我觉得有三层推力缺一不可。第一层是上下文窗口的有解。Claude 和 GPT 的上下文虽然越来越大但把几十页的规范、模板、样例全部塞进 system prompt 依然是巨大的浪费而且会影响 agent 的注意力。skills 这种“按需加载”的设计让 agent 只在真正需要时读取对应文档上下文效率高一个量级。第二层是编程工具竞争带来的生态外溢。Claude Code 率先把 skills 做成了正式功能Codex、opencode 们紧接着跟进社区里开始出现大量“skills 推荐”“skills 下载”的资源仓库。有人管这种现象叫 superpower skills意思是装上之后 agent 跟“开了挂”一样能干细活。这个说法夸张了点但确实抓住了核心——skills 能把一个通用 agent 快速调教成垂直领域熟练工。第三层是“可评测、可分享”带来的正循环。一个 skill 写得好不好不再是一个玄学问题可以直接拿一组测试任务去评。有了评测就有排名有了排名就有分享生态就滚起来了。现在 GitHub 上已经有不少相关的 skill 评测仓库专门给各种 skills 打分。这件事对行业最大的意义是把“调 prompt”这种手工艺变成了“写技能包”这种可工业化沉淀的工程。2. 各平台的 skills 生态与安装实操2.1 Claude Code 的 skills目录即技能Claude Code 是把 skills 产品化最彻底的一个。它的 design 是一个技能就是一个文件夹文件夹里必须有 SKILL.md其余文件自由组织。SKILL.md 的开头是 YAML frontmatter里面至少要有name和description正文则是给 agent 读的操作指南。实际安装时多数人把 skill 放到项目的.claude/skills/下这样只有这个项目会加载想全局生效就放到用户级 skills 目录。放好之后你在对话里提相关需求agent 会根据 frontmatter 里的 description 自动决定是否调用。这里有一个关键经验description 一定要写清“触发场景”和“不触发场景”。我在本地配过一个结构图 skills目录大概是这样的.claude/skills/diagram-maker/ ├── SKILL.md └── references/ ├── mermaid-template.md └── d2-sample.d2SKILL.md 的 description 我写了这么一句“当用户需要绘制架构图、流程图、时序图、ER 图时使用支持 mermaid 和 d2 两种语法如果用户只是要文字描述不要调用。”加了后半句之后误触率明显下降。这算是我配 skills 踩坑后补的一点经验不要以为 description 越短越好关键是把边界条件说清。2.2 Codex、opencode 与国内工具链的 skills 落地Claude Code 起了一个头后面的工具跟进得很快。Codex CLI 里也有了一套 skills 机制社区里“codex 好用的 skills”这类推荐帖子也越来越多。opencode 同样支持类似结构核心文件依然是 SKILL.md只是目录位置和加载规则略有差异。这种“事实标准”让我挺感慨只要一个文件格式被足够多工具采纳它就会成为默认规范所以你现在学 SKILL.md 的写法未来大概率是通用的。在国内工具链里CodeBuddy 也明确支持 skillsPI Agent 推出了桌面端还有 Hermes agent 这类新兴 agent 项目也把 skills 当成标配能力。我用下来最大的感受是各家都在往“本地目录优先 可迁移”这个方向靠这对使用者是好事因为你沉淀的 skills 资产可以跨工具带走不会被单一厂商锁死。真要比差异的话主要在看三点第一skills 的加载优先级是怎么规定的第二能不能在 SKILL.md 里声明依赖比如需要某个 Python 包第三会不会自动读取文件夹里的脚本并注入工具列表。最后这点尤其关键有些实现支持把 skill 里的脚本注册为可调用工具有些则只把它当文档参考行为差别很大。2.3 值得关注的 skills 类型与仓库筛选思路现在社区的 skills 数量已经多到看不过来了我建议你先关注这几类它们是需求最刚、效果最明显的前端开发 skills约束组件结构、样式规范、代码风格适合团队统一 AI 产出代码。结构图 / 图片生成 skills封装 mermaid、d2、SVG 或绘图 API 的调用规范输出一致性好。LaTeX 排版 skills把自然语言内容排版成规范 LaTeX 文档写论文和报告必备。代码现代化 skills比如 agent legacy modernizer 这类专门把老项目逐步升级到新架构。AI 逆向 / 代码分析 skills解析别人代码、生成结构说明注意只能用于合法授权的场景。筛选仓库时不要只看 star 数我看一个 skills 仓库值不值得试核心看三点。第一SKILL.md 有没有写清楚使用边界和禁止事项写得越细越可信。第二有没有配套的样例输出或测试用例纸上谈兵的 skill 大概率不靠谱。第三参考文件是不是真实可用的模板而不是一堆无意义占位符。按这三条筛下来能避掉八成水分很大的 skills。3. 从零开发一个 LaTeX 排版 skill3.1 标准目录与 SKILL.md 的写法光说概念容易飘我拿自己开发的一个 LaTeX 排版 skill 作为完整案例把每一步拆开讲。这种 skill 的需求其实挺常见很多每周要写技术报告、论文草稿的人总是反复教 agent “用 LaTeX、要规范、要能编译”每次对话都要重新解释。封装成 skill 之后一句话就能触发完整工作流。我的目录结构是这样latex-typesetter/ ├── SKILL.md ├── references/ │ ├── article-template.tex │ ├── beamer-template.tex │ ├── resume-template.tex │ └── common-macros.tex └── scripts/ └── check_compile.shSKILL.md 的 frontmatter 是--- name: latex-typesetter description: 将用户提供的内容排版为规范的 LaTeX 文档。适用于论文、技术报告、简历、幻灯片等场景。用户明确提到 LaTeX / 排版 / 论文模板时使用用户只想要 Markdown 时不要调用。 ---正文部分我建议大家分成三块而不是写一大段话。第一块叫“输入要求”告诉 agent 需要收集哪些信息比如文档类型、目标期刊/会议格式、图片素材路径、参考文献列表。第二块叫“执行流程”按顺序列出步骤。第三块叫“输出要求与自查清单”把成品需要满足的约束写清楚。3.2 编排规则让 agent 严格按流程干活LaTeX 排版这活儿agent 最容易犯的毛病是“自信地生成一堆编译不过的代码”。所以我特意把执行流程写得像强制规范。完整的执行步骤大致是根据用户需求从references/选择基础模板论文用 article演示稿用 beamer中文简历用自定义 ctex 模板。将用户提供的内容按章节结构映射进模板图片路径统一放在figures/下并检查文件名是否有中文与空格。如果用户提供了 BibTeX 文件保留原始 key不重命名如果没有自动生成thebibliography环境并注意格式一致性。调用scripts/check_compile.sh做一次本地编译验证失败则逐行检查错误日志并修复然后再次编译最多重试 5 次。向用户输出编译后的 PDF 路径同时附带说明做了哪些格式调整。这个流程看起来不复杂但把“要不要编译验证”这件事写进去效果立竿见影。以前 agent 生成的 LaTeX 经常缺包、缺\end{document}或者引用了未定义的宏现在它会在交付前自己跑一遍编译错误率几乎降到了零。这种“把检查动作写进 skill 规则”的思路你可以迁移到任何技能上。在编排时记得写“反向约束”。我在 SKILL.md 里明确写了几条禁止事项不允许修改模板里预设的页面尺寸和字体不允许在用户未要求时引入多余宏包不允许把参考文献转成纯文本。agent 是服从性很高的执行者你不告诉它边界它就会按最省事的路径走最后产出一堆“看起来很专业但不符合要求”的东西。3.3 测试与评测skills 质量怎么量化skill 写好之后怎么知道它到底行不行我自己的做法是准备三份测试输入覆盖典型场景一份 4000 字的中文技术报告一份含图表和公式的英文论文草稿一份简历内容。每次对 skill 做修改都拿这三个用例跑一遍重点观察四个指标触发准确率需求相关时是否正常调用不相关时是否误触发。格式一致性输出模板是否统一页边距、字号、章节编号是否符合规范。编译通过率直接决定交付质量。人工修改成本用户拿到结果后还要改多少东西。这个指标最真实改得越少说明 skill 越成熟。这里我用的是最朴素的“金标准比对法”先由人工制作一份理想输出再让 skill 生成结果逐项对比差异。社区里也有人在做更系统的 agent evals把测试集和评分规则都代码化每次改完 skill 自动跑评分。我自己的建议是先手工评测跑通主要场景等 skill 真正稳定了再考虑自动化 eval不要一上来就搭复杂框架。3.4 同思路迁移前端、结构图、图片生成与逆向分析LaTeX 排版 skill 的开发模式完全可以平移到其他场景。这也是我写这个小节的用意——你自己不一定要照抄 LaTeX 的例子但可以把它当成一个“模板”去理解所有 skills 的套路。前端开发 skills 的核心是“规范固化和组件复用”。把团队的项目结构、命名规范、样式约定、常用组件代码都写进 referencesagent 生成的代码就会迅速贴合团队风格而不是每次产出一套“随机风格”。我见过不少团队用这种方式把前端 AI 助手的代码评审成本砍掉了一半核心就是让 skill 替人记住所有隐性规则。结构图 skills 和图片生成 skills 更多是“工具链封装”。比如结构图 skill 规定统一用 mermaid 还是 d2、节点标签怎么命名、颜色怎么分组图片生成 skill 则封装好提示词模板、固定比例、负面提示词和后处理步骤。这种 skill 看起来简单但能让输出从“能看”变成“一致”在多轮迭代中价值非常大。AI 逆向 / 代码分析类 skills 则需要额外强调权限边界。我的建议是这类 skill 只能用于分析自有代码或已获授权的开源项目SKILL.md 里也明确写入“禁止绕过鉴权、禁止分析未授权代码”的条款既是安全底线也是合规要求。skill 本身再强也必须跑在可审计、守规矩的流程里。4. skills 之外的 agent 技术栈全景4.1 框架与 harness先跑通业务再考虑自研skills 是 agent 生态里非常耀眼的一层但它不是全部。真正做 agent 项目时你很快会遇到 framework 和 harness 的选型问题。我的总体建议是如果你在用 Claude Code、Codex 这类现成产品那就老老实实用它自带的 harness先跑通业务不要一上来就琢磨自研框架。框架层比如 LangGraph、AutoGen、CrewAI解决的是“多个 agent 之间怎么编排、怎么通信、怎么共享状态”的问题。这类框架适合复杂业务系统比如你需要多个专业 agent 协作处理一个长流程任务。但它的学习成本和调试成本都不低很多项目其实用不上这么重的结构。判断标准很简单如果你的 agent 单个就能完成 80% 的任务只是偶发需要人工介入那优先优化 skills 和工具而不是换框架。Harness 层面更要克制。我见过团队花三个月自研 harness最后发现做出来的东西连 Claude Code 免费功能的六成都不到。Harness 真正难的不是发请求而是上下文管理、工具故障恢复、长任务断点续跑、权限控制这些“脏活”。除非你是要做产品级差异化否则站在成熟 harness 之上做业务集成是性价比最高的路径。4.2 记忆、安全与 evals 三道坎agent 项目做到第二个月你大概率会遇到三道坎记忆、安全、评测。记忆这块“agent 记忆”是社区里的热门话题。短期记忆靠上下文管理长期记忆就要靠外部存储。最朴素的方案就是让 agent 把关键信息写进 Markdown 或 JSON 文件下次启动时读取本质上是你手写一套“文件系统记忆”。更复杂的方案会引入向量数据库支持语义检索。我的建议是从文件记忆开始够用之后再升级。很多人一上来就上向量库结果检索结果不稳定反而把问题搞复杂了。安全这块需要认真对待重点防范三类风险。第一是提示注入恶意内容诱导 agent 执行非预期操作所以在 skill 里要写清“不执行来源不明的指令”。第二是匿名代码执行给 agent 配了 shell 权限之后务必要限制目录范围和命令白名单。第三是恶意技能包下载第三方 skills 时检查 SKILL.md 里是否有可疑脚本装完后先让它跑只读任务验证行为。Evals 则是保证 agent 不越改越差的唯一手段。你不给 agent 建立评测集就没法知道一次 prompt 调整是提升了还是恶化了整体效果。我的做法是从 20 个典型任务开始每次改动全量跑一遍输出对比结果。这套东西做起来不复杂难在坚持维护。4.3 学习路线与常见问题快查最后给想入行 agent 开发的朋友一份路线图。先打基础认真学 LLM 原理、prompt engineering 和结构化输出然后学工具调用理解 function calling 的机制和局限接着熟悉至少两个主流 agent 产品比如 Claude Code 和 Codex重点研究它们的 skills 和 agent 配置方式再做项目挑一个重复性高的任务开发一个 skill 并反复打磨最后进阶去理解 evals 和 agent 安全。按这个顺序走比盲目翻框架文档要扎实得多。攻克完这些你需要掌握的最核心的知识点实际上就是我上面反复出现的那些。我把它整理成一个常见问题排查清单方便你干活时直接翻问题现象可能原因解决思路Agent 不调用已安装的 skilldescription 边界不清晰改写触发条件和反向约束Skill 放在项目里不生效目录位置/命名错误检查 skills 目录结构和 name 字段“Agent execution terminated due to error”上下文超限、工具异常或限流看日志定位是上下文问题还是工具调用问题Skill 输出质量不稳定缺少校验步骤在 SKILL.md 里加入自查清单和测试用例多个 skill 行为冲突触发条件重叠明确每个 skill 的场景边界和优先级关于 “Agent execution terminated due to error” 这条我再单独多说两句。这是最吓人也最常见的一条报错但绝大部分情况并不是 agent 本身坏掉了而是上下文太长、单次工具超时或模型服务限流。排查时不要慌先去翻 harness 的输出日志看具体错误是发生在模型调用还是工具调用阶段再对症处理。实在看不出来就把任务拆小一点重试一次八成能过。最后说点我的实际感受我在实际使用中最大的体会是skills 这个生态还处在非常早的阶段现在入场是最好的时机。工具会迭代模型会升级但“把一个领域的工作流固化成可复用技能包”这件事不会过时。如果你现在开始动手写自己的第一个 skill哪怕只是最简单的一个“技术文档格式化”技能你积累的经验都会在后续所有 agent 项目里持续复利。而且你会发现写得越久你对 agent 能力的理解就越准——因为 skills 本质上是“人类经验”和“模型能力”之间的桥梁这座桥修得越好agent 替你做事的边界就越宽。我的建议很简单不要囤那些永远不用的收藏夹了挑一个你每周都要重复做的场景今晚就写一个 skill 出来。