AI编程Skills指南：安装、编写与工作流落地

1. 从“提示词”到“skills”一次正在发生的工作流升级最近我身边聊AI编程的人开口闭口已经很少提“提示词”三个字了说得最多的是“skills”。不管是Claude Code、OpenCode还是Codex各家命令行工具都把skills当成核心功能在推GitHub上打着“awesome-skills”旗号的仓库一个接一个冒出来。你不是在收藏夹里存了一堆skills链接就是在纠结“Claude Code怎么手动装GitHub上的skills”。这个变化其实很自然的提示词是一次性的话术MCP是给模型接外部工具的手而skills是想把“某个领域的完整工作方法”固化下来让模型一进入对应场景就知道该按什么流程干活什么时候该调用哪个工具最终输出什么格式的结果。先说人话版本。skills本质上是一份带固定结构的文档通常是一个目录下放一个SKILL.md文件里面写清楚这个技能是干嘛的、在什么条件下触发、分哪几步执行、中间要遵守什么规则、最后交付什么成果。模型拿到这份文档后会在你触发它时把它当作“岗位说明书”来用。比如你写了一个“数学建模赛题分析”的skill模型一碰到建模比赛题目就会自发地按你写好的流程走先拆题目需求、再列假设、再选模型、再规划灵敏度分析而不是每次都从零开始瞎猜。这个思路能流行是因为AI编码这件事已经从“模型能写代码”进化到了“模型能在复杂任务里稳定交付”。写代码的能力模型已经不缺了缺的是可复用的流程和约束。哪里需要稳定的工作流哪里就需要skills。前端开发要统一组件规范数学模型要统一步骤AI漫剧要统一分镜生成流程这些全都是skills的典型主场。1.1 skills到底给模型加了什么很多人刚接触时会想skills不就是把它塞进system prompt里的提示词吗真不是。提示词是你临时发给模型的聊天内容对话一多就被冲淡了skills则是一个可以被主动查询、按需加载的结构化知识包。模型会先判断当前任务和哪个skill匹配匹配了再把整个skill文档加载进来。我比较喜欢用一个类比提示词是你给临时工口头交代“今天把地扫了”skills是给正式员工一份《保洁SOP手册》里面有清洁范围、操作顺序、验收标准、工具清单。同一个员工有手册和没手册干出来的活稳定程度完全不一样。AI模型天生擅长自由发挥skills就是用来压制这种自由发挥、把输出拉回正轨的。更进一步说skills还能封装“经验”。比如你反复做前端页面评审发现最容易出问题的是空状态、字体层级、间距体系那你把这些经验写进一个“前端UI review”的skill里以后每次让模型评审页面它都会自动按这套清单查。团队里其他人也能直接用这个skill经验就从一个大脑复制到了所有协作者手里。1.2 skills、MCP、提示词的分工关系这三样东西放一起容易搞混我直接列个对比表是我自己实践后整理出来的维度提示词MCPskills本质一次性指令外部工具接入协议结构化工作流知识包作用对象单次对话模型调用的外部工具模型长期的执行方式复用性低每次都要重新写中工具可复用高整个方法论可复用典型例子“帮我把这个组件改成暗色”GitHub API、数据库查询“前端页面评审五步法”失败模式模型发挥不稳定工具链报错skill不触发或流程僵硬核心结论是skills负责“告诉模型怎么干活”MCP负责“让模型手里有工具”提示词负责“启动这一次任务”。三者不冲突实际上一个好用的skill里经常会引用MCP工具。比如你的“数据分析”skill里写着“需要读取数据库时调用mcp__database查询”模型就会在对应步骤自动去调MCP工具两者是联动的。社区里曾经很火的superpower skills就是把一大堆现成方法封装成了skills集合确实降低了上手门槛。但我实际用下来之后的态度是直接抄袭配置不如自己动手写。原因很简单你用了别人的skill就等于把工作方法外包给了一个你管不住的黑盒一旦版本更新、工具名变动你连哪里坏了都找不到。自己写哪怕粗糙一点至少每一条规则都知道是为什么。1.3 我看到的最值钱的几个使用场景按照搜到的热点词盘点一下目前反馈最集中、最经得住实战的skills大概有这么几类前端开发场景统一页面结构、组件命名、样式规范模型生成页面时不会天马行空乱造组件适合做前端页面快速生成和代码审查。数学建模场景包括华为杯、国赛这类竞赛赛题分析步骤、模型选型依据、灵敏度分析方法都可以打包成skills比赛时直接让模型按流程工作能省掉大量重复组织语言的时间。AI漫剧创作分镜、角色一致性描述、转场逻辑这类内容高度模板化固定成skill之后生成质量稳定得多。代码仓库治理模型改代码前先读一遍项目说明修改完自动跑测试这类“流程类skill”特别适合做团队规范落地。这几种场景有一个共同点任务的输出标准是明确的步骤是可以穷举的失败的成本又很高。凡是这类活儿都值得固化成skills。2. 5分钟手动装一个GitHub上的skills并让模型认得它不少人不习惯用现成的安装命令或者只是想体验一下更倾向手动从GitHub装。这个需求太常见了我就拿Claude Code举例把完整路径和步骤写清楚。整体说得极端一点手动装一个skill一共就三步改目录、放文件、让模型重新加载。2.1 去哪些地方找你想要的skill先解决“去哪找”的问题。我最常用的渠道是GitHub直接搜关键词用“awesome skills”加上工具名能找到很多聚合列表。那些列表里收录的仓库质量普遍有保证毕竟能被加进合集意味着作者维护过一段时间。另外也会看官方示例和头部团队的公开仓库老牌的那几个agent skill仓库更新频率高参考价值大。判断一个仓库靠不靠谱我一般看三个指标第一仓库里有没有规范的SKILL.md文件而不是只有一堆零散文档第二目录结构是不是按“每个技能一个子目录”组织的命名是否清晰第三最近一个月有没有提交记录长期不更新的skills大概率已经跟新版本模型脱节了。满足这三点才值得clone。2.2 Claude Code手动安装的三个步骤第一步找到Claude Code全局skills目录。默认路径是~/.claude/skills/如果目录不存在就手动创建mkdir -p ~/.claude/skills第二步把你下载好的skills目录放进来。最简单的办法是clone整个仓库后把其中需要的技能子目录拷贝到skills目录下面。比如我在GitHub上下了一个仓库里面有个叫frontend-review的skill那结构就是~/.claude/skills/frontend-review/SKILL.md注意一定是“技能名目录之下直接放SKILL.md”中间不要多套一层。很多人装完不生效十有八九是路径多套了一层比如变成了~/.claude/skills/仓库名/frontend-review/SKILL.md那模型就找不到。第三步用/skills命令列出来验证。如果列表里出现了对应的skill名字说明加载成功了。没出现的话先检查是否当前会话还在用旧缓存重启一下会话再看。这里有个很容易忽略的点有些工具对新增skill是支持热加载的有些不行最好是装完就重启一次新会话省得排查半天。2.3 opencode、codex等工具的位置差异除了Claude CodeOpenCode、Codex这些命令行工具也在做类似的事但目录位置和配置方式不完全一样。以opencode为例它的配置目录通常在用户配置目录下技能相关文件也放在那里具体子路径各版本之间有差异。Codex那边的定位也一直在调整有的版本会直接读取项目目录下的约定位置。这里我给一个通用原则先看对应工具的官方文档里怎么描述“skills”“agents”“command”的存放路径不要拿Claude Code的路径生搬硬套。我自己就因为想当然把Claude Code的目录套到另一个工具上结果模型根本不认来回折腾了半小时。工具之间的差距不大但“不大”不代表可以忽略。2.4 一次别装太多上下文成本的真实账另有一个悬崖要提醒别一次性装几十个skills。我见过有人从GitHub上拉了一堆明星仓库一口气装了四十多个结果用的时候模型光判断该用哪个skill就磨蹭半天而且每次加载相关文档都会占用上下文窗口。上下文窗口就那么大塞了skills文档留给实际任务的空间就小了输出质量必然下降。个人经验是在日常项目里保持五到十五个活跃skill比较舒服。全局只留高频通用的项目相关的skill放到项目目录下面按需加载这样既不会占太多上下文又能保证每个skill被触发时都是精准的。3. 手把手写一个能上手的skill以数学建模赛题分析为例网上流传的skills越多你越会发现一个事实真正好用的skill都是自己写的。别人不知道你的具体场景写出来的规则再漂亮也隔着一层。这一章我拿“数学建模赛题分析”当例子完整带你写一遍。这个场景正好从搜索结果里能看到大量需求华为杯这类建模比赛大家找的就是能直接用的skills。3.1 SKILL.md的骨架和frontmatter写法先看一个最精简的文件结构。任何skill的最核心文件都是SKILL.md其他辅助文件都是可选的。第一步是写frontmatter也就是文件开头用---包起来的元信息区--- name: math-modeling-analyzer description: 适用数学建模竞赛赛题拆解帮助制定建模方案并输出可执行的分析计划包括问题重述、假设清单、模型选型、算法步骤和灵敏度分析。 ---description是skill的灵魂。模型能不能在合适的时机想起你这个skill全靠它读description做匹配。写得越具体越包含触发词、场景词、任务词匹配就越准。像“数学建模”“赛题”“分析计划”这些关键词都要出现在description里但别写太长两三句话足够。有些版本的skill定义还支持在metadata里写工具权限字段用来限制这个skill可以调用哪些外部工具具体字段格式建议打开对应工具的官方文档确认因为不同工具的字段差异很明显。写错了模型未必会报错但权限不会生效。3.2 正文怎么组织模型才不跑偏frontmatter下面是正文。我实践下来的最佳结构是“原则、步骤、约束、输出格式、示例”五段式。原则部分是给模型定基调的比如“你是一位数学建模竞赛教练”“先理解问题再选模型禁止直接套模板”步骤部分按顺序写清1、2、3、4步约束部分写清绝对不能做的事输出格式部分规定最终交付的markdown结构示例部分给一个标准样例。以数学建模赛题分析为例正文可以这么写## 执行流程 1. 问题重述用不超过300字复述赛题核心目标列出题目给出的约束条件和数据资源。 2. 假设清单整理建模需要的前提假设每条假设说明必要性并标注对结果可能的影响。 3. 模型选型根据问题类型给出候选模型对比表推荐首选模型并说明理由。 4. 算法步骤按输入、处理、输出的顺序描述实现路径关键参数要写出初值和调整方式。 5. 灵敏度分析定义需要检验的关键参数说明改变参数后如何评估结果稳定性。 ## 输出格式 使用Markdown输出包含“问题分析”“模型方案”“算法实现”“灵敏度分析”四个一级标题。 ## 禁止事项 - 禁止在未确定数据类型前直接推荐梯度提升等复杂模型。 - 禁止忽略量纲问题所有公式必须标注单位。这里的关键是给模型“约束”而不是只给“指引”。模型天然倾向自由发挥你把“禁止事项”写得越具体模型踩雷的概率越低。我最开始写skill的时候只写了流程和步骤没有写约束结果模型还是会自作主张地跳过中间环节加了禁止事项之后输出才真正稳定下来。3.3 想让skill调用外部工具权限这样配如果你的skill需要调用外部能力比如读取数据文件、查询数据库、拉取接口那就涉及工具调用。现在的做法通常是两条路一是在skill文档里直接用工具名写清楚比如“读取Excel时调用工具mcp__excel_tool__read”二是通过工具的权限配置去限制该skill可调用的工具范围。我的建议是文档里写清楚要调用的工具名同时在配置层面放开最小权限。写工具名的时候务必用全名尤其是MCP工具名字里可能带了mcp__前缀和服务器名。有一条重要经验skill里面写到工具调用时一定要写“如果工具不可用则给出替代方案”。比如你写“先调用数据库查询若连接失败则提示用户检查数据库配置”。不写这层兜底模型调用失败后往往会卡在那里反复重试白白浪费时间。3.4 项目级skill与全局skill怎么取舍最后说存放位置。你完全可以把skill放在项目目录下一般对应.claude/skills/之类的隐藏目录。项目级skill适合团队协作跟着代码仓库走同事clone下来就能直接用全局skill放在用户目录什么项目都能用适合个人高频场景。我的划分标准很简单凡是跟具体业务绑定的放项目级凡是跟工作方法相关的放全局。比如前端开发规范是项目级赛题分析方法就是全局级。这样既不污染其他项目又能保证团队新成员一进入仓库就能获得同样的工作流能力。4. 不同场景的skill写法差异前端开发、漫剧创作、代码审查一个skill模板走天下是不现实的。不同场景的稳定性要求不同输出颗粒度也不同。我在实际项目里同时维护过前端开发、漫剧创作和代码审查三种skill感受非常深分开讲讲。4.1 前端开发skills重规范、轻自由发挥前端开发是skill落地最普遍的场景之一。生成页面、写组件、做评审只要把公司的规范写进skill模型产出的质量会直线上升。比如写一个“前端页面生成”skill重点要写清楚组件文件怎么命名、样式用什么方案、响应式断点用哪几档、公共组件必须从哪个目录引入。前端skill最容易犯的毛病是写得太细把每个页面该怎么布局都规定了结果模型生成出来的页面千篇一律。更好的写法是只定“红线”和“规范”比如“所有按钮必须支持键盘操作”“所有图片必须写alt属性”“组件库中没有的组件不允许新建”让模型在框架内自由发挥。还有一点前端开发skills非常适合结合代码审查。我写过一个“UI review”skill里面列了二十条常见问题空状态没处理、按钮层级混乱、间距用魔法数字、色彩对比度不达标等等。每让模型做一次审查它就会逐条核查并输出报告效率比人工review高太多了。4.2 AI漫剧skills拼的是流程稳定性AI漫剧这个场景这几年特别火核心问题是流程长、环节多从剧本、分镜、角色设定到画面生成每一步都容易风格漂移。这种场景下skills的作用是把整个生产流程固定下来。我的“漫剧分镜”skill写下来最重要的部分是角色一致性描述模板每个角色出场前必须在画面描述里附带固定的外貌特征短语不能每次用不同说法然后是分镜脚本的格式每一镜都要有景别、时长、画面描述、台词、转场方式五个字段。这些要求写进skill后模型生成的分镜就不再是乱糟糟的一堆文字而是整齐的表格。另外这个场景里有大量内容合规、正向引导的要求。我在skill的禁止事项里会强制写上“不得生成暴力、低俗及违背公序良俗的内容遇到敏感题材主动规避”。这一条既是底线也是让模型在创作过程中不跑偏的护栏。4.3 代码审查skills小但超值代码审查skills我愿称之为“性价比之王”因为写起来只需要几百字但每次用都能省下大把人工review时间。核心是把你们团队平时review容易提的问题沉淀成清单比如“函数是否超过80行”“错误处理是否覆盖了空指针分支”“有没有重复造轮子”“日志是否泄漏敏感字段”。真正的写法要点是让skill充当“检查员”而不是“修改者”。我会明确要求它“只输出问题和修改建议不要直接改代码”。改代码和分析问题的逻辑是不一样的一旦让模型顺手改了审查边界就会模糊问题清单质量也会下降。前端、漫剧、代码审查三个案例放在一起看你会发现一个共通的规律skill写得好不好取决于你对自己的工作流程熟不熟悉。如果你连自己平时先干什么后干什么都说不清楚那写出来的skill必然也是模糊的。5. 我踩过的skills深坑问题排查与避坑实录市面上光鲜的宣传贴很多真正干活时踩的坑没人说。我把过去几个月反复遇到的几类问题整理出来按“现象、原因、解法”的格式写希望能帮你少走弯路。5.1 装了半天模型就是不认最经典的现象就是skill装完了模型却视而不见。原因大概率是路径不对或者文件名不对。我一直强调SKILL.md必须放在“技能名目录”的根下文件名必须严格叫SKILL.md大小写都不能错。我一开始就吃过大小写的亏目录名大写、文件名小写结果模型直接无视。另一个隐蔽原因是旧会话没有重新加载。有些工具对skill是会话启动时扫描的中途新装的skill要等下一次会话才可见。排查的时候先重启新会话再不行就检查目录结构最后再检查文件内容有没有语法错误。别一上来就怀疑工具出了问题八成是你自己的路径问题。5.2 触发了但输出一点不“skill”skill确实被触发了模型也读了文档但输出的质量跟没装之前没什么区别。这一般是skill正文写得“太软”。什么叫太软就是通篇只有“请你认真分析”“请参考最佳实践”这种正确的废话没有可检验的硬性约束。我自己踩过一次比较深的写“竞品分析skill”的时候只写了分析维度没有写输出模板。模型每次分析都给我完全不同的格式用起来非常难受。后来我在skill里直接规定了“必须包含市场规模、用户画像、功能对比、差异机会四个章节且对比表必须不少于十行”输出才稳定下来。记住skill越硬输出越稳。多写可检验的硬性要求少写软话。5.3 MCP工具调用时报错skill里写了调用MCP工具实际执行时报“工具不存在”或者“连接失败”这类问题我遇到好几次。先说工具名MCP工具名通常是mcp__服务器名__工具名这样的三段式少一个下划线都不行。你在skill里写工具名之前一定先用工具列表确认一下准确命名别凭记忆写。再说连接问题。很多MCP服务器是依赖外部服务的数据库连不上、API key过期都会导致调用失败。我的习惯是在skill里给每个工具调用都写一个替代方案让模型在工具失败时能主动告知用户而不是闷头重试。最后是权限问题。如果模型明明能看到工具但skill执行时被拒要检查是不是工具权限配置没放开把对应工具名称加入允许列表即可。5.4 上下文浪费严重会话越来越慢这个问题的根源通常是skill文档太大。有些开源skills把大量示例、历史记录、详细说明全部塞进一个文件加载一次就吃掉几千token。原本模型干活的上下文就紧张再来这么个大家伙自然变慢、变笨。解决办法是给skill文档瘦身。核心流程和约束控制在五百到一千字以内示例可以精简成一个更多的辅助材料放到同目录下的附加文件里让模型按需读取。另外就是定期清理不再使用的skills尤其是那种装了一个月只用过一次的果断删掉给上下文留出更多空间。6. 构建你自己的skills库目录规范、更新节奏与学习路线最后把格局放大一点说。如果你已经把skills当成日常工具在用那就不该满足于零散安装而是要考虑怎么管理自己的skills库。毕竟skill的数量会越来越多没有规范迟早变成一堆没人敢动的旧配置。6.1 一套值得抄的本地目录组织方式我目前的本地目录结构是这样的可以抄作业~/.claude/skills/ ├─ process/ # 流程类代码审查、发版检查、需求拆解 ├─ domain/ # 领域类数学建模、前端开发、AI漫剧 └─ team/ # 协作类团队规范、会议纪要生成、周报整理每个skill目录下我一般放一个SKILL.md偶尔加一个examples.md放示例。如果某个skill比较复杂还会放一个README.md记录当初为什么写它、踩过哪些坑。这些信息写在skill文档本身里太占空间放在旁边当附录非常舒服。6.2 更新与删除别让你的skill库变成垃圾堆skills是需要维护的。模型版本升级后以前好用的skill可能会逐渐失灵因为不同版本对指令的偏好和理解会有细微差异。我的习惯是每个月抽出一点时间把最近没触发过的skill过一遍测试一下还有没有效果没效果的要么修要么删。删除skill不需要太多感情。我之前收藏了一个很火的“财务分析”skill装了三个月一次都没触发过因为我的实际场景跟它写的预设差了十万八千里。删掉之后上下文明显轻松了不少。记忆里没必要堆满不用的技能真正在用的五到十个才是最值钱的。6.3 后续可以扩展的方向如果想把skills玩得更深有几个方向值得关注。第一是skills和MCP的深度组合让skill文档驱动工具调用实现真正意义上的“模型自主完成整条业务链路”。第二是团队级skills库的版本管理用Git管理技能变更让团队成员同步更新。第三是根据模型反馈反向优化skill比如看模型在某些步骤经常出错就针对性地把那个步骤写得更细、约束更具体。我个人的体会是写skills这件事本身就是一个自我复盘的过程。你要把平时干活的方法一条条写清楚就得先想明白每一步为什么要这么做。这个思考过程会让你的工作方法也变得更清晰。所以哪怕你现在只用得上三个小skill也建议亲自写一次收获远大于去下载一百个。