Skills实战手册：AI编程能力包的安装、编写与应用

最近这半年只要你玩命令行 AI 编程工具八成躲不开一个词skills。Claude Code、Codex、OpenCode 陆续把 Skills 做成官方能力之后GitHub 上一夜之间冒出来一大堆 skills 仓库从 superpower skills 到各种场景合集前端开发、数学建模、AI 漫剧全都有人在做。说白了Skills 就是把“怎么完成一类任务”的经验打包成一个 AI 能自动读取、自动调用的文件夹。这篇文章我不讲虚的直接从我自己的使用经历出发把 Skills 是什么、怎么从 GitHub 手动装、怎么挑怎么用、怎么写自己的、以及装多了以后怎么清理一步步讲清楚。不管你是用 Claude Code 写业务代码还是备战华为杯这类建模比赛又或者在做 AI 漫剧流水线这篇都能帮你少走弯路。1. Skills到底是什么先把概念吃透1.1 一个文件夹 一个 SKILL.md 一份可复用的能力在 Claude Code 里一个 Skill 的物理形态特别简单一个文件夹文件夹的根目录下放一个SKILL.md文件下面还可以带脚本、模板、参考资料。比如my-skill/ ├── SKILL.md ├── scripts/ │ └── check_format.py └── reference/ └── style-guide.mdSKILL.md 是核心开头有一段 YAML 格式的元信息然后是正文。大致长这样--- name: code-review description: 当用户要求 review 代码、检查 PR 时使用用于系统性审查代码质量。 --- # 代码审查 ## 审查步骤 1. ... 2. ... ## 输出模板 ...当你在项目里和 Claude Code 对话时它会根据 description 判断“现在这个任务是不是该调用某个 skill”命中就自动读入 SKILL.md 里的指令按你写好的流程执行。这里有个很关键的细节不要把 description 写成“这是用来做代码审查的技能”而要写成“当用户要求 review 代码、检查 PR 时使用”。因为模型是靠 description 做“什么时候该用”的匹配描述里写清楚触发场景比写清楚功能重要得多。这一点我后面还会反复强调。1.2 Skills、提示词、MCP 到底啥区别很多人刚接触的时候会把三者搞混我当初也迷糊过。简单说提示词Prompt是一次性的话。你复制一段长文本给 AI它按这次对话内容执行换一个项目就得再复制一次而且越长越容易让模型“忘记”重点。Skills 是结构化的能力包。AI 自动判断何时加载里面有说明、有步骤、甚至能跑脚本是可复用、可分享、甚至可版本管理的。MCP 是一种让 AI 连接外部工具和数据源的协议。Skill 解决的是“做事的方法”MCP 解决的是“能碰到的资源”。比如一个数据库 MCP 让 AI 能查表一个 SQL 审查 Skill 让 AI 知道怎么审查你写出来的 SQL。理解了这个区别你就知道为什么社区会突然把 skills 捧得这么高。它把以前散落在各种“提示词合集文档”里的经验变成了一种可以被 AI 自己调度的文件这其实是在往“沉淀专家工作流”的方向走。我自己的体会是装几个好 skill 比在系统提示词里塞几千字说明管用得多。1.3 社区里这些 skills 仓库都在解决什么问题GitHub 上现在流行两个方向。一个方向是“通用工作流”代表作就是 superpower skills社区里有人叫它“超能力技能包”里面是一整套 brainstorming、planning、TDD、debugging 之类的工作流技能本质是把优秀工程师的做事顺序教给 AI。另一个方向是“场景专用包”比如前端开发、数学建模、AI 漫剧这些垂直领域有人把选型经验、代码风格、输出模板全塞进 skill 里。还有像 typesafe-ai 这类团队维护的仓库偏工程化做 TypeScript 全栈的人可以留意。再就是各种“合集站”有人把多个仓库的 skill 整理成索引网页方便浏览、挑着下载。热搜里那个“skills网页版”指的就是这个——不用命令行逐个翻仓库直接在网页上看 description选中后手动下载对应文件夹。另外像 cola、nature 这类以作者或团队命名的垂直合集也有人在维护质量高低全看维护频率用之前一定打开 SKILL.md 亲自读一遍。想系统学习 skills 的话我的建议很直接读十个高质量 SKILL.md 比搜一百篇教程有用。官方示例仓库是入门必读superpowers 里的技能文件是进阶教材拆解它们怎么写 description、怎么组织步骤比你到处找“skills 教程”效率高得多。2. 从GitHub手动装Skills照着做就行2.1 先搞清楚该装到哪个目录拿 Claude Code 举例skill 有两个存放位置用户级全局~/.claude/skills/所有项目都能用。适合通用技能比如代码审查、写提交信息、整理 CHANGELOG。项目级局部项目根目录/.claude/skills/只有当前项目能用。适合绑定项目技术栈、目录结构和约定。Codex 的规则也差不多默认位置是~/.codex/skills/项目级可以放项目根/.codex/skills/OpenCode 的机制还在快速迭代不同版本装法差异比较大建议以对应仓库的 README 为准核心思路仍然是“把 SKILL.md 放到 AI 会去扫描的目录”。一个容易踩的坑很多人图省事把所有 skill 都丢全局目录结果不同项目的需求互相干扰。比如你有一个“前端组件生成”技能在写 Python 后端项目时它也可能被自动触发反而添乱。我的习惯是纯通用技能放全局跟业务或技术栈强相关的放项目级。2.2 完整手动安装步骤从 GitHub 手动装 skill核心就四步找到文件夹、下载、放到对应目录、验证。下面按 Claude Code 走一遍。第一步先确认仓库结构。大部分 skills 仓库是这样组织的superpowers/ ├── skills/ │ ├── brainstorming/ │ │ └── SKILL.md │ ├── test-driven-development/ │ │ └── SKILL.md │ └── ...注意你要装的是某个子文件夹不是整个仓库。直接把整个仓库塞进~/.claude/skills/是最常见的错误装完一看怎么一个都不生效——因为 Claude Code 扫描的是skills下一级目录里的SKILL.md层级不对就读不到。第二步把目标文件夹下载下来。三种方式任选git clone整个仓库然后用cp -r把子目录复制到目标位置。这种方式最稳缺点是如果仓库大会带走一堆用不上的文件。在 GitHub 网页上进到具体子目录下载该目录内容有些仓库支持直接下载文件夹。如果只想看内容也可以直接在网页文件列表里手动逐个复制。有些仓库提供了打包好的 zip 或者 release 附件直接下载解压。第三步复制到目标目录。以用户级为例# 把下载/克隆得到的某个 skill 文件夹放到全局 skills 目录 mkdir -p ~/.claude/skills cp -r ./brainstorming ~/.claude/skills/装完之后建议用ls确认一下层级ls ~/.claude/skills/brainstorming/ # 应该能看到 SKILL.md第四步验证生效。重启 Claude Code 会话输入/skills正常情况下应该能看到刚装上的名字。也可以直接问一句“你现在有哪些技能可以用”它如果答得上来说明加载成功了。Codex 用户同理装完用对应的技能列表命令或系统提示确认。2.3 懒人路线用安装命令手动复制文件夹用多了你会发现新版工具其实已经提供了命令。Claude Code 的claude install-skill可以直接从本地路径安装也可以指向仓库地址不过不同版本的子命令名略有差异动手前先执行claude --help或claude skills --help看一眼本机支持的写法。Codex 也有类似的codex install-skill命令可以接 GitHub 仓库路径。但我要说句实在话命令装虽然快但遇到仓库结构特殊或者网络不太给力的情况老老实实下载文件夹再复制反而更可控。我自己的习惯是先手动装一次理解原理再用命令提速。比如superpower skills这种大型合集直接整仓安装容易出问题我都是进去找到具体 skill 目录单独复制。2.4 装完必做的三件事第一检查命名。skill 文件夹名应当是小写字母、数字、连字符的组合不要有空格和中文。Code Review这种命名会导致识别异常改成code-review立刻正常。第二检查 SKILL.md 位置。它必须在 skill 文件夹的根目录放深一层就读不到。这个错误我踩过无数次尤其是从网上下载到嵌套文件夹的时候解压完多了一层目录不处理就直接扔进 skills 目录结果全不生效。第三检查是不是装重复了。如果全局和项目级各有一个同名 skill项目级会覆盖全局。你发现行为“变了”但不确定为什么的时候先想想是不是有这个覆盖关系。3. 值得收藏的Skills源和场景推荐3.1 几个口碑不错的仓库我平时主要关注几类来源官方示例Anthropic 官方仓库里有 skills 的示例和最佳实践适合入门和了解标准写法。superpower skills社区里名气最大的通用工作流合集主打头脑风暴、规划、TDD、调试这些方法论型技能适合想“让 AI 按正规流程干活”的人。typesafe-ai 这类工程向仓库偏 TypeScript 和全栈质量比较稳定适合工程团队直接借鉴。垂直场景合集华为杯、数学建模、AI 漫剧这些热词背后都有人在维护对应的 skills 合集。这类仓库更新快、质量参差装之前一定先看 SKILL.md 里的 description 写得怎么样描述写得越具体大概率越实用。另外就是前面提到的“skills 网页版索引站”浏览体验好适合没事翻一翻看看别人都在封装什么能力。这些站点本质上是把仓库里的 SKILL.md 渲染成网页看完 description 觉得合适再回到 GitHub 下载对应文件夹。3.2 分场景挑选清单我直接给一张按场景挑 skill 的速查表基本都是我实际用过或者认真读过的方向场景优先找这类 skill理由前端开发组件生成、代码审查、可访问性检查、CSS 排错前端样板代码多、约定多用 skill 统一风格很划算数学建模/华为杯数据清洗、统计分析、优化求解、论文排版LaTeX比赛流程固定从数据处理到写论文都能量化AI 漫剧剧本分镜、角色一致性、场景描述、字幕时间轴把反复出现的提示词模式封装起来避免每集重写通用开发TDD、代码审查、重构、写提交信息方法论型 skill 能明显提升 AI 输出的稳定性文档/写作技术文档、README、CHANGELOG输出格式统一省去反复调格式的沟通成本我特别想提醒一点不要看到一个 skill 就觉得“我都要”。skill 装多了AI 每次做任务都要在大量 description 里做匹配匹配精度反而下降。你装 5 个精挑细选的 skill效果大概率好过装 50 个来者不拒的。3.3 数学建模场景华为杯这类比赛具体怎么配华为杯、国赛这类数学建模比赛时间紧、环节多用 Codex 或 Claude Code 配上一组建模 skill效率能差出好几倍。我建议按比赛的完整流程配四类第一数据预处理。包括缺失值处理、异常值检测、数据标准化甚至自动生成探索性数据分析EDA报告。这类 skill 的价值在于把“拿到表格先干什么”的流程固定下来不会每次让 AI 自由发挥。第二统计与建模方法。常见的有正态性检验、相关性分析、主成分分析、回归、聚类还有优化类的线性规划、整数规划、遗传算法。用一个 skill 把这些方法的适用条件和代码模板收在一起AI 选方法时会靠谱很多。第三结果可视化。比赛论文里图表质量很影响观感封装一个“按比赛规范出图”的 skill把 matplotlib/seaborn 的样式、字体、配色、坐标轴标注全部固定住AI 出的图能直接进论文。第四论文排版。LaTeX 模板、公式规范、三线表、参考文献格式这些重复劳动非常适合 skill 化。尤其是比赛最后半天大家都在改格式有个排版 skill 能省下大量时间。配好之后实际使用时我会先丢给它一份题目数据让它按“数据预处理 → 建模 → 可视化 → 论文”的顺序走中途遇到问题再人工介入。这样至少保证流程完整不会出现“模型跑完了才发现数据没清洗”这种低级事故。3.4 AI 漫剧场景把“提示词工程”沉淀成技能AI 漫剧也就是 AI 生成漫画和动画短剧的工作流是最近特别火的赛道。这类项目最大的痛点是每一集都要写大量重复的提示词——角色形象要保持一致、场景要有镜头感、旁白要有统一风格。把这些封装成 skills 之后一条流水线就成立了。比如做一个“角色一致性”skill里面记录每个主要角色的外貌特征、服装细节、常用动作以及生成图片时的固定提示词模板。AI 在生成新一集分镜时会自动调用这个 skill不会出现上一集红头发、这一集黑头发的翻车事故。再比如“分镜脚本”skill把“剧本 → 分镜表”的转换规则写清楚包括景别、机位、时长、台词、旁白输出格式固定成表格后续所有环节都能直接对着表格干活。这就是典型的“经验资产化”。我自己做这种项目的时候习惯把“提示词风格包”也做成 skill这样不管是换工具还是换项目成员风格都能一键迁移。这个思路其实任何内容创作场景都通用AI 漫剧只是其中一个典型例子。4. 自己动手写Skills核心格式与技巧4.1 标准格式拆解一个标准的 SKILL.mdYAML 头里最重要的两个字段是--- name: my-skill description: 当用户需要……时使用。该技能主要用于…… ---name 就是技能名必须和文件夹名一致字母数字加连字符。description 前面说了一定要写“触发场景”少写空泛的功能介绍。下面这几个字段按需用allowed-tools限制这个 skill 能用哪些工具比如只允许读文件防止 AI 执行危险操作。disable-model-invocation: true关闭自动触发改成手动调用。适合那些不能被 AI 自作主张执行的技能。model指定执行该 skill 时的模型比如复杂规划任务指定更强的模型。context控制上下文窗口等运行参数进阶玩法新手可以先不管。正文部分没有强制 schema但写得好不好直接决定 AI 执行质量。我自己习惯的正文结构是先说“这个技能在什么情况下用、什么情况下别用”再给“执行步骤”编号列表最后给“输出模板”或“检查清单”。步骤一定要具体到可执行而不是讲道理。4.2 写 SKILL.md 的三个关键原则第一个原则描述写触发条件不写功能定义。我比较过两种写法效果差异极大。description: 对代码进行审查这样写AI 经常“该用的时候不用不该用的时候乱用”。改成description: 当用户要求 review 代码、检查 PR 或发现 bug 时使用用于系统性地审查代码质量之后触发就准多了。因为模型是靠语义匹配来判断何时加载 skill把触发场景写透比什么都强。第二个原则给流程不给概念。正文里写“应该仔细审查代码注意潜在问题”AI 执行时还是不知道具体该怎么办。正确写法是给出 checklist## 审查步骤 1. 读取变更涉及的每个文件 2. 检查未处理的分支和边界条件 3. 检查硬编码值和魔法数 4. 检查错误处理是否完整 5. 按以下模板输出审查报告AI 是“按步骤执行”最稳的机器。你把步骤拆到它不用动脑子就能执行输出质量立刻上一个台阶。第三个原则能放脚本就放脚本。如果某一步是确定的重复操作比如格式化、检查文件编码、批量重命名直接写好脚本放进scripts/目录在 SKILL.md 里告诉 AI 去调用。这比让 AI 现场发挥写脚本稳定得多。我见过很多 SKILL.md 写得天花乱坠但里面全是让 AI“自己想办法”的空话这种 skill 装不装没区别。4.3 实战示例写一个“数据探索报告”Skill假设我要给数学建模团队写一个 skill目标是一拿到数据就自动产出规范的探索性分析报告。SKILL.md 大概长这样--- name: eda-report description: 当用户给出一份数据文件并要求做数据探索、写 EDA 报告或比赛刚开始需要快速了解数据时使用。负责生成包含缺失值、分布、相关性、异常值的完整报告。 --- # 探索性数据分析报告 ## 使用时机 - 拿到新数据、开始任何建模之前 - 用户要求“看一下数据”“探索性分析”“EDA” ## 执行步骤 1. 用脚本读取数据输出行列数、字段类型、缺失值统计 2. 对数值列计算描述性统计均值、中位数、标准差、分位数 3. 检查并标记缺失值、重复行、异常值超过 3 倍 IQR 的记为异常 4. 生成相关性矩阵标注强相关|r| 0.7的字段对 5. 按下方模板输出报告并把关键图表保存到 reports/ 目录# scripts/eda.py —— 容错优先文件编码、缺失列都不能直接崩 import pandas as pd import sys path sys.argv[1] try: df pd.read_csv(path) except UnicodeDecodeError: df pd.read_csv(path, encodinggbk) # 继续按步骤输出统计结果...写作要点是每个步骤都足够具体AI 不需要猜测“应该做什么”只要按顺序执行。同时脚本里最好带上容错比如文件编码不识别时自动尝试多种编码这样比赛现场才不会因为一个小格式问题卡住。4.4 写完怎么测试写完之后别急着到处发先做一轮验证。最直接的办法是在一个临时项目里调用它故意让它处理一份测试数据观察它有没有按你的步骤走、输出格式是否符合预期。如果某一步它跳过了多半是正文里写得不够强制——“应该”这种词在模型眼里是弱约束改成“必须”“按以下顺序执行”效果更好。我还会故意测一下“不该触发的时候会不会误触发”。比如这个 EDA skill我让它去写一个登录接口如果它跑偏去做数据报告说明 description 的范围写宽了需要收紧。5. 常见问题与排查技巧实录5.1 Skills 不生效先查这五件事我把自己和群里朋友踩过的坑梳理了一下八成是下面五个原因第一目录层级不对。SKILL.md 没有直接放在skills/技能名/下而是多了一层嵌套。这是头号原因检查方式前面说过直接ls看。第二命名不规范。文件夹名有空格、大写、中文或者 name 字段和文件夹名不一致。改成小写连字符命名即可。第三description 写得让模型“无感”。模型扫到一堆 description 但都觉得跟当前任务无关就不会加载。这时候要优化描述把触发场景写清楚。第四装的位置不对。装到了项目级目录但在别的项目里用或者反过来。检查当前项目根目录下有没有.claude/skills以及你的操作是否在那个目录里。第五缓存和会话问题。装完 skill 之后没有重启会话或者旧会话还带着之前未加载的状态。重启一个新的 Claude Code 或 Codex 会话再试大部分“装完不生效”都能解决。5.2 清理无用 Skills 的正确姿势skill 装多了必然要清理。社区里 tibo 分享过的清理方法我试下来很实用核心思路是先看哪些 skill 在真实对话里从来没被触发过再决定留不留而不是凭感觉删。具体做法把skills目录里的每个文件夹按“最后使用时间”过一遍同时翻对话记录里出现过哪些 skill 名。一直没出现过的先移到备份目录禁用一两周确认工作流没受影响再彻底删掉。这个“先隔离再删除”的思路比一口气全删安全得多。清理的时候还有一个细节同名覆盖。如果你早期手动复制过一个 skill后来又用命令装过同名的新版目录里可能出现两个一样的名字。删之前对比一下两个文件夹里的 SKILL.md 版本留新的。另外/skills管理界面里如果显示禁用状态也可以直接在界面里启用或禁用不一定非要动文件系统。5.3 踩坑速查表现象大概率原因解决办法装了但技能列表看不到目录层级或命名不对检查 SKILL.md 位置改成小写连字符命名看得到但从不触发description 触发场景写得模糊重写 description强调“当用户……时使用”项目里行为突然变了项目级 skill 覆盖了全局同名 skill检查两个目录删除多余版本执行到一半乱来正文步骤不够强制把“应该”改成“必须”按编号顺序执行想删又怕误删没有隔离机制先移到备份目录观察两周再删命令装总是失败仓库结构特殊或网络不稳定改用手动下载文件夹加复制的方式最后分享一点我自己的体会。Skills 这套机制最大的价值不是“能装多少”而是“能把多少重复劳动沉淀下来”。我现在的做法是凡是同一种事情让我重复做过三次我就会考虑把它封装成一个 skill凡是装进来的 skill先在小项目里验证一周不好用立刻清理。另外一个小技巧我会把自己写的所有 skill 放进一个私有 GitHub 仓库统一管理本地通过软链接指到~/.claude/skills/这样改一处、全局生效换机器也不用重新拷贝。这套流程我用了大半年最大的感受是 AI 从“每次都像第一次干活”变成了“带着我全部经验来干活”这个差异你用一次就能感受到。