最近一段时间我几乎每天都能在技术社区里刷到agent skills相关的讨论。Claude Code 里挂 skills、codex skills 的新玩法、superpower skills 这类被打包好的技能合集还有一堆人开始维护自己的 agent skills 仓库。我自己也在实际项目里试了一轮一个很直接的感受是Agent 好不好用越来越不取决于底层模型有多聪明而是取决于你往它的技能库里装了什么。这篇文章想把 agent-skills 这条线完整梳理一遍。我会先讲讲为什么 AI Agent 突然需要一套“技能系统”然后帮你把 skill、agent、prompt、harness 这四个高频概念彻底分清再给出安装现成 skills、从零开发 skills、以及测评 skills 效果的具体方法最后把我踩过的坑和正在用的组合分享出来。适合正在接触 agent 开发、想给 Claude Code / Codex 这类工具配置技能或者准备做自己技能包的同学参考。1. 为什么 Agent 突然需要“技能库”了1.1 从“每次重新教”到“一次打包带走”如果你从 GPT-3.5 时代就开始折腾 AI 编程应该对下面这个场景不陌生每次想让模型按规范做事都得先写一大段系统提示词。拿前端代码审查来说我之前的做法是复制一份披着“你是一个资深前端专家”头衔的 prompt然后把可访问性、语义化标签、性能优化、响应式断点这些检查点逐一列进去。问题是这套提示词在不同项目里几乎不能复用。换个技术栈要改一遍换个团队成员又要重新讲一遍。更烦人的是模型并不是每次都乖乖按清单执行偶尔漏掉一两个点审查质量就不稳定。我一度以为是自己的 prompt 写得不够好于是把提示词改得更长、更细结果上下文占用越来越高效果却没有质的提升。后来我接触到 agent skills才意识到自己真正缺的不是一段更长的 prompt而是一套能被 Agent 自动发现并加载的技能文件。Skills 把我过去写在提示词里的规范、步骤、检查清单变成项目里的一段独立资产。Agent 在判断任务类型后会自动读取对应的 skill 并执行不再需要我每次手把手“重新教一遍”。1.2 Skills 的本质把“知道怎么做”变成“可执行资产”一个完整的 skill 并不只是一个文本文件。它通常包含三样东西元数据name、description操作指引SKILL.md 正文里写给 Agent 看的步骤以及可选的可执行资源脚本、模板、参考资料。当 Agent 判断当前任务和 description 匹配时会在运行时把 SKILL.md 加载进上下文必要时还会调用脚本去完成操作。这个机制厉害的地方在于它把“经验”变成了结构化、可版本管理的资产。Prompt 是一次性的skill 是可复用、可分享、可放进 git 里做代码评审的这两者的定位完全不同。我当时用了一个很直观的类比来理解过去的 prompt 相当于你每次雇一个临时工时都重新培训一遍而 skill 相当于给这个临时工一本操作手册告诉他“遇到什么情况翻开第几页按步骤做”。前者消耗沟通成本后者沉淀组织经验。1.3 为什么偏偏是这个时候爆发skills 这个概念其实不算全新很多 Agent 框架早期就有类似“工具列表”或者“插件”的概念但真正形成讨论热潮我觉得有三个因素碰到了一起。第一Agent 框架开始提供标准化的 skills 加载机制。Claude Code 支持项目级和个人级 skill 目录Codex CLI 也有自己的 skills 配置方式OpenCode 等开源工具同样在往这个方向靠。当底层工具形成统一约定第三方技能才能被方便地安装、分享和复用。第二模型能力已经足够强但默认状态下它并不知道“你的团队怎么做事情”。上下文窗口再大也不可能每次会话都塞一套完整规范。技能文件用极低成本解决了定制化问题而且可以针对不同项目、不同组织灵活切换。第三生态开始出现“技能市场”的雏形。从 superpower skills 这样的开源合集到各种 awesome-claude-skills 的导航仓库再到个人作者陆续发布自己的技能包这条路和当年 vim 插件、VSCode 插件的发展路径非常像。现在入场构建技能资产大概率能吃到早期的生态红利。2. Skill、Agent、Prompt、Harness最容易搞混的四个概念这几天好几个朋友问我harness 和 agent 到底什么区别skill 和 agent 又是什么区别我聊完发现这四个词并不是同一个层级的东西很容易在配置文件和教程里被混在一起。先把这个理清楚后面干活才能少走弯路。2.1 Skill 是“能力单元”Agent 是“工作体”Skill 是单一、高内聚的能力单元比如“生成单元测试”“执行代码审查”“撰写 commit message”。Agent 则是一个完整的工作体它负责接收目标、拆解任务、决定调用哪个 skill、管理上下文的上下文和记忆直到把任务做完。一个更生活化的类比Agent 像是带班的老师傅skill 是他工具箱里的专用工具。老师傅接活之后会判断“现在这活儿该用扳手还是螺丝刀”而扳手和螺丝刀自己不会决定做什么它们只负责在正确的场景下发挥功能。所以你在设计系统时不用纠结“该做 agent 还是该做 skill”两者本来就要配合agent 负责规划和调度skill 负责具体执行。2.2 Prompt 是一段指令Skill 是可复用资产很多人看到 skills 的正文之后说“这不就是个长一点的 prompt 吗”确实SKILL.md 的正文本质上仍然是给模型的指令。但它多了一层结构化的外壳description 字段用来让 Agent 判断触发时机元数据用来索引脚本用来落地执行references 资源文件用来提供参考。这一层外壳把 prompt 从“一次性口头交代”变成了“可检索、可安装、可升级的资产”。你可以用 git 管理它可以在不同项目之间复制也可以像安装依赖一样把它拉下来。更重要的是prompt 通常只影响模型的文本回复而 skill 可以连带执行脚本、操作文件、调用外部工具这是纯文本提示词绝对做不到的。如果你做一个 skill 只是把提示词写得更漂亮那它的价值确实有限。真正拉开差距的地方在于把提示词和可执行脚本组合起来让 Agent 不仅“知道”该怎么做而且能直接“动手”去做。2.3 Harness 是运行框架Agent 是业务实体关于 harness 和 agent 的区别其实是在问“运行环境”和“业务逻辑”的分离。Harness 负责管理上下文窗口、工具调用、模型切换、子任务调度以及技能的加载机制。Claude Code、Codex CLI、OpenCode 这些开发工具底层各有各的 harness 实现。Agent 则是跑在 harness 之上的一个具体业务逻辑体。同一个 harness 可以运行多个 agent比如一个负责写代码一个负责审代码一个负责写文档同一个 agent 只要 skills 兼容也可以在不同的 harness 之间迁徙。这就是它们两个看起来“长得像”但实际分工不同的原因。很多教程会把 agent 配置文件、skills 目录、prompt 模板摆在同一个目录下初学者很容易混淆。其实不用慌你只要记住“harness 提供场地agent 是演员skill 是道具prompt 是剧本”这四个角色各干各的事就不会再绕晕了。3. 安装现成 Skills我从 superpower skills 开始的踩坑实录3.1 先装一个合集感受“技能系统”我建议刚开始接触 agent skills 的同学别急着从头写 skill先装一个社区合集看看它的目录结构、SKILL.md 格式和触发方式。这种“用起来再理解”的方式比看十篇文档都有效。最容易上手的是 superpower skills因为作者把很多高频场景都拆成了独立技能包仓库里目录结构一目了然。我当时用的是比较朴素的方式克隆到本地再配置到 Claude Code。git clone https://github.com/obra/superpowers.git然后有两种接法一种是直接让 Claude Code 指向这个目录claude config set skillsDir ./superpowers/skills另一种是把需要的技能复制到当前项目的技能目录里这样做的好处是团队协作时技能定义跟着代码库走mkdir -p .claude/skills cp -r superpowers/skills/* .claude/skills/装完之后我在对话里触发了一次前端相关任务然后看到一个直观变化Agent 会主动去读取对应 SKILL.md 文件并按照里面的清单逐步执行而不是自由发挥。那一刻我才真正理解“技能系统”是什么意思——它的本质是给 Agent 提供了一套内置的操作 SOP。3.2 Claude Code 的 skills 目录约定如果你用 Claude Code需要先知道它的目录约定。个人级 skills 放在~/.claude/skills下项目级 skills 放在项目根目录的.claude/skills下。每个子目录就是一个 skill目录内必须有SKILL.md作为入口文件名是固定的不要随意修改。Harness 会扫描这些目录解析每个SKILL.md的 description 字段在合适的时机自动调度。这意味着你配好路径之后不需要在每轮对话里手动说“请使用 xxx skill”Agent 会根据用户请求和描述之间的匹配度来触发。这个自动化机制既是好事也是坑。好处是不用频繁干预坏处是如果 description 写得模糊Agent 很可能完全不触发。我看到不少新手在这里困惑明明已经把 skill 放进目录了Agent 却像没看见一样。其实不是没看见而是描述和当前任务没有建立有效关联。3.3 我踩过的三个坑第一个坑是路径没配对。第一次我把 skills 目录配置到仓库子目录但启动 Claude Code 时忘记切到项目根目录结果 Agent 一个技能都没加载。后来我养成了一个习惯配置完先用一个小任务验证让 Agent 自己报当前可用的 skill 列表再确认文件名有没有被扫描进来。不要凭感觉认为“配置应该生效了”。第二个坑是脚本依赖缺失。有些 skill 会调用本地脚本比如check_links.py、summarize.py。如果你本机没有安装对应的 Python 依赖或者脚本里的路径写的是绝对路径运行时报错会特别隐蔽表面看起来是“Agent 执行失败”实际是脚本环境有问题。建议在安装新技能后先打开 skill 目录看看有没有requirements.txt或package.json把所有依赖安装好再跑。第三个坑是无脑堆技能导致上下文暴涨。我一开始看到什么技能都往目录里塞结果发现 Agent 会把一堆 SKILL.md 全文甚至 references 目录里的资源一起带进上下文。虽然模型上下文窗口已经很大但塞满之后轻则响应变慢重则丢失前面几个回合的关键信息。我现在保持的原则是一个项目周期内只启用真正高频的 5-8 个技能其他的一律从目录里移走。一句话总结安装阶段的教训先克隆再配路径最后用一个小任务验证确认 skills 真的被 Agent 看到了再进入正式使用。4. 从零开发一个 Skills目录规范、SKILL.md 写法与发布流程4.1 先了解标准目录结构安装了一轮社区技能之后就可以开始写自己的技能了。按照目前的主流约定一个 skill 的标准目录结构大致长这样summarize-links/ ├── SKILL.md ├── scripts/ │ ├── requirements.txt │ └── summarize.py └── references/ └── output-template.mdSKILL.md是入口文件harness 一般只认这个文件名其他文件都可以自由组织。scripts/放可执行脚本references/放 Agent 执行任务时需要查阅的参考资料。如果你的 skill 不涉及外部脚本可以不要scripts/目录保持最小结构即可。4.2 SKILL.md 的骨架SKILL.md 由 YAML frontmatter 和正文两部分组成。frontmatter 提供元数据正文是写给 Agent 的操作指引。下面是一个最简示例--- name: summarize-links description: 当用户给出两个及以上 URL并要求总结或对比这些链接的内容时使用。输出结构化摘要包含核心观点和差异点。 --- # 目标 将多个网页链接的内容整理成结构化摘要。 # 操作步骤 1. 用 scripts/summarize.py 抓取并提取每个页面的正文内容。 2. 将结果填入 references/output-template.md 的模板。 3. 输出前检查是否有失效链接并在结果中标注。你会发现正文读起来就是给同事写的操作手册。这其实是 good skill 的核心特征描述要准确步骤要可执行校验要明确。你没有必要把话说得多么华丽关键是让 Agent 在执行时有据可依而不是凭空猜测。4.3 描述字段是重中之重如果说 SKILL.md 只能优化一处我会毫不犹豫选 description 字段。因为 Agent 是靠 description 来判断“当前任务是否应该使用这个技能”。写得模糊技能就在关键时候隐形写得具体技能才会在正确的场景下跳出来。写 description 有个实用技巧把用户可能的话术变体都纳入描述。比如你做一个“根据 diff 生成单元测试”的技能description 里别只写一句“生成单元测试”可以补上“当用户要求加测试、补充用例、提高覆盖率、或者针对某些改动写单测时使用”。这样覆盖的场景越多命中率越高。我还习惯在描述里明确写“不要使用时”的条件比如“当用户只是询问概念解释时不要使用本技能”。这种排除法看起来很笨但实际非常减少误触发尤其是同时挂多个技能的时候。4.4 怎么确认 skill 生效没有测试你很难进步很多人写完 skill 直接说“好像有用但不知道有没有生效”。我建议设计一套最简单的回归测试把自己平时最常用的任务固定成 3-5 个测试用例每个用例是一个输入文件加一段用户请求。每次改完 skill都用同一批用例跑一遍对比输出质量、token 消耗、失败率。这其实就是 agent evals 的朴素版不一定非要上复杂框架。一个 markdown 清单加几个输入文件就能开始。我在动手写 skill 之前并没有意识到测试的重要性直到有一次调整了 description 的措辞发现触发率从 20% 涨到了 80%才明白“可度量”三个字对技能开发有多重要。4.5 发布与分享发布一个 skill 并不复杂把它放到 GitHub 仓库写个 README 说明使用方式别人就能克隆下来配置。如果你想让它更容易被发现可以把仓库结构保持和生态标准一致方便后来的人通过 skillsDir 直接引用。我之前提过一次技能包 PRreview 时发现社区对“description 是否可理解”和“脚本是否有可维护性”非常在意。这和开源项目一样不只是你自己能用还要能被别人理解和复用。所以发布前建议找一位不熟悉这个技能的人看看如果他们单凭 SKILL.md 就知道什么场景触发、按什么步骤执行你的文档就合格了。4.6 实战样例给前端开发做一个代码审查 skill结合我最近在做的页面改造给你看一个简化版的前端审查 skill。它的目录就是标准的SKILL.md加一个可选脚本。--- name: frontend-review description: 当用户要求对 React/Vue 组件进行前端代码审查或提交 PR 前需要检查可访问性、响应式、性能问题时使用。 --- # 审查清单 1. 可访问性检查按钮和输入框是否有 aria-label图片是否有 alt 文本焦点状态是否可见。 2. 语义化优先使用 button、nav、main 等语义标签避免无意义的 div 嵌套。 3. 性能检查组件是否存在不必要的重渲染列表是否设置稳定 key大型图片是否有懒加载。 4. 响应式检查断点设置是否覆盖移动端与 PC 端核心操作在窄屏下是否可触达。再配一个简单的检查脚本扫描缺失 alt 和 aria-label这一步能把人工审查从“我要想着看”变成“工具替我扫雷”。脚本不用写得很复杂能覆盖高频问题就够了。5. 值得收藏的 Skills 推荐与一套可复制的测评方法5.1 我推荐先收藏这几类现在社区里可用的技能越来越多但并不是每个都值得装。目前我自己最常用的几类技能大概是这样分类典型技能适合什么项目代码审查与单测根据 diff 生成单元测试、PR 审查清单中大型代码库、团队协作文档自动化README 生成、CHANGELOG 更新、API 文档同步开源库、内部项目质量与验证链接检查、依赖版本检查、基础安全扫描上线前后的工程化环节专项能力数学建模思路生成、结构图/架构图生成、AI 逆向分析具体领域项目如果你想快速体验建议先从文档自动化入手因为它的触发场景非常清晰规则也好定义。想挑战复杂一点可以试试代码审查类技能它需要把团队规范组织成可执行的清单这比单纯生成文本更有技术含量。5.2 我给 skills 做的一次完整测评为了搞清楚一个技能到底有没有价值我做了一次简单对比。任务很固定“检查下面这个 React 组件的可访问性问题”附上一段包含好几个隐患的组件代码。没用 skill 时模型给出的建议比较泛会提到“添加 alt 属性”但遗漏了对话框焦点管理、颜色对比度这些细节。挂了 frontend-review skill 之后输出明显更收敛按清单逐项检查并且会给出修复建议。从 token 消耗上看加载 skill 确实多占了一些上下文但换来的是输出更加稳定返工率下降。这个测试告诉我两个结论对于重复性高、标准明确的场景skill 的价值非常明显对于开放式的创意任务比如“帮我想十个产品 slogan”skill 反而可能限制模型的发挥空间。这也就是为什么我坚持给 skill 做回归测试。你不测就永远不知道当前效果到底是模型的功劳还是技能文件的贡献也无法判断一次改动到底是改善了触发率还是引入了新的问题。5.3 我现在在用的组合拳现在我的主力是三个 skill 的组合代码审查、提交信息生成、版本更新记录。代码审查负责把关提交信息生成保证 git 历史规范版本更新记录自动生成 CHANGELOG。这套组合解决的不是“让模型写更多代码”而是把编码工作流里的重复决策点固化下来。审查环节减少低级问题提交信息生成保证 commit 信息格式统一CHANGELOG 则省去了每次发布前手动整理变更记录的时间。三者叠加起来我明显感觉自己的 Agent 使用流程变顺了不再需要频繁在对话里补充规则。要说实话对我个人影响最大的不是某个具体技能而是“把技能文件当作一等项目资产”这个思路。以前我写代码前会先写一堆规范文档但很少有人认真读现在我把同样的规范写进 skillAgent 会在运行时自动执行。两者内容差不多落地效果却完全不同。如果你也想尝试别贪多先挑一个每天都要重复做的任务把它写成 skill跑两周你应该就能感受到差别。
