最近是不是经常刷到“skills”这个词不是GitHub个人主页那个绿格子技能墙而是AI编程领域里真正在改变使用方式的新东西——给Claude Code、Codex、OpenCode这些编程Agent装上一个个“技能包”让它们在某些专业场景下表现得像换了一个人。我最早是从“superpower skills”这个仓库开始接触的后来陆续在几个项目里手动装过GitHub上的skills也踩了不少坑今天这篇就把整个来龙去脉和实操过程讲透。这篇文章不是单纯介绍某个工具而是把skills从“是什么、为什么火”一直讲到“怎么装、怎么写、怎么调试”全程拿我实际跑过的案例说话。内容覆盖Claude Code手动安装第三方skills的完整步骤、SKILL.md文件的结构与写作要点、自己开发skill的完整流程、常用skill源推荐以及我最头疼的几个报错和排查思路。适合正在使用或准备上手Claude Code、Codex、opencode的开发者也适合想把自己工作流沉淀成skills的人。1. 先把skills这层窗户纸捅破1.1 一个skill到底长什么样我刚开始接触时也以为这是个很高深的东西后来拆开一个真实仓库才发现它本质上就是一个带固定结构的文件夹my-skill/ ├── SKILL.md # 核心描述文件AI主要靠读它理解技能 ├── reference/ # 参考资料、模板、示例触类旁通用 ├── scripts/ # 可执行的辅助脚本 └── assets/ # 图片、数据文件等静态资源任何以目录形式存在的“技能”只要里面有SKILL.md就能被支持skills机制的Agent识别。我的第一个反应是“这跟配置文件有什么区别”后来在实战中才明白区别非常大。传统配置文件描述的是“系统应该怎么运行”而SKILL.md描述的是“当AI遇到某一类问题时它应该按照什么思维流程去处理”。前者是规则后者是工作方法。举个容易理解的例子普通提示词是告诉AI“你会写论文”而一个论文写作类的skill则是告诉AI“拿到题目先拆解需求再列提纲每章控制在多少字论证要有数据支撑最后必须附上参考文献列表”——这是一种可以反复调用、跨项目复用的行为模式。1.2 它跟插件、MCP有什么区别很多人问过我这个事skills跟插件到底什么关系其实我也是用一遍才真正分清的。用一个装修队的比喻可能更直观。MCP类似“工具箱里的电钻、水平仪”提供的是外部能力接口。比如让AI能查数据库、能操纵浏览器、能读本地文件这是“连接真实世界”的部分。Plugin/插件类似“施工规范手册”告诉AI哪些场景下可以使用这些工具以及用之前要做什么检查。Skill则更接近“老师傅带徒弟时的口头禅”面对特定活儿告诉AI应该按什么顺序、用什么思路、避免什么坑去做。放在实际项目中一个完整的方案往往是“MCP提供能力Plugin控制权限Skill决定思维”。我试过只装一个优秀的模型而不装任何skills遇到复杂任务时AI还是会陷入“该问的不问、该验证的不验证”的毛病。而装上了合适的skills之后它会把任务当成“按流程干活”而不是“自由发挥”。1.3 什么时候别用skill这里要泼一盆冷水。有一个很常见的误区以为skill越多越好、越强大越好结果装了几十个之后Agent反而变笨了。原因很简单大部分编程Agent会通过description对场景做“语义路由”也就是说每次任务它都要在脑子里过一遍自己有哪些skill、哪个匹配度最高。技能库太杂太乱路由就会不稳定甚至会选中一个风格完全冲突的skill。我现在养成了一个筛选规则如果一个工作流我用提示词就能稳定描述清楚就别硬做成skill如果它需要“多轮决策、分支判断、结构化的流程”才值得沉淀成skill。换句话说skill是为了把复杂流程固化成模板不是为了多装东西而装。2. 手动安装GitHub上的skills保姆级步骤2.1 先分清你怎么装、装到哪很多教程让你直接用Claude Code内置的“/install-skill”命令但实际使用中你会发现有些GitHub仓库并没有适配官方市场的目录规范或者你根本不想让某个第三方仓库直接获得安装权限。这时候手动安装反而是最可靠、最可控的方式。手动装之前先搞清楚目录放哪。以Claude Code为例当前版本同时兼容两种存放方式~/.claude/skills/ # 传统技能目录 ~/.claude/plugins/ # 新版插件目录可以再嵌套skills/大多数把“skills”作为核心功能的仓库比如anthropics/skills这个官方示例库都会在README里给一个目标目录。如果没有明说就默认放到~/.claude/skills/skill名称/。Codex、OpenCode各自有自己的配置目录后面会提到。注意目录名强烈建议用英文小写加短横线不要带空格和中文。这样后续agent解析文件路径时会少掉很多麻烦。2.2 完整的安装五步我把常用的手动安装过程整理成了五步每一步都用我踩过坑的版本写出来。第一步找到并且看清楚仓库结构。不要急着clone整个仓库。先在GitHub页面上看一下目录树判断它的顶层是不是一个规范skill目录。如果整个仓库就是“一个skill一个子目录”那要装的是里面的子目录不是仓库本身。第二步下载目标内容。两种方式任选# 方式A浅克隆整个仓库再拷贝目标目录 git clone --depth 1 https://github.com/example/skill-repo.git ~/tmp/skill-repo # 方式B直接用svn或者GitHub的Download ZIP下载压缩包后本地解压我实际更推荐方式B尤其当网络访问不稳定时压缩包一次性下载比git克隆更省心。下载后把对应文件夹拷贝到技能目录。第三步确认命名。拷贝完成后检查路径是否类似这样~/.claude/skills/code-review-master/SKILL.md这里最容易踩的坑是下载解压后文件夹名字常常带-master或-main后缀比如code-review-main。Agent解析技能名时会拿文件夹名当skill的内部ID所以最好把文件夹改成一个干净且有意义的名字比如code-review。第四步做一次静态检查。用编辑器打开SKILL.md确认YAML头部的name字段和实际文件夹名一致。如果不一致后续在路由时可能出现“明明装了Agent却不认识它”的诡异现象。第五步重启会话或执行一次刷新指令。以Claude Code为例重启会话最稳妥然后问它一句“你现在有哪些skills”它会扫描目录并列出所有可用的技能。如果列表里没有刚装的说明目录或格式有问题。2.3 装完怎么验证真的生效装完并不等于一定能用。手动安装的验证通常分三层。第一层确认能被发现。打开Claude Code后注意观察Agent在收到任务时会不会主动“复习”对应skill。很多Agent会在日志里打出“Loaded skill: xxx”之类的记录看到这个基本就稳了。第二层确认能按流程走。直接用一句测试指令触发它。比如装的是“code-review”类skill就给一段有明显错误的代码问它要怎么走审查流程。如果输出里带上了skill内定义的步骤编号或专属模板说明生效了。第三层确认没有覆盖冲突。如果同时装了多个类似功能的skill比如两个都叫“数学建模”Agent可能会在模型里混乱。安装阶段就尽量避免重复功能的技能。这里分享一个我自己的检验技巧在SKILL.md里加一个差值很小的特殊标记比如在最后加一句“本流程结束前必须复述校验码01A2”。验证时只要看它有没有输出校验码就能判断它到底有没有完整地执行整个skill流程而不是只凭大概记忆随便输出。3. SKILL.md到底怎么写拆开看3.1 frontmatter是路由命根子任何一个SKILL.md不管内容多复杂头部的YAML frontmatter都是最重要的。拿我的一个“数学建模题目拆解”skill为例--- name: math-modeling description: 当用户给出数学建模竞赛题目、要求建立数学模型、或者需要优化建模方案时使用。侧重问题拆解、模型选型与论文结构组织。 when to use: 适用于建模竞赛、课题研究中的数学建模部分不适合纯粹的代码调试任务。 ---name是内部IDdescription决定了Agent在什么时间、什么触发词下会想到这个skill。这一点极其关键——很多人的skill写得很好但description写得太泛比如“帮助用户解决问题”结果Agent根本不会在恰当时候调用它。我在写description时总结出一个公式触发场景 典型任务 明确的排除项。必须说清楚“什么时候应该用”也要说清楚“什么时候不该用”。when to use可以写得更口语化甚至带一些风格化的提示比如“当用户给出的是一个题目而不是一段报错时请优先考虑本技能”。它的作用不是给用户看的是给Agent做语义匹配用的。3.2 正文部分流程化而不是话痨化正文是整个SKILL.md的主体我强烈建议用“流程步骤 边界条件 校验点”三段式结构来写不要写成一篇散文。## 任务流程 1. 先复述用户给出的题目标注出所有已知条件与未知量。 2. 建立数据与变量清单检查是否有遗漏指标。 3. 选择至少三种候选模型并对比适用条件。 4. 输出推荐模型说明理由附上简化假设。 5. 论文结构建议提出问题→数据探索→模型构建→结果验证→结论。 6. 最后生成一份“下一步操作清单”供用户继续往下走。 ## 边界条件 - 如果题目中缺少关键数据不要自行编造必须向用户询问。 - 如果涉及随机过程优先考虑蒙特卡洛模拟类方法。 - 如果发现模型复杂度远超竞赛需要主动建议简化。 ## 校验点 - 在最终回复末尾检查是否包含“推荐模型”和“数据缺失项”两个必需小节。 - 如果步骤超过8步每步控制在150字以内说明避免冗长。这里有一个关键认知SKILL.md不是在给AI讲“知识”而是在给AI定“工作节奏”。它本身就是给模型看的提示词只不过用了一种高度结构化的形式让每个调用它的模型都能按同一个节奏走从而保证输出质量稳定。3.3 为什么这么写能提升稳定性我之前也试过把很多背景知识、微调经验直接塞进SKILL.md结果Agent每次调用时都要解析大量上下文反而导致关键指令被稀释。后来才意识到模型在调用skill时通常会优先读取frontmatter来做路由判断进入详细流程前还会做一次“是否真的适用”的确认。所以SKILL.md应该控制篇幅尽量在200行以内把最核心的流程和边界写清楚参考资料、示例模板放reference/目录通过相对路径去引用而不是一股脑全塞在正文里。这就像做饭时把调料放厨房而不是把所有瓶瓶罐罐都堆在餐桌上。4. 自己开发一个skill的完整流程4.1 第一步把“擅长的事情”拆成步骤很多人一上来就想写一个大而全的skill比如“写论文”“做数据分析”这些主题太宽泛写出来的SKILL.md往往空而无物。我的做法是先记录自己真正做这件事时的最少必要步骤。比如这段时间整理团队代码评审流程我先把平时的评审行为记录下来拉取变更、检查关键文件、优先看危险操作、类与接口的兼容性、异常处理是否完整、有没有安全硬编码。这些步骤拆出来之后skill的骨架就已经成型了。你完全可以这样操作下周无论做什么刻意记录自己处理任务时“先做什么、再做什么、卡住了怎么办”一周后把这些碎片整理成流程就是一个不错的skill雏形。4.2 第二步写初版先让技巧大于文采初版SKILL.md不需要太完美我把重点放在“可执行”而不是“可读”。上面那个数学建模的例子其实就是我的初版你会发现里面没有多少华丽的修辞都是指令式的短句。写完初版之后别急着发布直接扔给Agent实测。我用的是“模拟任务测试法”构造10个会触发该skill的问题依次交给Agent看它有多少次能按照定义好的步骤走完全程。如果命中率低于8成说明步骤描述还有歧义得继续改。这一步最关键的是分析Agent为什么没有按流程走。一般情况下出问题的总是frontmatter里的description写得不够具体模型压根没意识到该调用这个skill。4.3 第三步迭代与沉淀Skill写完之后不是一劳永逸。我最近维护的几个skill基本都会在每次实际使用后补一两句话把“这次遇到的问题”变成“下次的校验点”。举一个具体例子我早期写的代码审计类skill最初没有“敏感信息检查”步骤直到某次真在日志文件里发现硬编码密钥之后就立刻把这个步骤加进去了。Skill的成长应该是渐进式的。每用一次就在对应步骤下补一行“如果出现xx情况应该yyy”。时间久了这个文件就是你把隐性经验显性化的过程价值甚至超过当初装的那些第三方技能。5. 值得关注的skills来源与推荐清单5.1 公开来源速查表我整理几个自己实际体验过、且相对靠谱的来源不一定全但足够你起步。来源适合场景说明anthropics/skills官方入门与基础技能结构规范适合研究SKILL.md怎么写obrasen/superpower-skills学习、写作、规划类技能社区口碑高质量相对稳定codex nature skillsCodex用户专用面向Codex机制的技能集合typesafe ai skillsTypeScript/全栈项目偏工程实践的类型安全和全栈开发数学建模/竞赛类仓库建模竞赛、论文写作通常包含模型选型、论文结构等技能很多人问从哪里“下载skills”其实根本没有一个官方统一市场GitHub就是最大的源。你可以直接在GitHub搜“awesome skills claude”这种关键词也能找到聚合列表。5.2 superpower skills怎么用热词里被问最多的“superpower skills”确实值得单独讲一下。这个仓库和很多其他仓库不一样它不是单个skill而是一个包含多个子技能的大型集合比如study、write、plan等。我第一次安装时就踩了坑直接clone整个仓库到技能目录结果Agent告诉我没有发现任何有效skill。原因是用它需要把仓库里单个子目录独立拷贝到skills目录而不是把整个仓库当成一个skill。正确的安装其实超简单git clone --depth 1 https://github.com/obra/superpowers.git ~/tmp/superpowers cp -r ~/tmp/superpowers/skills/study ~/.claude/skills/study cp -r ~/tmp/superpowers/skills/write ~/.claude/skills/write装完后重点不是用而是学它的写法。我翻过它的SKILL.md里面的流程设计很考究比如“study”技能不仅在教AI如何拆解概念还要求AI把自己的理解画成知识图谱这种强制输出结构的方法很值得借鉴。5.3 数学建模与论文类推荐针对热词里提到的“华为杯建模比赛”和“数学建模skills推荐”我可以负责任地说不要指望一个skill能帮你“自动建模”但它能极大缩短你从读题到定思路的时间。我目前常用的三个组合是题目拆解类skill把比赛题目转化成明确问题、论文结构类skill按竞赛论文模板指导写作、代码检查类skill避免常见的数值计算符号问题。这三个配合起来一套比赛初稿的产出效率能提升明显。提醒比赛类skill最大的风险是“格式固化导致内容雷同”。建议使用后手动打散模板痕迹至少调整数据表格样式和章节顺序不要让最终提交的论文看起来像同一台机器批量生产的。6. 常见问题排查实录6.1 装完不生效Agent不认账这是我遇到最多的一个问题。排查顺序固定为先确认目录路径→再确认SKILL.md是否能被找到→再看frontmatter是否正确。经常有人在~/.claude/skills/下放置了一个没有SKILL.md的文件夹或者把SKILL.md放进了reference子目录Agent自然扫不到。标准做法是每次手动安装后执行一次“扫描确认”。Claude Code里可以直接问“你现在有哪些skills”如果列表里没有再打开文件检查编码。6.2 中文乱码和路径问题SKILL.md里的中文在部分客户端会出现乱码这种事我碰过两次。建议所有skill文件统一使用UTF-8无BOM格式保存不要用系统记事本默认的编码保存。另外如果skill文件夹路径中有中文目录名部分Agent在bash环境下解析会莫名失败整套技能直接失灵。我在团队内部约定英文名创建目录中文内容统一放文件内这样兼容性最好。6.3 Skill和MCP互相干扰一个容易被忽略的问题一旦某个动作既匹配了MCP工具调用又匹配了某个skillAgent可能先调用MCP工具把流程打乱之后才想起skill里定义的步骤最终输出内容两边不靠。遇到这种情况我的处理方式是在skill的frontmatter里明确写“当本技能被触发时优先执行SKILL.md内部流程外部工具仅用于获取数据不做决策”。说白了就是在skill里给Agent划定权力边界。6.4 团队协作时skill目录怎么管理如果你不是一个人用而是整个团队共享一套skill别再把目录散落在各人电脑上了。我现在的做法是把skills放成一个独立Git仓库客户端通过一个启动命令自动拉取同步。比如在Claude Code的配置里设置启动钩子cd ~/.claude git pull origin main这样每个人打开工具时技能目录都自动更新到最新版。配合Git分支做技能“评审”比让大家手动拷贝文件夹要稳得多。我个人的最终体会是skills的价值不在于“装得多”而在于“写得准”。试着把一个你日常最熟练的工作流固化成SKILL.md打磨一周再回头看你会发现AI产出的可信度有明显的变化。现在每开始一个新项目我第一件事就是建一个.skills目录把当前项目需要的工作步骤写进去哪怕只有十条。这个习惯比任何热门技能库都好用。