过去三个月我的工作方式有了一个比较明显的变化以前在Claude Code里写代码每次都得把项目结构、代码风格、输出格式从头交代一遍AI稍微跑偏就得拉回来重新说现在这些交代被统一打包成了skills让AI按需加载基本不用重复唠叨了。这东西说起来不算黑科技本质就是把散落在对话里的规则、步骤、模板固化成结构化文件在合适的时机自动进入模型上下文。最近skills在AI编程社区里几乎天天上榜从Claude Code到Codex、opencode都在做类似能力GitHub上的skills仓库也越攒越多前端开发、数学建模、AI漫剧这些垂直场景都有对应技能包。这篇内容我打算按是什么、怎么装、怎么写、用哪些、踩坑这条线来讲适合两类人一是已经在用Claude Code、Codex这类编程代理但还没系统接触过skills的二是已经在用但经常遇到装了不生效自己写的老是误触发这类问题的。我会把从GitHub手动安装的完整流程、SKILL.md的写法、真实场景里的技能取舍都讲清楚最后聊聊什么样的技能值得长期维护。1. 先搞懂skills是什么它和提示词的根本区别1.1 一个让我决定封装skills的场景我第一次意识到光靠提示词不行是在一个周末临时接的需求上。那是一个数据处理任务要求把一批CSV文件按固定口径清洗、补充缺失值、生成描述统计最后导出符合论文格式的表格。这些步骤本身不复杂但每条规则都很碎哪些字段要保留、缺失值怎么插补、表格要用三线表还是普通Markdown表格、输出里要带哪些指标。我一开始直接把这些要求都写在对话里让Claude Code一次跑完结果它前两步做对了第三步开始自己发挥把字段口径改了表格格式也换了。之后我改成把要求拆成几段提示词每次做完一步再贴下一步的规则确实稳定一些但非常累而且换个项目又得重新写一遍。那时候我就想如果这些规则能像函数一样被封存起来AI遇到这类任务自动装载甚至还能带着脚本一起执行该多好。后来深入了解skills之后发现它解决的就是这个问题。大家常说的AI编程上下文窗口在Claude Code这类代理工具里真的不够用。每次会话要装代码、装文件内容、装对话历史你再往里面塞一大堆业务规范模型既记不住也容易混。而skills机制是按需加载的模型先读到的是每个技能的简要描述只有当任务匹配到某个技能描述时才把这个技能的完整内容读进上下文。这就像你请了一个远程助理桌上只放了一沓技能卡片卡片正面写着什么情况找我翻过来才是详细操作手册。1.2 skills的本质是可执行的上下文包如果只用一句话概括skills就是给AI用的可执行上下文包。它比普通提示词多个两个层面的东西。第一层是结构化。一个skill通常是一个目录里面有主文件SKILL.md头部用YAML写name和description正文用Markdown写操作步骤、注意事项、示例。模型看到这个文件就知道这个技能叫什么、什么时候用、该怎么执行。这种结构不是为了好看而是为了让模型在几十上百个skill之间做路由判断快速识别当前任务该调哪个。第二层是承载附属文件。skill目录里可以放脚本、模板、参考资料、图片资源SKILL.md里可以明确说先读references/calc_spec.md再调用scripts/eda.py。这听起来简单但意味着你给AI的不再是一段话而是一个包含代码逻辑、模板产物、数据文件的完整工具包。一个做数学建模的skill完全可以带上一整套数据预处理脚本和论文LaTeX模板。从这里能看出它和提示词的根本区别提示词用完即走skills留下来沉淀。你今天在对话里把生成带storybook的React组件这个规范调好了明天新开一个会话又得重新调一次而如果写成了skill每个新会话里模型都能自动按这套规范输出。这才是skills真正改变工作流的地方。1.3 skills目录里到底有什么——以Claude Code为例用Claude Code举例子最直观。它读取skills的位置主要有两个项目级是.claude/skills/技能名/SKILL.md用户级是~/.claude/skills/技能名/SKILL.md。项目级的只有当前项目能用适合放这个项目专属的规范比如这个后端项目的代码分层规则用户级的全局生效适合放跨项目通用能力比如写可复用的数据分析报告。一个典型的skill目录长这样~/.claude/skills/eda-report/ ├── SKILL.md ├── scripts/ │ ├── quick_eda.py │ └── describe_data.py ├── templates/ │ └── data_report_template.md └── references/ └── field_mapping.mdSKILL.md是必选项其余都可以按需加。模型加载这个skill时默认只读SKILL.md不会把整个目录都塞进上下文scripts和references只有在SKILL.md中明确指示当需要清洗数据时运行scripts/quick_eda.py时才会被调用。这个懒加载设计很重要如果一个skill里附带了一堆大文件而模型一上来全部读一遍那上下文直接爆掉。要注意的是不同工具的路径规则不完全一样Codex、opencode虽然也在采用类似思路但各自文档里写的目录和配置方式有差异。我第一次从Claude Code切到另一个终端工具时习惯性地把skills放在.claude/skills下面结果完全没生效后来查文档才发现它读的是自己约定的路径。所以跨工具复用skills的时候先看目标工具的用户文档别想当然。2. 从GitHub把现成skills装进本地手动安装全流程2.1 先确定你的工具读取哪个目录手动装skills这件事说简单也简单说容易踩坑也真的容易踩。很多人把文件夹放到错误的位置然后跑来问为什么我的skills没生效十有八九是目录没放对。以Claude Code为例我自己的习惯是先把通用技能放到用户级目录把跟当前项目强相关的技能放到项目级目录。判断规则很简单——如果换了项目你还想继续用这个技能就放用户级如果只服务当前这个仓库的代码规范、目录结构就放项目级。项目级和用户级同时存在同名skill时项目级优先。确定好放哪之后创建目录再进入mkdir -p ~/.claude/skills cd ~/.claude/skills如果你的工具是Codex或者opencode建议先去官方文档搜一下skills directory或者custom skills。很多工具会注明兼容Claude Code的SKILL.md规范但目录名可能不同也有工具要求你必须先开启某个配置项否则就算文件放对了也不加载。这些细节文档里都有千万别跳过。2.2 手动安装的操作细节与目录结构检查从GitHub装一个skill我一般分三步。第一步在GitHub上找到目标仓库先花两分钟看目录结构。有的仓库整个就是一个skill根目录直接是SKILL.md有的仓库是聚合型几十个skill按类目放在skills/xxx下面。如果你不看结构直接整仓复制很容易把仓库外壳当成skill目录导致多套了一层文件夹。第二步把skill目录拷到本地。整仓拉下来再删掉多余内容是最省事的cd ~/.claude/skills git clone --depth 1 https://github.com/某个用户/某个skills仓库.git # 如果仓库里有多层结构比如技能在 skills/skill-name 下 cp -r 某个仓库/skills/skill-name . # 拷贝完成后把克隆的仓库删掉避免混淆 rm -rf 某个仓库如果只想要单仓库里的某一个技能也可以不git clone直接在GitHub网页上进入该技能目录用Download ZIP或逐个文件复制。我自己更倾向git clone因为有些skill里带脚本和模板逐个复制容易漏文件。第三步也是最重要的一步检查最终目录结构。正确的结构必须是技能目录的根下面直接放SKILL.md~/.claude/skills/skill-name/ └── SKILL.md如果变成了这样就说明你多包了一层~/.claude/skills/skill-name/技能仓库/技能目录/SKILL.md这种一层套一层的情况工具根本识别不到。检查完成后重启Claude Code或者重新打开会话再执行/skills命令看列表里有没有新技能。2.3 装完如何确认真的生效装完之后最怕的就是看起来装了实际没生效。我建议做三个验证步骤。第一步用命令列表确认。Claude Code里输入/skills正常情况下会列出所有已加载skill的name和description。如果列表里没有你刚装的技能基本就是目录放错或者SKILL.md格式不对直接回到2.2检查结构。第二步故意触发一次。根据你装的skill的description构造一句能命中的任务描述发给AI。比如装了一个生成React组件的skill你就直接说帮我生成一个带筛选功能的表格组件。注意观察两点一是AI有没有主动引用这个skill的内容二是输出风格是否明显变规范了。如果AI完全没反应说明description的匹配逻辑没接上。第三步追查日志或verbose输出。Claude Code这类工具一般都有调试模式开启后能看到模型当前加载了哪些上下文、调用过哪些文件。有一次我装了个技能但模型始终不用日志里显示模型每次都在犹豫要不要调用因为description和用户任务描述语义差太远。这类问题光看表面很难发现看日志最直接。2.4 去哪找质量还不错的skills库关于常用skills源网站这个问题我分享几个我实际用过、觉得靠谱的方向而不是直接丢一个固定网址因为这些源更新很快。GitHub搜索是最直接的。搜claude skills、awesome claude skills、codex skills这几个组合词能找到不少社区维护的awesome列表。Anthropic官方也维护过一套skills示例仓库里面是做docx、pdf、pptx这类文档处理的技能规范性强非常适合当学习样板。除了GitHub一些第三方插件市场也值得关注。Claude Code的插件市场里有多人维护的合集包比如社区里叫Superpowers的那类插件安装后会附带一整批实用技能。这类合集的好处是开箱即用坏处是鱼龙混杂装完经常发现一堆技能你根本用不上反而增加了模型做路由判断的负担。我一般会装完立刻清理掉不需要的部分。还有一个小众但好用的途径直接看你用的工具官方文档里的示例技能。这些示例虽然简单但胜在规范、兼容性好适合作为二次开发起点。很多你现在觉得难写的skill都是从官方示例改出来的。3. 手写一个技能包的完整过程SKILL.md结构、description写法与常见返工3.1 一个最小可用的SKILL.md长什么样自己写skill没有想象中难但格式必须严谨。我贴一个我最常用来演示的最小示例这是一个给数学建模前做数据探索的skill--- name: eda-report description: 当用户提供一张或多张数据表CSV/Excel希望快速完成数据探索、缺失值检查、异常值识别并输出描述性统计报告时使用。适用于数学建模、论文数据分析的前期环节。 --- # 数据探索 EDA Report ## 目标 对输入数据做结构化探索输出一份可直接粘贴到论文/报告中的中文章节。 ## 输入 - 用户会提供数据文件路径或直接把表格内容粘贴到对话里。 - 用 user_input 标记数据来源不要擅自读取无关文件。 ## 执行步骤 1. 用 pandas 读取数据先打印 shape 和 column names。 2. 对每一列计算缺失率、类型、唯一值数量输出摘要表。 3. 对数值型列输出 min/max/mean/std对分类型列输出 top3 频次。 4. 识别明显异常值如负数的年龄、超过5倍标准差的数值单列说明。 5. 最后按 templates/report_template.md 的格式输出报告。 ## 注意 - 不要输出Python代码过程只输出结论报告。 - 不确定的字段口径先提问确认不要替用户假设。这个文件虽然短但要素齐全frontmatter只有name和description正文用明确编号步骤告诉模型做什么有输入标记、预期输出、边界约束。写得太短的SKILL.md往往没有操作价值AI读完只知道个大概不知道具体怎么执行写得太长又浪费上下文。3.2 description是灵魂怎么写才不误触发如果说SKILL.md正文决定技能好不好用那description就决定它能不能被正确触发。我踩过最大的坑就是把description写成了功能简介比如用于数据探索结果模型看到一个稍微沾边的问题就把这个skill加载了几轮对话下来上下文全是一堆不相关的内容。正确的description应该是一个触发条件说明而不是功能概括。我的写法是固定句式当用户【给出什么输入/提出什么需求】时使用本技能完成【什么目标】适用于【什么场景】。要明确写清楚前置信号比如当用户提供CSV/Excel数据表还要明确排除场景比如仅用于论文/报告格式的数据表格不用于实时流数据。为什么这一点这么重要因为模型在面对多个skills时靠的就是description之间的语义匹配。写得太宽所有任务都会撞上写得太窄真到了场景又匹配不上。有个很实用的检查方法你把所有skills的description拉出来通读一遍想象自己是AI看到用户说帮我分析一下这份销售数据你会选哪个要是两个description看起来都像在说同一件事那触发就一定会乱。3.3 三种技能形态文档型、脚本型、模板型我接触过的skills基本可以分成三类理解这个分类有助于你想清楚自己该写哪种。文档型最简单目录里只有SKILL.md本质是一份操作规范书。AI只需要按说明输出内容不需要调脚本、不需要产模板。适合写代码审查规范周报生成格式需求分析框架这类流程性技能。脚本型带可执行文件SKILL.md里会指定运行scripts/xxx.py来生成中间产物。我写的eda-report就属于这类。这里有个关键点脚本要设计成能被模型直接调用输入输出必须是命令行参数或标准输入输出别搞成必须手动改代码才能跑的那种。我吃过亏脚本里写死了文件路径模型换了个数据文件路径就不知道该怎么调用了后来统一改成python script.py --input 路径的形式才好用。模板型则是在目录里放要产出的模板文件可能是Markdown、docx甚至LaTeX。SKILL.md负责描述怎么填模板。数学建模论文生成、AI漫剧分镜脚本这类技能特别适合模板型因为最终产出格式相对固定把模板沉淀下来能极大减少模型自由发挥的空间。3.4 写skills时最容易返工的四个错误第一个错误是没有定义输入。很多技能文档洋洋洒洒写了一大段但没说清楚用户需要提供什么。模型遇到缺信息时要么瞎猜要么卡住不执行。我现在写每个skill都会先定义输入——用user_input标记并明确缺少哪些信息时需要先向用户提问。第二个错误是缺少负面约束。只写做什么不写不做什么模型会自己发挥。比如你希望它输出结论而不是代码过程SKILL.md里必须写明。我在3.1的示例里专门写了不要输出Python代码过程这条约束才是实际使用中稳定性的核心来源。第三个错误是塞了太多一次性内容。把特定项目的文件路径、特定一次的字段名写死在skill里导致换个数据源就用不了。技能应该是可迁移的方法论具体的配置应该通过输入参数传入或者放在references里作为示例而不是硬编码。第四个错误是忽略版本说明。skills是会迭代的一开始没有version字段改了两版之后我自己都分不清哪个目录是最新的。现在我会在frontmatter里加version在目录里保持一个CHANGELOG.md改了什么写清楚。团队协作时这个习惯尤其重要不然同事还在用旧版处理流程你这边已经换了三套方案。4. 现实中该挑哪些skills用前端、数学建模、AI漫剧三类场景拆解4.1 前端开发skills把团队规范变成AI的肌肉记忆前端是skills应用最密集的领域之一。前端项目里规矩特别多组件放哪个目录、样式用Tailwind还是CSS Modules、需不需要写storybook、代码风格是函数组件还是class组件。这些规范如果全靠对话里交代每次都要重复而且换个人写可能用的还是另一套风格。我见过的前端团队技能一般就干两件事第一把项目的技术栈和目录结构写进skill让AI知道在这个项目里生成代码应该放在哪里按什么分层写第二把组件开发流程固化成步骤比如先写props类型定义再写样式文件再写基础展示逻辑最后补storybook用例。这样即使基础差的AI输出也能保持团队统一风格。有个细节值得说前端技能最好和代码库一起放进项目仓库而不是放全局。因为前端项目的规范强依赖具体技术栈你在这个ViteReact项目里写的规范放到另一个Vue项目里反而有害。把skill放进.claude/skills并随仓库提交新同学clone下来就能获得同样的AI辅助这是我认为效率最高的用法。4.2 数学建模skills从数据到论文的全流程打包数学建模这个场景是我近期看到skills社区里最热闹的方向之一特别是华为杯、国赛这类比赛期间不少人直接找现成的建模技能包。原因不难理解建模比赛流程非常标准化——读题、假设、数据预处理、模型选择、求解、结果分析、论文排版每个环节都有固定套路但又很繁琐。一个完整的数学建模skills库通常包含几个独立技能数据处理技能负责清洗和描述统计模型选型技能负责根据题目类型优化、预测、评价推荐可用模型LaTeX论文技能负责把结果输出成比赛要求的排版格式。这些技能各司其职又按顺序衔接。我在实际用过之后最大的体会是技能的价值不只是写得对更是稳定地写得对。人写论文时状态起伏AI也一样没有约束时同一份数据它能给出好几种风格不一致的结果。而建模技能把流程锁死之后每次跑出来的中间结果和论文段落格式都一致这对分块协作特别重要——让队友可以并行推进不担心最终拼不起来。4.3 AI漫剧/短剧创作skills把流程感和一致性交给AIAI漫剧是最近一段时间内容创作领域的明显趋势做漫剧的人开始用skills来沉淀分镜脚本、角色设定、画面描述的整套流程。这个领域我研究不多但看了不少别人写的素材发现skills解决的核心问题是一致性。漫剧生成最难的地方在于多张画面之间风格一致、角色一致、叙事节奏一致。纯靠自然语言对话生成两三个分镜之后风格就开始飘。而一个漫剧分镜技能会在SKILL.md里定义标准的表格结构镜头号、景别、画面描述、角色状态、对白、情绪基调。模型按这个结构输出每张分镜的信息完整度就高很多后续再做图像生成、视频生成时提示词可以直接从表格字段里组装。这种技能通常还会带上角色设定文件把主角的外貌特征、性格标签写清楚。分镜技能里明确说生成任何画面描述前必须查询references/character.md中的角色设定。这就是skills相对纯提示词的又一个优势——它可以要求模型先读取指定文件把角色设定这个记忆固定下来而不是每次靠对话上下文去猜。4.4 多skills配合时怎么避免打架当你装了十几个skills一定会遇到触发冲突。比如同时装了数据处理和数学建模EDA用户说分析这份数据时模型可能随机命中其中一个导致输出风格不稳定。我的处理办法是增加一个总控技能。它的description写得非常宽专门描述当用户提出一个完整的建模/分析任务时正文则拆解成多步明确每一步该调哪个子技能。这样模型不会在一堆平级技能之间乱选而是先进入总控流程再按流程落到具体技能上。相当于一个项目经理而不是让所有执行者都来抢活。如果不想引入总控那就必须把每个技能的description边界划清楚。比如数据清洗技能里写明仅当用户明确提到缺失值/重复值/格式统一时使用EDA报告技能里写明仅当用户需要最终报告时使用。边界越清晰模型越不容易触发错。5. 装了不生效、乱触发、拉取失败实际使用中的五个典型坑5.1 技能目录没被识别结构问题排查顺序装了没生效是出现频率最高的问题。遇到这种情况我的排查顺序基本是固定的按下面这个顺序查基本能定位先确认SKILL.md的位置方案里必须要放在技能目录的根下不能多包一层再确认frontmatter格式name和description两个字段不要写错大小写不要漏掉前面的---然后确认工具的路径把工具版本和官方文档对一遍最后确认是否重启了会话Claude Code这类工具一般不会热加载新技能。有一次我排查了半天最后发现是目录里多了一个隐藏的.DS_Store文件导致识别异常删除后一切正常这类玄学问题也值得留个心眼。5.2 一聊无关话题就触发description写得太宽乱触发是第二个高发问题根因绝大多数是description写得不够精确。我接手过一个团队技能description写的是用于数据分析结果每次用户问任何和数字相关的问题这个技能都会被加载。一次会话下来模型读了好几千字的技能说明真正处理的任务反而没占到多少上下文。修复方法就是把数据两个字改成具体的数据形态和任务信号。比如当用户上传Excel/CSV文件并希望输出可视化图表时使用缩窄了触发面误触发率立刻降下来。写完后建议跑几组负样本测试故意说一些听起来相关但实际不同的任务看模型会不会误加载这是个很好的自检手段。5.3 GitHub拉不下来或网络波动时怎么办装GitHub上的skills最常见的问题是git clone失败或者中途断掉。这和你的网络环境、仓库大小都有关系。我的备用方案很简单第一不要在人多的时候去拉那种体积很大的聚合仓库尽量用--depth 1只拉最新版本第二如果clone一直失败直接到GitHub网页进入技能目录点Download ZIP打包下载再在本地解压拷贝。还有一种更稳定的做法不直接拉别人的仓库而是把技能文件复制到自己的GitHub仓库里统一维护。这样你只需要拉一个自己维护的仓库文件来源可控更新也方便。GitHub本身的访问情况因人而异多试几个时段和下载方式一般都能解决犯不着为了下个技能折腾半天。5.4 技能文件太大导致加载后上下文不够用这是个很隐蔽的坑。SKILL.md写得再精简如果references目录里放了好几个大文件模型按要求读取后照样会把上下文撑爆。我之前写了一个素材分析技能附带了三份各一万多字的行业报告作为参考资料结果加载这个技能后用户聊几句就提示上下文超限。解决思路有三个一是精简文件把参考资料里真正会被用到的部分剪出来不要整份放进去二是拆分技能把读取参考资料和基于资料生成报告分成两个skill前者完成总结后把结果存成中间文件后者再读取中间文件三是明确指示模型只读取与当前任务相关的段落而不是全文件。这三种方法可以组合用核心原则是一个技能加载后占用的上下文不要超过整个窗口的三分之一。5.5 skills越攒越乱我常用的清理方法GitHub上那些一装装一整套的合集包用一段时间后一定会发现一半以上根本没触发过。我现在的清理思路就三条第一每次新装一个技能前先问自己这个技能是不是替代了现有技能如果是先把旧的删掉再装新的第二每两周review一次/skills列表凡是description我都说不出它具体干嘛的直接删第三项目级skills随项目删项目不做了就清空不要让它留在用户级目录里继续占用全局路由。清理的时候动作要果断。skills这东西不是越多越好模型在每个会话里都会扫描所有技能的description做路由判断装三百个技能和装三十个技能的判断负担完全不同。我自己的经验是全局技能保持在二十到三十个左右项目级技能跟着项目走这个量级下触发准确率最舒服。6. 什么时候值得维护自己的skills库筛选标准与长期使用心得6.1 值得沉淀成skills的三个判断标准跟skills打了几个月交道我最大的体会是不是所有东西都值得做成技能。花两小时写一个技能结果一个月只用一次那不如直接在对话里写提示词。我目前判断是否值得沉淀就看三条标准是不是高频、是不是稳定、是不是多步骤。高频是前提至少一周能用一次以上稳定指这套流程基本固定不会三天两头大变多步骤指任务本身包含多个判断和操作节点值得用结构化文件来约束。如果只满足前两条那一段好的提示词就够用了。三条都满足做成skills才能体现出一次封装、长期复用的价值。6.2 我的长期维护习惯按项目隔离定期review我现在维护技能的载体就是Git仓库所有全局skills放在一个单独的repo里内部按类型建目录。每次改动都会顺手更新CHANGELOG并标注哪些技能加了新步骤、哪些修了触发条件。这样做有个额外的好处就是多台机器之间可以轻松同步——把仓库拉下来链接到用户级skills目录就完成环境迁移了。项目级技能我一定会提交到项目仓库里而不是留在本机。这样做对团队协作的价值太明显了新同事clone项目之后AI自动知道这个项目的代码规范、目录结构、测试要求他不需要翻半天文档就能让AI产出符合团队风格的代码。目前我的项目文档也逐步考虑写进技能因为AI读取技能的条件反射比人翻文档快得多。6.3 最后再分享一个实用小技巧最后说一个我近期用得很顺的小技巧把那些每次开始任务都要说的开场白也做成一个轻量技能。比如我自己有一个task-brief技能description写的是当用户开始一个新任务但没有提供完整背景时使用正文要求AI先主动补齐五个关键信息——目标、输入、输出格式、约束条件、验收标准。以前每次开新任务我得自己把背景交代得很完整不然AI容易做偏现在它学会了先问清楚再动手省下来的返工时间相当可观。这个技巧的本质是把好的提问方式也沉淀成技能。你会发现skills不仅能约束AI的行为模式还能反过来约束你自己的任务表达习惯。当你和AI都按同一套结构化框架协作时产出的稳定性和效率都会上一个台阶。如果你还在纠结第一个技能写什么不妨就从让AI学会先问清需求开始这是投入产出比最高的一步。