这两年做 AI agent 开发最明显的一个变化是大家讨论的重点从怎么让 agent 更会推理逐渐转向了怎么让 agent 更会干活。而会干活这件事绕不开一个东西——agent skills。简单说skills 就是给 agent 准备的一组可复用、可插拔的能力包让它在面对具体任务时不用靠临场发挥而是有一套规范化的操作流程和领域知识可以直接调用。最近agent skills相关的讨论热度涨得很快从 Claude Code skills、Codex skills 到 superpower skills再到各类 skills 源网站和安装教程说明大家已经不只是停留在让 agent 聊天的阶段而是真的想让 agent 进到自己的开发流程、写作流程、排版流程里做实事。这篇文章我想结合自己做 agent 项目、写 skills 的实操经验把 skills 的底层逻辑、设计方法、安装路径、测评思路以及那些容易被忽略的坑一次性说清楚。整篇内容更适合正在用 Claude Code、Codex、或自研 agent 框架的开发者也适合想系统学习 agent skills 开发的新手照着做就能上手。1. agent-skills 到底是什么从会聊天到会干活1.1 一个概念的快速演化先理一下背景。早期大家玩 agent主流思路是 prompt 工程把任务背景、角色设定、约束条件一次性塞进 system prompt。任务简单的时候这种方式没问题但任务复杂度一上来把所有东西都堆进上下文的做法就显得很吃力token 成本高、指令之间互相干扰、想更新某一个业务规则还得分不清改哪里改完又怕影响其他地方。于是后面陆续出现了 RAG、tools、MCP 这些方案。RAG 解决的是模型不知道的知识怎么补tools 解决的是模型不会的动作怎么接MCP 则是把这些工具调用标准化。而 skills 是另一个维度的解法它既不是单纯给模型更多上下文也不是单纯暴露更多工具入口而是把完成一类任务所需要的知识、步骤、示例、脚本打包成一个标准化的目录让 agent 在需要的时候按名字加载。这个思路在 Claude Code 和 Codex 里体现得最明显。拿 Claude Code 来说它会读取项目里的.claude/skills/目录也会读用户级的~/.claude/skills/目录每个子目录就是一个 skill。Agent 根据任务描述判断哪个 skill 匹配当前需求再把 skill 里的指令注入上下文执行。整个过程对使用者来说是声明式的你只需要把能力包装好agent 自己知道该用的时候用不需要你每次手动指定。1.2 skills 的底层构成metadata、instructions 与 assets我第一次接触 skills 的时候以为就是一个 markdown 文档后来真正拆开看才发现一个标准的 skill 目录通常包含三层内容元信息与操作指令一般就是 SKILL.md文件头部带 YAML frontmatter写 name、description 这些元数据正文部分则是对 agent 的操作指引。资产文件包括模板、示例、参考文档等比如 LaTeX 模板、代码风格指南、领域知识库。可执行脚本如果 skill 涉及本地操作比如格式转换、图片处理、数据抓取可以在 scripts 目录里放可执行脚本由 agent 按需调用。这套结构的设计逻辑是把知识和动作分开。SKILL.md 负责告诉 agent 应该怎么做assets 负责提供做的时候需要用的内容scripts 负责真正动手执行。三层分离之后同一个 skill 可以被不同模型、不同框架复用只要它们能解析这套目录结构。这里我想强调一点很多新手写 skills 容易把 SKILL.md 写成一篇文章洋洋洒洒几百行科普结果 agent 加载后只是读了一遍并没有真正形成行为约束。好的 SKILL.md 应该像一份 SOP明确输入、处理步骤、输出格式、判断标准和常见陷阱让 agent 看完就知道该按什么顺序做事、做到什么程度算合格。打个比方skills 就像是给一个新员工发的一本《岗位操作手册》。手册不是给他讲行业历史而是告诉他接到什么单子走什么流程、每步做到什么标准、遇到异常找谁处理。Agent 拿到这样的手册才能真正独立干活而不是每次都要你盯着。2. skill 和 agent 的分工边界别再混为一谈2.1 两者的定位差异相关的热搜词里频繁出现skill和agent的区别、还有harness和agent区别说明这是现阶段大家最困惑的地方。我结合自己项目里的实践把边界理一理。Agent 是目标驱动的执行体。它负责理解用户需求、拆解目标、规划步骤、调用工具、与环境交互最终完成一个任务闭环。它有自己的判断力和主动性可以在不确定的情况下做出决策。Skill 是能力模块。它封装的是某类任务具体怎么做的知识和流程本身没有目标没有循环执行的能力也不会主动发起行动。它更像一个被动的专家包只有被 agent 调用时才生效。举个例子。你让一个 agent 处理一篇论文的排版agent 会先规划读题目要求、整理内容结构、调用排版工具、检查输出结果。在这个过程里它可能会调用一个 latex 排版相关的 skill这个 skill 只负责把 Markdown 内容转成符合学术规范的 LaTeX 文档这一件事。它不关心论文主题是什么、内容有没有写好它只保证排版环节的输入输出符合规范。2.2 实际开发中两者的配合方式从架构角度来看agent 是大脑和手脚skills 是工具箱里的专用附件。Agent 决定用不用、什么时候用、用完之后怎么验证结果skill 决定怎么把事情做对。我在实际项目里一般是这样组织的顶层是一个 agent 编排层负责理解用户需求、拆任务、管理执行顺序和结果校验。中间是框架层比如 Claude Code、Codex 或者自研的 agent 框架负责模型调用、工具注册、上下文管理。底层就是 skills 集合按领域拆分成不同目录比如latex-skills、frontend-skills、image-generation-skills。这样组织有一个很实际的好处可以独立更新某个 skill 而不影响整体框架。比如前端组件规范变了我只需要改对应用 skill 里的文档和模板agent 下一次执行时自然就按照新规范走不用重新调整个 agent 的 prompt也不用担心改一处坏一片。还有一个容易踩的坑是skill 的粒度问题。粒度太粗一个 skill 里塞了几百行指令agent 加载后占大量上下文无关内容多执行效果反而差。粒度太细每个 skill 只解决一个极小的问题agent 需要在多个 skill 之间反复跳转容易丢失任务上下文。我个人的经验是一个 skill 对应一个可独立验收的任务类型比如代码审查Markdown 转 LaTeX前端登录组件生成图片风格统一处理而不是写代码写文档这种大而全的类别。3. 手写一个 skills 的完整过程以 LaTeX 排版 skill 为例3.1 需求拆解与目录设计写 skill 不能上来就写文档第一步是拆需求。以LaTeX 排版 skill为例我看到很多参赛和写论文的人都在找这类 skills结合热词怎么做一个latex排版skills的高频出现我把它当典型来说。先明确这个 skill 要解决什么问题。假设目标是把用户提供的 Markdown 内容包含标题、段落、表格、公式占位符转换成一个符合学术规范的 LaTeX 文档。那它要处理的事情有识别 Markdown 的标题层级映射到 LaTeX 的 section/subsection。处理列表、表格、图片引用、公式。套用统一的模板包含中文支持、页边距、字体设置。输出可编译的 .tex 文件并在末尾给出编译命令。明确了这些之后再设计目录结构。我建议的目录如下latex-formatter/ ├── SKILL.md ├── templates/ │ └── academic.tex ├── scripts/ │ ├── md_to_tex.py │ └── compile_check.sh └── examples/ ├── input_sample.md └── output_sample.tex这样的结构好在边界清楚SKILL.md 只负责指导 agent 如何调用模板和脚本templates 提供最终要套用的格式scripts 处理自动化转换examples 则给 agent 一个标准答案参考。Agent 在执行时如果拿不准某个转换规则该怎么做可以先看 examples 里的示例输出对齐格式。3.2 SKILL.md 的核心写法SKILL.md 是整个 skill 的入口文件Claude Code、Codex 这类框架都是靠它的内容来决定何时调用、如何执行。我写 SKILL.md 的时候会严格分两个部分。第一部分是 YAML frontmatter。name 要短description 要写得像检索词因为 agent 是靠 description 来匹配任务的。比如--- name: latex-formatter description: 将 Markdown 内容转换为符合学术规范的 LaTeX 文档支持中文、公式、表格和图片引用。适用于论文排版、实验报告和建模大赛文档。 ---description 的写法很有讲究。太笼统比如处理文档排版agent 在遇到无关的排版需求时也可能错误加载太具体比如只处理华为杯论文适用范围又太窄。最好是动词 对象 适用范围的结构让 agent 能在几毫秒内完成匹配判断。第二部分是正文。正文不用写成论文但要包含几个固定模块任务输入说明这个 skill 期望接收什么比如一个 Markdown 文件路径或直接粘贴的内容。处理流程按序号列出步骤比如先检查内容结构、再生成中间格式、套用模板、最后校验。输出标准说明什么样的输出算合格比如生成的 .tex 文件必须能通过 xelatex 编译中文必须使用 ctex 宏包。常见错误与规避把容易犯的错写进去比如图片路径不能包含中文、公式里的特殊字符需要转义。我写正文的时候通常控制在 60 到 120 行左右。太少信息量不够agent 执行时容易自由发挥太多加载成本高而且很多内容 agent 根本用不到。3.3 编写过程中的几个关键决策第一模板要厚还是要薄。我建议模板尽量厚把常规设置都写进去比如 documentclass、ctex、geometry、amsmath 这些宏包和页边距配置。这样 agent 在生成内容时只需要聚焦内容本身不用每次都在脑子里重建格式框架出错率会低很多。第二脚本要不要自动化到底。像 md_to_tex.py 这种转换脚本理论上可以实现完全自动化但实际跑下来我发现完全自动化的脚本在处理复杂表格和嵌套列表时经常出错反而不如让 agent 先生成中间结构、再手工介入调整来得可靠。所以我的方案是脚本负责重活、比如批量转义和模板套用agent 负责逻辑判断和格式校验人机协作而不是全自动。第三举例要干净还是丰富。examples 里的输入样本要覆盖常见场景但不追求穷举。我一般放两个案例一个简单的纯文本案例一个带公式、表格、图片引用的综合案例。两个案例就能让 agent 理解大多数转换规则多了反而干扰判断。写完后一定要做的一件事是用真实内容跑一遍。我第一版 latex 排版 skill 就是没跑真实用例结果 agent 生成出来的 .tex 文件在 xelatex 编译时报错原因是一个布尔字段的大小写写错了。所以我现在每个 skill 写完都会做一个最少可行测试确保端到端能走通再提交使用。4. 安装与使用实测Claude Code、Codex 与聚合包4.1 常用 skills 源与挑选标准热词里频繁出现常见 skills 源网站skills 下载skills 推荐说明大家第一步卡在找资源上。目前公认的几个渠道主要是 GitHub 上的技能仓库、社区维护的技能市场以及像 superpower skills 这样个人维护的高星聚合仓库。但我会提醒一句不是所有 skill 都值得装。挑选 skill 时我一般看四个标准判断维度怎么看活跃度最近 3 个月有没有 commitissue 有没有人回应结构完整度是否包含 SKILL.md有没有 examples 和 scripts还是只有一个说明文档描述质量description 是否写清楚了适用场景能不能被 agent 准确匹配依赖复杂度是否依赖特定框架版本或特定操作系统安装文档清不清楚看过太多所谓skills 合集点进去发现就是把一堆 prompt 拼在一起没有目录结构没有示例也没有脚本。这种不是 skills是提示词合集装进去对 agent 的行为约束非常弱还额外占上下文。4.2 安装步骤与注意事项不同框架的 skills 安装路径不太一样但思路是共通的。以 Claude Code 为例把 skill 目录放到指定位置即可# 用户级 skills作用于所有项目 mkdir -p ~/.claude/skills # 项目级 skills只作用于当前项目 mkdir -p .claude/skills # 拉取远程仓库到 skills 目录 git clone https://github.com/yourname/latex-formatter.git ~/.claude/skills/latex-formatterCodex 的环境也类似一般放在~/.codex/skills或项目目录下的.codex/skills。这里有几个容易踩的坑我单独列出来目录名与 skill 名不一致。很多框架是按目录名识别 skill 的目录叫 latex-formatterSKILL.md 里的 name 写 latex_format加载时容易出现匹配不上或重复加载。我的建议是保持两者一致都用短横线命名。权限问题。如果 skill 里的脚本需要执行权限clone 下来之后记得chmod x scripts/*.py不然 agent 调用时会报 permission denied而且这类报错还不好排查因为不是模型的问题是环境的问题。更新方式。拉取的 skill 是静态副本上游仓库更新了你不会自动同步。建议把常用 skill 统一放在一个目录里定期git pull不要让 agent 项目里散落着多个版本的同一 skill。4.3 superpower skills 该类聚合包的使用体验再重点聊一下 superpower skills因为我看到相关搜索热度很高。这个项目本质是一个大型 skills 集合把写作、编程、身份设定等很多能力打包在一起。我的使用感受是它作为学习素材的价值很高。你能看到别人是怎么设计 description 的、怎么组织处理流程的、怎么通过例子约束 agent 行为的。这些对提升自己写 skill 的水平很有帮助。但从实际项目使用角度我不建议整个仓库无脑装进生产环境。原因很直接它体积大加载时会占用不少上下文而且它面向通用场景和你项目的具体业务规范和工具链未必匹配。我更推荐的做法是挑出其中跟你的工作流强相关的三五个 skill精读之后改造把模板换成自己项目的、把例子换成自己业务的、把脚本调整成和现有工具链兼容的版本。这样得到的才是你的 skill而不是一个跟项目有隔阂的通用包。顺便说一句这类聚合包名字起得很有营销感什么 superpower 之类的但本质上还是信息组织的问题。真正决定一个 skills 生态好不好用的从来不是名字而是 description 是否清晰、步骤是否可执行、示例是否可参考。5. skills 怎么测评不测评等于白写5.1 评测维度和评测集的建立很多人的 skill 写完后直接投入使用遇到效果不好就开始怀疑模型能力其实问题往往出在 skill 本身。我自己在使用skills怎么测评agent evals这些高频热词时也发现大家的困惑很一致怎么写 skills 已经有不少教程了但怎么判断一个 skill 写得好不好几乎没有系统性的方法。我现在每写一个 skill 都会配一个 mini 评测集。不需要很重但至少要有三个用例标准用例完全符合预期输入格式的内容验证主流程是否走通。边界用例比如空内容、超长标题、特殊字符、本地化内容验证容错能力。干扰用例和这个 skill 不相关的任务验证 agent 是否会被误触发加载。有了评测集之后我会在每次修改 SKILL.md 后跑一遍记录三个参数触发准确率需要用的任务是否加载了不该用的任务是否没加载。执行成功率输出是否符合 output 标准比如能不能编译通过。token 开销加载这个 skill 平均消耗多少上下文是否值得。5.2 一个完整的排查链路为什么 agent 不按 skill 执行分享一个我实际踩过的排查案例整个过程能帮大家理解 skill 执行链路。有一段时间我写了一个前端生成 skilldescription 写的是生成符合项目规范的 Vue 组件。结果测试的时候发现agent 在遇到相关任务时根本没有加载这个 skill而是自己直接生成了组件。开始我以为是框架的调用逻辑有问题浪费了不少时间。后来一步步排查发现问题出在项目规范四个字上。Agent 在执行任务前会根据用户需求做一个快速匹配。如果任务表述里出现的是写一个登录页而 skill 的 description 强调的是生成组件两者的话题连接不够直接agent 就会觉得这个 skill 跟当前任务没关系于是跳过。另外一个隐患是 description 太宽泛时agent 每次都想加载验证导致上下文被大量无关指令占据。我当时的修复方式是把 description 改成根据项目 design-token 与组件规范生成可直接运行的 Vue 组件代码适用于登录页、列表页、表单页等常见页面。这样既点明了适用场景又暗示了输出标准。改完之后触发准确率明显提升。这个案例告诉我们一个通用的排查思路当 agent 的某个行为不符合预期时不要先怀疑模型按这个顺序检查——先是 description 是否匹配、再是 SKILL.md 内容是否可执行、然后是资产文件路径是否正确、最后才是框架配置问题。先检查自身再检查环境能省下大量时间。6. skills 与记忆、安全的关系以及后续演进6.1 skills 的权限与安全边界很多人把 skills 当成普通文档忽略了它其实具备代码执行的能力。一个 skill 里如果带了 scripts那 agent 加载它之后就可能执行这些脚本这就涉及到权限和安全边界问题。我在项目里对 skill 的安全管理有几个硬性要求。第一不随意拉取来源不明的 skill 仓库尤其是带自动化脚本的先人工审查一遍再放入生产目录。第二限制 skill 脚本的执行权限能读的不要给写能执行的尽量沙箱化。第三对涉及网络请求、文件删除、系统配置的脚本加一层明确确认机制不默认放行。这个观点可能有人觉得保守但我的理解是skills 的便利性正是来自它的可执行性这份可执行性如果不加约束agent 的潜力有多大风险就有多大。特别是团队里多人共用一套 skills 的时候安全策略必须前置。6.2 skills 与 agent 记忆的配合另一个值得展开的点是策略在热词中同样高频的agent记忆和agent架构之间的关系。记忆解决的是跨会话保留偏好和经验的问题skills 解决的是单类任务怎么做的问题。两者配合起来效果才会好。举个例子。你让 agent 每次都按你的习惯输出工作报告开头是结论、中间是数据、结尾是下一步计划。这种偏好属于记忆agent 靠历史记录就能学到。但如果你的报告需要符合某一种特定格式模板这个模板就应该沉淀成 skill因为模板是稳定的、可复用的、跨会话不变的。那偏好类和规则类怎么分我的标准很简单如果一项约束会因为项目、场景不同而变化放在记忆里由 agent 动态调整如果一项约束是固定的、标准的、可以固化成流程的放进 skill。这样分记忆不会被无关信息塞满skill 也不会因为频繁改动而失去稳定性。6.3 我接下来的使用方向写这篇总结的时候我正在做的事是把项目里分散的几个 prompt 片段和脚本逐步收敛成标准 skills同时给团队搭一个内部的 skills 评审流程。后续我会更多关注 skills 生态的测评工具以及不同框架之间 skills 格式的互操作性——如果哪天 Claude Code、Codex、自研框架能共用同一套 skills 目录规范那 agent 的可迁移性会好很多。另外基于热词里ai skills怎么写skills开发这些高频问题我也在准备把写 skill 的通用套路整理成一个模板仓库统一放 demo、评测集和检查清单。如果你也想从零开始积累自己的 skills 库我的建议是先挑一个你每周都会做的重复性任务把它写成 skill跑通一个再复制经验到下一个。不要一上来就想做一个大而全的个人 skills 平台那既消耗精力也很难真正沉淀出高质量的能力包。先从一个能解决实际痛点的 skill 开始比什么都重要。
