最近半年，AI编程圈子里提到“skills”这个词的频率，快赶上当年大家聊插件和Agent了。Claude Code、Codex、OpenCode这些工具都在推自己的技能包机制，GitHub上一下子冒出来一堆“superpower skills”“codex nature skills”之类的仓库，社区里讨论“skills怎么装”“skills怎么写的”人也越来越多。今天这篇，我就从自己实际折腾这些技能包的经验出发，把这东西到底是什么、怎么手动从GitHub装上、哪些场景真值得用、怎么自己写一个、以及踩过哪些坑，一次讲清楚。

如果你只想快点用上别人做好的技能包，重点看第2部分和第3部分；如果打算公司内部或者比赛期间自己沉淀几个技能，第4部分是核心；已经碰到“装了没反应”这类问题，直接翻第5部分的速查表。为了说明标准路径，我用Claude Code做主要演示，其他工具的原理完全一致。

1. 先搞清楚：AI工具里的Skills到底是什么

1.1 从“会聊天”到“会干活”：Skill补上的能力缺口

大模型什么都懂一点，但它默认的状态是“临时发挥”。你让它写一个React组件的审查意见，它写出来像模像样，可换个问法、换个项目背景，结果就飘了。问题的根源不是模型不够聪明，而是它缺少一套“稳定执行的流程”。一个AI工具要让用户真正信任，就必须让模型在特定任务上形成肌肉记忆，而不是每次都靠运气。

Skills就是干这个的。它把一份“遇到这类任务先干什么、再干什么、按什么标准输出”的说明，连同可能用到的脚本、模板、参考文档，打包成一个目录，放进工具的技能目录里。模型在对话中识别到任务匹配，就会主动读取这个说明，按里面写好的流程执行。用生活里的例子打比方：默认状态的AI像个什么都会一点的实习生，你交代一句它干一步；Skill机制等于给这个实习生发了一本工作手册，手册里连检查清单、常见坑、参考案例都写好了，而且还有配套工具，干活自然稳得多。

这个机制从今年开始在编码Agent里集中爆发，直接原因是这些工具已经进到真实工作流里了。再强的Agent，如果每次都要用户重新交代一遍“你先看项目结构、再跑测试、再给我报告”，用起来依然累。Skills把这一层重复劳动彻底省掉，也让普通用户可以把自己验证过的做事方式沉淀下来，给AI反复使用，这就是社区里那些“superpower skills”强调的超级能力。

1.2 Skills和普通Prompt、插件、MCP到底有什么不一样

很多人第一次接触Skills时容易和几样东西搞混：普通Prompt、传统插件、还有MCP Server。它们之间不能画等号，各有各的位置。

最常被拿来和Skills比较的是MCP。我自己的理解是，MCP更像给AI“配外设”，把数据库、浏览器、文件系统这些外部能力接进来；Skills更像是给AI“派导师”，告诉它一件事在企业标准流程里应该怎么做。两者完全不冲突，甚至可以叠加：MCP负责让AI能读到数据，Skill负责让AI知道读完之后怎么分析、怎么出报告。

传统插件通常是在IDE或者客户端层面做的按钮、UI扩展，属于“人操作工具”的交互方式；Skills则是给AI自己阅读和执行的，核心文件就是一个带元信息的Markdown文档。你不用开发一个复杂的界面，只要把流程写清楚、把脚本放对位置，AI就能代理完成整个任务，这也是它能爆发的根本原因。

2. 动手装第一个Skill：从GitHub手动接入

2.1 先弄明白你的工具读哪个目录

不同工具的技能目录路径不一样，但结构逻辑完全一致：一个技能一个文件夹，文件夹根目录里必须放一份命名为SKILL.md的说明文件。这个文件的开头有一段被---包裹的元信息，里面是name和description，模型靠这些字段来判断什么时候该调用它。

以我手上常用的几个工具为例：

• Claude Code：用户级目录是~/.claude/skills/，项目级目录是.claude/skills/
• Codex CLI：用户级目录是~/.codex/skills/，项目级目录是.codex/skills/
• OpenCode：通常在配置目录下建skills文件夹，不同版本稍有差异，装之前建议看一眼官方文档确认

