如果你用过Claude Code、Codex或者opencode这类AI编程助手多半会遇到一个特别尴尬的场面明明是同一个仓库昨天刚让AI按团队风格写了一个模块今天让它改个bug它却像第一天入职一样把项目里约定俗成的命名规范、提交格式、TODO写法全忘了。直到我把skills这个功能认真收拾明白情况才彻底改观。先说人话解释一下skills就是给AI助手准备的“岗位手册工具箱”。它不是一个需要联网调用的神秘接口而是一个有固定结构的目录里面装着SKILL.md说明文件、参考文档、可执行的脚本。只要装进Claude Code、Codex这类工具的配置目录AI就会在遇到相关任务时自动翻出对应手册照着里面的规范干活。这篇文章我会从“什么是skills”讲起写清楚怎么手动安装GitHub上的skills、有哪些靠谱的skills源和场景推荐最后也把自己开发skills的模板和踩坑记录一并分享出来。如果你是第一次接触这个概念按文章的步骤走一遍基本就能上手如果你已经装过几个技能包但觉得不好用重点看第4、5节的写法原则和排查思路。1. AI Skills到底是什么给AI助手的“专业手册工具箱”1.1 一个解决“AI有知识但没规矩”的方案我最早接触skills这个概念是在一次重构老项目的时候。项目里有套很老但必须兼容的数据格式转换逻辑我在对话里把格式文档、转换规则、禁止踩的坑都贴给了Claude Code它干活还算靠谱。可到了第二天新开一个会话继续改另一个文件它又把规则忘得一干二净。当时我的第一反应是“模型记忆力不行”后来才意识到问题不在模型在我没给模型一个稳定的知识载体。skills的核心思路就是把那些“每次都要重新粘贴、每次都要口头强调”的知识沉淀成固定的文件目录。它本质上是一个带有结构化说明的技能包SKILL.md里描述了这项技能是干什么的、什么时候该用、具体按什么步骤执行旁边还可以带上scripts脚本和references参考文档。AI助手根据当前对话的任务描述自动判断是否需要激活某个技能。这个机制解决的是LLM最常见的毛病——它掌握通识知识但不懂你所在团队、你手头项目里的隐性规则。打个比方你就明白了。普通prompt是你在路边拦下一个资深工程师临时口述需求他凭经验干活MCP像是给这位工程师办了一张工牌让他能调用公司内部系统和数据库而skills则是一本《老员工入职手册》里面写了公司的代码规范、评审流程、哪些坑绝对不能碰。三者不是竞争关系而是从“一次性指令”到“工具接入”再到“领域方法论”的三个层次。1.2 和prompt、MCP到底有什么区别很多人一上来会混淆skills和MCP我也一样。后来我用一张对比表才彻底理清对比维度普通提示词MCPSkills本质载体对话里的临时文本外部工具/服务协议本地文件目录文档解决什么问题单次任务的指令让AI能调用工具和数据让AI按专业流程与规范完成工作是否需要每次输入是每次都要重新组织否按需调用否按任务描述自动匹配复用与分享弱中强可打包成固定技能维护成本每次都在变需要服务端支撑改SKILL.md和脚本即可从这个表能看出来skills真正解决的是“可复用、可沉淀、可分享”。MCP解决的是“能不能连上”skills解决的是“会不会干好”。我在实际使用中还有一个感受skills对多文件项目尤其有用。AI处理一个任务的时候往往要连续接触好几个文件如果你只在某个文件头部写了注释它处理另一个文件时大概率看不到但如果把规范写进一个skill任务一触发整套规范都会被加载进上下文。这也解释了为什么社区里很多“superpower skills”这类技能库要设计成十几个技能包的形式——它们想把每个细分场景的规范都固化下来而不是塞进一段超长prompt里。2. 手动安装GitHub上的Skills完整实操记录2.1 安装前先搞懂目录约定手动安装skills本质就三件事把仓库代码拿到本地、按目标工具的目录约定放进去、让配置正确加载出来。但很多人恰恰卡在第二步因为不同工具对skills目录的约定并不一样。以我日常在用的几个工具为例Claude Code项目级技能放在.claude/skills/目录下用户级放在~/.claude/skills/macOS和Linux或对应用户主目录里。装进去之后在支持命令的版本里可以直接用/skills之类指令查看列表。OpenAI Codex支持在.codex/skills/目录中定义技能也可以在项目说明文件里声明路径。查看当前技能状态也有对应的交互命令。OpenCode同样支持skills机制它的目录约定和TypeSafe AI那一套工具链相关具体以仓库README为准。还有一点要提醒同一个技能包在Claude Code里能用不代表换个工具就能直接识别。目录对了还要确保SKILL.md里的frontmatter字段和目标工具兼容。不同工具的约定细节有差异手动安装前一定要去看目标工具官方文档里关于skills的说明别想当然。2.2 手动安装的四个步骤第一步找到合适的skills仓库。GitHub上搜索“awesome claude skills”、“codex skills”、“superpower skills”、“nature skills”都能找到大量技能库。挑的时候别只看star数我一般看三个东西最近提交时间是否在半年内、仓库里是不是真有SKILL.md文件、README里有没有清楚的目录结构和使用说明。长期没人维护的仓库技能大概率跟不上新版本的模型能力。第二步下载。两种方式任选直接Download ZIP或者用git clone拉下来。图省事就下载压缩包但后续想更新还得重新下一次想长期跟进某个技能库就clone到本地更新的时候在仓库目录里pull一下就行。第三步放到正确位置。这里有个关键细节把压缩包解压后里面往往还有一层仓库文件夹例如superpower-skills-master/superpowers/skills/...。不能直接把最外层文件夹塞进skills目录而要把里面真正包含SKILL.md的那个子文件夹拷到目标配置目录。如果目标仓库是一个“一仓库多技能”的结构那你只需要复制用到的几个技能子目录不必整仓搬过去。第四步验证是否加载。重新打开一个AI编程会话用一句和该技能强相关的描述发个任务看AI给出的回答有没有体现技能里的规范。比如装了一个“代码审查”技能就让AI“按技能规范审查当前分支的改动”。如果AI明显使用了技能里的术语、流程或格式要求说明加载成功。在Claude Code里也可以直接输入管理命令查看当前技能是否出现在列表中。2.3 装完不生效的常见原因如果验证时发现“石沉大海”先别急着骂工具大概率是下面几个问题目录层级不对。最常见的是多套了一层目录SKILL.md没有被直接放在技能根目录。技能目录名和SKILL.md里的name不一致。很多工具是认文件夹名或认name字段的两边最好保持一致。没有重启会话。技能加载发生在会话初始化阶段老会话里可能还是旧的上下文。触发的描述写得太模糊。AI判定“是否激活该技能”主要靠description和当前任务文本的语义匹配如果你描述的任务偏离了技能说明它就不会调用。这些坑我在第5节会展开讲先记得一点手动安装不是“文件放进去就结束”验证和语义匹配同样重要。3. 值得收藏的Skills源与按场景推荐3.1 几个口碑不错的skills源仓库现在GitHub上skills仓库很多但质量参差不齐。我建议你重点参考这几类第一类是综合型技能库比较有代表性的是superpower skills这类项目。它把开发中常见的代码审查、重构、测试生成、文档编写等场景都封装成了独立技能包结构统一、模板清晰很适合作为学习和安装的起点。第二类是特定工具或特定团队维护的技能集比如TypeSafe AI相关的skills仓库它们往往和opencode这类工具链结合得更紧密。第三类是聚合类“awesome”仓库这类仓库本身不直接提供技能而是把散落在各处的优质技能源收录在一起适合按图索骥。我个人的建议是优先选综合型技能库先把两三个核心场景跑通比如“代码审查”和“提交信息生成”。不要一上来就装二十个技能技能包越多AI在上下文里做匹配的时候噪音越大反而容易误触发。3.2 按场景推荐的skills组合结合我自己和身边朋友的实际使用不同场景适合装的技能方向大致如下场景常用技能方向推荐理由前端开发组件规范、可访问性检查、测试生成、样式类名整理前端项目约定多技能能保证改动风格统一数学建模/华为杯数据清洗、特征分析、论文LaTeX排版、图表配色规范建模比赛要同时兼顾代码、论文和图技能可一站式约束AI漫剧分镜脚本、角色一致性、画面提示词生成、字幕断句这类创作型任务最需要统一的风格约束通用效率代码审查、commit信息生成、CHANGELOG维护、重构建议覆盖面广安装成本低收益立竿见影拿数学建模举例。参加华为杯这类比赛的时候你大概率既要写数据处理代码也要排LaTeX论文还要画图表。装一个“数据清洗规范”技能AI处理缺失值、异常值的时候就不会随手drop一整列装一个“论文排版”技能AI输出的LaTeX片段会符合你事先定义的模板再配一个“图表配色”技能所有图的风格就能保持统一。这些事如果靠每次手动在prompt里写基本坚持不过第二天。AI漫剧方向同理。漫剧创作者最头疼的是角色一致性——同一张脸在不同分镜里经常漂移。把“角色描述生成”和“画面提示词规范”封装成skills后AI画分镜时能参考同一套角色设定至少不会在同一个项目里画出两张脸。这种场景里skills的潜力其实比写普通prompt大得多因为技能可以跨会话持续生效。4. 开发自己的Skills从SKILL.md开始4.1 SKILL.md的frontmatter和正文结构自己开发skills没有想象中复杂核心就是写一个高质量的SKILL.md。SKILL.md的开头是YAML格式的frontmatter最关键的字段是name和description。name要短能代表这项技能description则是灵魂它决定AI什么时候激活这个技能。写description要具体给出触发场景、任务类型和输入输出特点。一个合格的description应该像这样当用户要求对TypeScript代码进行代码审查、检查潜在bug、发现性能问题或评估架构合理性时使用此技能。适用于PR review、代码走查等场景。注意这里的描述要“窄而准”。你写“处理代码相关任务”这种泛化描述AI几乎随时都会尝试加载它效果反而很差。正文部分不要写成大段的理论。我建议用这种结构先写核心原则用三到五条不可妥协的规则再写执行步骤按顺序列出每一步要做什么最好配上输入输出示例然后写禁忌清单明确告诉AI哪些事绝对不要做。这样做的好处是技能的约束从“规则”到“流程”再到“边界”三层下来AI执行起来基本不会跑偏。4.2 一个可以直接抄的模板我把自己一直在用的SKILL.md模板简化了一下你可以直接抄走改成自己的--- name: frontend-component-review description: 当需要审查前端React组件代码、评估组件可维护性与可访问性、检查状态管理逻辑时使用。 --- # 前端组件审查规范 ## 核心原则 1. 组件必须保持单一职责一个组件只做一件事。 2. 禁止在组件内部写超过200行的逻辑超出的部分必须拆分。 3. 所有交互元素必须考虑键盘可达性和ARIA标签。 ## 执行步骤 1. 先阅读组件整体入口确认Props类型定义。 2. 梳理状态区分组件内部state与外部store数据。 3. 检查渲染逻辑列表渲染是否有稳定key条件渲染是否有兜底。 4. 输出审查结果按“问题-定位-修改建议”的格式列出。 ## 输出格式 每个问题用三级标题呈现包含 - 所在文件和行号 - 问题类型可维护性/可访问性/性能 - 修改建议代码片段 ## 禁忌 - 不要只提问题不给修改建议。 - 不要展开与本次审查无关的重构讨论。 - 不要使用console.log作为调试替代方案。模板里最关键的不是内容本身而是它体现了“具体到能执行、严格到不跑偏”的原则。写的时候多想想一个AI拿到这份文档能不能不需要额外解释就把活干出来如果它还来问你“这个组件的边界跟header组件重叠怎么办”说明你的文档还需要补充更多边界情况。4.3 让skills“好用”的五个原则写了不少skills之后我总结了五个原则分享给你参考。第一个原则是示例驱动。AI最擅长的就是模仿与其写一百句抽象的“要优雅”不如给一个“优雅”和“不优雅”的对比示例。第二个原则是边界清晰。description里说清楚“什么情况下用”正文里再补一段“什么情况下不用”可以大幅降低误触发率。第三个原则是保持可验证。每次改完SKILL.md用一个真实小任务去验证它有没有生效不要凭感觉判断。第四个原则是用git管理你的skills目录。我自己的技能库就是一个独立仓库需要的人可以直接clone来用。第五个原则是定期做减法。功能重复的技能只留一个效果不明显的直接删掉别心疼。5. 常见问题排查与Cleanup经验5.1 装不上、不加载、乱触发怎么办按我的经验skills相关的问题基本可以分三类。第一类装不上。通常是目录放错了或者缺少SKILL.md。检查顺序目标工具是不是支持skills - 目录路径对不对 - 技能文件夹里有没有SKILL.md - frontmatter字段格式对不对。这四个环节排查一遍九成问题能解决。第二类不加载。主要是语义匹配的问题。你可以在对话里明确提到技能名称比如“用代码审查技能检查这个文件”这样比隐晦的描述更容易触发加载。如果这样还是不加载把技能note里的description改得更贴近你的常用说法。第三类乱触发。比如你明明只让AI改个小bug它却非往“架构重构技能”上靠。这类问题多半是description写得范围太大需要把触发条件收窄加上“仅当用户明确要求评估架构时使用”之类的限定。5.2 技能冲突与加载优先级当装了多个技能时可能会遇到两个技能描述相近、上下文重叠的情况。我的建议是尽量精简技能库。一次维护两三个高频技能比堆二十个技能更可靠。万一真的遇到冲突先在SKILL.md的description里增加互斥条件明确“本技能不适用于XX场景”。如果还不行就停用其中一个。大多数工具加载技能是按目录扫描的直接把冲突技能目录改名或移到备份目录即可不必删除。5.3 关于清理什么时候该删、怎么删网上讨论skills清理方法的帖子不少我也强烈建议定期清理。我的经验是一段项目结束后把那些只服务这一个项目的技能移出用户级目录只保留项目级配置里连续两周没用过的通用技能考虑删除安装超过三个同类技能但效果都一般的全部删掉只留一个最顺手的。清理本身很简单删目录、改配置、重启会话三步。但要提醒一点删除前看一眼SKILL.md里有没有值得保留的内容比如某些示例代码片段可以先存到自己的笔记里。很多人的技能库越用越乱核心原因是舍不得删而不是不会装。我自己现在的做法是通用技能只保留代码审查、commit信息生成、CHANGELOG维护这三样其他的全部按项目放在项目级目录里。项目结束目录一删环境干净。最后再分享一个心得skills这个机制最妙的地方不在于它能让AI多聪明而在于它能逼着我把自己的经验、团队的规范、项目的边界想得更清楚。你写得越具体AI执行得越稳反过来它也会让你发现自己所谓的“经验”里有多少其实是模糊的直觉。试着把最常做的那个任务写成一份SKILL.md你大概率会回来感谢这个功能的。