最近几个月“skills”这个词在AI编程社区里热度肉眼可见地涨。Claude Code、Codex、OpenCode这些工具都开始支持“技能”机制大家从“写一次性prompt”转向“沉淀成可持续复用的skill”。我今天就把这段时间实际折腾skills的经验完整梳理一遍它到底是什么怎么从GitHub上手动装哪些技能库值得关注以及怎么自己写一个能用的skill。先说结论skills机制不复杂核心是给AI agent一份“稳定的操作手册”。现在很多AI编程工具本质上还是对话模型你告诉它“按这个规范写代码”“先写测试再写实现”它这次能记住下次换个会话又忘了。skills解决的就是这件事把一段经常用的工作流沉淀成文件放在固定目录里工具会自动感知并在合适的时候加载。用起来之后你就会发现AI从“每次都要重新教育的实习生”变成了“上手就能干活的老手”。1. 先搞清楚skills到底是什么1.1 为什么大模型聊天很好但干活不够“稳”用过Claude Code或Codex的人都遇到过类似场景你让AI改一个模块它在当前对话里表现得很好会主动写单测、会遵守项目规范。但你把会话一关第二天新开一个任务它又回到了“忘性大”的状态。这不是模型变笨了而是对话式交互本身缺少“长期记忆”和“流程约束”。传统prompt工程的做法是把规范写在一个很长的系统提示里每次对话都塞一遍。但这种做法有几个硬伤一是token消耗大动辄几千字的规范每次都算钱二是容易冲突多个规范混杂在一起模型分不清优先级三是维护困难改一句话要重新复制粘贴到所有会话里。skills走的是另一条路把“知识”和“行为流程”拆成独立文件放到工具约定的目录下由工具按需加载。比如你写前端页面然后装一个“前端开发skill”里面写了组件规范、CSS约束、可访问性检查清单。当AI判断当前任务跟这个skill的描述匹配时就会自动读取并遵循里面的规则。它不需要你每次手动粘贴也不会污染无关任务的上下文。1.2 skills、plugins、MCP、prompt之间到底什么关系这块很多人会混。我整理了一张表方便对照理解机制本质适合场景典型工具skills静态指令工作流文档约束AI行为、固定产出规范Claude Code、Codex、OpenCodeplugins可执行代码扩展给编辑器/工具添加全新功能各IDE插件MCP servers外部数据/工具接入让AI读写文件、调API、查数据库Claude、Cursor等prompt/规则文件会话内指令注入一次性约束、项目级规范几乎全覆盖简单来说MCP解决的是“手够不够长”的问题——比如让AI直接操作浏览器、连数据库skills解决的是“脑子清不清楚”的问题——让AI知道按什么套路干活。两者不冲突实际项目里经常配合用。一个典型场景MCP server负责把设计稿文件读进来skill负责规定“图片必须懒加载”“色彩只能用设计系统里的变量”。1.3 一套skill的典型文件结构不同工具大同小异以Claude Code为例一套skill通常长这样~/.claude/skills/ └── frontend-dev/ ├── SKILL.md └── references/ ├── component-guide.md └── accessibility-checklist.md核心就是根目录下的SKILL.md它带YAML frontmatter里面至少要有name和description。description是最关键的字段AI靠它判断“什么时候该用这个skill”。正文部分写具体的操作步骤、规范、注意事项。references目录用来放辅助材料避免SKILL.md过长。这个设计很像写技术文档主文档简明扼要细节放到附录。好处是AI读取时先看主文档需要更多细节再按需翻阅references不会一下子把几百行内容全塞进上下文。2. 怎么把GitHub上的skills手动装到本地工具2.1 通用安装思路先搞清楚目标目录很多新手上来就问“某个skill怎么安装”其实思路很简单第一步找到工具约定的skills目录第二步把skill文件夹clone或复制进去第三步重启会话或执行刷新命令。就这么简单。常见工具的目录如下工具默认skills目录查看方式Claude Code~/.claude/skills//skills命令Codex CLI~/.codex/skills/codex skills listOpenCode~/.config/opencode/skills/按工具文档确认Cursor部分版本.cursor/skills/项目级加载网上很多仓库会写“一键安装脚本”但我不推荐盲跑。手动安装一次你能真正理解机制后面出问题也容易排查。2.2 手动安装一个skill的完整流程以Claude Code为例假设你在GitHub上看到一个叫awesome-dev-skills的仓库里面有个code-review技能想装到本地。第一步确认目录存在mkdir -p ~/.claude/skills第二步cloning整个仓库到临时目录然后只把需要的skill复制过去git clone https://github.com/example/awesome-dev-skills.git /tmp/awesome-skills cp -r /tmp/awesome-skills/code-review ~/.claude/skills/第三步验证结构ls ~/.claude/skills/code-review/正常会看到一个SKILL.md文件可能还有references等辅助目录。确认无误后打开一个新的Claude Code会话输入/skills里面应该能看到刚装的技能。这里有个细节我习惯只复制需要的子目录而不是整个仓库塞进skills目录。有些仓库会把几十个skill打包在一起如果全部复制会让工具的技能列表很臃肿且每次描述匹配都要多扫一遍反而拖慢响应。2.3 分场景安装Codex和OpenCode的差别Codex CLIOpenAI官方命令行工具的安装方式和Claude Code很像目录是~/.codex/skills/。但Codex对skill的触发策略和Claude不太一样Claude偏向由模型根据description自主决定Codex则更多结合项目上下文和用户的指令。装的skill不生效时先别急着怪文件很可能只是触发条件没满足。OpenCode作为开源方案目录结构一般是~/.config/opencode/skills/。它最大的优势是配置灵活你甚至可以在项目根目录放一个.opencode/skills/实现“项目级技能”——团队协作时大家clone仓库后自动拥有统一技能非常适合作坊式小团队。提示安装完skill之后如果工具没有立刻识别先把当前会话关掉重开。绝大多数“装不上”的问题都是因为会话缓存了旧目录不是文件放错。2.4 装完怎么验证skill真的生效很多人装完就以为完事了其实验证这一步很关键。我一般做三件事第一用工具自带的命令列一下当前skills确认文件被扫描到。第二故意做一个跟该skill相关的任务观察AI的行为变化。比如装了一个“数学建模排版”skill你就让它用LaTeX格式输出一段论文看它是否主动套用该skill里的模板。第三打开调试日志。Claude Code可以用--debug模式启动里面能看到具体加载了哪些skill文件。这一步能帮你确认到底是“没加载”还是“加载了但没遵守”。3. 值得关注的skills推荐与技能源网站3.1 前端开发类从规范到效率“前端开发skills”算是最热门的一类因为前端项目琐碎约束多——组件怎么写、样式怎么组织、可访问性怎么保证全靠口头叮嘱很容易翻车。推荐一个我很常用组合一个负责“组件开发规范”的skill加上一个“页面还原”skill再配一个“测试编写”skill。组件规范skill里写了组件Props命名规则、默认值处理、样式优先级页面还原skill里写了如何从设计稿提取间距、颜色token、响应式断点。实测下来模型产出的代码风格稳定很多代码评审时少扯很多皮。这类skills在GitHub上非常多搜frontend skills claude就能找到一堆。注意区分质量靠谱的skill会写明适用框架React/Vue/原生带有具体示例那种几百行全是空话的建议直接跳过。3.2 数学建模场景竞赛er的实用性选择数学建模相关的skills火起来跟“华为杯”、国赛这些赛事关系很大。参赛时间紧建模和论文都要赶AI能帮忙分担很大一块。实用的数学建模skills大致有三类数据处理类、可视化类、论文排版类。数据处理类技能会规定一套完整的探索性数据分析流程包括缺失值处理、异常值检测、相关性分析可视化类技能要求所有图表必须有标题、来源、单位风格统一论文排版类技能直接内置LaTeX模板给定表格数据就能生成三线表。这类技能不一定要多“AI”很多其实是把成熟的数据分析工作流固化成文档。好处是省心——你不用每次比赛都临时写一轮promptAI会自动按固定套路走。3.3 社区热门整合包Superpowers Skills和TypeSafeSuperpowers Skills是我个人比较推荐的整合包GitHub上直接搜superpowers skills就能找到。它包含几十个按方向组织的skill覆盖需求拆解、TDD开发、代码审计、架构讨论等场景。它的特点是比较“重”适合追求工程化流程的团队新手上来全装可能会觉得繁琐我建议先挑其中两三个体验。TypeSafe AI Skills是另一类值得关注的资产它围绕Scala/Java方向维护了一套较完整的技能库。如果你做JVM生态开发直接引入比自己从零写规范要靠谱得多。它的结构和Claude Code兼容稍作调整就能在Codex里用。3.4 常用技能源网站和检索技巧现在并没有一个“官方应用商店”式的skills分发平台主要靠GitHub和社区网站。我常用这几个渠道GitHub直接搜索关键词加claude skills或codex skills按stars和最近更新排序。一些社区聚合站用标题里提到的“用户推荐技能库网址”收集了多渠道的skill列表。知名AI工具官方文档官方文档里通常有skills最佳实践和示例。检索技巧我习惯把“场景词skills”放在一起搜比如想要数学建模相关就搜数学建模 skills想要前端相关就搜前端开发 skills。比起漫无目的逛仓库直接命中目标效率高很多。4. 从抄到写自己开发一个可用的skill4.1 解剖一个最小的SKILL.md动手写之前先看一个标准的SKILL.md长什么样--- name: python-data-science description: 用于进行标准化数据分析的流程指引当用户需要处理结构化数据并生成统计分析报告时使用。 --- # Python 数据分析流程 ## 第一步加载与检查 - 用 pandas.read_csv() 加载数据 - 打印 shape、dtypes、前5行 - 检查缺失值比例超过10%的列单独处理 ## 第二步清洗与转换 - 统一列名snake_case - 日期列统一转 datetime - 对数值列执行异常值检测IQR方法 ## 第三步建模前探索 - 至少绘制3张基础分布图 - 输出相关性矩阵 - 记录所有业务洞察 ## 输出规范 - 所有代码必须包含注释 - 最终交付一份 markdown 格式的数据摘要这个例子虽然简单但结构很典型。frontmatter里的name用来展示description用来触发。正文部分是真正的“干货”AI会严格按它执行。4.2 description怎么写决定AI能不能正确触发写skill最容易翻车的点就在description。很多人写得很含糊比如“用于数据处理”结果AI在任何数据相关任务里都想触发反而干扰正常任务。我给一个比较稳的写法模板当用户需要[做什么]时使用尤其是[关键特征]。如果只是[不相关场景]不要使用。举例description: 当用户需要将现有React组件迁移到TypeScript时使用包括类型定义、Props接口生成、any类型清理等工作。如果只是新建组件或已有TS组件小改动不要使用。这里面包含触发场景、任务范围、负向排除。写清楚负向条件特别重要能省掉很多“不该触发却触发”的麻烦。4.3 把操作细节写具体避免“正确废话”很多新手写skill容易写成“正确废话”让AI“写出优雅的代码”“保证性能”。这种话模型听了等于没听因为它没有一个可执行的检查标准。正确做法是写“可验证的行为约束”。比如“所有API调用必须用try/catch包裹错误信息须包含HTTP状态码”“每个组件文件必须不超过150行超过则拆分子组件”“后端接口返回数据必须经过DTO校验禁止直接透传数据库字段”。这些规则越具体AI越容易执行评审时也越容易判断“有没有遵守”。我写skill时有个习惯每条规范都用“当…时必须…如果…则…”的句式让模型有明确的决策路径。4.4 从踩坑里迭代一场真实调试记录我第一次写skill时踩过一个很典型的坑。当时写了个“代码评审”skill装了之后发现AI确实在评审但产出非常泛泛给了一堆“建议提升代码可读性”的废话。后来我查了加载日志发现skill确实被读取了问题出在正文里缺少“评审必须输出什么格式”的硬性要求。我改成这样每条建议必须给出“问题描述所在文件行号修改建议示例代码”并且按严重程度分级阻塞、重要、建议。一个“严重”级问题至少要匹配一个明确的行为标准比如“未处理异常分支”或“裸SQL注入”。改完再跑评审质量明显能打后续直接把它用到了自己项目的PR检查上。整个过程其实很简单写一个粗糙版本 → 观察AI的表现 → 找到AI不到位的地方 → 把对应要求写进skill → 再跑一次。循环三四轮skill基本就能用了。5. 常见问题与排查技巧实录5.1 装完不生效第一反应不该是重装“装完skills没反应”是出现频率最高的问题。我建议按这个顺序排查目录对不对确认放进的是工具默认扫描目录没有多套一层子目录。文件名对不对必须是SKILL.md任何大小写或改名都会导致不识别。会话刷新没Agent工具通常只在会话启动时扫描skills目录老会话里不会自动加载新skills。description清不清晰如果描述本身模糊模型可能读到了但认为“不适合当前任务”。有没有日志打开调试模式确认工具确实读取过这个SKILL.md。我见过最离奇的问题是把文件放在了~/.claude/skills而不是~/.claude/skills/具体技能名/SKILL.md工具扫不到就完全没反应。这类问题只要按上面顺序检查基本五分钟能定位。5.2 技能“乱触发”或“不触发”怎么办先说不触发。多数原因是description里负向条件写得太少。模型判断过于保守拿不准该不该用就干脆不用。解决方法是把触发和排除场景都写具体甚至可以加“当用户提到…时必须使用”的强触发句式。再说乱触发。常见于description写得太宽泛比如“帮助用户编程”。这种描述几乎适配所有编程任务导致每个任务都会加载反而拖慢响应、干扰主任务。解决方法是给description加限制词“仅当用户明确要求…时”“当项目包含…时”。配合负向条件能显著减少误触发。注意乱触发的问题往往比不触发更让人抓狂因为它会默默污染上下文。如果你发现AI突然变得“啰嗦”或者夹带无关规范先检查是不是某个skill的description过宽了。5.3 如何清理和卸载不再使用的skills清理skills的目的有两个一是减少描述匹配时的扫描开销二是避免技能间冲突。有些整合包装完包含几十个skill但实际常用的就三四个剩下的全是负担。清理方法很直接在skills目录里删掉对应文件夹即可。如果只是想暂时禁用更推荐的做法是把SKILL.md改名比如改成SKILL.md.bak。这样既能保留文件又能让工具不再加载。团队协作时我用的是“按需分发”策略——只把真正需要的几个skill放进共享目录而不是把整个技能库丢进去。5.4 项目级skills和全局skills怎么取舍最后补充一个容易被忽略的问题全局skills放个人目录项目级skills放项目内。两者有什么差别我的经验是个人习惯、编码风格、通用规范放全局项目特定的技术栈约束、目录结构、团队约定放项目级。举个例子“所有代码必须加注释”是全局约束“本项目所有页面组件必须放在src/pages下且文件名受路由约束”是项目级约束。推荐做法是在项目根目录放一份精简的skills配置只包含这个项目的关键约定。不要从全局把所有skills都复制到项目里否则换项目时反而要花时间排查哪个skill在“捣乱”。6. 一点个人心得用好skills的关键不在“装得多”说真的skills这个机制最迷人的地方不是“装一个技能库就变强”而是逼你想清楚你希望AI在什么场景下、按照什么标准、稳定地做什么事。这本身就是一套工作方法论。我现在的做法是每个项目开始前花十分钟检查一下现有skills是否匹配项目中途遇到重复性的、需要交代很多背景才能让AI做好的任务就顺手沉淀成一个新skill。迭代几轮之后很多繁琐的重复劳动基本就交出去了。如果让我给一条最实用的建议那就是从小处开始选一个你最常重复的任务把它固化成skill然后不断用真实需求去打磨它的描述和细节。用不了几轮你就会感受到AI编程从“偶尔超神、常常抽风”到“稳定及格”的变化。