选择用户级目录还是项目级目录不是随意的。用户级目录里的技能对所有项目生效，适合放通用能力，比如代码审查、日志分析、JSON处理；项目级目录里的技能只对该项目生效，适合放团队规范、竞赛专用流程、某套业务的定制脚本，不会污染其他项目。按这个原则分配，比一股脑全塞到用户级目录要清爽得多。

还有一点要注意：装完技能后，十有八九需要新开一个会话才会生效。工具在启动时扫描技能目录，运行中新增的目录不一定会被立刻加载，不是越改越快，这是正常现象。

2.2 从GitHub拉取并安装：完整步骤

GitHub上的技能仓库通常有两种形态：一种是单个技能一个仓库，一个仓库里就一个SKILL.md；另一种是“全家桶”仓库，一个仓库里放了十几个甚至几十个技能目录。实操中大多数是后者，所以安装的核心动作不是“clone完就完事”，而是“把你要的那个子目录复制到技能目录里”。

第一步，创建一个技能目录并进入：

mkdir -p ~/.claude/skills cd ~/.claude/skills

第二步，把技能仓库克隆到当前目录：

git clone https://github.com/example/awesome-coding-skills.git

第三步，查看仓库里有哪些技能子目录，挑需要的复制出来：

ls awesome-coding-skills cp -r awesome-coding-skills/code-review-skill ~/.claude/skills/

第四步，检查目录结构是否正确。一个可识别的技能目录，根目录下至少要能看到SKILL.md文件：

find ~/.claude/skills -maxdepth 2 -name "SKILL.md"

第五步，重启你的AI工具，开启一个新会话。

这套流程看着简单，但有一个地方特别容易翻车：有人把整个仓库克隆完就直接用，没有把子目录挪到技能目录。工具扫描的是技能目录下的一级子目录，如果嵌套层级不对，或者仓库本身的说明文件不在预期位置，AI根本认不出来。这也是为什么手动装技能时，很多人对着官方文档一步步做还是失败，最后发现是目录结构没对齐。

2.3git clone不好使的时候，改走备选方案

GitHub仓库有时候会因为网络原因clone很慢，甚至直接失败。这时候不要硬等，我常用的替代方案是从网页端下载ZIP包。

在GitHub仓库页面右侧找到Download ZIP按钮，把整个仓库下下来，解压之后进入对应的技能子目录，把它复制到~/.claude/skills/下就行。这个办法慢是慢一点，但胜在稳定，而且下载ZIP还有一个附带好处：你会顺便看到完整的仓库目录结构，方便判断哪些子目录是技能、哪些只是说明文档或者模板。

卸载技能就更简单了，直接把技能目录删掉，例如：

rm -rf ~/.claude/skills/code-review-skill

注意：不要把整个技能合集仓库一股脑塞进~/.claude/skills/。技能装多了会拖慢加载，更麻烦的是AI会在多个相似的description之间犹豫，导致该触发的技能没触发，我在第5部分会详细讲这个坑。

3. 场景化推荐：哪些Skills实测好用

3.1 前端开发与Web设计类

前端是Skills落地最活跃的领域，社区里流传最广的superpower skills合集，里面有相当一部分都是为产品开发场景设计的。这类技能最大的价值，是把“代码审查、设计规范落地、响应式排查”这些重复劳动标准化。

以代码审查类技能为例。直接贴一段代码让AI“帮我review一下”，它确实能找出一些问题，但水平不稳定，而且经常忽略项目里的设计系统约束。装了对应的技能之后，AI会主动先读项目里的组件库配置和设计tokens，再按检查清单逐项审查，输出内容包括风格一致性问题、可访问性问题、性能隐患，连修改建议都按你的代码风格来写。这种稳定度是普通Prompt给不了的。

前端场景里我个人使用频率最高的几种：

