AI编程助手Skills指南：从原理到安装编写SKILL.md

最近明显能感觉到AI 编程助手圈子里被讨论得最多的一个词已经从 prompt 变成了 skills。不管你是 Claude Code、Codex 还是 OpenCode 的用户GitHub 上标着 skills 的仓库几乎一天一个样superpower skills、官方示例技能、各种社区合集大家都在往自己的配置里塞各种技能包。但很多人问的问题其实很具体skills 到底是什么GitHub 上的技能怎么手动装进去装了不生效怎么办以及到底什么样的 skills 才值得装、值得自己写。这篇文章就围绕这些真实问题展开。我会先讲清楚 skills 的本质和工作原理再列出常用的技能源网站与筛选方法然后给出逐工具的手动安装步骤最后用一个数学建模场景的实战示例带你完整写出一份能直接用的 SKILL.md。如果你是刚接触 AI 编程的新手这篇可以当安装手册用如果你已经在写自定义工作流中间关于描述词设计、清理维护的部分应该能给你一些新启发。1. skills 是什么本质上是一份给 AI 的 SOP 手册1.1 从 prompt 到 skills为什么现在大家都在谈技能化过去我们调教 AI靠的是把一大段指令塞进 system prompt。比如你是一个资深前端工程师请按照以下规范写代码然后把项目规范、命名规则、提交格式全部写进去。这种方式在小任务里没问题但一旦项目变大prompt 会膨胀到几千字模型上下文被占掉一大块而且每次对话都要重新强调一遍。skills 解决的正是这个知识复用问题。你可以把一个完整的做事流程拆成独立的技能包比如生成三线表做数据分析写周报评审代码每个技能包都是一个目录里面有一份 SKILL.md 文件来定义触发条件、执行步骤、输出规范。AI 编程助手在启动时会扫描这些技能目录当用户的问题和某个技能描述匹配时再把对应的文件内容按需加载进去。我习惯把它理解成给 AI 配了一套 SOP 手册。就像一个新员工入职时你不会把公司全部规章制度一次性塞进他脑子里而是给他一摞工作指引遇到哪类问题就翻哪本手册。skills 就是 AI 领域的那摞手册。它跟传统 prompt 最大的区别在于prompt 是一次性上下文指令skills 是可复用、可版本管理、可跨项目共享的结构化知识包。这也是为什么大家会说skills 是 AI 编程助手的插件生态雏形。早期想看模型表现好不好靠写 prompt 的玄学现在有了技能化体系你完全可以像搭积木一样把不同场景的处理逻辑拆成一个个独立文件跟代码一起放进 Git 仓库里管理。1.2 它和 MCP 有什么区别一个给工具一个给方法很多人刚开始接触 skills 时会把它和 MCP 混淆因为名字都像给 AI 加东西。实际上两者解决的问题完全不同。MCP 是给 AI 外接数据源和工具能力的它连接的是函数、API、数据库这些手。比如你接入一个文件读取 MCP 服务AI 就能直接操作本地文件接入一个数据库 MCPAI 就能执行 SQL 查询。MCP 强调的是我能调用什么。skills 则不是新增任何工具而是教 AI 遇到某类事情应该怎么一步步做完的流程知识。它解决的是我知道怎么做才是对的。同一个 MCP 工具在不同 skills 的约束下执行方式可能完全不同——比如同样能调用代码解释器数据分析的 skill 会要求输出缺失值报告而算法竞赛的 skill 会要求先分析复杂度。打一个比方MCP 像是给厨师配了更多厨具和食材skills 像是告诉厨师做川菜要先爆香、做粤菜要尽量保留原味。一个管资源一个管方法论。两者可以配合使用但在设计上要分开。我见过不少人把 MCP 配置和 skills 混在一起结果排查问题时根本分不清到底是工具没接上还是技能描述没触发。另外还要区分一下 subagent子代理和 skills 的关系。子代理是更聚焦的模型会话角色skills 是挂在会话里的流程知识。最新的一些工具已经允许技能包里声明自己的子代理配置但这属于进阶玩法。初期你只需要记住不会写子代理也可以正常用 skills它俩不是绑定关系。2. 去哪找 skills常用技能源与筛选方法2.1 官方与社区技能库先认准来源想要快速上手 skills第一步不是自己写而是先学会捡现成的。目前比较靠谱的来源有三类第一类是官方仓库。Anthropic 官方维护的 anthropics/skills 项目是很好的起点里面有好几个完整的示例技能比如构建网页工件、处理文档、生成 SVG 等。它的价值不在于数量多而在于你能看到官方对 SKILL.md 的结构规范和描写风格这是最好的范本。第二类是社区大合集。GitHub 上搜 awesome claude skills 或者 superpower skills 能翻到大量聚合仓库。其中 obra/superpowers 是流传比较广的一套主打开发工作流增强包含了一批精心设计过的技能覆盖代码规划、任务分解、测试驱动开发等环节。还有一些名字里带 typesafe、cola、nature 之类风格的集合各有各的侧重本质都是 SKILL.md 的集合选的时候看适用场景就行。第三类是各种skills 网页版技能库站点。有人把这些合集做成在线文档站方便你直接浏览每个技能的内容再决定要不要装。网页版主要用来查阅和复制实际使用还是要下载到本地。这里要特别提醒一句社区技能库的质量参差不齐。有的仓库 star 数很高但实际内容可能就是几百行口水话有的仓库很小却真的很能打。我的筛选标准有四个有没有完整的 SKILL.md、最近有没有更新过、description 写的是触发场景还是自夸广告、目录里有没有附示例数据。一把梭之前先 git clone 下来本地读一遍比在网页上翻半天都有用。2.2 分场景推荐清单前端、数学建模、AI 漫剧根据我自己的观察和实际使用不同场景对 skills 的需求差异非常大。整理一份推荐清单供参考应用场景推荐装的 skills 方向典型任务示例前端开发项目脚手架生成、组件代码规范、设计稿还原、代码评审帮我把首页的组件按这个规范重写一遍数学建模 / 数据分析赛题理解拆解、数据清洗、EDA 探索分析、LaTeX 论文排版生成三线表做数据分布分析AI 漫剧 / 内容创作角色设定一致性、分镜脚本、运镜提示词、台词润色根据这段设定生成 10 个分镜脚本通用办公会议纪要、周报生成、Markdown 排版、PPT 大纲把这通录音整理成待办清单前端开发的 skills 建议集中在规范约束上。单纯让 AI 写页面很容易但让它按你的组件库风格、目录结构、命名规则来写才难这正是 skills 的用武之地。把团队编码规范做成一个 skill比写在 README 里对 AI 的效果好得多。数学建模场景在华为杯这类比赛临近时尤其热门。竞赛类任务有很强的流程性拿到赛题先理解背景、再拆解问题、做数据预处理、选模型、写论文。每一步都能做成独立技能。这类技能的好处是就算你换队友、换电脑只要把 skills 目录跟着项目走AI 的解题习惯就不会丢。AI 漫剧属于内容创作赛道skills 的核心价值是一致性。角色长相、说话风格、镜头语言都是可以结构化的东西。把这些写成技能以后每次生成新桥段时AI 就会自动按照之前的设定来而不是每轮对话都像失忆了一样。我的建议是不要一上来就装几十个先挑三个最常干的场景各配一个用顺手了再扩展。技能多不代表能力强描述之间互相干扰反而会让模型频繁误触发。3. 手动安装 GitHub 上的 skills逐工具实操3.1 Claude Code 三步装好路径放对最重要以 Claude Code 为例手动安装一个 GitHub 上的技能其实就三步建目录、拉文件、重启会话。第一步在终端里创建技能目录。Claude Code 支持两个层级的存放位置用户级放在~/.claude/skills/全局所有项目都能用项目级放在当前项目根目录下的.claude/skills/只作用于这个项目适合团队协作。mkdir -p ~/.claude/skills git clone https://github.com/你的账号/技能仓库.git /tmp/skills-repo cp -r /tmp/skills-repo/具体技能目录 ~/.claude/skills/ ls ~/.claude/skills/具体技能目录第二步确认技能目录结构是否正确。最关键的是目录里面必须有一份SKILL.md文件。很多仓库会把一堆技能放在一起你只复制需要的那个子目录就行不要整个仓库直接堆到 skills 根目录下否则 Claude Code 扫描的时候会出问题。第三步重启会话。Claude Code 一般是在启动时扫描一次技能目录装完不重启的话模型大概率感知不到新技能。重启后可以直接问模型你当前加载了哪些 skills看它能不能列出来。部分版本还支持/skills之类的命令来查看可用技能具体可以进帮助菜单看。中途如果提示权限不足或者技能里引用的脚本无法执行还要检查一下对应文件是否有执行权限chmod x ~/.claude/skills/具体技能目录/scripts/*.sh3.2 Codex、OpenCode 等其他工具的路径差异如果你用的是 Codex 或 OpenCode安装思路完全一样就是路径不同。Codex 的常见技能目录是~/.codex/skills/项目级对应.codex/skills/。安装命令就是把上面例子里的路径替换掉。OpenCode 目前常见的是~/.config/opencode/skills/项目级放在.opencode/skills/。当然这些工具迭代很快路径偶尔会调整动手之前先看一眼各自官方 README 里关于 skills 的说明永远是最稳的做法。这里顺便回应一下热搜里skills 网页版进入这个词。很多人以为有某个网页可以直接开启技能其实网页版更多是浏览和查阅技能内容用的。真正要生效还是要把技能文件下载到本地对应目录不存在网页点一下按钮就全局生效的黑科技。还有一种更简单的装法有些仓库提供 zip 包你直接 Download ZIP解压后只拷贝目标技能目录到 skills 路径下效果和 git clone 完全一样。如果你只是临时用一次甚至可以直接用curl拉单个 SKILL.md 文件。但我不推荐这种一次性做法因为技能是要和维护的放进 Git 管理才是正经方案。3.3 验证安装是否生效装完不等于生效我无数次被这个问题坑过。验证分两步走第一步是结构验证。打开技能目录检查有没有SKILL.md、有没有把脚本文件放错层级。一个标准技能目录长这样my-awesome-skill/ ├── SKILL.md ├── scripts/ │ └── run.py ├── assets/ │ └── template.json └── examples/ └── demo.csv第二步是行为验证。在对话里输入一个和该技能 description 强相关的命令看模型是否真的按技能里的步骤在走。比如你装了一个三线表生成技能就让它把这段回归结果做成三线表然后观察输出格式是不是符合技能里定义的规范。如果模型完全没反应或者回答的格式跟技能里写的完全不搭多半是描述没触发或者路径没扫到。我自己的习惯是在每个技能目录里放一个examples/文件夹里面保存一两个测试用的典型请求。这样每次调整完技能我都能快速做回归测试不用靠脑子记忆当时是怎么验证的。4. 写好 SKILL.md自己动手开发一个 ai skill4.1 目录结构与 frontmatter 规范自己写 skills 没有想象中难但有几个规范值得认真对待。先看一个最小可用的 SKILL.md--- name:>--- name: eda-quickstart description: 数据集快速探索与描述性统计。当用户提供 csv、xlsx 数据文件或提到EDA数据探索描述性统计数据分布缺失值分析时使用。输出字段字典、缺失值报告、数值分布总结和相关性结论。 --- # 快速数据探索 ## 目标 对输入数据集完成一次标准化的探索分析输出四段式报告字段字典、数据质量、分布特征、相关性结论。 ## 输入要求 - 支持 csv、xlsx 文件 - 数据量较大时优先用 pandas 分块读取禁止一次性把全量数据载入内存 ## 执行步骤 1. 读取数据先打印 shape 和前 5 行样本。 2. 逐字段生成字段字典字段名、类型、非空数量、示例值。 3. 数据质量检查缺失值、重复行、异常极端值用表格列出。 4. 数值字段做分布分析均值、中位数、标准差、偏度、峰度并判断是否需要标准化。 5. 分类型字段做频次统计TOP 5 类别要单独列出。 6. 选取 10 个以下数值字段做相关性矩阵标出绝对值大于 0.7 的高相关对。 7. 汇总成四段式报告反馈给用户。 ## 输出格式 Markdown 报告每段必须有明确的二级标题。结论处必须区分数据事实和推测建议。 ## 禁止事项 - 禁止修改原始数据文件 - 禁止未做缺失值说明就进行填充 - 禁止输出超过 20 行的原始数据展示这段 SKILL.md 我实际在竞赛场景里跑过效果很稳定。它最大的特点是阶段性强命令每个步骤都要求模型产出具体的东西比如打印 shape列出 TOP 5 类别标出高相关对这样模型不会泛泛而谈。配套还可以写一个latex-table技能专门负责把 pandas 的 DataFrame 转成 LaTeX 三线表并把数学符号、小数位数规则写进去。这就是技能拆分的魅力把探索分析和结果排版分成两个技能各自独立触发比揉成一个巨无霸技能要可靠得多。5. 常见问题与清理经验实录5.1 高频症状排查速查表装了不少 skills 之后你一定会遇到各种不生效的问题。我把自己踩过的坑整理成一张速查表按症状排查效率最高症状可能原因解决办法装完后模型完全感知不到目录路径放错或没有 SKILL.md检查是否放在~/.claude/skills/这类正确目录下确认目录名与 name 一致看到技能了但永远不触发description 写得太泛缺少触发场景词重写 description用用户真的会说的原话来描述场景触发了但执行步骤混乱正文缺少强顺序编号在 SKILL.md 里给步骤加上明确的 1. 2. 3. 编号技能引用的脚本报错缺少依赖或执行权限不够检查 python/node 环境给脚本加chmod x权限多个技能互相抢任务description 描述重叠合并同类技能明确拆分边界加载速度明显变慢skills 目录太大、文件太多只保留高频技能把低频技能移出扫描目录最隐蔽的问题永远出在 description 上。模型的调用逻辑多半是根据用户问题和技能 description 的语义匹配来决定的如果你写的描述像广告词而不是搜索关键词那再好的技能内容也白搭。我写 description 的通用套路是当用户提到 A、B、C 时使用输入是 X输出是 Y。简洁、具体、像用户真的会说的话。5.2 一套可落地的 skills 清理方法网上有个流传较广的清理方法核心思路是三个词盘点、合并、裁剪。我练过几次之后觉得非常实用。盘点是指定期让模型列出它当前能识别到的全部技能。你可以在对话里直接问你现在有哪些 skills 可用然后把输出跟实际目录比对找出那些以为装了但根本没扫描到的问题项。合并是把功能重叠的技能合并成一个比如把生成三线表和LaTeX 排版合并成论文表格排版。技能之间边界清晰模型才不会误触发。裁剪则是把超过 30 天没用过的技能移出技能目录放到一个~/skills-archive/之类的备份目录里。我目前的生产环境长期只保留 15 个以内的技能。这听起来很少但每个都是高频刚需。技能数量一旦膨胀到 50 个以上模型每次做语义匹配的负担会变大误触发率也会明显上升。保持精简不是保守是稳定。另外技能也要定期迭代。我每次在实际任务里发现某个技能步骤不够格式不对漏了场景词会当场把 SKILL.md 改掉并提交到项目仓库。把它当作代码一样对待有版本历史、有 review、有问题回溯而不是一个写一次就永久不动的配置文件。5.3 我自己踩过坑之后的几点体会最后聊几句个人的真实感受。很久以前我也迷信技能越多越强往配置里塞了几十个从网上搬来的技能包结果日常任务里模型频繁把写周报和写会议纪要搞混输出格式乱七八糟。后来我专门花了一个下午做瘦身删掉三分之二从那以后干活反而顺了。还有一点就是好技能不是搜来的是改出来的。网上那些高 star 技能库更多是给你提供思路真正贴合你工作习惯的技能一定是从你自己的真实任务里迭代出来的。第一次用时把流程写成初版连用几周再逐步调整步骤和禁止事项它会变成你最顺手的那一套。所以我的建议是不用等学会再开始写下一件你频繁让 AI 处理的事就是你第一个自研 skills 的选题。从复制现成的开始用不顺手就改改到顺为止。这个循环才是 skills 体系真正值钱的地方。