最近这段时间我几乎把市面上主流的AI编程工具都试了个遍从Claude Code到Codex再到OpenCode发现一个很有意思的现象同一个工具在不同人手里生产力差出一大截。有人能用它自动跑完整个项目流程有人却连让它稳定输出代码都得反复纠正。这个差距的根源很大程度上就落在skills上。如果你也在搜skills推荐、skills开发、ai skills怎么写大概率已经意识到这东西是绕不开的坎了。今天这篇不聊虚的我把自己从怎么手动装GitHub上的skills、到自己动手写skill、再到实际调优踩坑的完整过程捋一遍。内容偏实操文中的目录结构、配置路径和写法都是我实际跑过的照着抄基本不会出大问题。1. Skills到底是什么值得我花时间折腾吗先说结论非常值得尤其是当你手里的AI工具不止一个或者你希望AI能稳定复现某类专业任务时skills几乎是目前最优雅的解法。1.1 我理解的Skills不是魔法是标准化的工作手册要理解skills先别把它想得太玄。本质上skills是把AI完成某类任务时所需的全部上下文、操作步骤、判断规则和输出格式打包成一个AI可以直接读取、执行的标准化文件集。核心文件就是那个SKILL.md里面写清楚这个技能是干嘛的、什么时候用、按什么步骤执行、有哪些注意事项。我自己的理解是Prompt是给AI的一句话指令Skills是给AI的一本岗位SOP手册。前者依赖AI临场发挥后者让AI按标准作业程序干活。比如你让AI审查这段代码它可能随便看看就回复但如果挂上一个code-review的skill它会先拉变更清单、再逐文件检查潜在风险、按规范输出审查结论整个流程是可预期的。目前社区里流传的skills主要分两类一类是工作流型侧重做事的步骤和判断标准比如代码审查、数据库迁移、数学建模另一类是知识增强型侧重给AI喂特定领域的背景知识比如某种框架的API文档整理、特定竞赛的解题套路。1.2 Skills、普通Prompt和MCP的边界在哪里这是我在折腾过程中最绕的一段。很多教程把这三个概念混着讲但实际用起来边界其实很清晰对比维度普通PromptSkillsMCP上下文感知工具核心形态一次性指令文本结构化的SKILL.md文件客户端-服务端工具连接解决的问题告诉AI现在做什么告诉AI这类活按什么流程做给AI读取外部数据和调用工具的能力复用性低换个场景要重写高可跨会话跨项目复用中偏环境配置典型场景临时让AI改个文案让AI稳定执行代码审查让AI直接查数据库、调接口一个直观的类比Prompt像是你口头跟实习生说帮我把这份报表整理一下Skills像是你给他一份《报表整理标准作业指引》里面连核对逻辑和输出模板都写好了MCP则是给他开了一个能直接连到公司数据系统的账号。三者不冲突实际项目中常常叠加使用。对我来说skills最大的价值在于把个人经验沉淀成了可分发、可复用的资产。以前我在AI工具上积累了一套如何写好代码审查意见的套路但那是我脑子里的东西换个工具、换个项目就断了现在写成skill任何支持该格式的工具都能直接用这就是superpower skills的含义——普通技能在标准化之后会变成可叠加的超级能力。2. 从GitHub手动安装Skills一步一步说清楚说完了概念直接进入大家最关心的实操环节。我自己最开始就是卡在Claude Code怎么手动装github上的skills这一步网上搜到的资料大多是讲仓库里的内容很少说清楚文件到底放哪、怎么被AI发现。这里我把完整链路拆开讲。2.1 先搞懂AI到底怎么发现你装的Skills每个支持skills的AI编程工具启动时都会扫描指定的目录把目录下的SKILL.md文件加载为可用技能。以Claude Code为例它主要扫描两个位置项目级目录.claude/skills/只对当前项目生效适合放这个项目专属的技能用户级目录~/.claude/skills/对所有项目生效适合放个人通用技能Codex的扫描路径逻辑类似通常在~/.codex/skills/OpenCode一般在~/.config/opencode/skills/。虽然路径不同但原理一致——把下载的skills仓库直接放进这些目录重启工具即可生效。我第一次安装时犯了个低级错误把整个skills仓库clone下来之后忘了看它内部的目录结构直接把仓库根目录当成技能根目录放进了~/.claude/skills/。结果重启后AI完全没反应。后来才发现skill的文件层级是有要求的正确的结构应该是~/.claude/skills/ └── code-review/ # 技能文件夹名称即技能标识 ├── SKILL.md # 技能定义文件必选 └── reference/ # 辅助材料可选比如范例、模板 └── review_template.md也就是说SKILL.md外面必须包一层以技能名命名的文件夹AI扫描时是以文件夹SKILL.md为单位识别技能的。光有文件、没有正确的层级等于白装。2.2 三种手动安装方式按场景选方式一git clone整仓到技能目录最通用大部分GitHub上的skills仓库会直接按一个技能一个文件夹的格式组织所以最省事的做法就是clone到本地再复制对应文件夹过去# 进入用户级技能目录 cd ~/.claude/skills # 克隆包含skills的仓库以某个社区合集仓库为例 git clone https://github.com/example/awesome-skills.git temp # 把需要的技能文件夹复制出来 cp -r temp/code-review . cp -r temp/math-modeling . # 清理临时文件 rm -rf temp注意这里我刻意用了cp而不是直接把整个仓库放在skills目录下。原因很实际仓库里往往混杂着README、LICENSE和其他非技能文件直接挂载可能会干扰AI的技能识别而且如果后续仓库更新直接git pull容易把与你本地其他skills的目录结构搞乱。方式二手工复制单个SKILL.md适合轻量技能有些技能只有一个文件没有辅助材料那直接手动创建目录、写文件即可mkdir -p ~/.claude/skills/commit-message touch ~/.claude/skills/commit-message/SKILL.md然后编辑SKILL.md把内容粘进去。这种方式的优点是灵活缺点是绕过了Git的版本管理后续想更新只能手动再改。我一般是临时的、试验性质的技能才这么装试好了再转成Git仓库管理。方式三用工具自带的管理命令仅部分工具支持像 Codex 部分新版本提供了/skills之类的内置命令可以直接从GitHub安装。不过这类功能还在快速迭代不同版本差异很大我建议是把它当成辅助手段不要把安装流程完全依赖在命令上否则换个版本可能就变了。手动装虽然看起来笨但胜在稳定可控而且能让你真正理解技能挂载的原理。2.3 装完之后怎么确认真的生效了很多人装完skills就急着开始干活结果AI半天没反应就以为失败了。这里我分享一个很笨但很有效的验证方法启动工具后直接问AI一句你当前可用的技能有哪些观察它能不能报出刚安装的技能名称。如果报不出来按这个顺序排查目录层级对不对是否把技能文件夹放进了技能根目录SKILL.md是否在技能文件夹的一级子目录下路径是否用对当前项目需要访问项目级技能但你放到了用户级目录或者反过来。工具是否重启大多数工具只在启动时扫描一次技能目录中途新增的目录不会热加载。文件名是否规范技能描述文件必须是SKILL.md有些人随手命名成skill.md或SKILL.MD这会导致识别失败。我自己的习惯是装完一个技能就立刻问一次可用技能有哪些确认能识别后再用一句明确的触发指令测试实际效果。双保险避免在项目运行半路才发现技能根本没装好。3. 自己动手写一个可复用的Skills其实没有想象中难看了很多现成的skills之后我开始觉得与其等着社区出更好的不如自己写一个真正贴合自己工作流的。等到真正动手才发现写一个能用的skill不难难的是写出一个能被AI稳定触发、且执行结果符合预期的skill。这一节我完整还原我的开发过程用我自己写的一个代码审查skill当例子。3.1 第一步明确你的Skill到底要解决什么场景写skill之前先别急着动笔写内容。先问自己一个问题这个skill在什么场景下、被谁、用来做什么场景定义越清晰后面的description越容易写AI也越容易正确触发。以代码审查为例我一开始写得太宏大了审查项目代码发现潜在问题提高代码质量。这个定义放出去AI十有八九会在任何跟代码有关的对话中触发它结果就是过度干预。后来我收敛了一下适用范围当用户请求对某个Pull Request、分支提交或单文件改动进行代码审查时使用。典型触发场景包括帮我看看这段改动有没有问题审查一下这个PR这个提交需要注意什么。收敛之后技能触发的准确性明显提升不该管的场合它不插手该管的场合它按流程走。这一点是整个skills开发中最容易被忽略、却最能拉开体验差距的地方。3.2 第二步搭好SKILL.md文件的基础骨架一个标准的SKILL.md文件大多包含三部分YAML frontmattername技能的唯一标识、description给AI看的触发说明正文工作流分步骤描述这个技能的执行过程边界与规范什么时候不要用这个技能、输出格式要求、质量红线我用的是这套结构--- name: code-review description: 用于对代码变更Pull Request、分支比较、单文件改动进行系统性审查。当用户请求审查代码检查PR评估这次改动时使用。不适用于一般性的代码问答或编写新代码。 --- # 代码审查技能 ## 执行工作流 1. 获取待审查的代码变更范围明确哪些文件被修改、删除了哪些逻辑。 2. 按以下维度逐项检查 - 功能正确性逻辑分支是否完整边界条件是否处理 - 安全性是否引入了注入、越权、敏感信息泄露风险 - 性能是否存在明显的循环内查询、N1问题 - 可维护性命名是否清晰、函数是否过长、是否有重复代码 3. 对每个发现的问题标注严重级别阻断/重要/建议。 4. 输出审查报告按阻断问题、重要问题、建议优化分区展示。 ## 输出格式 - 每个问题必须包含文件路径行号、问题描述、修正建议、严重级别 - 如果没有发现问题也要明确输出未发现阻断级问题的结论 ## 边界 - 仅审查代码变更不审查业务需求文档 - 不执行自动修复只输出审查报告这个骨架的好处是职责清晰AI拿到之后知道先做什么、再做什么、输出什么不会自由发挥跑偏。frontmatter里的description要谨慎措辞特别是不适用的部分一定要写出来这能大大减少技能的误触发率。3.3 第三步怎么设计触发词让它恰好在该出现时出现触发词设计是skills开发中最玄学、最需要迭代的部分。我的经验是从两个方向同时收敛第一描述中多写实际对话中的自然表达。用户不会按照你文档里的术语说话他们大概率会说帮我看看这段代码怎么样而不是请执行code-review技能。所以我慢慢把这类口语化表达也融进description让它能匹配真实对话。第二明确陈述不适用场景。在description里加上不适用于...帮助AI排除掉绝大多数无关请求。这一点在前面已经提到这里想强调的是边界写得好不好直接决定了AI会不会过度触发把普通对话搞得束手束脚。3.4 第四步用真实任务迭代验证我自己写第一个skill花了半小时但后面调整了近一天。迭代验证的流程大概是这样先用模拟数据测试一遍构造一个故意包含多个问题的代码片段看技能是否能按流程输出审查报告。再看输出的质量问题定位是否准确级别标注是否符合预期报告结构是否清晰最后做防误触测试问几个与代码审查无关的问题确认AI不会错误触发该技能。有一个很典型的迭代案例我第一次写的输出格式要求按严重级别排序结果AI每次审查报告开头都先列所有建议级问题把真正的阻断问题压到了后面。后来我在工作流里加了一步最后按严重级别重新排序阻断问题必须置顶实测效果立竿见影。这说明skills的迭代本质上是把你自己审代码时的隐性习惯逐步翻译成AI能执行的显性规则。4. 实测值得收藏的Skills资源哪些能闭眼入自己会写了之后我用技能的效率高了不少但与此同时也在持续关注社区里那些优秀的开源skills。毕竟有些垂类领域的技能比如数学建模、前端开发要写成完整skill需要投入的时间成本是个人很难承担的。我把自己用过、觉得靠谱的资源分了个类。4.1 按场景分类的实用skills清单场景推荐方向使用心得代码审查社区热门的code-review类技能配合规范输出格式基本能替代初级人工审查前端开发包含React/Vue最佳实践的skill对项目脚手架搭建、组件抽取有显著帮助数学建模搜索数学建模skills、codex skills相关仓库解题思路标准化尤其在华为杯等场景下价值很高提交信息commit-message技能按Conventional Commits规范生成好用不贵数据库迁移含schema分析、回滚方案的技能比通用Prompt靠谱十倍如果你搜typesafe ai skills github会发现一个很有意思的方向把skills和类型安全结合让AI在执行任务时自带强约束的类型定义和输出schema。这个思路我认为是未来一个重要的演进方向尤其适合对AI输出结构化程度要求高的团队。4.2 我目前常用的一套技能组合写代码的场景我常年挂一组技能逻辑上是从需求理解到发布确认的一条线需求澄清AI不会上来就写代码而是先拆解需求、列出疑问技术方案设计根据项目技术栈给出选型和架构设计代码实现包含项目规范、文件组织、命名约定代码审查对我写的代码做一轮审查提交信息生成按规范生成commit message这五个技能串起来基本覆盖了一次完整开发交付的闭环。打好之后即使我临时换一个AI工具只要把这组技能装过去工作流就能整体复用这就是技能库的搬迁价值。4.3 善用GitHub上的Skills合集仓库但别照单全收GitHub上已经有大量skills合集仓库有的收录了几百个技能。我踩过的坑是装得越多AI越容易技能打架。技能数量一旦超过某个阈值AI对该调哪个技能的判断就会出现混乱甚至偶尔两个技能同时触发输出结构互斥。所以我的建议是按精而不多的原则保持常用技能在5~10个左右从合集仓库里挑选自己真正需要的技能文件夹复制出来而不是整个仓库一把梭每引入一个新技能短期内观察是否会与现有技能冲突尤其是触发边界有重叠的那些技能库这个东西重质不重量。一个写得精准的skill抵得上十个马马虎虎的skill。5. 实战中的踩坑记录排查链路与调优思路最后这部分我说说真正在真实项目里使用skills时遇到的各种问题。它们在网上教程里基本不会被提到但几乎必然会遇到。5.1 技能没被触发问题到底出在哪有一次我在一个Claude Code项目里装了个代码审查skill但无论怎么请审查这个PRAI都像是没这个技能一样输出的是默认的通用回答。排查过程如下第一步先确认技能文件存在ls ~/.claude/skills/code-review/SKILL.md文件确实在。第二步直接在会话里问可用技能有哪些AI报出来的技能列表里没有它。第三步检查项目级目录发现项目根目录的.claude/skills/有同名技能文件夹但里面只有一个空目录没有SKILL.md。AI扫描时可能因为这个残缺的同名技能导致用户级技能被遮蔽了。删掉项目级那个空目录后重启问题立刻消失。这个坑给我的教训是同名技能在不同层级之间存在遮蔽关系项目级会优先于用户级哪怕项目级那个不完整。排查技能触发问题第一步永远是确认是否存在幂等路径之间的冲突。5.2 技能被滥用的痛苦AI为什么总爱用错技能另一个高频问题是滥用。我装了一个文档生成技能本意是AI在完成代码任务后能顺手生成说明文档结果它几乎在所有对话里都想套用文档模板问一个简单的函数逻辑解释它也按文档生成的流程来先列标题再写API说明啰嗦得不行。后来我从两个方向解决了这个问题一是收紧description把仅当用户明确要求生成文档或写README时使用写得特别清楚二是把技能的触发等级调低明确写普通对话、代码问答不需要使用本技能。这让我意识到description里写清楚什么时候不要用往往比写清楚什么时候用更重要。5.3 上下文窗口被技能内容挤爆的困境Skills在加载时会占据上下文窗口。如果一次性挂载10个超长的技能每个都塞大量示例代码和参考文档那AI真正用来处理用户请求的上下文空间就被大量挤占输出质量反而下降。我的优化思路把大段的参考文档移到reference/目录而不是直接写满主文件AI按需读取主文件保持在60~100行以内只保留最精炼的步骤和规则同一个主题下如果既有知识型内容又有工作流型内容拆成两个技能分开挂载经过这轮瘦身同样一组技能上下文的占用降低了大概三分之一响应质量和速度都有改善。5.4 多技能混用时的输出格式冲突当一个操作同时触发多个技能时AI的输出格式选择困难症就会出现。我做生成代码并审查时代码实现技能要求输出完整代码块代码审查技能要求输出审查报告AI有时候会生成一份既是代码又是报告的混合体两边的要求都没完全遵守。要解决这个问题我给技能增加了一条协作规则在代码实现技能里写明如果后续有审查类技能参与你的输出仅保留代码本身审查结论由审查技能负责输出。这样一来技能之间明确了分工输出就不再混乱。这说明技能设计不能只看单个技能内部的逻辑还要考虑它和其他技能协作时的交互。5.5 我的经验Skills也会过时要像代码一样维护最后想提一个很多人忽视的点skills是有保质期的。我写的前端开发的skill里引用的某个脚手架版本三个月后项目更新了AI按旧流程跑就容易出错。现在我把skills都纳入Git管理定期跟进底层工具的更新就像维护代码库一样维护技能库。给技能加版本号、写更新日志才有条件让AI的工作方式持续贴合真实项目的演进。我个人在实际操作中的体会是skills的价值不在装得多而在用得准。与其把时间花在收集各种花哨的技能上不如花点时间把手头最常用的几项任务打磨成精确到步骤级的标准作业流程。等这套体系跑顺了你会发现AI工具的能力上限很大程度上是由你给它的工作手册的质量决定的。
最近这段时间我几乎把市面上主流的AI编程工具都试了个遍从Claude Code到Codex再到OpenCode发现一个很有意思的现象同一个工具在不同人手里生产力差出一大截。有人能用它自动跑完整个项目流程有人却连让它稳定输出代码都得反复纠正。这个差距的根源很大程度上就落在skills上。如果你也在搜skills推荐、skills开发、ai skills怎么写大概率已经意识到这东西是绕不开的坎了。今天这篇不聊虚的我把自己从怎么手动装GitHub上的skills、到自己动手写skill、再到实际调优踩坑的完整过程捋一遍。内容偏实操文中的目录结构、配置路径和写法都是我实际跑过的照着抄基本不会出大问题。1. Skills到底是什么值得我花时间折腾吗先说结论非常值得尤其是当你手里的AI工具不止一个或者你希望AI能稳定复现某类专业任务时skills几乎是目前最优雅的解法。1.1 我理解的Skills不是魔法是标准化的工作手册要理解skills先别把它想得太玄。本质上skills是把AI完成某类任务时所需的全部上下文、操作步骤、判断规则和输出格式打包成一个AI可以直接读取、执行的标准化文件集。核心文件就是那个SKILL.md里面写清楚这个技能是干嘛的、什么时候用、按什么步骤执行、有哪些注意事项。我自己的理解是Prompt是给AI的一句话指令Skills是给AI的一本岗位SOP手册。前者依赖AI临场发挥后者让AI按标准作业程序干活。比如你让AI审查这段代码它可能随便看看就回复但如果挂上一个code-review的skill它会先拉变更清单、再逐文件检查潜在风险、按规范输出审查结论整个流程是可预期的。目前社区里流传的skills主要分两类一类是工作流型侧重做事的步骤和判断标准比如代码审查、数据库迁移、数学建模另一类是知识增强型侧重给AI喂特定领域的背景知识比如某种框架的API文档整理、特定竞赛的解题套路。1.2 Skills、普通Prompt和MCP的边界在哪里这是我在折腾过程中最绕的一段。很多教程把这三个概念混着讲但实际用起来边界其实很清晰对比维度普通PromptSkillsMCP上下文感知工具核心形态一次性指令文本结构化的SKILL.md文件客户端-服务端工具连接解决的问题告诉AI现在做什么告诉AI这类活按什么流程做给AI读取外部数据和调用工具的能力复用性低换个场景要重写高可跨会话跨项目复用中偏环境配置典型场景临时让AI改个文案让AI稳定执行代码审查让AI直接查数据库、调接口一个直观的类比Prompt像是你口头跟实习生说帮我把这份报表整理一下Skills像是你给他一份《报表整理标准作业指引》里面连核对逻辑和输出模板都写好了MCP则是给他开了一个能直接连到公司数据系统的账号。三者不冲突实际项目中常常叠加使用。对我来说skills最大的价值在于把个人经验沉淀成了可分发、可复用的资产。以前我在AI工具上积累了一套如何写好代码审查意见的套路但那是我脑子里的东西换个工具、换个项目就断了现在写成skill任何支持该格式的工具都能直接用这就是superpower skills的含义——普通技能在标准化之后会变成可叠加的超级能力。2. 从GitHub手动安装Skills一步一步说清楚说完了概念直接进入大家最关心的实操环节。我自己最开始就是卡在Claude Code怎么手动装github上的skills这一步网上搜到的资料大多是讲仓库里的内容很少说清楚文件到底放哪、怎么被AI发现。这里我把完整链路拆开讲。2.1 先搞懂AI到底怎么发现你装的Skills每个支持skills的AI编程工具启动时都会扫描指定的目录把目录下的SKILL.md文件加载为可用技能。以Claude Code为例它主要扫描两个位置项目级目录.claude/skills/只对当前项目生效适合放这个项目专属的技能用户级目录~/.claude/skills/对所有项目生效适合放个人通用技能Codex的扫描路径逻辑类似通常在~/.codex/skills/OpenCode一般在~/.config/opencode/skills/。虽然路径不同但原理一致——把下载的skills仓库直接放进这些目录重启工具即可生效。我第一次安装时犯了个低级错误把整个skills仓库clone下来之后忘了看它内部的目录结构直接把仓库根目录当成技能根目录放进了~/.claude/skills/。结果重启后AI完全没反应。后来才发现skill的文件层级是有要求的正确的结构应该是~/.claude/skills/ └── code-review/ # 技能文件夹名称即技能标识 ├── SKILL.md # 技能定义文件必选 └── reference/ # 辅助材料可选比如范例、模板 └── review_template.md也就是说SKILL.md外面必须包一层以技能名命名的文件夹AI扫描时是以文件夹SKILL.md为单位识别技能的。光有文件、没有正确的层级等于白装。2.2 三种手动安装方式按场景选方式一git clone整仓到技能目录最通用大部分GitHub上的skills仓库会直接按一个技能一个文件夹的格式组织所以最省事的做法就是clone到本地再复制对应文件夹过去# 进入用户级技能目录 cd ~/.claude/skills # 克隆包含skills的仓库以某个社区合集仓库为例 git clone https://github.com/example/awesome-skills.git temp # 把需要的技能文件夹复制出来 cp -r temp/code-review . cp -r temp/math-modeling . # 清理临时文件 rm -rf temp注意这里我刻意用了cp而不是直接把整个仓库放在skills目录下。原因很实际仓库里往往混杂着README、LICENSE和其他非技能文件直接挂载可能会干扰AI的技能识别而且如果后续仓库更新直接git pull容易把与你本地其他skills的目录结构搞乱。方式二手工复制单个SKILL.md适合轻量技能有些技能只有一个文件没有辅助材料那直接手动创建目录、写文件即可mkdir -p ~/.claude/skills/commit-message touch ~/.claude/skills/commit-message/SKILL.md然后编辑SKILL.md把内容粘进去。这种方式的优点是灵活缺点是绕过了Git的版本管理后续想更新只能手动再改。我一般是临时的、试验性质的技能才这么装试好了再转成Git仓库管理。方式三用工具自带的管理命令仅部分工具支持像 Codex 部分新版本提供了/skills之类的内置命令可以直接从GitHub安装。不过这类功能还在快速迭代不同版本差异很大我建议是把它当成辅助手段不要把安装流程完全依赖在命令上否则换个版本可能就变了。手动装虽然看起来笨但胜在稳定可控而且能让你真正理解技能挂载的原理。2.3 装完之后怎么确认真的生效了很多人装完skills就急着开始干活结果AI半天没反应就以为失败了。这里我分享一个很笨但很有效的验证方法启动工具后直接问AI一句你当前可用的技能有哪些观察它能不能报出刚安装的技能名称。如果报不出来按这个顺序排查目录层级对不对是否把技能文件夹放进了技能根目录SKILL.md是否在技能文件夹的一级子目录下路径是否用对当前项目需要访问项目级技能但你放到了用户级目录或者反过来。工具是否重启大多数工具只在启动时扫描一次技能目录中途新增的目录不会热加载。文件名是否规范技能描述文件必须是SKILL.md有些人随手命名成skill.md或SKILL.MD这会导致识别失败。我自己的习惯是装完一个技能就立刻问一次可用技能有哪些确认能识别后再用一句明确的触发指令测试实际效果。双保险避免在项目运行半路才发现技能根本没装好。3. 自己动手写一个可复用的Skills其实没有想象中难看了很多现成的skills之后我开始觉得与其等着社区出更好的不如自己写一个真正贴合自己工作流的。等到真正动手才发现写一个能用的skill不难难的是写出一个能被AI稳定触发、且执行结果符合预期的skill。这一节我完整还原我的开发过程用我自己写的一个代码审查skill当例子。3.1 第一步明确你的Skill到底要解决什么场景写skill之前先别急着动笔写内容。先问自己一个问题这个skill在什么场景下、被谁、用来做什么场景定义越清晰后面的description越容易写AI也越容易正确触发。以代码审查为例我一开始写得太宏大了审查项目代码发现潜在问题提高代码质量。这个定义放出去AI十有八九会在任何跟代码有关的对话中触发它结果就是过度干预。后来我收敛了一下适用范围当用户请求对某个Pull Request、分支提交或单文件改动进行代码审查时使用。典型触发场景包括帮我看看这段改动有没有问题审查一下这个PR这个提交需要注意什么。收敛之后技能触发的准确性明显提升不该管的场合它不插手该管的场合它按流程走。这一点是整个skills开发中最容易被忽略、却最能拉开体验差距的地方。3.2 第二步搭好SKILL.md文件的基础骨架一个标准的SKILL.md文件大多包含三部分YAML frontmattername技能的唯一标识、description给AI看的触发说明正文工作流分步骤描述这个技能的执行过程边界与规范什么时候不要用这个技能、输出格式要求、质量红线我用的是这套结构--- name: code-review description: 用于对代码变更Pull Request、分支比较、单文件改动进行系统性审查。当用户请求审查代码检查PR评估这次改动时使用。不适用于一般性的代码问答或编写新代码。 --- # 代码审查技能 ## 执行工作流 1. 获取待审查的代码变更范围明确哪些文件被修改、删除了哪些逻辑。 2. 按以下维度逐项检查 - 功能正确性逻辑分支是否完整边界条件是否处理 - 安全性是否引入了注入、越权、敏感信息泄露风险 - 性能是否存在明显的循环内查询、N1问题 - 可维护性命名是否清晰、函数是否过长、是否有重复代码 3. 对每个发现的问题标注严重级别阻断/重要/建议。 4. 输出审查报告按阻断问题、重要问题、建议优化分区展示。 ## 输出格式 - 每个问题必须包含文件路径行号、问题描述、修正建议、严重级别 - 如果没有发现问题也要明确输出未发现阻断级问题的结论 ## 边界 - 仅审查代码变更不审查业务需求文档 - 不执行自动修复只输出审查报告这个骨架的好处是职责清晰AI拿到之后知道先做什么、再做什么、输出什么不会自由发挥跑偏。frontmatter里的description要谨慎措辞特别是不适用的部分一定要写出来这能大大减少技能的误触发率。3.3 第三步怎么设计触发词让它恰好在该出现时出现触发词设计是skills开发中最玄学、最需要迭代的部分。我的经验是从两个方向同时收敛第一描述中多写实际对话中的自然表达。用户不会按照你文档里的术语说话他们大概率会说帮我看看这段代码怎么样而不是请执行code-review技能。所以我慢慢把这类口语化表达也融进description让它能匹配真实对话。第二明确陈述不适用场景。在description里加上不适用于...帮助AI排除掉绝大多数无关请求。这一点在前面已经提到这里想强调的是边界写得好不好直接决定了AI会不会过度触发把普通对话搞得束手束脚。3.4 第四步用真实任务迭代验证我自己写第一个skill花了半小时但后面调整了近一天。迭代验证的流程大概是这样先用模拟数据测试一遍构造一个故意包含多个问题的代码片段看技能是否能按流程输出审查报告。再看输出的质量问题定位是否准确级别标注是否符合预期报告结构是否清晰最后做防误触测试问几个与代码审查无关的问题确认AI不会错误触发该技能。有一个很典型的迭代案例我第一次写的输出格式要求按严重级别排序结果AI每次审查报告开头都先列所有建议级问题把真正的阻断问题压到了后面。后来我在工作流里加了一步最后按严重级别重新排序阻断问题必须置顶实测效果立竿见影。这说明skills的迭代本质上是把你自己审代码时的隐性习惯逐步翻译成AI能执行的显性规则。4. 实测值得收藏的Skills资源哪些能闭眼入自己会写了之后我用技能的效率高了不少但与此同时也在持续关注社区里那些优秀的开源skills。毕竟有些垂类领域的技能比如数学建模、前端开发要写成完整skill需要投入的时间成本是个人很难承担的。我把自己用过、觉得靠谱的资源分了个类。4.1 按场景分类的实用skills清单场景推荐方向使用心得代码审查社区热门的code-review类技能配合规范输出格式基本能替代初级人工审查前端开发包含React/Vue最佳实践的skill对项目脚手架搭建、组件抽取有显著帮助数学建模搜索数学建模skills、codex skills相关仓库解题思路标准化尤其在华为杯等场景下价值很高提交信息commit-message技能按Conventional Commits规范生成好用不贵数据库迁移含schema分析、回滚方案的技能比通用Prompt靠谱十倍如果你搜typesafe ai skills github会发现一个很有意思的方向把skills和类型安全结合让AI在执行任务时自带强约束的类型定义和输出schema。这个思路我认为是未来一个重要的演进方向尤其适合对AI输出结构化程度要求高的团队。4.2 我目前常用的一套技能组合写代码的场景我常年挂一组技能逻辑上是从需求理解到发布确认的一条线需求澄清AI不会上来就写代码而是先拆解需求、列出疑问技术方案设计根据项目技术栈给出选型和架构设计代码实现包含项目规范、文件组织、命名约定代码审查对我写的代码做一轮审查提交信息生成按规范生成commit message这五个技能串起来基本覆盖了一次完整开发交付的闭环。打好之后即使我临时换一个AI工具只要把这组技能装过去工作流就能整体复用这就是技能库的搬迁价值。4.3 善用GitHub上的Skills合集仓库但别照单全收GitHub上已经有大量skills合集仓库有的收录了几百个技能。我踩过的坑是装得越多AI越容易技能打架。技能数量一旦超过某个阈值AI对该调哪个技能的判断就会出现混乱甚至偶尔两个技能同时触发输出结构互斥。所以我的建议是按精而不多的原则保持常用技能在5~10个左右从合集仓库里挑选自己真正需要的技能文件夹复制出来而不是整个仓库一把梭每引入一个新技能短期内观察是否会与现有技能冲突尤其是触发边界有重叠的那些技能库这个东西重质不重量。一个写得精准的skill抵得上十个马马虎虎的skill。5. 实战中的踩坑记录排查链路与调优思路最后这部分我说说真正在真实项目里使用skills时遇到的各种问题。它们在网上教程里基本不会被提到但几乎必然会遇到。5.1 技能没被触发问题到底出在哪有一次我在一个Claude Code项目里装了个代码审查skill但无论怎么请审查这个PRAI都像是没这个技能一样输出的是默认的通用回答。排查过程如下第一步先确认技能文件存在ls ~/.claude/skills/code-review/SKILL.md文件确实在。第二步直接在会话里问可用技能有哪些AI报出来的技能列表里没有它。第三步检查项目级目录发现项目根目录的.claude/skills/有同名技能文件夹但里面只有一个空目录没有SKILL.md。AI扫描时可能因为这个残缺的同名技能导致用户级技能被遮蔽了。删掉项目级那个空目录后重启问题立刻消失。这个坑给我的教训是同名技能在不同层级之间存在遮蔽关系项目级会优先于用户级哪怕项目级那个不完整。排查技能触发问题第一步永远是确认是否存在幂等路径之间的冲突。5.2 技能被滥用的痛苦AI为什么总爱用错技能另一个高频问题是滥用。我装了一个文档生成技能本意是AI在完成代码任务后能顺手生成说明文档结果它几乎在所有对话里都想套用文档模板问一个简单的函数逻辑解释它也按文档生成的流程来先列标题再写API说明啰嗦得不行。后来我从两个方向解决了这个问题一是收紧description把仅当用户明确要求生成文档或写README时使用写得特别清楚二是把技能的触发等级调低明确写普通对话、代码问答不需要使用本技能。这让我意识到description里写清楚什么时候不要用往往比写清楚什么时候用更重要。5.3 上下文窗口被技能内容挤爆的困境Skills在加载时会占据上下文窗口。如果一次性挂载10个超长的技能每个都塞大量示例代码和参考文档那AI真正用来处理用户请求的上下文空间就被大量挤占输出质量反而下降。我的优化思路把大段的参考文档移到reference/目录而不是直接写满主文件AI按需读取主文件保持在60~100行以内只保留最精炼的步骤和规则同一个主题下如果既有知识型内容又有工作流型内容拆成两个技能分开挂载经过这轮瘦身同样一组技能上下文的占用降低了大概三分之一响应质量和速度都有改善。5.4 多技能混用时的输出格式冲突当一个操作同时触发多个技能时AI的输出格式选择困难症就会出现。我做生成代码并审查时代码实现技能要求输出完整代码块代码审查技能要求输出审查报告AI有时候会生成一份既是代码又是报告的混合体两边的要求都没完全遵守。要解决这个问题我给技能增加了一条协作规则在代码实现技能里写明如果后续有审查类技能参与你的输出仅保留代码本身审查结论由审查技能负责输出。这样一来技能之间明确了分工输出就不再混乱。这说明技能设计不能只看单个技能内部的逻辑还要考虑它和其他技能协作时的交互。5.5 我的经验Skills也会过时要像代码一样维护最后想提一个很多人忽视的点skills是有保质期的。我写的前端开发的skill里引用的某个脚手架版本三个月后项目更新了AI按旧流程跑就容易出错。现在我把skills都纳入Git管理定期跟进底层工具的更新就像维护代码库一样维护技能库。给技能加版本号、写更新日志才有条件让AI的工作方式持续贴合真实项目的演进。我个人在实际操作中的体会是skills的价值不在装得多而在用得准。与其把时间花在收集各种花哨的技能上不如花点时间把手头最常用的几项任务打磨成精确到步骤级的标准作业流程。等这套体系跑顺了你会发现AI工具的能力上限很大程度上是由你给它的工作手册的质量决定的。
