写这篇文章的时候我电脑上已经躺了二十多个 skills 文件夹了。最近这半年Claude Code 和 Codex CLI 带火了 skills 这个概念前端开发skills、数学建模skills、superpower skills 这些词在社区里到处刷屏。坦白说我第一次看到 SKILL.md 的时候也是一头雾水这不就是一个 Markdown 文件吗怎么就能让 AI 从一个“偶尔聪明的助手”变成一个稳定的“领域专家”直到自己动手装了十几个、又拆了几个开源仓库之后才算把这块玩明白。这篇文章不打算给你堆概念而是把我折腾出来的整套方法——从去哪找、怎么装到自己写、怎么调试再到踩过哪些坑——一次讲清楚。1. AI Skills 到底是什么为什么突然大家都开始玩1.1 从一条临时指令到一个可复用的技能包先给一个最朴素的定义AI Skills 是一组按照约定格式组织的文件核心是一个叫SKILL.md的 Markdown 文档里面写清楚“在什么场景下、按照什么步骤、输出什么格式”。AI 编程工具在合适的时候会把这份文档读进上下文再结合用户的对话内容去执行。你可以把它理解成新员工入职手册。以前你用 AI 干活每次都要在对话框里重新交代一遍“你是一个前端工程师请先看我的规范文件再生成组件最后写测试……”这件事很累而且你一旦换了一个对话窗口这些交代就全丢了。技能解决的就是这个问题把这段“入职培训”变成永久资产存放在固定目录里AI 需要时自己拿来看不需要你反复强调。1.2 它和传统的提示词工程差在哪很多人问我这跟写好一点的 prompt 有什么区别我的看法是它本质上是把提示词工程从“聊天技巧”升级成了“文件工程”。对比维度传统提示词AI Skills存放位置聊天框、变量、配置项里的一段文字磁盘上的文件夹 Markdown 文件复用方式手动复制粘贴不同窗口各自独立自带发现机制多个项目都能加载内容结构单段文本很难超过几千字可拆分成多文件主文件 参考资料多人协作发一段话对方还要自己调放进 Git 仓库拉下来就能用维护成本改了这次下次还要改版本化管理改动可追踪还有一点很关键提示词是“一次性指令”它告诉 AI 这次怎么回答技能是“永久能力”它告诉 AI 这件事以后都该这么做。这种差异带来的直接好处是你可以把质量稳定的工作流沉淀下来而不是每次依赖随机发挥。1.3 为什么是现在突然火起来表面原因是工具生态成熟了。Claude Code 把~/.claude/skills目录变成了默认扫描路径Codex CLI 也提供了类似的技能目录OpenCode 同样支持加载本地技能。工具只要支持“丢文件进去就自动识别”就会有人生产技能包社区很快就热闹起来。深层原因是大家发现 AI 的能力瓶颈已经不是“模型聪明不聪明”而是“怎么让模型稳定地按照你的流程干活”。一个模型本身很强但如果没有技能约束它可能这次给出完美答案下次换个说法结果完全跑偏。技能把“发挥”变成了“流程”这是生产环境里最需要的特性。所以并不是大家突然想玩一个新概念而是它正好补上了 AI 编程落地时最疼的那块短板。2. 现成技能库怎么找、怎么装2.1 值得关注的几类仓库先说结论搜现成技能最有效的路径就是上 GitHub 搜关键词awesome claude skills、codex skills、opencode skills这类合集仓库通常会把人气的技能包整理成清单。热度和口碑比较高的大概有这么几类全家桶型像superpower skills这种一次装几十个技能覆盖写代码、写文档、审代码、复盘等场景。优点是量大管饱缺点是加载太多会让 AI 选择困难后面我会讲怎么清理。编程专项型主要针对具体开发场景比如“前端开发skills”里会包含 React 组件生成、样式规范检查、页面代码生成等技能适合做业务开发的团队直接抄作业。竞赛科研型数学建模 skills 在竞赛圈里很受欢迎。这类技能通常把读题、假设、建模、求解、写论文整条链路拆成步骤参加华为杯或者其他建模比赛时能省下很多磨合时间。内容创作型AI 漫剧、短视频脚本相关的技能核心是解决“分镜怎么写、文案节奏怎么控、人物台词怎么不重复”这类问题。你找到仓库之后不要急着复制粘贴先看它的目录结构。一个成熟的技能包应该是每个子文件夹里都有一个SKILL.md旁边可能还带references、examples、templates这些辅助目录。只有SKILL.md的也靠谱但说明它功能比较单一。2.2 Claude Code 手动安装流程网上经常有人在问“claude code 怎么手动装 github 上的 skills”其实非常简单不需要什么图形界面三步就够。在 GitHub 上找到目标技能仓库复制仓库地址或者直接下载 ZIP 压缩包。打开终端执行mkdir -p ~/.claude/skills cd ~/.claude/skills git clone https://github.com/username/some-skills-repo.git如果只想要某一个子技能就不建议整个仓库 clone而是把对应子目录单独下载然后放进~/.claude/skills/技能名/下面。检查目录结构是否正确find ~/.claude/skills -maxdepth 2 -name SKILL.md只要这个命令能列出文件Claude Code 启动时就会自动扫描到。之后重启一下终端里的 Claude Code输入/skills或者直接问它“你有哪些技能”正常情况下它会把安装清单告诉你。这里有个容易踩的坑很多人下载完技能压缩包之后直接把它解压到了Downloads目录然后在 Claude Code 里怎么都找不到。原因很简单它只认~/.claude/skills或者项目下的.claude/skills别的路径一概不管。你只要把技能整个文件夹挪进这两个位置之一问题立刻解决。2.3 Codex、OpenCode 等其他工具怎么装Codex CLI 的安装思路完全一样只是目录名换成了~/.codex/skills。把包含SKILL.md的文件夹丢进去重启后就能被识别。OpenCode 稍微灵活一点它既支持全局目录也支持项目级目录。而且 OpenCode 的网页版入口可以直接打开技能管理页面在里面能看到已安装技能的状态不需要一直盯着终端。如果你手里正好有.json或者.md格式的技能描述文件网页端通常也支持手动上传比命令行更直观。还有一类项目里的技能比如.claude/skills跟代码一起提交到 Git 仓库这样同一个团队的人克隆下来之后什么都不用配技能自动生效。这种方式我特别推荐给做内部规范建设的团队比在文档网站上写十页说明有效得多。2.4 装完之后怎么确认真正生效了技能装完不生效是很常见的事所以一定要做验证。我先看目录再看触发。目录层面执行ls -la ~/.claude/skills确认里面都是独立的技能文件夹而不是套了一层“技能仓库名”再套一层“子技能名”的嵌套结构。很多技能识别不到就是因为路径多了一层AI 只扫描固定深度。触发层面找一个跟该技能强相关的需求去试。比如装了一个前端组件生成技能就让它“按技能要求生成一个按钮组件”然后看它有没有主动去读项目规范文件。如果它只是当成普通对话回答说明技能没被加载或者描述里的触发词太弱。这个问题我在下一部分详细说。3. 自己动手写一个 AI Skills3.1 SKILL.md 的骨架自己写技能没有想象的那么玄乎我习惯用一个固定模板起步。--- name: frontend-component-gen description: 生成符合项目规范的前端组件代码。当用户提到“组件”、“页面”、“按钮”等关键词时使用。 version: 1.0.0 --- # 前端组件生成技能 ## 适用场景 需要创建或重构 React/TypeScript 组件时。 ## 工作流程 1. 先阅读项目根目录下的 design-tokens.json 与 component-rules.md。 2. 确认组件名称、props 接口、使用场景。 3. 生成组件代码包含样式文件和基础用法示例。 4. 检查代码是否符合项目命名规范。 ## 输出要求 - TSX 文件 配套 SCSS 文件 - 必须包含 JSDoc 注释 - 提供最小可运行示例这个模板里的 frontmatter 非常关键尤其是description。它决定了 AI 什么时候会想起这个技能。如果你写的是一堆形容词比如“优秀的组件生成方案”AI 很难判断触发时机如果你明确写了“当用户提到组件、页面、按钮时使用”它就能快速命中场景。3.2 描述怎么写技能才容易被触发我调试过几十个技能之后发现触发率最大的影响因素不是技能内容而是description写得够不够具体。写description有三个原则先说触发场景再说能力。优先写“当用户提到 XX 时使用”而不是“本技能可以提供 XX 能力”。给出排除情况。比如“仅当用户要求生成完整页面时使用单一的样式调整不需要”避免技能跟日常对话抢活。控制长度。描述太长反而让模型抓不住重点我看到比较理想的长度是两到三句话约 50 到 100 字。另外技能名称也要克制不要用“超级无敌前端优化大师”这种名字尽量用短横线连接的语义化命名方便后续通过/skills列表快速识别。3.3 新手最容易踩的三个设计坑第一个坑是内容贪多。我见过有人把一个技能写到一万多字想一次解决所有问题。结果上下文直接被塞爆模型既没有记住关键步骤又丢失了用户当前任务的上下文。正确做法是SKILL.md只写骨架和关键约束把详细的代码规范、示例、参考文档放到同级的references目录里让 AI 按需读取。第二个坑是把技能当成角色扮演 prompt。技能应该用来定义“做什么、怎么做、按什么标准交付”而不是让 AI“你是一个资深专家”。角色感写多了反而容易让 AI 在输出中加很多空话延误真正干活的时间。第三个坑是写完不测试。技能是软件资产不是日记改完必须放进一个干净项目里试一遍。最好给它建一个最小测试项目里面放一个假的规范文件然后故意用弱触发词和强触发词各测一次确认它能在正确时机被加载。3.4 调试与迭代把技能当成代码维护调试技能我基本靠两个手段。第一是看加载日志Claude Code 启动时加--debug参数会输出它扫描技能目录的记录第二是直接在对话里问“你现在有没有加载前端组件生成技能”AI 会照实告诉你。迭代的时候建议做版本管理。version字段不要一直写 1.0.0每次调整行为就升一个版本号。我还会在技能目录里加一个CHANGELOG.md记录每次修改的原因这样过了两个月再回来看你还能想起当时为什么加某个步骤。这套习惯跟写代码一样看似多花了五分钟实际上能帮你省掉大量回忆成本。4. 三个高频场景的技能实战拆解4.1 前端开发 Skill让生成代码自带规范前端开发 skills 现在几乎是需求量最大的技能类型因为前端项目规范差异极大有人用 Tailwind有人用 SCSS有人用 styled-componentsAI 如果没有明确指令很容易生成一套“看起来很对但完全没法用”的代码。我的做法是技能第一步强制 AI 读取项目的 tokens 文件和规范文件而不是直接写代码。这个“先读后写”的顺序能减少大量返工。设计规范文件里通常会写清楚颜色变量、间距体系、圆角半径、字体大小等设计 token把它跟技能绑定之后AI 生成的组件天然符合设计系统的口味。实际写技能时我还会加一条约束生成组件必须附最小可运行示例和使用说明。这样团队成员拿过去就能直接落成文档不用再单独花时间补示例。个人体会是这类技能最好从你自己最常写的一类组件开始比如按钮和表单验证顺手之后再扩展到列表、弹窗等复杂组件。4.2 数学建模竞赛 Skill把参赛流程变成检查清单数学建模 skills 能火起来核心原因是竞赛场景的时间压力极大。三天比赛看着很长但拆掉读题、查资料、建模型、写论文这些环节之后留给每一段的时间非常紧张。我见过比较多参赛者直接拿现成的建模技能包我的建议是你至少要自己改一遍。因为每个队伍的习惯不一样有人擅长机理分析有人擅长数据驱动一个通用技能很难覆盖你的拿手路线。一个合格的数学建模技能应该包含这几个阶段读题拆解把问题背景、决策变量、约束条件、目标函数拆出来假设罗列写清楚每条假设的依据防止后面模型跑不动时无从下手模型设计先判断问题属于预测、优化、评价还是分类再套对应方法求解验证明确用什么工具求解给出结果合理性检查论文输出把模型建立过程写成逻辑完整的论文片段你可以把它做成纯文字检查清单也可以在每个阶段让 AI 输出表格比如“目标函数是什么、约束条件是什么、求解方法是什么”。这套技能在准备华为杯或者其他建模比赛时能帮你把一群人的脑子对齐到同一条流程上少吵很多架。4.3 AI 漫剧脚本 Skill把创意流水线化AI 漫剧最近也是热词之一很多内容创作者开始用 AI 批量产出短剧脚本但质量往往参差不齐。最大的问题是同一个 AI 反复写脚本之后会出现角色语气趋同、分镜雷同、台词抽象等毛病。解决办法就是给 AI 定义一个漫剧技能。我在写这种技能时会强制它输出固定结构主题背景、主角人设、核心冲突、分集大纲、分镜脚本、台词和配音提示。分镜脚本里必须写清楚镜头景别、画面描述、时长、台词还要规定“每三段台词至少要出现一次视角切换”防止画面单调。另一个很有效的约束是给角色设定固定句式库。比如主角生气时喜欢用短句配角解释时喜欢用比喻这些约定写进技能之后AI 生成的剧本就不容易出现“所有人都像同一个 AI 在说话”的塑料感。这也再次印证了一件事技能管理的不是 AI 的“聪明程度”而是它的“一致性”。5. 常见问题与排查技巧实录5.1 技能不生效该怎么查技能不生效基本是出现率最高的问题我整理了三步排查法。第一步看目录执行find ~/.claude/skills -maxdepth 2 -name SKILL.md如果没有任何输出说明目录结构不对或者技能没放进正确位置。第二步看描述确认技能里description写了准确的触发词并尝试用一模一样的词去对话。第三步看日志开启调试模式确认工具是否真的把技能目录纳入了加载路径。还有一种容易被忽略的情况技能文件编码出了问题。某些仓库的SKILL.md是 UTF-8 带 BOM或者包含特殊字符工具解析 frontmatter 时可能直接失败。遇到这种情况直接用编辑器另存为 UTF-8 无 BOM 格式就好。5.2 技能互相抢活怎么办装得多了之后会出现一个尴尬局面你让 AI “生成一个页面”结果两个技能都觉得该自己上AI 不知道该听谁的输出反而更差。我的处理方案是隔离目录 窄化描述。全局目录只放通用技能项目目录只放当前项目需要的专用技能两个地方都有的话以项目目录为准。同时把每个技能的description写得再窄一点比如一个只处理登录页另一个只处理列表页这样重叠区域就小很多。如果两个技能必须共存可以在SKILL.md里互相写一句“如果用户提及 XX 功能请先调用另一个技能”让 AI 知道分工边界。这听起来有点绕但实际上非常有效。5.3 技能太多怎么清理和归档技能也会膨胀。我之前一口气装了四十多个启动的时候慢对话也经常出戏后来只能定期做清理。网上流传比较广的清理方法其实核心就三步列清单、看体积、删冗余。先列清单du -sh ~/.claude/skills/* | sort -h看每个技能占了多少磁盘空间这能侧面反映它里面塞了多少参考资料。再用一个简单脚本统计每个技能是否被触发过grep -l skills/ ~/.claude/logs/*.log 2/dev/null如果你不确定某些技能到底要不要留我的建议是不要直接删而是把它们移到一个~/.claude/skills_archive目录里。这样既不影响当前加载又保留了一份“后悔药”。5.4 怎么把技能交给团队复用技能要达到团队复用的程度光靠一个人桌面上的文件夹是不够的。最好把它做成一个独立的 Git 仓库放到团队代码库下面然后用项目级目录.claude/skills去引用。这样任何人 clone 项目代码之后技能自然就是可用的不需要额外传递文件。团队技能需要注意的坑是不要每个人都往同一个技能里加自己的偏好否则很快会变成一个四不像。我建议每个技能指定一个 owner其他人提修改意见owner 统一合入。这跟代码评审是一个道理技能也是需要 review 的。最后再分享一个小技巧。我会在自己所有技能目录里放一个USAGE.md用几句话说明这个技能解决什么问题、在什么场景下不要用。刚开始觉得多此一举后来发现过几个月再回头看它救了我很多次“这个技能为什么在这”的困惑。工具会换、模型会变但一套清晰、整洁、随时可解释的技能库是越攒越值钱的资产。