• 组件代码审查：绑定项目内的组件规范和设计变量，输出结构化审查意见
• 响应式布局排查：给张截图或者一段渲染结果，自动检查断点行为和移动端适配
• 页面生成：从需求描述、接口文档直接生成符合项目目录结构的页面代码
• Tailwind类名整理：检查类名冲突、冗余和动态类名问题

这类技能的安装门槛极低，社区仓库里基本都是开箱即用，特别适合前端团队做统一规范落地。

3.2 数学建模与数据竞赛类

最近看到不少人问“华为杯建模比赛好用的codex skills有哪些”，数学建模这个场景其实非常适合用Skills。因为建模比赛的核心痛点不是“不会做”，而是“流程太长、重复劳动太多”：数据要清洗、特征要做体检、模型要反复求解、论文里的表格和公式要折腾到凌晨。

一套好用的建模Skills，等于把“数据工程师+算法助手+论文排版员”的标准流程全部固化了。常见的几个方向：

• 数据体检技能：读取一份CSV后自动跑缺失值统计、异常值检测、数据类型总览、分布特征摘要，最后输出一份数据报告
• 自动化特征工程技能：按项目要求生成特征候选列表，给出特征构造代码和相关性检验结果
• LaTeX公式转换技能：识别手写公式或截图，输出可直接编译的LaTeX代码，比赛写论文时省下一大块时间
• 敏感性分析技能：对模型关键参数做扫描，自动生成对比图和结论摘要，不用手动写一堆循环脚本

这里有个特别重要的经验：比赛类的技能千万别放在用户级全局目录里，应该放进比赛项目目录下的.codex/skills/或者.claude/skills/。这样既不会弄脏日常开发环境，也方便整个队员共享。技能文件用Git管理后，队友clone项目就能同步拿到全部技能。

3.3 内容创作与AI漫剧场景

AI漫剧这种新形态内容，看起来是创意活儿，其实内部也是一条标准流水线：脚本拆成分镜，分镜变成画面描述，画面描述又变成绘图模型的提示词，再加上配音、字幕、角色一致性要求。一个人单独干很累，原因就在这些转换环节每次都要人工操作一遍。

Skills在这里的价值体现得淋漓尽致。把“脚本转分镜表格”这个动作固化下来之后，你只需要输入小说原文或者剧本段落，AI就会按固定格式输出分镜表格，包含镜头号、景别、画面内容、台词、预估时长。每一列都是下一步生成的直接输入，工序之间完全咬合。

更进阶的做法是维护一个角色设定文件，做成“角色一致性技能”。这个技能目录下的references文档里写死主要角色的外观细节、性格标签、常用语气词，每次生成画面描述时自动带入，漫剧角色就不会出现上一集和下一集长得不像的问题。

这类内容创作技能的写法并不难，难度在梳理流程。只要你把平时手工干活的动作一步步拆出来，写成文字让AI照着做，就已经是一个skill了。拆得越细，AI输出越稳。

3.4 值得关注的专题仓库

GitHub上现在有成体系的Skills仓库，基本覆盖了各种场景。比如偏科研写作的codex nature skills、社区整理的cola skills合集、面向类型安全方向的typesafe ai skills，以及一堆以awesome开头整理的技能列表。

这些仓库不用全装。我的习惯是：先按关键词搜一下，看仓库的README，确认里面有没有解决我实际问题的子目录，然后按第2部分的流程只挑需要的装。有人上来就把几千个star的合集全clone进技能目录，结果AI对话里频繁读错技能，那就是给自己找麻烦了。

4. 从用到写：如何开发自己的Skills

4.1 Skill的最小目录结构

自己写技能并不神秘，核心就是一个文件夹加一份Markdown。标准的最小结构如下：

my-skill/ ├── SKILL.md ├── scripts/ │ └── check_json.py └── references/ └── examples.md

SKILL.md是整个技能的灵魂，它有一个标准的文件头。下面是一份基准模板：

