最近大半年我一直在跟 AI Agent 打交道先说结论决定 Agent 上限的早就不再是模型本身而是你给它配了什么 Skills。同样是 Claude有人用起来像高级实习生有人用起来像只会复读的聊天机器人差距基本都出在 Skills 这一层。尤其当你开始做 agent 开发会发现市面上讨论的 skills 推荐、claude code skills 安装、superpower skills 安装 这些热词本质都在解决同一个问题怎么让 Agent 不只是会说话而是会干活。这篇文章不写虚的我会从概念讲到实操再从踩坑讲到测评把我这一年里折腾 agent-skills 的经验完整摊开。适合正在学 agent 开发、想给自己前端的 Claude Code 或 Codex 加技能、以及准备 agent 开发面试的朋友。文章会有不少可以直接抄的配置和脚本也会说清楚每个设计背后的理由。1. Agent Skills 是什么从只会聊到会干活的那一层1.1 没有 Skills 的 Agent 有多低效我一开始用 Claude Code 写项目时最大的痛苦是每次都要重新给 Agent 讲规矩。比如让它写 Python 代码我要在对话里反复强调用类型注解、用 dataclass、错误处理要写清楚、测试要放在 tests 目录。这一套话术每个新会话都要复制粘贴一遍。更麻烦的是领域知识。我做一个 LaTeX 排版需求时Agent 每次都会在中文支持上翻车——要么编译出来全是乱码要么忘了用 xelatex。这不是模型笨而是它没有稳定的、可复用的领域操作流程。它就像一个没有受过岗前培训的新人每次都凭感觉干活质量完全随缘。传统做法是把这些要求写进 system prompt。但你试试就知道prompt 太长之后 Agent 会选择性失忆关键的几条规则被淹没在一大段话里它该犯的错照样犯。1.2 Skills 本质上是一个能力包Skills 解决的就是这个问题。一个 skill 本质上是一个能力包把某一类任务的操作流程、判断标准、示例、脚本、参考资料打包在一起放在一个固定目录里让 Agent 在遇到相关任务时自动加载并使用。它跟 prompt 最根本的区别是结构化和可复用。Skill 不是一个孤立的文本它是一套完整的文件夹结构my-skill/ ├── SKILL.md # 技能主文件包含元信息和核心流程 ├── reference/ # 参考资料按需加载 ├── templates/ # 可复用的模板文件 ├── scripts/ # 可执行的脚本 └── examples/ # 示例输入输出SKILL.md 是入口开头有一段 YAML 格式的元信息其中 description 字段最关键——Agent 就是靠读这段描述来判断当前任务要不要调用这个技能。后面正文则用普通 Markdown 写操作流程、注意事项、质量标准。你可以把它理解成给 LLM 插的 U 盘平时不占内存用到时插上读一下里面的知识和方法就全有了。对 Agent 来说它不需要把整套技能都塞进上下文只需要按需加载这也是为什么 skill 可以做得很大而不会拖慢 Agent 的日常响应。1.3 一个 Skill 的标准形态长什么样拿我自己写的前端开发 skills打个样。我维护了一个 frontend-dev 的技能包里面不只是写你要写 React而是把组件设计规范、状态管理策略、样式约定、目录结构、代码审查清单全部拆开。SKILL.md 的开头是这样--- name: frontend-dev description: 用于React前端项目开发。当用户要求实现组件、修复界面问题、优化前端性能或评审前端代码时使用。包含组件设计规范、状态管理、样式约定和代码审查清单。 ---然后正文按照设计阶段 - 实现阶段 - 审查阶段组织每个阶段有明确的检查和输出要求。Agent 读到这个文件后就会严格按照里面的流程来干活而不是自由发挥。这就解释了为什么 skills 能让 Agent 的表现从随机变成稳定它给 Agent 提供了确定性。模型本身是概率性的但技能文件是确定性的只要 description 被正确触发Agent 就会遵循文件中写好的、你验证过有效的流程。2. 概念边界Skill、Agent、Harness、Prompt 别再混着用了skill 和 agent 的区别、harness 和 agent 区别——这两个问题在搜索热词里出现频率极高。很多新手被绕晕主要是因为这几个概念在英文社区里经常混着说翻译过来更乱了。我把边界理一遍。2.1 Skill 和 Prompt 的本质差异这是最好理解的一组对比。Prompt 是你发给模型的一次性指令生命周期只有一次对话Skill 是持久化的能力模块可以反复调用、迭代更新。看这张表更清楚对比项Prompt提示词Skill技能生命周期单次对话内有效持续存在跨会话复用结构纯文本松散目录结构 元信息 脚本触发方式用户主动输入模型根据描述自动判断维护方式每次重新编写独立文件随时迭代可测试性难以自动化验证可建测试集回归验证有一个常见的偷懒做法是把超长 prompt 直接塞进 skill 文件夹里当 SKILL.md这种做法能用但没有发挥 skill 的优势。Skill 真正的价值在于渐进式披露progressive disclosureSKILL.md 只写核心流程细节放到 reference 目录里让 Agent 按需读取。如果所有内容堆在 SKILL.md 里就又回到了超长 prompt 的老问题。2.2 Agent 是执行者Skill 是能力包Agent 是一个完整的自治系统它包含 LLM 主脑、规划能力、记忆、工具调用循环以及决策机制。它负责理解任务、拆解步骤、调用工具、根据结果调整行动。Skill 则只是这个系统里的一个可插拔组件。Agent 是大脑Skill 是大脑可以随时查阅的工作手册。Agent 决定什么时候该干活Skill 提供活该怎么干的具体方法。我习惯用厨师来类比Agent 是主厨Skill 是他案头那本菜谱。主厨知道什么时候该做菜、怎么统筹整个后厨但他不能啥菜都会做遇到不熟悉的菜就得翻菜谱。菜谱不会替他翻炒但保证了他做出来的菜稳定、不翻车。所以skill 和 agent 的区别一句话就能说清Agent 是主体Skill 是它使用的工具Agent 可以没有 Skill 运行只是效果差但 Skill 脱离了 Agent 就只是一堆文件。2.3 Harness 是 Agent 的运行环境Harness 这个概念讨论的人少但恰恰是harness 和 agent 区别的热度来源。Harness 直译是马具在 AI Agent 语境里指运行环境——就是那套把模型、工具、外部命令、沙箱、文件系统、网络访问串起来的执行框架。Agent 负责想Harness 负责做。Agent 决定调用某个工具Harness 负责真正执行这个工具、捕获输出、处理超时和错误把结果回传给 Agent。你可以把 Harness 理解成 Agent 的身体和作业系统。对比项AgentHarness角色决策者负责规划和判断执行环境负责工具运行核心组成LLM、记忆、规划、工具调用逻辑CLI、沙箱、进程管理、权限控制类比驾驶员汽车举个例子Claude 模型 它的推理Claude Code 这个 CLI 工具本身这里有个容易混淆的点像 Claude Code、Codex CLI 这类产品其实是Agent Harness的合体所以大家经常把这两个词混用。但在讨论架构时区分它们很重要——当你给 Agent 配置 skills 时你实际上是在给 Agent 添加知识而当你处理权限、网络、脚本执行问题时你面对的是 Harness 层的问题。2.4 几个说不清楚就踩坑的误解第一个误解Skill 就是提示词工程的高级版本。严格说 Skill 确实建立在提示词之上但它的结构化和脚本能力是纯提示词没有的。Skill 可以携带可执行脚本做确定性操作比如编译、转换格式这是纯文本提示永远做不到的。第二个误解Skill 目录越多越好。Skill 多了之后description 之间会互相打架Agent 反而不知道该调哪个。我见过有人一口气装了几十个 skill结果 Agent 判断频繁出错。好的实践是精而不多每个 skill 边界清晰。第三个误解Agent 一定会遵守 Skill 的指令。模型有概率性SKILL.md 写得再清楚Agent 也可能在某些上下文里跳过或部分执行。这也是后面要讲测评和调试的原因——Skill 不是写了就完事它需要被验证和迭代。3. 生态盘点Claude Code、Codex、Superpower Skills 与主流框架的 Skills 实现3.1 Claude Code Skills 的安装与目录逻辑Claude Code 是目前对 Skills 支持最完善的工具之一。它有两种存放位置# 个人级 skills对所有项目生效 ~/.claude/skills/你的技能名/SKILL.md # 项目级 skills只对当前项目生效 你的项目/.claude/skills/你的技能名/SKILL.md安装 skills 的方式有三种手动 clone 到目录、用claude skill add命令、或者直接复制文件夹。我推荐从 GitHub 找现成 skill 时用命令安装claude skill add https://github.com/某用户/某技能仓库命令会自动把它放到正确位置省去手工摆放的麻烦。这里分享一个实际经验项目级 skills 比个人级 skills 重要得多。个人级放在全局目录里的技能解决了我的偏好问题比如代码风格、常用技术栈但项目级技能解决的是这个项目的特殊规则问题比如项目的目录结构、第三方库版本、构建命令。我接手新项目第一件事就是看看项目的.claude/skills里有什么。3.2 Codex Skills 与 AGENTS.md 的关系OpenAI 的 Codex 也推出了类似机制。Codex 项目级配置用AGENTS.md文件描述项目规范而技能skills是可复用的跨项目能力。两者关系有点像公司制度和个人职业技能AGENTS.md 管的是这个项目怎么办事skills 管的是某类事情应该怎么做。Codex 安装技能的命令是codex skills add跟 Claude Code 的目录结构类似Codex skills 也是描述 指令 参考文件的结构。我实际用过后的感受是Codex 的 skills 机制偏简洁不如 Claude Code 的生态丰富但核心思路一致——用结构化的指令包让 Agent 在特定任务上有稳定的表现。社区里那些codex 好用的 skills、codex 论文 skills 推荐的帖子本质都是把某个领域的专家级操作流程固化成了技能。论文写作类 skill 通常会包含写作结构模板、引用格式规范、审稿人视角的自检清单这些都是靠 prompt 很难稳定复现的。3.3 Superpower Skills 与第三方社区库Superpower Skills 是社区里非常有名的技能包集合由 Superpowers 团队维护。它把大量经过验证的 skills 打包在一起覆盖写作、编程、研究等多个方向。安装很简单一条命令搞定claude skill add superpowers我用了它的结构化输出类技能之后对skills 推荐这事有了新认识好技能的核心是流程设计而不是花哨功能。Superpower Skills 里的技能普遍有一个特点——把任务拆成明确阶段每阶段有输入、处理和输出定义。这种设计天然适合 LLM 执行因为它给了模型清晰的路标。社区里还有大量专项技能比如结构图 skills让 Agent 输出规范的结构图标记语言、图片生成 skills 安装包整合图像生成工具的调用流程、ai 逆向 skills逆向分析的工作流。这些第三方技能包的质量参差不齐我建议安装后第一时间通读 SKILL.md判断它的流程是否符合你的预期。3.4 其他框架与工具的 Skills 实现除了 Claude Code 和 Codexagent 生态里还有一批框架和桌面端在做类似能力。pi agent 的桌面端做得挺早注重本地运行和数据隐私hermes agent 主打多工具协同它对 skills 的加载机制更接近自动化工作流不是靠 LLM 自主判断而是有明确的条件触发。codebuddy、opencode 这类新工具基本都跟随了项目级配置 技能包的范式。opencode 更激进一些直接把 skills 插件化支持运行时热加载。agentscope 则有比较完整的 skills demo我建议学概念时去看看它的示例——它对同一任务配置多个 skill 后能清楚看到模型是如何在技能之间做选择的。给 agent 开发新手一个忠告不要急着把所有工具都试一遍。先选一个主流生态我推荐 Claude Code把 skills 的开发 - 安装 - 触发 - 调试闭环跑通再看其他工具会发现都是换汤不换药。你真正要学的不是某个工具的命令而是如何设计一个高质量的 SKILL.md。4. 从零开发一个 Skill以 LaTeX 排版 Skill 为例4.1 为什么拿 LaTeX 举例子怎么做一个 latex 排版 skills在搜索里热度不低原因是 LaTeX 是个特典型的规则密集场景中文支持、字体配置、编译引擎选型、常见报错处理这些知识又碎又繁琐模型很容易踩坑。我早期用 Agent 写论文时几乎每次都要跟它解释一遍 xelatex 和 ctex 的关系。把它做成 skill 之后效果天差地别。这里我把完整开发过程拆给你看。4.2 规划 Skill 边界在动手写文件之前先想清楚这个 skill 的边界。我给自己定的范围是要覆盖从 Markdown/文本内容生成标准 LaTeX 文档、中文排版支持、代码块处理、图片插入、编译循环不要覆盖LaTeX 的完整语法教学那是参考文档的事、特定期刊模板的定制一个好的 skill 遵守单一职责只解决一类问题。边界太宽description 就很难写得精准Agent 会频繁误触发。这个 skill 的目录结构设计如下latex-typesetting/ ├── SKILL.md ├── reference/ │ ├── chinese-fonts.md # 不同系统下的中文字体方案 │ └── common-errors.md # 常见编译错误对照表 ├── templates/ │ ├── article.tex # 论文模板 │ └── beamer.tex # 幻灯片模板 └── scripts/ └── build.sh # 编译脚本4.3 编写 SKILL.md 与配套脚本SKILL.md 是整个技能的核心我建议按元信息 工作流程 质量检查 注意事项四段式写。下面是精简后的示例--- name: latex-typesetting description: 将内容排版为 LaTeX PDF 文档。当用户需要学术论文、实验报告、简历或幻灯片时使用。处理中文乱码、公式排版、图片插图、参考文献等问题时使用。不适用于简单的 Markdown 转 PDF。 ---正文部分# LaTeX 排版技能 ## 工作流程 1. 确认文档类型article论文/报告、beamer幻灯片 2. 从 templates 目录选择合适的模板文件复制到工作目录 3. 根据用户内容填充正文注意 - 代码块使用 listings 或 minted 宏包 - 图片统一放入 figures 目录 4. 使用 xelatex 编译原因原生支持 UTF-8 和中文 5. 检查编译日志处理 error 和 warning ## 质量检查 - [ ] 中文正常显示无乱码 - [ ] 公式编号连续 - [ ] 引用和参考文献可交叉跳转 - [ ] 编译过程无 error ## 常见问题 - 中文乱码检查是否用 xelatex 编译、是否引入 ctex 宏包 - 字体缺失查看 reference/chinese-fonts.md 中的系统配置方案 - 图片找不到确认相对路径正确工作目录是否有 figures配套的编译脚本#!/usr/bin/env bash set -euo pipefail # 用法: ./scripts/build.sh main.tex # 设计意图: -interactionnonstopmode 让编译不因错误暂停 # -halt-on-error 在第一个致命错误时立即停止并退出码非零 # 这样 Agent 能直接发现编译失败。 TEX_FILE${1:-main.tex} xelatex -interactionnonstopmode -halt-on-error ${TEX_FILE}写 SKILL.md 时有几个要点第一description 里要有正向触发词论文排版PDF和负向排除不适用于 Markdown 转 PDF这样能显著降低误触发率第二工作流程的每一步要可执行、可检查不要写注意排版美观这种模糊要求第三把高频问题的处理方案直接内联而不是全塞到 reference 里减少 Agent 跳转读取的成本。4.4 安装与验证开发完成后把文件夹复制到项目级或个人级 skills 目录mkdir -p ~/.claude/skills cp -r latex-typesetting ~/.claude/skills/验证环节容易被跳过但这一步非常重要。我会用一组试探性问题测试技能的触发和效果帮我看看这段论文的公式怎么排版预期触发并且给出公式相关处理把下面的内容转成 PDF 试试预期触发走完整编译流程帮我写一段 Python 冒泡排序预期不触发正常回答编程问题第一次测试很少一次通过。最常见的现象是描述写得太宽或太窄触发时机不对。调整 description 后重新测试直到触发行为稳定为止。这里插一句题外话很多 agent 开发教程会教你写完 skill 就完事但我坚持认为验证触发机制和验证输出质量同样重要。一个写得很详细但从不被触发的 skill跟不存在没有区别。5. 实测中的坑Skill 不生效、误触发与调试经验5.1 描述写得不够触发友好技能根本不会被调用这是最普遍的问题。很多 skills 的 description 写得太笼统比如用于文档排版。结果 Agent 在遇到任何排版需求时都犹豫要不要调它甚至完全忽略。我后来总结出一个有效的 description 写法正面场景写具体 负面场景明确排除。正面场景要把用户可能的说法也覆盖进去比如排版成 PDF、写个论文、生成简历负面场景要用不适用于不要用于明确边界。描述文本本身的质量也影响触发概率。模型是向量匹配的语义检索逻辑描述里的关键词越接近用户任务的表达方式触发越稳。我开发技能时会把用户最可能说的话在描述里翻译一遍。5.2 误触发与多 Skill 冲突装了几个 skills 之后问题就来了同时装了latex-typesetting和document-format遇到论文排版需求时Agent 可能在两个 skill 之间摇摆不定甚至选了错误的那一个。解决办法有两个层面。一是编写时给每个 skill 划清边界用排除句互相隔离二是当冲突无法避免时合并为一个 skill内部做分支处理。我实际踩过的一个坑是图片生成 skills和结构图 skills的冲突。同样一句帮我画个架构图可能触发前者生成图片也可能触发后者输出结构图标记语言。后来我在前者的描述里加上仅用于位图图像生成不用于图表/架构图冲突才算解决。5.3 脚本执行与权限问题带脚本的 skill 容易出现SKILL.md 写得挺好但脚本一执行就报错的情况。常见原因排序脚本没有可执行权限chmod x忘记shebang 缺失或路径不对依赖命令不在 PATH 中Harness 的沙箱环境可能与你的终端环境不同跨平台问题在 macOS 上能跑的 shell到了 Linux 容器里可能因为路径差异挂掉我的排查方法很简单先在终端里手动执行一遍脚本确认它能独立运行再以最小化环境变量的方式执行模拟沙箱场景最后再让 Agent 去调。很多人忽略了Harness 环境不等于本机环境这一点脚本在终端里跑通了在 Agent 的沙箱里照样可能失败——比如沙箱禁网脚本里却有个pip install。另外涉及安全的经验也要说一句装别人的 skill 之前一定花两分钟翻一遍里面的脚本。skills 是有执行能力的恶意的技能可以窃取你的环境变量、读取密钥文件。agent 安全不是高大上的话题它就在每一次 skill 安装的当下。5.4 改完了却不生效还有一种让人血压升高的场景SKILL.md 改了Agent 却还在用旧行为。可能的原因有三个路径不对你改了 A 目录的文件Agent 加载的是 B 目录的同名 skill会话缓存当前会话早期已经加载过该 skill 的内容模型上下文里还是旧版本。新开会话通常会解决项目级/个人级同名冲突项目级目录存在同名 skill 时会覆盖个人级而你只改了个人级的那份检查时先确认加载的是哪个路径再决定改哪里。我发现一个比较稳的习惯一个技能只保留一份要么放项目级要么放个人级不要两个地方都有同名副本。5.5 调试方法论让 Agent 把决策过程露出来调试 skills 有个尴尬的地方Agent 不会主动告诉你我刚才没调用 skill 是因为描述匹配度只有 0.3。所以我的调试手段很直接第一步复现。用一个最小化的 prompt 在干净会话里复现问题去掉无关上下文降低干扰。第二步反问。直接问 Agent你刚才有没有考虑使用 XX skill为什么没用。这个方法看似笨但经常能拿到有价值的线索模型的推理过程会暴露它是不是没找到、还是找到了但觉得不适用或是读取了但没按流程执行。第三步加日志。在 skill 的脚本里加输出到固定日志文件确认技能是否被执行、执行到哪一步。对不带头脚本的技能可以在 SKILL.md 里加一句使用本技能后请在回答末尾标注[USED SKILL: latex-typesetting]这样就能在输出里追踪技能的触发情况。这套方法论我用了很久效果稳定。核心思路是先确认技能有没有被触发再分析触发后有没有被正确执行——两件事不能混在一起查。6. 怎么测评 Skill、如何进阶学习路线6.1 给每次输出定基线标准skills 怎么测评这个话题社区讨论得不多但它恰恰是 skill 开发最容易被忽略的一环。很多人写完 skill 试一次觉得能用就再也不管了。等某天 Agent 表现突然变差也说不清是模型问题还是 skill 问题。我给自己的要求是每个 skill 必须有一份基线测试单定义 3 到 5 条可检查的成功标准。以 latex-typesetting 为例中文内容编译后无乱码编译日志无 error模板结构标题、作者、摘要、章节完整输出 PDF 文件存在且大小合理每次修改 skill 后用同一份测试单跑一遍能过就算没改坏。6.2 批量回归与 Agent Evals单次测试能发现问题但发现不了回归——你改了一个地方某个原本正常的场景被搞坏了。所以要建一个简单的测试集。我的做法是准备 10 到 20 个代表性任务 prompt存在tests/prompts.txt里然后写一个轻量脚本批量调用 CLI 执行 Agent把每次输出和编译产物保存下来#!/usr/bin/env bash # 简易回归脚本逐个执行测试 prompt # 思路把 Agent 输出保存到 outputs/ 目录 # 然后人工快速核对基线标准。 while IFS read -r prompt; do safe_name$(echo $prompt | md5sum | cut -c1-8) echo Running: $prompt claude -p $prompt outputs/${safe_name}.md 21 done tests/prompts.txt这套东西再往上走就进入了 agent evals 的范畴——给 Agent 建一套标准化的评估集把表现量化。现在圈子里讨论的 agent evals很多就是从skills 怎么测评这个朴素需求长出来的。你不需要一开始用重型框架一个 prompt 列表 一份基线 一个跑批脚本就能覆盖大部分技能回归需求。skills 怎么测评的实操建议就三条小测试集起步、每次改动必回归、测试集从真实失败中积累。这里的真实失败是指——日常使用中发现技能某个场景表现不好就立刻把那个场景的 prompt 加进测试集防止以后再犯。6.3 Skill 的迭代节奏与版本管理Skill 文件小迭代成本低我一般遵循两周一小改、有 bug 随时修的节奏。每次改动建议在 skill 目录下留一个 CHANGELOG 或在 SKILL.md 里加一行更新时间否则用久了会忘记它到底包含哪些逻辑。版本管理的技巧是测试集跟 skill 一起管理。给测试集文件加上版本号skill 改版时同步更新测试集保证测试的有效性跟得上功能。随着你经验积累还可以从写技能升级到设计技能体系把一个大的技能拆分成基础技能和组合技能。基础技能做原子操作组合技能里引用多个基础技能完成复杂任务。这个思路跟工程化里的模块化、组合是一回事也是 agent 架构里比较进阶的设计能力。6.4 从使用 Skills 到 Agent 开发的学习路线最后聊一下学习路线。如果搜索热度有参考价值agent 开发学习路线和agent 开发教程是很多人的起点而 skills 是最好的切入点。我建议按下面几个阶段走阶段一只使用不开发。装一两个高质量的现成 skills比如 superpower skills 里的基础技能体验一下Agent 突然变稳是什么感觉。同时拆解它的目录结构读它的 SKILL.md理解好技能长什么样。阶段二克隆改造。选一个你日常用得上的现成技能克隆后改造成自己的版本。这比从零写简单还能学到别人的流程设计思路。我第一次改的就是一个文档转换技能改完才发现原来 description 里的每个措辞都是有讲究的。阶段三解决自己的痛点。观察你在使用 Agent 过程中反复需要解释的内容把它写成技能。这个阶段的目标不是写出完美的技能而是跑通开发 - 安装 - 触发 - 调试 - 迭代的完整闭环。阶段四测评与深入框架。给自己的技能建测试集做回归然后去看 opencode、agentscope 这类框架的源码理解 skills 在运行时是怎么被加载、选择、执行的。到了这一步你已经能应对大部分 agent 开发面试题了——skill 和 agent 的区别、harness 和 agent 区别、如何设计一个可复用的 skill这些面试题的答案都会在你脑子里。最后分享一个我个人的体会我写过最复杂的技能后来反而很少用真正每天在用的是一个花了不到一小时写的小技能——它只是规定了我项目里日志格式怎么写、错误码怎么定义。这让我想明白一件事skills 的价值不取决于技术含量而取决于它是否击中了 Agent 日常行为的最高频痛点。与其到处找最新好用的 skills不如静下来想想我在哪类任务上被迫对 Agent 重复解释最多那里就是你第一个 skill 的起点。