GitHub Skills 实战：为 AI 编程助手打造可插拔的能力包

GitHub 上的“Skills”这几年被玩出了新花样尤其是在 AI 编程助手圈子里这个词已经不完全是我们常说的“技能栈”或者“软技能”了。现在很多人聊的 skills指的是给 Claude Code、Codex、OpenCode 这类工具装上的一种“外挂能力包”——让 AI 不只是能聊天还能直接调用某个领域的完整方法论、工作流甚至帮你干完一整条流水线的活。我最早接触这个玩法也是一脸懵GitHub 上一搜 skills出来的仓库几百个有的叫 superpowers有的叫 codex-skills有的叫 cola根本分不清谁是谁。后来自己装了几个、也手写了不少才算理清楚这套东西的门道。这篇文章我就从一个实际动手折腾过的人角度把“skills 到底是什么、怎么装、怎么写、怎么用”完整拆开讲一遍。适合想给 AI 编程工具提效的开发者也适合正在准备数学建模、AI 漫剧这类特定场景项目、想用 skills 把重复劳动压缩掉的朋友。1. 先搞懂 skills 到底是什么别把概念玩混了1.1 Skills 的本质是一份“可复用的能力说明书”先说人话一个 skill 本质上就是一个文件夹里面有一份SKILL.md文件作为入口配上一些参考文档、代码模板、脚本甚至是一整套操作规范。AI 编程助手在执行任务的时候会根据你写的提示词自动去匹配这个 skill然后按照里面的说明来“调取相关知识、按步骤干活”。你可以把它理解成给 AI 写了一份工作手册。平时你让 AI 帮你写一个 React 组件它靠的是预训练的通用知识但你让它“按照公司前端规范、用某个组件库、带测试和 Storybook 文档”地完成一整个需求通用知识就不够用了。而 skill 做的事情就是把“公司规范 组件库用法 测试要求 文档格式”全部封装进一个文件里AI 一旦命中这个 skill就会按你写的流程来执行。从安装形态上看主流的 AI 编程工具都支持通过“项目目录下的.claude/skills、.codex/skills或者.opencode/skills”这种隐式约定来加载。你从 GitHub 上把别人做好的仓库 clone 下来放进对应目录重启工具就装好了。部分工具还支持通过命令行/skills直接查看和切换已安装的技能相当于给 AI 助手做了一次“能力插拔”。1.2 它和 prompt、插件、MCP 有什么区别很多人一上来就会问skills 不就是个提示词吗我自己在 prompt 里写一段话也能达到类似效果凭什么要单独搞个文件夹。差别其实挺大的。Prompt 是“一次性”的。你写进 conversation 窗口里的提示词AI 看得到但它往往只在那一次对话里起作用而且对话一长、上下文一挤这些规则就容易被冲淡。而 skills 有更稳定的“视野”它是在项目上下文层面被加载的AI 在规划任务的时候就能感知到“这里有对应的 skill 可用”。两者像什么呢Prompt 是你在开会前给临时工口头交代了两句skills 是你给正式员工发了一本员工手册前者靠脑子记后者靠制度管。插件和 MCP 解决的是“AI 能不能调用外部工具”比如读数据库、调 API、操作浏览器。而 skill 解决的是“AI 知不知道活儿该怎么干、按什么标准干”。一个是手脚一个是大脑里的知识库和流程库。实际项目中两者互补但如果你只是想约束 AI 的输出质量和流程skills 往往是最轻量、门槛最低的方案。1.3 为什么最近这东西突然火了以前我们调教 AI 全靠“在世界里写规则”要么写一大段 system prompt要么把工作流塞进项目文档。但这样做有两个问题一是项目一复杂这些规则就和业务代码混在一起、维护成本很高二是不同的项目往往需要不同的规则把全部规则塞进一个 prompt 里又臭又长、还互相干扰。skills 之所以能火起来是因为它把“规则”做成了模块化、可插拔、可分享的东西。你想让 AI 帮你做前端开发就装一个前端 superpower你要参加华为杯数学建模就装一个建模专用 skills 包你在做 AI 漫剧就装一个漫剧分镜脚本生成技能。写完一个高质量的 skill还能传到 GitHub 上让整个社区复用这很像当年“Vim 插件化”或者“VS Code 扩展生态”走过的路——一旦形成“库”生态就活了。2. 怎么手动安装 GitHub 上的 skills三种主流工具都给你捋一遍2.1 Claude Code 的手动安装路径我先说 Claude Code因为它的生态现在最完整GitHub 上的很多 skills 也都是优先适配它的。安装的核心动作就是把仓库内容复制到指定目录具体路径是~/.claude/skills/不同项目也可以放在项目的.claude/skills/目录下这样只有当前项目能用到适合团队内部共享规范。从 GitHub 手动装一个 skill 的流程我建议这样来# 1. 找到目标仓库比如 tibo 的清理技能库 git clone https://github.com/xxx/skills-repo.git # 2. 进入仓库看它的目录结构 cd skills-repo ls -la # 3. 找到真正包含 SKILL.md 的那个文件夹 # 假设它叫 cleanup-skill复制到 Claude 的全局 skills 目录 cp -r cleanup-skill ~/.claude/skills/ # 4. 重启 Claude Code输入 /skills 查看是否加载成功有几点实际操作中很容易踩坑我单独拎出来说别把整个仓库一股脑全复制过去。很多仓库是“全家桶”里面包含几十个 skill全部复制进去会导致每次 AI 做意图识别的时候开销变大、甚至出现多个 skill 互相抢优先级的情况。我一般只挑当前真正用得上的。注意仓库内如果还有嵌套的skills/子目录复制的时候要把那一层结构保留好只复制最外层包含SKILL.md的目录再往下的子目录不要动AI 需要按相对路径去读取附件。装完之后一定要重启终端或者重启 AI 会话这个动作经常被忽略结果装完了半天实际没生效然后就开始怀疑人生。Claude Code 对 skills 目录的扫描是启动时做的不重启就不会刷新。2.2 Codex 和 OpenCode 的安装方式Codex主要指 OpenAI 的 Codex CLI 工具现在也有自己的 skills 支持。它的思路是把 skills 放在~/.codex/skills/目录下然后在config.toml里声明启用。安装命令差不多只是目标目录换成cp -r xxx-skill ~/.codex/skills/然后编辑配置文件[skills] enabled true注意 Codex 的 skills 规范目前和 Claude Code 大体相似但部分 frontmatter 字段有细微差别比如有的工具认name、有的要allowed-tools。安装前最好看一眼仓库 README 里写没写“Compatible with Codex”之类的说明不然装进去可能识别不了。OpenCode 是另一个很受命令行爱好者欢迎的 AI 编码工具它的 skills 目录一般在~/.opencode/skills/也支持项目级的.opencode/skills/。OpenCode 的优势在于配置文件比较直白装完之后直接在 TUI 里用/skills就能触发选择器体验很流畅。2.3 装完之后先做“冒烟测试”不管用哪个工具我强烈建议装完 skill 后先做一次冒烟测试不要直接一头扎进正式任务里。测试方法很简单打开你的 AI 工具输入类似“请列出你现在可用的 skills并说明每个 skill 的适用场景”的指令看它能不能准确说出刚装的那个技能。如果它说不出来别急着怀疑 skill 本身有问题先检查这几个地方路径是不是放对了大小写有没有写错目录名是不是和 SKILL.md 里的name字段对应终端是不是重启过了如果是团队项目是不是被项目级的.gitignore把 skills 目录排除了我经历过最无语的一次就是把 skill 放在了~/.calude/skills/这种手误路径下结果 AI 一直加载不到排查了快二十分钟才发现是拼写错了。3. 手把手教你写一个自己的 skills前端、建模、漫剧场景通吃3.1 SKILL.md 的结构与 frontmatter 写法写一个 skill 没有想象中那么难核心就是写好SKILL.md。这个文件由两部分组成YAML frontmatter和Markdown 正文。Frontmatter 是文件的“元信息”我们拿一个最简单的例子来看--- name: frontend-review description: 用于前端代码审查专注于 React 组件性能优化和可维护性。当用户要求 review 前端代码或优化组件性能时使用。 ---name是技能的唯一标识description必须在开头就写清楚触发条件因为 AI 主要就是靠读 description 来决定要不要调用这个 skill 的。很多人写 description 写得太模糊比如“用于前端开发”结果 AI 在几乎所有任务里都想用它互相打架效果反而差。正文部分用中文或英文写皆可但结构一定要清晰。我习惯的分段方式是背景与目标→核心原则→执行流程→输出规范→参考示例。前面两段是告诉 AI“为什么存在这个技能”中间是“怎么干”后面是“干完要交什么活”。这里有个很关键的细节SKILL.md 尽量不要写成一本“百科全书”信息量太大会导致 AI 读取的时候吃掉大量上下文。正确做法是正文里只写精炼的操作规范和流程把真正的大块头内容比如设计规范 PDF、模板代码、数据字典放到同目录下的附件的文件里在 SKILL.md 里用相对路径引用。AI 只有在需要的时候才会去读取附件这样可以省下大量 token。3.2 一个数学建模 skill 的实际拆解华为杯、国赛这类数学建模比赛其实非常适合用 skills 来提效。很多参赛队其实没意识到建模工作流里有大量“套路化”的环节数据预处理、探索性分析、模型选型、论文排版这些几乎每道题都要做一遍。把这些环节沉淀成一个 skill比赛的时候就能省下大量时间。我参考社区里比较受欢迎的数学建模 skills 包给一个最小可用结构math-modeling-skill/ ├── SKILL.md ├── templates/ │ ├── paper_template.md │ └── code_template.py └── references/ ├── model_selection.md └── data_checklist.mdSKILL.md里我会写明拿到一道建模题后第一步做数据清洗与缺失值检查、第二步做探索性可视化、第三步按题目类型评价类、预测类、优化类选择模型、第四步按模板撰写论文。这样 AI 就不需要“临场发挥”而是像一个熟练的队员一样知道整个流程的先后顺序。3.3 前端开发和 AI 漫剧场景的 skills 怎么写前端方向社区里最有名的思路之一是“superpower skills”它强调的是把各种前端工程化的最佳实践拆成你可以直接给 AI 用的能力模块。比如我写过一个用于 React 性能优化的 skilldescription写的是“当用户想要优化 React 组件渲染性能时使用重点解决重复渲染、useEffect 依赖错误、大列表渲染卡顿问题”。正文里整理了 React.memo 的使用边界、useCallback 和 useMemo 的适用场景、React Profiler 的分析步骤。实测下来AI 在接这类优化任务时输出变得非常稳定不会东扯一句西扯一句。AI 漫剧的 skills 就更有意思了。漫剧制作本身是一条完整流水线剧本创作、分镜脚本、角色设定、画面提示词生成、配音文案、后期剪辑建议。哪怕是一个人在家做漫剧也得把这几个环节全部跑一遍。把这些环节写进一个 skill 之后你只需要说出故事梗概AI 会按照 skill 里的流程一步接一步输出省去了反复“引导 AI 理解业务”的时间。这种 skills 的核心是把“工作流”这种隐性知识显性化它带来的效率提升往往是倍数级的。3.4 写 skill 时最容易犯的四个错误第一description 写得像“简历”。我见过有人写“这是一个功能强大的技能可以帮助用户解决很多问题”没有任何实际触发词。AI 不是人它不会去猜你的意思它只看关键词匹配。写清楚触发条件什么场景下用比写一百句赞美词都强。第二一切都要 AI “自由发挥”。skill 是用来约束 AI 行为的不是用来放飞它的。你写“请做出好看的视觉设计”这种话就等于没写AI 依然会凭感觉来。比较好的做法是给明确标准比如“正文字号不小于 14px、按钮圆角 8px、主色 #2563eb”。第三附件引用路径写错。我踩过一次在 SKILL.md 里写了./attachments/report_template.docx结果实际目录叫attachments/文件在templates/下AI 根本读不到附件最后输出一份没按模板来的报告前功尽弃。写完路径一定要自己验证一遍。第四不考虑“上下文预算”。SKILL.md 里放一个 10 万字符的 PDF 规范文档AI 每次调用都要读结果对话还没进入正题上下文窗口就快满了。正确做法是规范文档作为附件按需调用SKILL.md 本身保持精炼。4. 常用 skills 推荐清单前端、建模、清理、漫剧一次给你配齐4.1 前端开发场景superpower skills 和 typesafe ai skills前端领域现在口碑比较稳的两个仓库一个是superpower skills一个是type-safe ai skills。前者主打“给 AI 装配超级工作流”里面包含 React、Next.js、样式系统、状态管理等多个细分技能包后者则更偏向 TypeScript 工程化包含类型安全、API 设计约束、代码审查规范等。我的建议是不要全套照搬而是按需摘取。比如我只需要前端 review 能力就从 superpower 里把frontend-review那个目录拿过来单独安装。这样既不影响其他任务的意图识别又能精准控制 AI 的行为。4.2 数学建模场景几个高校团队维护的高质量技能包每年华为杯前后GitHub 上都会出现一批数学建模 skills 仓库大多是往年参赛的学生团队把自己备赛过程沉淀下来的。内容包括数据预处理模板、常用模型对照表回归、分类、聚类、时间序列、论文写作框架等。这些仓库的普遍特点是“实战性强”因为作者是真的拿它们在比赛里验证过的。不过坑也比较多很多仓库是临时建来交作业的质量参差不齐。挑选的时候我建议看三个点一是看更新时间尽量选最近三个月内还在维护的二是看 README 里有没有配使用说明和示例输出配了的说明作者认真三是看 SKILL.md 的 description 写没写清楚触发场景写着“适用于各种建模任务”的基本可以先跳过。4.3 系统清理和杂物管理tibo 的清理方法论热词里提到的“tibo 关于清理 skills 的方法推荐”指的是一位叫 tibo 的开发者做的一套“系统清理与文件整理”技能包。它的核心思想不是简单地“删除垃圾文件”而是按照“识别 → 分类 → 处置”的流程把电脑里的冗余文件、重复下载、临时缓存统一治理。我装过这套技能里面最有价值的一个子技能是“项目目录瘦身”它会让 AI 先扫描项目里的大文件、node_modules 磁盘占用、日志堆积情况再给出清理建议。相比自己手动清理这个技能最大的好处是“有章法”AI 会先生成报告让你确认再进行删除操作不会误伤重要文件。4.4 AI 漫剧和视频创作方向的技能包漫剧类 skills 相对小众但做的人输出的东西往往很实用。常见的子技能包括分镜脚本生成按景别、时长、台词、画面描述列成表格、角色一致性设定记录角色外貌特征、服装、性格关键词保证后续画面提示词的连贯性、画面提示词排版针对 Midjourney 或 SD 的正向负向提示词模板。这类技能包装完之后最大的感受是“AI 的产出终于不是黑箱了”。以前让它生成漫剧脚本经常东一榔头西一棒槌装上分镜生成技能后它会一步步给你场景表、镜头表、台词表后续做视频剪辑时只需要照着表格执行就行。5. 常见问题与排查技巧实录5.1 装了 skills 但 AI 完全没反应先检查这四点这个问题我在社区里被问过无数次自己也踩过。经验下来百分之九十的情况出在四个地方一是目录位置不对。不同工具有不同的默认目录最常见的是把 Claude Code 的 skills 装到了 Codex 的目录里两边各自认各自的装错自然无效。二是 SKILL.md 文件名大小写不对。Linux 和 macOS 的文件系统默认区分大小写skill.md和SKILL.md是两个文件。AI 解析器找的是标准命名名字不对就直接忽略了。三是 AI 工具没有重启。前面反复强调过这部分不能再多说了就是不重启等于白装。四是描述触发词和你的任务描述不匹配。比如你的 skill 描述里写的触发词是“前端代码审查”你实际对话时说“帮我看看这段代码”AI 没有建立起关联自然不调用。改进方式是在描述里多写几个同义触发词。5.2 多个 skills 互相打架怎么办当你装了几十个 skills 之后会遇到一个新问题AI 觉得好几个技能都能处理当前任务结果同时启用了输出风格混乱、规则互相冲突。这个问题的根源不是 AI 笨是技能之间的边界没划清楚。解决思路有两个方向。第一个方向是从源头控制数量只保留当前项目真正需要的技能把暂时用不到的移出目录。第二个方向是优化每个 skill 的 description强化“什么时候不该用”。比如某个专用技能描述里可以写明“仅当用户明确要求执行 XX 操作时使用其他通用代码任务请勿调用”。5.3 我在实际使用中的一点体会最后说点掏心窝的话。Skills 这个东西的门槛真的不高哪怕你完全不懂编程也能按照模板写出一份像模像样的 SKILL.md。但它的上限很高高到你给 AI 定义的能力边界越清晰、工作流越完整AI 产出的稳定性就越强。这就像带新人——你只丢给他一句话他做事全靠猜你给他一套 SOP、几个模板、几条红线他交付的水平立刻就不一样了。我个人现在工作里的习惯是每次完成一个有点重复性的任务就顺手把它沉淀成一个 skill 存起来。一个月下来等于给自己攒了一个懂行的 AI 专属助手团队。这种积累的感觉很好推荐你也试试。不用追求一次写得多完美从 15 分钟的“小技能”开始慢慢迭代你会看到自己的 AI 工具越来越好用。