最近两天skills这个词几乎把我各个信息流刷屏了。Claude 官方放出了 Agent Skills 的技术文档GitHub 上各种 awesome-claude-skills、superpower skills 仓库也开始被疯狂 star连 Codex 相关的工具链里都开始出现.codex/skills目录。我一开始觉得这就是把 prompt 换了个名字直到我周末整理自己.claude/skills目录的时候才发现里面攒了十多个技能包真正能稳定提升输出质量的却只有三个。这个反差让我决定好好研究一下Skills 到底是什么为什么大家愿意花时间去找、去装、去写以及它在实际项目里到底能不能兑现让 AI 更专业的承诺。这篇文章不打算复述官方文档而是记录我从零开始接触 skills 的完整过程顺便把那些只有亲手踩过坑才会知道的细节一并说出来。1. 从写提示词到带技能上岗为什么 Skills 突然刷屏1.1 我看到 agent skills 时的第一反应AI 编程和 agent 圈有一种很典型的现象一个新概念火了大家第一反应都是找旧瓶装新酒。Prompt 火了就说 Agent PromptMCP 火了就说 Agent 外部工具现在 Skills 来了又有人说这不就是 Prompt 套皮吗。我最初也是这个态度。毕竟一眼看过去SKILL.md 就是个 Markdown 指令文件里面写步骤、写注意事项、写示例这不就是结构化 Prompt 吗真正让我改变判断的是一件小事我用了别人写的一个 SKILL.md。那个 skill 并不是告诉我照着这个步骤做而是先教我怎么拆解任务再告诉我项目里有哪些文件可以带来信息——这里的执行粒度完全不一样。原来的 Prompt 像是给 AI 一份一次性订单帮我做 A、按照 B 方式做、注意 C。Skills 更像是给 AI 一套职业工作手册当任务属于这个领域时你要先读哪一节再按什么流程走哪些经验法则要记在脑子里。模型拿到的不只是一份订单而是一个岗位的行业常识。这个区别听起来抽象但在输出质量上非常明显。所以当社区开始出现 superpower skills、nature skills 这类项目时我就意识到这波不是炒概念而是真的在改变 agent 干活的方式。1.2 Prompt、Plugin、Skill 到底差在哪为了不让自己继续混淆我专门建了一张对照表维度PromptPlugin / MCPSkill载体对话里的一段指令外部工具/接口代码Markdown 技能包可含脚本生命周期一次性长期可用可复用、可分享、可版本管理模型关系直接跟随通过 API 调用作为上下文被模型理解并执行核心价值约束本次输出扩展模型能力边界教会模型如何做一件事Prompt 和 Skill 最大的差异在于上下文策略。Prompt 是每次都全量塞给模型Skill 是按需加载。我把 10 个方法的说明全写进 Prompt模型容易在细节里迷路而如果我把这 10 个方法做成 10 个 skill 包模型只会在遇到对应任务时把对应的 SKILL.md 读进来。这个按需加载机制才是 Skills 真正优于普通提示词工程的地方。Plugin/MCP 解决的是模型够不到外部数据的问题比如查数据库、调浏览器、跑本地脚本。Skill 解决的是模型知道怎么做但做不稳的问题比如搞前端组件、写技术方案、做代码审查。两者不冲突实际项目里经常一起用MCP 负责把项目文件内容喂给模型Skill 负责告诉模型该按什么套路处理这些内容。尤其是后面要讲的 agent tool agent skills 这类组合玩法本质都是工具负责触达技能负责方法。2. Skills 的第一性原理一份 SKILL.md 如何改变模型行为2.1 SKILL.md 的核心结构社区里流传的 skills 千奇百怪但核心骨架其实差不多。一个最小的 skill 包通常长这样my-skill/ ├── SKILL.md └── references/ └── examples.mdSKILL.md 是全套流程的入口。我见过写得好的 skill多半长这样简版--- name: code-review-essentials description: 当你需要审查代码变更、寻找潜在 bug、评估可维护性时使用。适合 PR 评审和提交前自查。 --- # Code Review Essentials ## When to Use - 用户要求 review 一段代码 - 提交前想检查自己写的逻辑 ## Workflow 1. 先读 diff 和上下文理解改动的目标 2. 按正确性 - 边界条件 - 可读性 - 性能的顺序检查 3. 对每个问题给出严重级别和修改建议而不是只贴结论 ## Checklist - [ ] 有没有遗漏的 null / undefined 分支 - [ ] 有没有隐藏的副作用 ## Pitfalls - 不要让 review 意见变成无依据的风格偏好frontmatter 里的 name 和 description 不是装饰而是模型的技能索引。模型在同一时刻要面对很多个 skill它不可能把所有 skill 的完整内容都读进上下文而是先扫描所有 skill 的 name description再决定这次任务要不要加载详情。换句话说description 写得好不好直接决定模型会不会在需要的时候找到这个技能。我见过很多人把 description 写成一句很泛的话比如用于代码审查结果模型在真正该用的时候完全没想起来改成当用户要求 review 代码变更、寻找 bug、评估可维护性时使用之后命中率明显提升。2.2 为什么用自然语言而不是代码开发者的第一直觉往往是把流程写成 Python 脚本让模型执行不就行了吗。但实际效果通常不如自然语言好原因有二。第一Agent 环境中的脚本执行能力并不总是可用模型要跑脚本就依赖额外工具而一份纯 Markdown 的 SKILL.md 只需要读进上下文任何支持文档输入的对话场景都能生效跨环境复用的门槛低得多。第二自然语言描述的知识更容易泛化。模型在训练时见过海量文本它对先看边界条件再看性能这种流程的记忆远比一个写死的脚本更能适配新项目。自然语言里天然带着判断标准、例外情况、经验法则这些恰恰是脚本最难写清楚的部分。很多人一听说 skills 可以带脚本就以为脚本是主角。实际用下来主角永远是 SKILL.md 里的自然语言流程脚本只是参考资料是给模型看的补充手册而不是强制执行的程序。一份纯文本的 skill 反而能有更强的环境适应性。2.3 调用机制与技能路由逻辑最近看到一篇非常深入的博客标题就叫 claude agent skills: a first principles deep dive里面从模型上下文机制的角度把 skills 拆得很细。我用自己的话说整个调用逻辑可以分成三步第一模型在对话开始或任务切换时扫描当前环境中所有 skill 的元信息形成一个技能清单但它不加载正文。第二步当用户请求或上下文特征和某个 skill 的 description 匹配时模型打开这个 skill把 SKILL.md 的正文注入当前上下文。第三步模型按照正文里的 workflow 逐步执行同时可以随时查阅 references 目录里的辅助文档或脚本。这个过程特别像人类面试官筛选候选人先看简历筛一轮面试时只看候选人的核心能力而不是把候选人的所有论文都背下来。对模型来说这个设计可以控制 prompt 的 token 开销对 agent 稳定性来说它也避免了所有技能的明文互相干扰。所以每次写技能时我都会反复打磨 description把它当成一个路由关键词来对待而不是例行公事地写一句这是一个强大的技能。3. 安装与发现从官方市场到 GitHub 的完整路径3.1 官方安装目录与市场配置不同工具对 skills 的目录约定略有差异但主流 Agent 正在快速收拢到一套相近的规范。以 Claude Code 为例全局技能目录通常是~/.claude/skills/项目级技能目录是.claude/skills/只要把下载好的技能文件夹放到对应目录下重启会话后就能被扫描到。当然版本迭代很快最权威的路径建议直接看官方文档不要盲信任何博客里写死的老目录。Claude 也支持通过 marketplace 安装技能类似 vscode marketplace 的机制。在配置文件里声明 marketplace 之后就能用命令一键安装和更新技能集合。我个人的建议是如果你只是想尝鲜先用全局目录放一个 skill 跑通流程如果你后面技能多了才值得搭 marketplace 做版本管理。团队场景更推荐把技能包放在项目仓库里随代码一起分发这样每个组员拿到的 skill 都一致不会出现我本地能用你本地不能用的经典问题。3.2 靠谱的 skills 来源与筛选标准现在在 GitHub 搜 skills出来的仓库多到看不完。比较值得看的几类一是 Anthropic 官方放出的一些 Agent Skills 示例里面包含浏览器自动化、PDF 处理等场景二是社区整理的 awesome 列表通常会把技能按前端、写作、研究、运维等分类三是个人开发者维护的垂直技能仓库比如专门给内容创作者用的分镜 skills、给安全工程师用的合规巡检类 skills。筛选标准我总结了四条。第一条不要只看 star 数先看 SKILL.md 里的 description 是否是when to use句式而不是这是一个强大的技能这类自吹自擂。第二条看 workflow 是否有明确的顺序和检查点光有空洞的原则没有步骤等于白写。第三条看是否依赖一堆需要另行安装的 Python 包依赖越少复现成本越低。第四条看有没有 examples 目录样例输出的质量能直接反映技能作者实际跑没跑通。凡是满足不了这几条的可以直接跳过能帮你省下大量试错时间。3.3 我踩过的装完不生效的坑第一次装 skill 时我以为放进去就能用结果在会话里反复触发模型始终无动于衷。排查了一晚上才发现三个问题。第一个是目录结构问题。我从 GitHub 克隆了仓库没有把内部的具体技能文件夹挪到 skills 目录而是把整个仓库包括 README 和一堆参考资料塞了进去。模型扫描时找不到根目录下的 SKILL.md自然无法识别。第二个是命名问题。官方要求主文件固定叫 SKILL.md我为了描述得更清楚改成了 code-review-skill.md结果同样没被识别。第三个是会话缓存问题。有些 Agent 启动时会缓存已加载的技能列表放入了新技能但没重启会话就不会出现在扫描结果里。重启之后问题立刻消失。除了这三个工程问题还要小心技能相似导致路由漂移两个技能描述都覆盖代码审查时模型可能随机选一个输出风格一会儿一变。解决方法是把 description 划清边界比如一个聚焦正确性与 bug 寻找另一个聚焦代码风格与可维护性让模型能区分开。4. 从零开发一个可用的 Skill以前端切图为例4.1 选题与拆解什么任务适合做成 Skill前端开发 skills是社区里热度最高的分类因为前端任务流程长、规范多、重复度高。我用来练手的是设计图转组件这个场景。通常模型拿到设计稿链接直接吐一个组件出来看着还行但细节经不起推敲没有提取设计 token颜色是现写的十六进制布局没有考虑响应式按钮的 hover 状态缺失。这不是模型能力不够而是没有一个稳定的流程约束它。做 skill 之前要先把任务拆解成可复现的流程。我把设计图转组件拆成了五步锁定设计规范颜色、字号、间距、圆角、还原页面结构从外到内、按 Tailwind 类名实现样式、补全响应式与交互态、最后自测对比。你会发现这五步本身就是一个前端工程师的 checklists把它写成 skill本质是把岗位经验沉淀下来。4.2 手写 SKILL.md结构、语气与边界我写的 SKILL.md 比第一版长不少关键是有明确步骤和边界--- name: design-to-component description: 当用户提供设计图、Figma 链接、图片或 UI 截图并希望生成可运行的前端组件时使用。适合 React Tailwind CSS 项目。 --- # Design to Component ## When to Use - 用户明确要求根据设计稿实现页面 - 用户只给了一张截图没有其他实现细节 ## Workflow 1. 从设计稿中提取 token主色、辅助色、字号、间距、圆角、阴影 2. 先搭建页面结构再填充样式避免边写边改 3. 组件使用 Tailwind 类名复杂样式可用 CSS 变量 4. 检查响应式断点确保 375px / 768px / 1280px 下不破版 5. 为可交互元素补充 hover / focus / disabled 状态 6. 输出后自测对照原图逐项检查间距和层级 ## Boundaries - 不主动安装依赖不修改后端代码 - 如果设计稿缺失部分信息先询问不假设 - 如果项目已有设计系统优先复用既有 token而不是新建这里有两个容易被忽略的点。第一我特意在 Boundaries 里写了不主动安装依赖、不修改后端代码因为模型经常为了完成任务擅自扩大范围给它画清楚边界它反而会更专注。第二Workflow 里每一步都写了原因比如避免边写边改是为了减少返工模型在执行时会更容易判断优先级。4.3 配套的脚本和模板资源一个重要的补充SKILL.md 不一定要绑定可执行的脚本但可以带一些纯文本资源。我的 skill 目录里放了templates/design-tokens.md给模型一个记录 token 的表格还有一个examples/放了两组输入截图 - 输出组件的对话示例。示例的作用是让模型知道最终产物长什么样很多时候比直接写具体要求更高效。要不要放可以执行的脚本我的建议是能不放就不放。脚本虽然能让某些环节自动化但它会引入环境依赖而 skill 本质上是要跨项目复用的。我更推荐的做法是代码逻辑由模型推理完成脚本只作为辅助参考。比如我在 references 里放了一个色板提取脚本的源码说明如果环境允许可以运行这个脚本先解析设计稿颜色但绝不在主流程里强制要求。这样既给了模型工具又不破坏 skill 的可移植性。5. 实测与评估Skills 到底值不值得装5.1 我的一组对照测试装与不装的区别我在一周里做了个小范围实验针对同样的三类任务让同一个模型分别在有 skill 和没 skill 的情况下各跑 5 次记录输出质量。结果如下任务不装 Skill装了 Skill设计稿转组件样式随机、经常漏响应式5 次产出差异大会先提取 token输出结构统一完整度明显提升技术调研只给结论和链接缺少证据链按预设评估维度输出结论稳定性更高分镜脚本格式每次都不一样镜头号、景别、时长、运镜、台词格式统一最直观的变化不是一次性输出更好而是多次输出的稳定性明显提升。对实际工作来说稳定比惊艳更重要团队合作里格式稳定的交付物可以直接进入下游流程不用每次花时间做格式整理。所以我现在判断一个 skill 值不值得留第一标准就是连续跑五次输出是不是都朝同一个方向走。5.2 什么时候该手动关掉 Skill装了 skill 不代表任何时候都该用。我碰到过三种情况会主动让模型忽略某个 skill。第一种是任务本身太简单比如让我把一段文案翻译成英文结果某个写作优化 skill 跳出来把句子重写了一遍反而引入了不必要的风格化。第二种是创意探索场景我在头脑风暴、想一些自由发挥的内容时会明确告诉模型不要使用任何技能直接给出你的第一反应。第三种是上下文已经非常紧张的时候技能正文会再占用一些 token如果任务不需要严格流程关掉反而更有余量给生成结果。临时关闭的办法很简单直接在对话里说忽略 xxx 技能按普通模式处理通常就有效。如果你发现自己经常要关某个技能那大概率是 description 写得太泛或者它本身覆盖了不该管的场景这时候该做的是改技能而不是每次手动绕开。5.3 从热门技能里挑出真正经得起用的几个结合热搜里的方向我实际测过的几类技能里有四类值得推荐。前端类一个design token 提取与组件生成类技能最实用能把设计规范变成可复用的变量适合有前端团队的读者。论文写作类很多写论文技能实际上应该是论文结构规划与文献综述辅助技能它帮你整理论点、厘清逻辑同时必须配合真实的文献检索。这里要特别提醒千万别把技能当成代写工具用模型生成的段落冒充原创内容学术诚信的边界是底线。视频分镜类适合做短视频、广告片的人技能会把流程固化成目标拆解 - 镜头设计 - 画面描述 - 旁白我试过一次文案产出效率提升很明显。安全巡检类社区里自动挖洞这类技能热度很高但我的态度是这类技能只能用于有授权的测试环境。安全技能的价值在于把所有合规检查步骤固定下来而不是提供攻击技巧。我会选择那些默认带授权声明和边界说明的技能避免越权操作带来麻烦。6. 给想入局的人的几个判断6.1 现在装 skills 的正确姿势避免体验崩盘很多人的第一个想法是去拉一个skills 大全一次性装三十个。我强烈不建议这么干。原因很简单模型每次任务开始都要扫描技能元信息装太多技能时路由噪音会非常大。就像你给一个实习生发了三十本手册他反而不知道该翻哪一本。我的做法是先想清楚自己工作里重复度最高的三个任务只针对这三个任务装技能。跑几天后把使用率低的都移出目录再慢慢扩展。这个增量思路比一把梭舒服得多。另外每引入一个新 skill我都会拿一个基线任务做回归测试。比如引入前端类技能后就用同一个设计稿生成一遍组件对比之前的结果。没有回归测试的安装说白了就是在碰运气。如果你发现某个技能装上后输出反而变差了不要怀疑自己很可能是这个技能的流程和你的工作方式八字不合。6.2 接下来值得盯的方向skills 与多工具组合技能再强如果模型访问不到外部数据效果也有限。所以现在大家讨论的已经不是要不要用 skill而是skill 怎么和 MCP、Agent 工具链结合。比如一个技术调研 skill可以在 Workflow 里写调用搜索工具收集信息再按评估维度整理这里的评估维度属于 skill搜索能力属于工具两者叠加才能完成一个完整的 agent 闭环。这个方向也是社区里 agent tool agent skills 这类热词出现的背景。另一个趋势是技能格式开始跨工具通用。Claude Skills 的格式本身就比较简单Codex 的 AGENTS 体系、Reasonix 这些工具也都在往可复用技能包的方向靠拢。以后很可能会形成一套事实标准不同模型、不同工具链都能加载同一份 SKILL.md。到那时候技能包会变成一种真正可流通的数字资产写一个高质量技能收益可能不亚于写一个开源库。6.3 关于写技能我个人的一点体会做 skill 的过程最难的不是 Markdown 语法而是把隐性经验写清楚。我做前端 skill 的时候一开始写的 workflow 平铺直叙模型照做也能做出东西但缺少什么情况要停下来问需求、什么时候可以直接决定这类上下文判断。后来我在 SKILL.md 里加了一句如果当前项目已有设计系统优先复用现有 token而不是新建一套。就这么一句话输出质量又上了一个台阶。最后分享一个小技巧我写的每个 skill 都会在正文末尾加一行如果以上流程与当前项目冲突可以直接跳过对应步骤并说明原因。这一行看起来不起眼却会让模型从机械执行变成有判断力地执行这是我在测试里发现的成本最低、收益最高的优化。Skills 的钥匙不在别处就在你日常那件最重复、最需要经验的事里。