最近如果你在AI编程工具圈子里冲浪大概率会被一个词反复刷屏skills。Claude Code这边刚把Agent Skills做成核心功能OpenAI Codex那边已经有人用skills跑完整套数学建模流程连OpenCode、superpowers这些项目都在往这个方向挤。我第一次看到skills这个词也懵了一下它到底是插件是提示词还是某种新配置文件后来把各家实现拆开看才明白skills其实是AI编程工具从会聊天走向会干活的关键机制。这篇文章不打算复读官方文档而是我装了一堆技能包、删了再装、踩了不少坑之后整理的一份实战笔记。如果你想给Claude Code手动装GitHub上的skills或者想搞懂前端开发、数学建模、AI漫剧这些场景里技能包该怎么选怎么配再或者想自己动手写一个AI skills这篇内容应该能给你一条直接复现的路径。1. Skills到底是什么AI编程工具里最容易被误解的新机制1.1 它不是插件也不是MCP很多人的第一反应是把skills当成AI插件这个理解最大的问题在于混淆了两套完全不同的工作方式。插件是代码要编译、要加载、有明确的函数入口它给模型提供的是实实在在的外部能力比如读写文件、调用API、操作数据库。skills则是一组结构化文本通常是一个目录里面放一个核心的SKILL.md文件再加上一些示例、模板、脚本资源。模型接到任务后会读取这份文本把里面的操作步骤和边界规则当成自己的行为准则来执行。打个比方插件是给模型增加手臂让它能碰到以前碰不到的东西skills是递给模型一本操作手册告诉它拿到某个任务时按什么流程拆解、注意哪些边界、输出什么格式。MCP则更容易和skills混淆因为现在不少项目二者都支持。MCP解决的是工具接入问题负责把外部系统和模型连起来skills解决的是流程规范问题负责让模型在特定场景下稳定按既定套路干活。一个是接食材的供应链一个是后厨的菜谱定位完全不同。1.2 一个Skill目录里到底有什么看一个典型的技能包结构就明白了skill-name/ SKILL.md examples/ input-demo.txt output-demo.txt assets/ reference-style.mdSKILL.md是整个技能的核心开头是YAML格式的frontmatter里面至少要有name和description两个字段。这两个字段不只是给人类看的更是给模型看的。模型在跑任务前会拿description和当前用户请求做语义匹配判断这个技能适不适合现在用。所以description写得含糊技能质量再高也大概率躺尸永远等不到被调用的一天。正文部分就是技能的操作手册什么时候触发、按什么顺序执行、有哪些雷区、最终输出用什么结构。模型并不是靠这些文本学会新知识而是靠它们约束自己在具体场景下的推理路径和工作方式。这其实是在模拟人类专家的行为——老师傅接到复杂任务不会直接上手先翻SOP确认流程再动手。skills就是把某个老师傅的SOP沉淀成了可以反复使用的数字文件。1.3 各家实现路径从配置文件看设计思路Claude Code用的是目录化skills放在~/.claude/skills或项目级.claude/skills下面OpenAI Codex用的是AGENTS.md体系把技能拆成Markdown章节通过codex skills add这样的命令管理OpenCode这类终端AI代理则把skills放在~/.config/opencode/skills。形态虽然不一样核心思路一致用结构化文本让模型按固定流程干活。这个模式在2025年集中爆发最直接的原因是上下文成本。模型窗口再大也不可能每次任务都把几百页行业文档喂进去。skills是按需加载的平时不占上下文当任务匹配到description时才去读取完整内容。对API成本和响应速度都很友好。这也是我愿意大量使用skills的根本原因——它不是让AI更聪明而是让AI更可靠把提示词工程变成了可复用、可分发、可版本管理的东西。2. 技能生态第一步从superpowers到GitHub源仓库安装前先看明白2.1 superpowers最出圈的工作流技能合集社区里讨论度最高的技能包之一就是superpower skills对应GitHub上的obra/superpowers项目。它把一套超能力工作法固化成Claude Code能直接调用的技能覆盖头脑风暴、深度写作、任务规划这类通用场景。这些技能的共同特征是包含完整的执行框架比如写一篇文章它会要求你先定义读者再定核心论点再写大纲然后逐段展开最后做自检清单。这套流程如果靠你每次打字给模型十有八九会漏步骤固化成技能文件之后模型每次都会老老实实走完整套流程。安装方式不复杂官网README里写得很清楚。大体是clone仓库后把对应技能目录复制或链接到你的skills目录git clone https://github.com/obra/superpowers.git cd superpowers # 按README说明把技能目录复制到 ~/.claude/skills 下有一点要提醒superpowers这类工作流技能包的价值不在于功能数量而在于流程完整性。它提供的不是零散的提示词片段而是一套带检查清单的操作框架。装完别急着删掉那个仓库目录后续版本更新时方便拉取对比。2.2 技能从哪里来值得收藏的检索与下载路径现在技能包的来源大致分三类。第一是官方仓库比如Anthropic官方放出来的skills示例质量和风格都稳定适合当学习样本。第二是社区聚合仓库像typesafeai/ai-skills这类会把公开技能按场景分类整理省去一个个逛GitHub的时间。第三是个人项目GitHub上有大量单技能仓库往往解决非常具体的问题比如生成API文档检查提交信息规范按团队风格重构代码。检索时直接在GitHub搜组合词就行比如claude skillscodex skillsfrontend skills或者math modeling codex skills。很多仓库还提供网页版浏览入口直接在浏览器打开仓库里的docs目录或SKILL.md预览页面不用clone就能看到完整内容这就是skills网页版入口的实际用法。下载方式通常是git clone或下载zip对于单个文件形式的技能直接在网页上复制内容到本地新建目录也可以。这里多说一句搜索技巧要看SKILL.md的具体内容别只盯着star数量。我见过一个四五千star的技能合集里面一半以上的description写得像help with everything这种就是典型的花架子。点开仓库里的SKILL.md如果看不到可执行的步骤和边界规则基本可以判断它只是个提示词合集不是真正意义的skill。2.3 各家安装入口与目录对照表根据我的实际使用经验各工具的技能安装路径可以整理成下面这张表工具用户级安装目录项目级目录主要命令/入口Claude Code~/.claude/skills/.claude/skills//skills、/pluginOpenAI Codex~/.codex/AGENTS.md或codex skills addAGENTS.mdcodex skillsOpenCode~/.config/opencode/skills/.opencode/skills/配置文件直接读取superpowers按README复制到对应工具目录项目内亦可手动clone这张表的路径在不同版本下可能略有差异但大方向不会跑偏。装完之后的第一件事一定要在工具里列出所有已识别的技能确认它真的被加载了再谈使用。很多我装了技能没反应的问题其实都是在这一步就能发现的。3. Claude Code手动装GitHub技能包从目录结构到排查链路3.1 先确认仓库结构别急着clone很多人手动装skills失败的根因是把整个仓库当成了一个技能包。比如你在GitHub上找到一个叫awesome-ai-skills的资源合集里面塞了几十个子目录直接clone到~/.claude/skills下面结果就是什么都没识别——因为所有SKILL.md都嵌套在更深层的子目录里。正确做法分两步。先看仓库根目录有没有SKILL.md如果有这个仓库本身就是一个技能包可以整体clone如果没有就进到子目录里找把包含SKILL.md的那一层复制到skills目录并保证目录名和skill的name一致。3.2 用户级与项目级安装的具体操作用户级安装的意思是全局都能用。执行git clone https://github.com/作者/仓库名.git ~/.claude/skills/仓库名然后重启Claude Code会话输入/skills新技能应该出现在列表里。项目级安装则只在当前项目生效。在项目根目录建.claude/skills把技能目录复制进去就行。好处是技能跟着仓库走不会污染其他项目也方便团队共享——只要把.claude/skills提交到git仓库队友拉下来就能拥有完全一样的工作流。实际操作中有一个高频坑从GitHub克隆下来的目录名往往带着-main或-develop后缀而SKILL.md里frontmatter声明的name又是另一个名字。目录名和name对不上会导致技能显示异常或调用失败。我建议clone完成后顺手改掉目录名让它和skill的name保持一致。3.3 装完不生效的排查链路如果/skills里没出现新技能按下面顺序排查确认路径没有多套一层目录。最容易犯的错误是clone到了~/.claude/skills/仓库名/仓库名/技能被多包了一层扫描不到。确认SKILL.md位于技能目录的根层而不是在子目录或examples文件夹里。确认文件编码是UTF-8且没有BOM。在Windows下编辑过的SKILL.md容易带BOM会导致frontmatter解析失败。重启会话。Claude Code在启动时扫描技能目录会话中途放进去的文件不一定能被热加载。最后做一个最小化测试把技能目录临时改成最简单的结构只保留一份SKILL.md排除是自己写错了frontmatter。这套排查逻辑同样适用于Codex和OpenCode只要把路径替换成对应工具的目录就行。3.4 装多了怎么办tibo式精简法技能装到一定数量后真正的问题不是不够用而是太多太杂。社区里tibo分享过一套清理思路我实践之后觉得非常有效。先把所有技能列出来把每个技能的description抄到一张表里凡是出现useful for many thingshelp with everything这类万金油描述的基本可以淘汰。再看语义重叠比如已经装了一个代码审查技能又装了一个Python代码质量检查这两个大概率会在同类任务里互相干扰保留那个场景边界更具体的。清理时把不确定的技能先移到备份目录而不是直接删除观察一到两周发现真的没再用过再彻底删掉。整个过程配合git管理随时可以回滚。这套方法解决的核心问题是技能选择困难技能越多模型在任务匹配阶段的判断成本越高甚至可能选错。把技能库精简到十个左右每次触发又快又准。4. 场景选型实录前端、数学建模、AI漫剧分别该装什么4.1 前端开发讲究约束力而非堆功能前端开发是我个人用技能最频繁的场景。装过一圈之后发现这个场景真正需要的不是多才多艺的大而全技能而是带强约束的规则型技能。前端痛苦点在于模型改代码时乱动无关文件、组件样式不统一、代码结构反复变化。好的前端skills应该明确约束只允许修改哪个目录下的文件样式优先使用design system token生成页面时先补响应式适配再考虑视觉细节。搜索关键词可以考虑frontend skillsreact component skillsdesign system skill。装完之后强烈建议自己改一遍SKILL.md把你所在团队的前端规范写进去hooks命名规则、错误处理方式、样式方案选型。技能文件是死的你的项目约束是活的不改写成自己的版本它永远只适配原作者的环境。4.2 数学建模华为杯场景下的Codex Skills组合数学建模比赛这两年越来越多人用AI工具华为杯这类赛题尤其看重流程管理。Codex skills在这块的优势是能用AGENTS.md承载完整建模流程。一套实用的数学建模技能库通常包含数据清洗技能、特征工程技能、模型选择对比技能、论文排版技能。甚至有人专门做nature skills把学术期刊写作风格封装成技能让模型输出的章节更接近论文语言。我的建议是不要幻想一个技能解决所有问题而是按竞赛阶段拆解。比赛第一天用数据清洗技能快速处理数据第二天切模型对比技能批量调参最后再用论文写作技能出报告。每个技能只负责一小段流程能显著降低模型在长时间、多步骤任务中跑偏的概率。GitHub上搜codex skills math modeling或者数学建模skills推荐能看到不少竞赛选手整理的现成配置拿下来改改就能用。4.3 AI漫剧与内容创作分镜脚本和角色一致性怎么拆AI漫剧是今年内容创作圈很火的方向核心流程是用AI批量生成漫画风格连续剧情的视频。这个场景里最需要的技能不是生成画面而是保证角色一致和标准化分镜。常见做法是拆成三个独立技能角色设定技能维护一个角色档案文件包含外貌、性格、口头禅生成画面时统一引用。分镜脚本技能规定分镜格式字段镜号、景别、台词、动作、时长让每集产出格式完全一致。风格一致性技能把画风关键词和负面词固化到技能文件里避免每一帧风格飘移。这些技能的定位都是确定性。模型本身不缺生成能力缺的是稳定的输出规范。有了这三个技能AI漫剧的生产流程才能从碰运气变成可复制。4.4 选型原则为什么最新最热不一定适合你社区里经常会冒出一些以缩写或颜色命名的小型技能包比如cola skills名字看着很唬人。我的处理原则很简单先看仓库最近提交时间超过半年没更新的直接排除再看description是否针对具体问题泛泛而谈的排除最后在隔离环境试跑一次效果不好就卸。选型最核心的判断标准是你的工作流缺哪一个环节而不是哪个技能最近火。技能不是越多越好也不是越新越好是越匹配越好。你每天实际在做的事才是skills应该服务的对象。5. 自己动手写AI Skill把经验文本化的完整流程5.1 写Skill前的三个自问动手写skill之前先回答三个问题。第一这个任务是高频的还是一次性的一次性任务不值得写技能写的过程比执行还费时间。第二这个任务的流程是不是稳定如果你的做法每次都在变固化下来反而会拖后腿。第三模型不靠这个技能会错在哪这个问题最关键——技能要解决的是模型的薄弱环节而不是重复常识。很多人写技能失败是因为把技能写成了通用提示词满篇都是请更仔细请做得更好这类无法执行的废话。技能文件必须像检查清单一样具体模型才知道该怎么落地。5.2 SKILL.md的标准结构与写作逻辑一个合格的SKILL.md通常长这样--- name: code-review description: 对提交的代码进行严格审查重点检查边界条件、错误处理和安全性。当用户要求review代码或准备合并PR时使用。 --- # 用途 在代码合并前执行审查步骤。 # 工作流程 1. 读取目标文件理解本次变更范围。 2. 逐行检查边界条件、异常处理、资源释放。 3. 按严重程度输出问题列表。 4. 对每个问题给出修改建议。 # 规则 - 不修改代码文件只输出审查意见。 - 不讨论与本次变更无关的代码。 - 输出格式优先级 | 文件:行号 | 问题 | 建议 # 示例 输入: [一段待审查代码] 输出: [高优先级 | utils.py:23 | 未捕获空列表 | 增加前置判断]frontmatter里的name最好不要有空格description一定要具体到什么条件下被触发。正文部分越像检查清单模型执行越稳定。规则部分重点写不要做什么对模型来说负面约束往往比正面要求更有效。5.3 示例一个代码审查Skill的诞生过程我实际写过一版代码审查技能第一版只有一句话请审查代码并发现问题。结果模型输出的全是格式问题真正的逻辑错误一个没抓到。后来我改成上面这个结构加了边界条件资源释放错误处理三个必查点又把规则改成只审查本次变更的文件输出质量立刻上来了。这个变化说明了一个道理技能的效力来自约束不来自文采。你把模型当成一个刚入职的实习生给它的SOP越具体它的产出越稳定。写技能的过程本质上就是给模型写一份不会遗忘的入职培训手册。5.4 调试与迭代技能不是一次写成的写完skill第一步先手动触发一次看它有没有按预设流程走。第二步故意给一个边界case看规则会不会生效比如在代码审查技能里塞一个空文件、一个可执行任意命令的反序列化漏洞看技能会不会真的拦截。第三步放进真实项目观察一段时间收集失败案例再去改SKILL.md。我习惯把skills目录用git管理每改一版就提交一次之后可以对比不同版本在相同任务上的表现差异。如果调试中发现模型完全无视某条规则优先怀疑规则表述太模糊。比如注意代码质量远不如不要在未处理空值的情况下直接索引数组。把规则写成可以判断真假的句子模型才容易遵守。6. 学习Skills的正确姿势与长期维护建议6.1 高效学习路径读、抄、改、测怎么系统学写skills我的路径比较笨但有效先去GitHub把明星技能仓库的SKILL.md全部读一遍留意它们怎么描述触发条件、怎么组织工作流、怎么用规则约束边界。然后挑一个和你的工作最接近的技能抄下来把里面的例子和规则改成自己的场景。最后反复测试。很多初学者会纠结我是不是得先系统学一遍YAML才能写frontmatter完全不需要。SKILL.md的frontmatter核心就两个字段name和description其他的都是锦上添花。先跑通最小可用版本再慢慢补充。技能的核心是文本组织能力不是技术复杂度这也是它比插件门槛低得多的原因。6.2 长期维护用Git管理技能库定期按场景清理最后聊聊长期维护。我的建议是把你所有工具的技能目录整个变成一个git仓库每次增加或删除技能都留一次commit记录。这样万一某个新技能不好用回滚就是一条命令的事不用怕删错。定期清理的节奏可以跟着项目走一个项目结束把只服务这个项目的技能移到归档目录开始新项目时再去技能库里重新组合。tibo那套精简法的核心思想就是让技能库始终保持小、准、快。我现在日常维护的技能稳定在10到15个每个description都写得像搜索引擎的索引条目一样清楚模型在选技能时几乎不会犹豫。这套体系的收益是长期的你每个项目积累的SOP都在往里沉淀越到后面你的AI工作流越接近一个真正熟悉你习惯的老同事。