Skills 实战指南：从 SKILL.md 到 Agent 技能包的全链路解析

最近技术社区里“skills”这个词几乎刷屏了前端开发 skills、codex skills、claude agent skills、superpowers……聊天时互相问“你装了哪些 skills”听起来像游戏里在攒技能点实际上这是大模型 Agent 生态里正在快速标准化的一种新玩法。今天我把这堆概念掰开揉碎讲清楚 skills 到底是什么、一个 SKILL.md 文件是怎么指挥 Agent 干活的、从哪些地方下载安装、装上之后不生效怎么排查以及一些我自己练手时踩过的坑。先说结论skills 本质上就是“把提示词、工作流、工具使用规范打包成一个可复用、可分发的最小单位”。你可以把它理解成给 Agent 准备的“岗位说明书”或者“操作手册”。相比那些动辄几千字的 system promptskills 的进步在于它是按需加载的——Agent 只有在需要这项技能时才会读取对应文件而不是每次对话都把几万字塞进上下文。1. Skills 这波热度是怎么来的从提示词到 Agent 技能包的演进1.1 为什么“写提示词”这一套正在失灵两年前大家玩 AI 的姿势还很原始在对话框里喋喋不休地写提示词把规则、示例、注意事项全部塞进去。这种玩法有两个硬伤。第一是上下文窗口永远不够用。你写一个“前端开发风格指南”可能就要几千字再加上项目背景、技术栈说明、组件设计规范一次对话轻松破两万 token。第二是“一次性消费”换一个项目、换一个模型、甚至换一个同事这些提示词就要重新写、重新调、重新对齐。你精心打磨的“帮我写 Table 组件”提示词在 A 项目里好用到了 B 项目里因为技术栈不同直接废掉。所以各家开始做“结构化复用”的东西。OpenAI 在 Codex 里引入 skillsAnthropic 在 Claude 里推出 Agent Skills社区则出现了 superpowers 这类“技能的技能”仓库。它们的核心思路一致把能力拆成文件按需注入长期沉淀。1.2 Skills、Tools、MCP 和普通提示词到底有什么区别很多刚接触的朋友容易把 skills 和 tools、MCP 搞混。我简单画一条线Tools 是 Agent 能调用的“函数”比如读文件、执行命令、请求某个 API这是能力层的概念。MCP 是给工具接线的协议让工具可以跨应用集成比如让 Claude 去查数据库、操作浏览器。Skills 更像是“方法论的封装”它不直接提供工具而是告诉 Agent “遇到这类任务时你应该按照什么样的步骤、用什么工具组合、以什么格式输出”。举个例子一个“写论文提纲”的 skill并不附带知网查询工具它只是规定第一步让用户上传文献 PDF第二步提取关键词并按研究问题归类第三步生成大纲表格。真正读 PDF 用的还是 Agent 自带的文件读取工具。普通提示词和 skills 的区别则在于隔离。提示词是每次都要完整注入的技能是描述匹配到才加载的。Claude 和 Codex 都会根据用户输入意图去匹配技能库里的描述命中之后才把整个 SKILL.md 交给模型。这个机制直接决定了技能文件的写作方式——描述写不好技能就是一堆躺硬盘的废文件。2. 技能包的内部构造一个 SKILL.md 是怎么指挥 Agent 干活的2.1 文件结构与 YAML 头信息无论 Claude 还是 Codex一个技能的标准形态都是“一个目录 一个 SKILL.md 文件”。目录名是技能名SKILL.md 是技能本体。有些复杂技能还会带上 references 子目录、scripts 目录、templates 目录用来放参考文档、辅助脚本和输出模板。SKILL.md 的开头是 YAML 格式的 frontmatter包含技能的基本元信息。Claude Agent Skills 的标准写法类似这样--- name: react_component_builder description: 根据设计稿和需求描述生成可复用的 React 组件适合项目已配置 Tailwind 和 Storybook 的场景。当用户提到“切图”“还原页面”“写组件”“前端开发”时使用。 allowed-tools: - Read - Edit - Write ---这里最关键的字段是description。它不光是给你自己看的说明更是 Agent 决定“要不要加载这个技能”的触发条件。这个字段写得越模糊、越长Agent 越容易误触发或者漏触发。我见过有人把 description 写成一小段博客结果什么任务都命不中最后还得手动把技能文件拖进会话里。2.2 正文的“操作手册”写法SKILL.md 的正文部分是模型的指令区相当于给 Agent 一本只属于这项任务的 SOP。我习惯用五段式结构去写What这个技能解决什么问题输入是什么输出是什么。How核心步骤每一步都要可判断、可执行。不要写“优化代码”这种含糊话要写“先阅读 src/components 下所有组件找出未使用 Tailwind class 的地方”。Constraints红线规则。比如“不要修改测试文件”“所有代码必须通过 lint”。Verification完成标准。比如“生成后需要运行 npm run test 且保证没改动现有用例”。Examples给一两个输入输出的示例模型会照着这个形状干活。我见过的最实用的技能文件都像“菜谱”食材、步骤、火候、出锅标准清清楚楚。如果你只是把一段提示词换个后缀名存成 md 文件那还是提示词不是技能。2.3 一个最小可用技能实例我在本地跑通了一个最简单的“前端开发 skills”SKILL.md 只有这么点内容--- name: figma_to_component description: 基于设计稿图片生成 React 组件代码。当用户上传设计图或提到“按图写组件”时使用。 --- # Figma 设计稿转 React 组件 1. 查看用户提供设计图列出所有可见 UI 元素包括按钮、卡片、输入框、导航栏。 2. 查找项目现有组件库优先复用已有样式而不是重新造轮子。 3. 生成组件代码到 src/components/{组件名}.tsx并配套导出语句。 4. 用 Tailwind 类名实现间距与响应式避免内联样式。 5. 输出的最后给出一段“如何使用”的说明包含 props 类型。这套内容看着简单跑起来效果非常好。Agent 拿到设计稿之后会先做元素识别再去翻组件库存量最后落在指定目录。整个过程只要 2 分钟过去起码要半小时起步。3. 从找技能到装技能全网 skills 下载平台与安装方式盘点3.1 常用技能来源渠道经常被问“skills 下载平台有哪些”我按优先级给你排一下来源特点适合场景官方文档与官方示例仓库质量最稳和模型行为对齐度最高学习格式、跑通第一个 skillGitHub 上的 awesome 系列聚合了大量社区技能按场景分类找特定领域技能如论文、前端、数据分析npm 包形式的技能集合如 superpowers一条命令批量安装多个技能想快速体验整套工作流的用户独立开发者的小型站点针对特定框架或玩法更新快追新、找边缘场景技能GitHub 可以直接搜awesome-claude-skills、awesome-codex-skills、claude-skills、codex-skills这些关键词筛选 star 数和最近更新日期。我自己的习惯是优先看带测试样例和文档的项目凡是只放一堆 md 文件没有使用说明的仓库多半是从别处转存来的旧版本装上之后问题多多。3.2 官方市场的“国内”安装思路很多人关心官方市场或官方仓库怎么装。以 Claude 生态为例官方技能通常走 GitHub 仓库分发你只需要把对应目录复制到本地的技能文件夹即可。这里我有一个诚恳的建议优先通过本地目录直接安装也就是把技能 clone 下来放进指定文件夹而不是依赖某种一键同步。因为技能的核心就是一堆本地文件本地安装有两个天然好处一是你能直接查看和修改技能内容二是安装路径完全可控出问题知道从哪里排查。至于 Codex它的技能同样支持两种位置全局目录~/.codex/skills/和项目内目录.codex/skills/。我强烈推荐把团队通用技能放全局目录把项目私有技能放进项目代码库跟着 Git 走。这样换机器、换同事都能自动同步比任何“同步平台”都可靠。3.3 Superpowers 的具体使用Superpowers 是社区里传播很广的一套技能集合里面包含大量元技能比如“从零开始一个项目”“拆解复杂任务”“代码审查”“仓库分析”等。它的安装方式非常简单在命令行里执行npx superpowers install它会自动检测当前环境的 Agent如 Claude Code、Codex 等把对应的技能文件放到合适的目录里。装好之后你在会话中描述一个项目需求Agent 会按它自己的流程模板工作比如先分析项目现状再分步实施。它本质上是一套“教你如何调用其他技能”的技能框架。用 Superpowers 时要注意它不是万能工具箱别指望一条命令解决所有问题。它是“方法论教练”你越能用清晰语言描述目标它的流程拆分能力越强你给的上下文越是模棱两可它拆出来的步骤也会跟着飘。4. 论文、前端、分镜几个值得动手实操的技能场景4.1 论文写作与研究辅助技能“codex 写论文的 skills”和“workbuddy skills 写论文”都是热词。我把论文类技能分为三种文献整理型、结构生成型、语言润色型三者合在一起可以覆盖“输入一堆 PDF输出一份带目录、带要点、带文献对照的初稿提纲”这样的完整流程。如果自己写一个论文技能核心动作要落到这几个环节提取文献的关键信息生成对照矩阵研究问题、方法、样本、结论、局限按研究主题归堆再输出大纲。很多科研型技能翻车是因为描述里写得太玄乎什么“深度洞察文献”“揭示研究空白”Agent 根本不知道怎么执行。好的描述是具体的、可度量的--- name: paper_outline_generator description: 从用户提供的文献文件夹中提炼研究框架并生成论文大纲适合课题开题、文献综述场景。当用户提到“写论文”“做综述”“文献太多不知道怎么组织”时使用。 --- 1. 读取用户指定目录中的所有 PDF 文件。 2. 为每篇 PDF 提取研究问题、方法、关键结论、局限。 3. 将提取结果合并成文献矩阵表格。 4. 依据矩阵归纳出 2-3 个核心研究主题。 5. 输出论文大纲包含引言、每个主题下的子章节、以及结论章节。这已经是可执行的状态了。这里补充一句任何要求模型“联网查文献”的技能都要考虑真实性校验问题。我的做法是不允许模型直接编造引用所有引用信息必须来自用户提供的文件这是论文类技能的底线。4.2 前端开发技能的高效组合前端开发 skills 是目前最成熟的技能方向之一。原因很简单前端任务的输入输出非常结构化设计稿、组件树、接口文档都是标准格式Agent 在这些任务上没有太多“自由发挥”的空间反而是优势。我在实际项目里组合了三套技能组件生成、样式统一、API 对接。组件生成技能读取设计稿后产出 React 组件样式统一技能遍历全项目 CSS/Tailwind 文件输出“重复类名检查报告”和“重构建议”API 对接技能根据接口文档自动生成请求函数和类型定义。三个技能各管一摊互不干扰。这种组合方式的好处是每个技能可以单独测试、单独迭代。哪个环节出了问题就改那个技能的 SKILL.md其他技能不用跟着动。一旦你把技能写进项目目录.claude/skills/或.codex/skills/所有参与这个项目的人都能共享同一套流程规范。4.3 分镜脚本技能从小说文本到分镜表“分镜 skills 下载”这类关键词最近在短视频和漫画圈火起来。分镜技能的价值在于它能把一段文字描述或小说章节转换成分镜脚本表镜号、景别、运镜、时长、画面描述、台词、音效。输出通常是 Markdown 表格可以直接贴给 AI 绘图工具继续生成画面。我试过不少社区的现成分镜技能共同问题是表头千奇百怪模型对“景别”这个术语的理解也不稳定。所以后来我自己写了一个在技能正文里明确列出了景别枚举值远景、全景、中景、近景、特写、大特写并且要求模型只能从枚举值里选。这是一个很有代表性的经验技能里的专业术语尽量用“白名单式”定义去约束模型而不是指望它能自动理解行业黑话。--- name: storyboard_splitter description: 将小说段落或剧本文字转换为分镜脚本表格适合短视频策划、漫画分镜、动画前期。当用户提到“分镜”“镜头表”“脚本可视化”时使用。 --- 1. 阅读用户输入文本切除与画面无关的内心独白。 2. 按动作节拍划分镜头每个镜头只表现一个明确动作。 3. 景别只能使用远景、全景、中景、近景、特写、大特写。 4. 若原文未说明运镜默认“固定”不要自行添加复杂运动。 5. 输出 Markdown 表格列顺序为镜号、景别、运镜、时长、画面内容、台词、音效/OA建议。这套技能跑下来的分镜表基本不需要大改。我把这类技能称为“格式强约束型技能”它们最适合做成可传播的技能包因为格式规则是明确的、可复制的。5. 写完技能不生效的全链路排查从触发到执行的每个环节5.1 描述词触发的常见翻车现场装了一堆技能结果发现 Agent 理都不理这是几乎每个人都会遇到的问题。我排查顺序是这样的首先怀疑description。技能的触发靠 description 和被匹配的意图这个过程本身就是模型判断有概率、有随机性。我见过最典型的问题是把 description 写得跟正文一模一样长模型把它当作“文档”而非“触发标签”反而不容易匹配。我的经验是控制在 50 到 150 字之间把用户最可能说的“触发话术”原样放进去。如果 description 写了“当用户提到 XX 时使用”但用户的实际表达是“帮我把这个页面还原一下”那就不一定能命中。所以在 description 里我会习惯性放上至少三个同义触发角场景词、任务词、结果词。比如“还原页面”“切图”“写组件”三个都放。5.2 目录加载与权限的坑触发上了技能却执行不了就要检查目录和权限。Claude 的项目级技能目录是.claude/skills/全局是~/.claude/skills/Codex 对应的是.codex/skills/和~/.codex/skills/。我发现很多人把目录搞混将 Codex 的技能放进了.claude/skills或者反过来那自然不生效。另一个隐蔽坑是allowed-tools。Claude 技能里如果没有写入工具白名单Agent 默认可能只具备读取权限不能改文件。你辛辛苦苦生成了组件代码它却拒绝写入磁盘——这不是技能“没用”而是没有给技能授权。我在技能里现在都会显式声明权限范围需要读写的就写读和写不需要写盘的就只给读尽量最小授权。5.3 从日志和“小样测试”定位问题如果以上都排除了那就做一个“小样测试”。我常用的方法是在会话里直接问一句“你现在有哪些可用技能”看它能否回答出来。答不出来就去查 Agent 的日志文件Claude 和 Codex 在 CLI 模式下都会把模型调用记录写到本地搜 SKILL.md 路径能看到它到底有没有加载这个文件。这一步能区分三种状态文件没找到、描述没触发、触发了但执行中途报错。还有一个值得养成的习惯每个技能文件目录下放一个fixtures测试目录里面保存一个小输入和一个期望输出。修改技能之后直接用这个测试跑一遍比反复整段对话验证高效得多。我把这套做法叫“技能的单元测试”它帮助我快速迭代且不破坏已有能力。6. 把技能当成产品来维护版本、共享与安全底线6.1 版本管理技能也要有更新日志技能不是一次性用品。我见过的最合理的做法是把技能仓库当成普通代码库管理每个技能版本号改了什么在 README 里列出来。比如“第 2 版增加了对 Vite 项目的识别修复了输出目录不对的问题”。这样当你把技能分享给团队或开源社区时别人能快速判断这个版本是否适合自己。社区里很多技能项目更新非常快跟上最新版当然好但别盲目追新。我自己的习惯是不直接替换正在稳定运行的技能先下载新版到本地跑一轮测试用例再决定是否切换。6.2 潜伏在技能文件里的风险与控制办法最后说安全。技能文件本质上是“可能被模型执行的指令”它附带哪些脚本、请求哪些接口、是否有删库之类的危险行为下载第三方技能时一概看不见。所以我的原则很简单第三方技能先打开 SKILL.md 和 scripts 目录逐行审一遍看不懂的脚本坚决不执行。尤其是从非官方渠道获取的技能先隔离运行、给小项目测试确认无害后再放到正式路径。还有一层是工程层面的约束技能目录里别放生产环境的密钥、本地绝对路径、内部服务器地址。技能是会被导出的一旦分享出去“代码里写死了内网地址”这种尴尬事就会发生。把技能当公共产品来写变量走配置路径走相对路径才是长期的相处之道。把技能当作一个可演进的“活儿”持续去打磨和校验它会在实际项目中积累出你的个人方法论。前几天我又把“前端开发 skills”调了一版把组件生成步骤里“先查组件库”挪到了第一位因为实测发现 Agent 经常跳过复用直接造新轮子。这种微调没有任何写的难度但对于流程效率来说就是决定性的差别。说到底skills 不是越装越多越好而是越打磨越贴合自己工作流越好。