--- name: json-toolkit description: Use this skill when the user asks to format, validate, compare, or debug JSON files. Trigger on phrases like "format JSON", "json is broken", "validate this json", "compare two json". --- # JSON Toolkit This skill helps the user process JSON files. ## When to use - User wants to format or pretty-print JSON - User wants to validate a JSON file - User wants to compare two JSON structures ## Steps 1. Locate the JSON file or input string. 2. Run the validation script: `python3 scripts/check_json.py <file>` 3. Report the result in a short summary. 4. If errors, explain the exact location and suggest a fix. ## Scripts - `scripts/check_json.py` — validate and format JSON.

name字段是技能的唯一标识，description字段决定AI什么时候调用这个技能。不要小看这个字段，它是整个技能里最重要的一段文本。AI在主对话里会把你说的每一句话和所有技能的description做匹配，描述里覆盖的关键词越多，触发的准确性越高。

references/目录用来放参考资料，典型输入输出案例、团队规范原文、模板文件都可以放进去。AI读到技能正文之后，会根据需要再去翻参考资料，所以这个目录对复杂技能很关键。

4.2 实操：手写一个JSON格式化校验Skill

空讲概念没有感觉，我带你完整写一个能直接用的“JSON格式化校验”技能，写完就能让主流的AI编码工具识别。

第一步，创建目录：

mkdir -p my-skill/scripts cd my-skill

第二步，创建SKILL.md，内容就是我上面贴的那份模板。注意description里要同时写清楚“什么时候用”和“用户会怎么说”，我把“format JSON”“json is broken”“validate this json”这些口语化触发词全塞进去了，这样用户怎么问都不容易漏触发。

第三步，写scripts/check_json.py。这里为什么要用脚本而不是让AI直接处理？因为JSON格式校验是确定性很强的工作，直接让AI“看着办”它可能给出过于自由的解释，而脚本的输入输出是固定的，可以保证结果可靠：

#!/usr/bin/env python3 import json import sys def main(): path = sys.argv[1] try: with open(path, "r", encoding="utf-8") as f: raw = f.read() except FileNotFoundError: print(f"ERROR: file {path} not found") sys.exit(1) try: data = json.loads(raw) except json.JSONDecodeError as e: print(f"INVALID JSON: {e}") sys.exit(1) formatted = json.dumps(data, indent=2, ensure_ascii=False) with open(path, "w", encoding="utf-8") as f: f.write(formatted) print(f"VALID JSON, formatted: {path}") if __name__ == "__main__": main()

第四步，在目录下加一个references/examples.md，里面放一个“格式乱掉的JSON示例”和对应的“格式化结果示例”。AI在调用技能时如果看到示例，更容易理解预期输出长什么样。

第五步，把整个my-skill目录放到~/.claude/skills/下，开新会话测试。输入“帮我格式化这个JSON文件”，然后扔一个文件路径过去，看AI是直接动手读文件并调用脚本，还是只会嘴上应承。我的经验是，只要description写得够具体，第一次基本就能触发。

4.3 设计一个高质量Skill的三个要点

写一个能跑的技能很简单，写一个“真正好用”的技能就考验设计能力了。回头看我维护的技能库，最深的体会是三条。

第一，单一职责。一个技能只干一件事，千万别搞成“瑞士军刀”。你把“JSON处理”和“数据库导出”写进同一个Skill里，AI反而会在多个任务之间犹豫，触发率惨不忍睹。宁可拆成两个目录，也不要塞到一起。

第二，description要模拟用户真实提问。这一步值得多花十分钟。问自己：用户会怎么表达这个需求？他会说“帮我看看这个json有没有问题”，会顺手打错成“json格式坏了”，还可能直接说“这文件乱了”。把这些表达全部写进description，你才有资格说自己写的技能“触发灵敏”。

第三，把判断标准和失败兜底写清楚。技能正文里不要只写“怎么做”，还要写“什么情况算成功、什么情况算失败、失败后怎么反馈”。AI不是人，它不会临场判断边界，你需要提前把所有异常路径交代好。我见过太多技能写“解析JSON并输出结果”，结果文件不存在就直接抛错，用户看得一脸懵。补一句“如果文件不存在，请告知用户并检查路径”，体验完全不一样。

