最近群里聊得最凶的一个词就是“skills”不是传统简历上的那种技能而是AI编程助手里的“技能包”。Claude Code、Codex、OpenCode这些工具陆续都支持了skills机制GitHub上冒出一堆技能库有人用它跑数学建模有人拿它做前端开发还有人靠它批量生成AI漫剧脚本。我花了两周时间把主流平台的skills安装、编写、排错全部过了一遍这篇就把完整路线整理出来从零讲清楚它到底是什么、怎么装、怎么写以及踩过的坑。这个内容适合正在用Claude Code或Codex、想给AI助手扩展能力的人也适合准备参加数学建模竞赛、想搭一套自动化工具链的学生。不夸张地说skills是2025年AI Agent领域最值得花时间研究的一层抽象搞懂它你就从“只会聊天的AI”进化到了“能指挥干活的外包团队”。1. 先搞清楚AI skills到底是什么1.1 从一个命令说起如果你用过Claude Code一定见过类似这样的界面——输入框下面有几条命令比如/init、/review、/compile这些其实就是一个最简单的skill形态把一段固定的指令、一套固定的检查流程打包成一个斜杠命令。当我们说“装一个skill”本质上就是往AI的工作目录里塞一个文件夹里面放上说明文档和脚本让AI在特定任务时按这套流程执行。我拿一个实际场景说明白这事。以前你让Claude Code写个前端页面它可能会自由发挥有时候给你Tailwind有时候给你纯CSS风格完全随缘。但如果你装了一个frontend-dev的skill它会自动遵守你预定义的规范必须用TypeScript、必须走组件化、必须加响应式断点、代码完成后必须自查。AI还是那个AI但它的行为被一套“专家规则”约束住了输出质量一下就稳了。1.2 skills和普通prompt的区别很多人觉得skill不就是个复杂点的prompt吗表面看确实像但实质差很远。普通prompt是一次性的对话指令你每次都要重新解释需求skill则是一个可复用、可版本管理、可共享的工作流单元。它有固定的目录结构有SKILL.md作为入口说明可以挂脚本、挂参考文档、挂模板文件。它带来的是一种工程化的能力沉淀——你上个月调出来的最优工作流可以打包成skill让团队所有人直接复用。我见过一个最典型的场景是数学建模。华为杯、美赛这些比赛三个人组队一个人负责建模一个人写代码一个人写论文但AI辅助的时候经常出现一个问题每个队员都用自己的一套prompt去问AI出来的结果五花八门。后来有人把完整的建模流程——从问题分析、假设建立、模型选择、代码实现到论文排版——封装成一组Codex skills全队统一调用AI的输出一致性立刻提升了一个档次。1.3 一个skill的标准结构以Claude Code和Codex兼容的规范为例一个最简skill长这样my-skill/ ├── SKILL.md # 技能说明AI读取的核心入口 ├── scripts/ # 可选辅助脚本 │ └── check.py └── references/ # 可选参考资料、模板 └── template.mdSKILL.md里面用YAML头信息声明技能名称和描述正文写具体的执行步骤、规则约束、输出格式。AI在收到任务时会通过描述判断“这个任务是否匹配该技能”匹配了才加载不匹配就忽略。提示SKILL.md的名字是严格的不能改成README.md或skill.mdAI代理主要按这个名字索引。我第一次写的时候就因为文件名不规范折腾了半天没生效。2. 手动安装GitHub上的skills完整实操2.1 安装前先确认三件事GitHub上现在有大量现成的skills仓库但不同平台的skill格式不一定互通。动手安装之前先确认三件事不然白费力气。第一确认目标平台的skills规范和加载路径。Claude Code的skills一般放在.claude/skills/目录下Codex则通常读.codex/skills/或通过配置指定OpenCode的路径又不一样。第二确认skill仓库的目录结构——有的仓库本身就是单个skill直接clone下来就能用有的是聚合仓库下面几十个skill子目录你需要挑着复制。第三确认SKILL.md里的frontmatter格式——Claude Code的规范是name和description字段Codex有的版本要求name、description外加version格式不兼容的skill就算复制进去也不会被识别。我自己踩过最典型的一个坑GitHub上有个热门的codex-nature-skills仓库里面很多skill是按Codex早期规范写的SKILL.md头部没有version字段。我把它原样复制到Claude Code里结果完全不生效。后来逐行对比官方示例才发现两家的frontmatter字段要求不一样。所以安装前花两分钟看一下仓库说明文件里的兼容性声明比闷头复制靠谱得多。2.2 Claude Code手动安装步骤手动安装其实就四步但每一步都有细节。以把一个叫modeling-competition的数学建模skill装到Claude Code为例第一步clone仓库到本地临时目录git clone https://github.com/example/modeling-competition.git第二步找到项目中的.claude/skills/目录。有些仓库把skills放在根目录的skills/文件夹里有些放在.claude/skills/下以仓库实际结构为准。打开目录看一下确认里面是SKILL.md还是又一个嵌套目录。第三步复制到Claude Code的全局skills目录。macOS和Linux在这里cp -r modeling-competition ~/.claude/skills/modeling-competitionWindows则在%USERPROFILE%\.claude\skills\下。如果你只想给某个特定项目用就放在项目的.claude/skills/里效果是只在该项目下生效。第四步重启Claude Code会话输入/skills或者直接问“你现在有哪些可用技能”确认skill已经被索引。没有出现的话八成是路径错了或者frontmatter格式不对。2.3 Codex和OpenCode的装法Codex这边稍微有点不一样。新版Codex CLI支持从~/.codex/skills/目录加载本地skills也会自动读取项目的.codex/skills/。装法和Claude Code大同小异但有个特别实用的功能——某些版本的Codex支持直接从GitHub URL安装codex skills add https://github.com/example/modeling-competition如果你用的Codex版本不支持这条命令就老老实实走clone复制路线。OpenCode则把skills统一放在~/.config/opencode/skills/目录下逻辑上跟前面两者一致只是路径不同。再说一句关于“skills下载”的常见困惑。很多人在网上搜索“skills网页版进入”“skills技能库网址”其实是想找一个在线面板来管理技能。目前主流平台都没有成熟的可视化管理界面最多也就是命令行里列个清单。我建议把skills当代码仓库管理用Git来维护版本更新、回滚都方便比等官方出面板靠谱得多。3. 值得安装的skill推荐清单3.1 前端开发的几个神级技能前端开发是skills生态里最成熟的方向之一。GitHub上搜索frontend skills能出来一堆仓库但质量参差不齐。我实测下来值得装的有三类。第一类是项目脚手架类skill它会把新项目的初始化流程固定下来——自动问你项目类型、选技术栈、生成目录结构、装依赖、配好ESLint和Prettier。以前新建一个项目要手动敲十几条命令现在一句话“按标准流程初始化一个ReactTS项目”skill会自动执行完所有步骤还顺手帮你把README和.gitignore都建好。第二类是UI审查类skill。这个是我最近才发现的宝藏它会截图或者读取页面代码按可访问性、响应式、视觉一致性、性能指标几个维度做代码审查输出一份带优先级的问题清单。强烈建议前端团队统一装一个代码评审的时候能省大量扯皮时间。第三类是组件生成类skill用来保证组件代码风格一致。比如规定所有组件必须用函数式写法、props必须写类型定义、样式必须走CSS Modules而不是全局类名。装了之后AI生成的代码会自动遵守团队规范新人写出来的东西也不会跑偏。3.2 数学建模和竞赛向的skills华为杯、美赛、国赛这几年的AI辅助趋势非常明显。GitHub上已经出现了专为数学建模设计的skills仓库最有代表性的是把完整竞赛流程拆成多个协作型skills的组合包。我实测过一个组合它包含四个skillproblem-analysis负责把赛题拆解成约束条件、目标函数和数据特征model-selection根据问题类型推荐合适的数学模型并给出理由code-implementation把模型转成可运行的Python代码自动补全数据预处理和结果可视化paper-writing则按照数模论文的标准结构生成LaTeX或Word模板把图表、公式、参考文献的格式都预先排好。用了这套skill之后最大的变化不是AI写代码更快了而是团队的思考过程被结构化了。以前三个人对题目理解不一样讨论半天现在每个人都用同一套skill去分析题目输出的问题拆解结构是完全一致的讨论效率明显提升。对准备华为杯的同学来说提前把这类skills跑通比赛期间确实能节省大量时间。3.3 AI漫剧、内容创作类skills别以为skills只能写代码内容创作方向也已经有不少现成作品。AI漫剧这个热词背后其实也是一套skills用AI生成分镜脚本、角色设定、提示词再配合绘画模型出图。GitHub上有人把整套工作流封装成了skill包括分镜模板、人物一致性描述模板、场景切换规则等等。这类skill的核心逻辑是把“感觉”变成“规则”。一个漫剧创作者靠感觉描述分镜每次输出的风格都飘忽不定但一个well-crafted的skill会把镜头语言、叙事节奏、人物表情描述都结构化AI每次生成的内容就更可控。内容团队如果想批量生产短视频脚本同样可以做一个short-video-script的skill把开头三秒抓眼球、中间反转、结尾引导关注的套路全部写进规则里。4. 从零手写一个自己的skill4.1 先想清楚四个问题再动手写skill最大的误区是一上来就写SKILL.md。我自己的经验是先花时间回答四个问题这个skill是给谁用的解决什么具体问题触发场景是什么期望的输出长什么样以我写的一个daily-standupskill为例——它让AI每天读取Git提交记录自动生成站会汇报。定义目标时我写的是“减少团队站会准备时间统一汇报格式”触发场景是每天早上技术团队开工时风险点是“AI可能误读提交信息导致汇报失真”。这四个问题想清楚之后写SKILL.md就是水到渠成的事。这里有个特别重要的设计原则skill的适用范围宁窄勿宽。很多人写skill恨不得囊括所有场景结果AI什么任务都往这个skill里套输出反而更难用。好的skill就像一个好的函数——单一职责、输入输出清晰。4.2 SKILL.md的写法细节SKILL.md分两部分YAML frontmatter和正文。frontmatter核心就是name和description两个字段其中description决定了AI什么时候调用这个skill一定要写清楚“适用于什么任务、不适用于什么任务”。下面是一个可参考的最简模板--- name: daily-standup description: 读取Git提交记录生成站会汇报。适用于团队日常站会场景不适用于代码审查。 --- # Daily Standup Skill ## 职责 - 读取最近24小时的git提交记录 - 按团队成员分组整理工作内容 - 标注阻塞项和风险点 ## 执行步骤 1. 运行 git log --since24 hours ago --prettyformat:%an|%s 2. 解析提交人、提交信息 3. 归类整理为进行中、已完成、阻塞项 4. 输出Markdown格式站会汇报 ## 输出格式 markdown ### 今日站会日期 **进行中**... **已完成**... **风险/阻塞**...写正文时要注意指令的粒度。AI理解能力已经很强但给它的步骤越明确执行结果越稳定。我习惯把所有步骤写成“动作命令预期结果”三段式比如“运行git log获取提交记录解析其中的人名和提交说明字段输出分组列表”。这样AI不会为了“创意”去过度发挥。 ### 4.3 scripts和references怎么组织 当skill需要执行复杂逻辑、处理文件、调用API时把逻辑写进脚本而不是让AI现场发挥。一个常见方案是scripts/目录下放Python或Shell脚本SKILL.md里只写“运行scripts/analyze.py并读取输出”。 我自己的习惯是一切有固定逻辑的操作都尽量脚本化。比如解析数据、调用外部API、批量重命名文件这些事AI现场写代码也许能完成但每次风格都不一样而且容易出错写成固定脚本放进skill里每次执行结果都是一致且可预测的。references/目录则用来放参考资料和模板比如论文模板、代码规范文档、常见错误列表。AI在执行skill的时候会按需读取这些内容等于给它配了一本操作手册。 ## 5. 常见问题与排查技巧实录 ### 5.1 装了skill但不生效怎么排查 这是被问得最多的问题。装完skill没反应90%是三个原因。第一是路径放错了skill目录层级不对AI根本没扫描到第二是frontmatter格式有问题description字段缺失或者不是字符串格式第三是会话没有重启AI没有重新索引技能列表。 按这个顺序排查最快先用官方命令列出已加载的skills比如Claude Code输入/skillsCodex用codex skills list。如果列表里压根没这个skill就是路径或格式问题检查目录名、检查YAML格式是否合法。如果列表里有但行为上没生效问题多半出在description写得不够准确AI判断这个任务和skill不匹配所以不调用。这时候要重新打磨description里的触发条件描述。 ### 5.2 skill打架了怎么办 多个skill同时匹配同一个任务的情况很常见。比如你有frontend-dev和react-component两个skill让AI写一个React组件的时候两个都可能被触发结果AI一会儿遵守这个的规则一会儿遵守那个的输出行为不稳定。 解决办法是给skill限定明确的边界。在description里写明触发条件比如react-component专门负责“单个组件文件的新建与修改”frontend-dev负责“整个前端项目的规划和架构”。这样重叠区域缩小AI的匹配也更精准。实在有冲突就删掉一个别舍不得。 ### 5.3 清理和瘦身的实用方法 GitHub上调研热词的时候看到有人专门讨论“清理skills的方法”这确实是个被忽视的痛点。装了几十个skill后每次AI加载时都要花时间扫描索引响应变慢是一方面更重要的是AI的选择困难症会加重——候选skill越多越容易匹配错。 我的清理策略是定期收编。每个月把那些一次都没被触发过的skill挑出来要么删掉要么把多个同类的合并成一个聚合skill。还有一个实用习惯全局skills目录只放通用性强的项目级的就放在对应项目的.claude/skills/或.codex/skills/里互不污染。Claude Code里可以直接rm -rf不想要的skill目录但推荐先把它移到备份目录观察两周确认不影响日常工作再彻底删除。 ## 6. 一些关于skills生态的个人观察 研究skills的这两周我最大的感受是这个机制把“AI提示工程”从聊天记录里解放了出来变成了可版本管理、可分发、可协作的工程资产。坏处是GitHub上技能库的质量鱼龙混杂很多skill就是把几个大而全的prompt塞进去既没有清晰的触发边界也没有可复用的脚本装多了反而拖累效率。 我个人在实际操作中的体会是与其追逐热门skills列表不如把这个机制当成一套优化自己工作流的框架。你日常反复在做的事情——做周报、搭项目、写脚本、跑分析——都可以先手动把流程跑顺再固化成一个skill。自己在真实场景里打磨出来的skill永远比网上下载的通用包好用。 另外一个小技巧分享给刚开始接触的人去翻一下你现在主力AI工具的官方文档里关于skills的章节不同版本之间的规范差异比想象中大社区里很多教程都是基于旧版本写的照着操作很可能对不上。官方文档通常很短但会写清楚路径、格式、版本要求花二十分钟过一遍能省掉之后几个小时的折腾。 最后说句实在的skills这个方向还在快速演进今天写的规范可能过俩月就变了。但核心思想——把AI的能力调用标准化、产品化——是不会变的。早点上手等到生态成熟的时候你已经积累了一堆趁手的技能包跑在很多人前面了。