5. 常见坑与排查技巧实录

5.1 装了Skills但AI完全不理会，先查这五处

这是我在社区里被问得最多的问题：“技能装好了，目录也对，为什么AI就是不调用？”每次遇到这种情况，我都是按顺序排查这五个地方。

• 路径对不对：确认技能目录在~/.claude/skills/的下一级，而不是嵌套了两层
• SKILL.md名字对不对：必须是SKILL.md，而不是skill.md或者README.md
• frontmatter写没写全：name和description两个字段缺一不可
• description的触发词覆盖面：用户习惯说的词，比如“格式乱”“坏了”“修一下”，你有没有写进去
• 会话重启没有：技能是启动时扫描加载的，新装完请新开会话

我自己踩过最隐蔽的一次坑：装了一个后端脚手架技能，怎么问都不触发，排查了半天才发现，触发描述里我用的是“backend scaffold”，而用户习惯说的是“搭个后端”。把描述改成“搭后端、创建后端脚手架、backend scaffold、初始化服务端项目”之后，立刻就能召唤出来。这件事让我养成一个习惯：写完技能的description，会先拿几种不同说法在对话里测试一遍。

5.2 脚本报错、依赖不全：权限和环境的锅

技能里带脚本时，报错概率会明显上升。最常见的三类原因，一是脚本没有执行权限，二是运行环境缺少依赖，三是脚本里写死了绝对路径。

解决权限问题很简单：

chmod +x ~/.claude/skills/my-skill/scripts/*.sh

环境依赖方面，如果脚本用到Python的第三方库，比如pandas、requests，一定要在SKILL.md里写清楚依赖声明，最好在技能目录里放一个requirements.txt。AI读到脚本后如果发现少了依赖，它可以尝试帮你装，但前提是它知道需要装什么。

绝对路径的问题最隐蔽。你本地调试脚本时可能直接写/Users/me/data/input.json，技能分发出去之后别人一跑就报错。正确的做法是全部使用相对路径，或者在SKILL.md里约定“入参永远由用户提供路径”，脚本只负责处理传入参数。

5.3 技能越装越多，AI反而“变笨”的清理心法

有一个现象很多人不愿意承认：技能装多了，AI会变笨。因为每次对话模型都要在一堆技能描述里做匹配，描述相似度太高时，它就容易抓错技能，或者把好几个技能的内容揉在一起输出。

社区里有人专门聊过清理技能的方法，核心思路其实就是三个字：做减法。具体做法我整理成了自己的清理流程：

1. 每月翻一次技能目录，看哪些技能在过去两周一次都没触发过
2. 把使用率高的技能和吃灰技能分组，吃灰的直接归档或删除
3. 全局技能只保留高频通用能力，建议控制在10到20个，其余下沉到项目级目录
4. 为技能加上统一的前缀命名，降低AI识别时的混淆

这里我特别认同一句话：哪怕一个技能写得再好，如果它不常在对话里被触发，对你就是负担。技能库不是收藏夹，装得越多，选择成本越高，匹配越不稳定。一个精挑细选过、每个都能稳定触发的10个技能的库，比一个堆了100个技能但频繁乱触发的大杂烩好用太多。

5.4 常见问题速查表

最后再分享一个我个人的小习惯。每装一个新技能，我都会先给它做一次“召唤测试”，用一句话直接点名触发的关键词，比如对json-toolkit说“帮我格式化这个JSON”，确认AI真的读取了技能内容，再把它放进正式的技能库。这个习惯帮我挡掉了至少一半的“装了等于没装”。

Skills这套东西，本质上就是把人的经验沉淀成AI的肌肉记忆。它不要求你会写多复杂的代码，也不需要你有所谓天赋，只要求你认真观察自己的工作流，把重复的事情固化下来。我在实际使用中越来越觉得，与其花时间找一堆别人的技能存着吃灰，不如先给自己最常做的三件事各写一个足够扎实的skill，让它们真的天天帮你干活。从手写第一个SKILL.md开始，慢慢迭代，这套东西就真正是你的了。