1. 先搞明白AI编程里的Skills到底是什么和普通提示词差在哪最近大半年我的终端工作流几乎被Claude Code和Codex CLI接管了。最开始只是当个高级问答机器人用后来慢慢发现问题同样是让AI改代码有时候它非常懂我有时候又蠢得离谱。直到我把重心从写更长更细的提示词转向给Agent装skills表现才真正稳定下来。Skills这个词在AI编程圈最近确实热得发烫但它不是什么玄乎的新模型能力本质上是一种结构化的技能包把某个领域的完整工作流——触发条件、操作步骤、注意事项、示例——写成一个Markdown文档放到Agent能读到的目录里让它在面对具体任务时按需调用。你可以把它理解成给AI外挂了一本操作手册或者说把原来靠人反复粘贴的那套SOP正式变成了Agent能自主检索的资产。这篇内容我会从Skills的结构原理讲起把当下最值得用的技能库、三种主流工具Claude Code、Codex CLI、OpenCode的手动安装姿势、手写技能的方法以及后期怎么清理和调试都完整过一遍。适合已经在用AI编程工具、但不太满足于对话式编码的开发者也适合刚听说Skills、想给自己的建模比赛或前端项目配置技能的人。要理解Skills最忌讳的就是把它当成某种插件市场里的黑盒子。我自己拆过不少技能包下面先看一个标准的Skills到底长什么样。1.1 一个Skills包的完整结构长什么样一个Skills本质上就是一个目录里面最关键的是SKILL.md这个文件。拿最典型的Claude Code生态来说一个技能包长这样my-skill/ ├── SKILL.md # 核心技能说明 操作流程 ├── examples/ # 可选示例输入/输出引导AI模仿 ├── assets/ # 可选模板、图片、代码片段 └── scripts/ # 可选辅助脚本被SKILL.md调用SKILL.md采用Markdown格式开头有一段YAML frontmatter里面是技能的元信息最重要的是name和description。下面是一个真实场景里的精简示例--- name: frontend-code-review description: 用于对前端项目进行代码审查。当用户要求检查React/Vue组件代码、发现潜在bug、评估代码可维护性时使用。输入是代码文件路径或具体变更片段。 --- # 前端代码审查流程 1. 先读取目标文件识别组件类型和主要逻辑 2. 检查状态管理是否合理关注useEffect依赖等常见问题 3. 检查样式方案是否与项目现有规范一致 4. 输出按严重程度分级的问题清单很多人会忽略description的作用这是最容易踩的坑。Agent在收到用户请求后会先扫描所有可用的SKILL.md通过description来决定到底该调用哪个技能。如果描述写得含糊比如帮助分析前端代码它和另一个检查代码质量的技能就很容易被混淆最后要么技能没被触发要么被错误触发。我在下面第4节会专门展开怎么写好描述。1.2 为什么Agent加载Skills后表现会明显变好这得从纯提示词工程的瓶颈说起。以前我们为了让AI稳定输出会在系统提示词里塞一大堆规则你必须先检查依赖碰到报错要输出排查步骤代码要带注释。问题在于这些规则在长对话里会被逐渐稀释而且所有任务都挤在一个上下文里Agent很难在恰当的时机想起哦这时候该走审查流程。Skills解决的恰恰是这个按需取用的问题。它把每个专项流程从全局对话中剥离出来做成独立的、可检索的模块。Agent只有在面对匹配任务时才会把对应的SKILL.md加载进上下文相当于现场翻开了工具箱里的那个抽屉。打个不那么严谨的比方提示词是给AI贴了一张注意事项便签Skills则是给AI配了一排标签清晰的抽屉。便签看久了会被忽略抽屉只有用的时候才打开。这也是为什么很多团队的体感是——配置了一个好的Skills之后AI在特定任务上的稳定性提升比调几版提示词要明显得多因为它在任务入口处就锁定了动作路径。1.3 关于Skills的常见误解第一批玩Skills的人包括我自己都产生过一些错误认知这里提前排掉三颗雷。第一Skills不是只能从官方商店装。Claude Code有claude skills命令也有官方示例仓库 anthropics/skills但社区里大量高质量的Skills就是普通GitHub仓库克隆下来复制到目录里就能用。这跟我下面要讲的手动安装方式直接相关。第二Skills的格式并不神秘。说穿了就是写得很规矩的Markdown文件。Claude Code的Skills、Codex CLI的Skills、OpenCode的Skills格式上大方向是兼容的都遵循目录SKILL.md这种结构只是在存放路径上不同。这意味着你写了一个技能包几乎可以在几个工具之间平移边际成本很低。第三Skills不是装得越多越好。这个我放到最后一节展开讲但先给结论一次对话里Agent能记在心上的技能容量有限十几二十个技能塞进去它光做匹配决策就要消耗不少tokens甚至会选错。真正的做法是保持少量精准的技能集就像真正的工具箱也不会把两百把螺丝刀全带在身上。2. 现在最值得装的Skills都在哪场景化推荐与技能库导航很多人问我的第一个问题不是怎么装而是先装点什么。Skills的推荐非常依赖场景一个建模比赛选手和一个前端工程师、一个做AI漫剧的创作者需要的技能包完全不同。我挑几个被讨论最多、我自己也实际验证过的场景来说。2.1 数学建模与竞赛场景华为杯、国赛数学建模是Skills话题里热度极高的应用场景尤其是华为杯、全国大学生数学建模这类比赛。原因很简单建模赛的核心产出是论文和代码而这两块都是AI编程工具发挥最稳定的地方。社区里流传的建模Skills主要覆盖这几个方向数据处理与清洗检查缺失值、异常值、数据分布自动生成探索性数据分析EDA报告。模型选择与灵敏度分析帮你在多个候选模型之间做对比输出选择依据并对关键参数做扰动分析。论文LaTeX排版把计算结果整理成比赛要求的摘要、正文、附录结构统一图表格式和数学公式风格。可视化规范一套固定的Matplotlib/Seaborn样式规则保证所有图表的字体、配色、坐标轴风格一致。用Codex CLI配合这些Skills跑建模的典型流程是先把赛题和附件丢给它技能会自动决定先做EDA还是先搭模型框架然后一步步输出中间结果。我给你一个务实建议比赛前别贪心装全套装一个数据处理、一个可视化规范、一个LaTeX排版基本就够用了重点是把这三件事的输出稳定性拉满。2.2 前端开发与网页应用场景前端是Skills生态里最成熟的方向之一因为前端任务的模式非常固定改组件、调样式、审查代码、修复特定框架的坑。常用的前端Skills大致有这几类代码审查按严重程度输出问题清单关注状态依赖、内存泄漏、可访问性等。UI组件生成给定设计稿描述或截图生成符合项目现有组件库风格的React/Vue组件。样式规约执行统一Tailwind类名顺序、颜色变量引用、响应式断点使用习惯把AI生成代码和团队规范强行对齐。Bug定位针对点击没有反应白屏接口报错这类症状给出结构化的排查路径。我个人感受最深的是样式规约类技能。以前让AI写Tailwind页面它总爱随机造颜色值比如bg-[#FAFAFA]这种任意值满天飞。挂了一个颜色规约Skills之后它稳定地从主题色板里取值改动一次就解决了我痛斥三个月的问题。2.3 AI漫剧与内容创意场景AI漫剧是我最近关注到的一个新场景——用AI批量生成漫画分镜脚本、角色设定、画面提示词再配合图生图工具做成短视频。这个场景的用户不一定是程序员但Skills机制同样适用而且效果很惊艳。社区里在传的漫剧Skills主要有分镜脚本生成把小说片段拆成分格脚本每格包含景别、角色动作、台词、氛围。角色一致性记录每个角色的人设关键词和视觉锚点生成新画面时自动带上这些特征词。提示词转绘把一段叙述文字转换成适合绘图模型的长提示词按镜头语言规则组织。这类技能对技术背景要求不高因为它的核心就是写得很细的SOP说白了就是把专业编剧的拆分逻辑复制给AI。如果你是做内容生产的完全可以从这类Skills入手它们会让你第一次直观地感受到原来AI的技能不只是写代码还包括固定风格的内容生产流程。2.4 常用Skills源网站与GitHub仓库既然Skills就是GitHub上的普通仓库那从哪找就变成了一个关键问题。我整理一下自己收藏夹里的门类和入口覆盖面比较广大家可以各取所需。类型代表性资源说明官方示例与文档anthropics/skillsAnthropic官方维护的示例技能集适合学习格式规范和设计思路社区聚合榜awesome-claude-skills收录大量社区技能按场景分类适合寻找灵感工程化技能库typesafe ai skillsGitHub偏工程实践的技能集合覆盖测试、修Bug、代码生成等场景工具配置参考opencode skills文档在OpenCode官方文档里能找到该工具的技能配置说明零散热传仓库cola skills、superpower skills社区里被反复提到的技能合集质量参差需要自己甄别一个很重要的提醒从GitHub下载Skills时一定要先看README和目录结构不要直接运行里面的脚本。虽然绝大多数技能包都是纯Markdown文本风险很低但凡是带scripts/目录的都要确认它是干什么用的。Skill的本质是改变Agent的行为不是改变系统的行为如果哪个仓库让你运行安装脚本注册全局命令建议直接退出。3. 三个主流工具装Skills的手动姿势Claude Code、Codex CLI、OpenCode搜索词里关于手动装Skills的讨论特别多因为大多数官方教程给的路径是从命令面板安装但实际从GitHub上扒下来手动放进去反而是更通用、更好理解的方式。我按工具拆开讲每个都给完整的落地步骤。3.1 Claude Code手动拉取GitHub上的Skills并挂载Claude Code对Skills的支持已经比较成熟。它主要读取两个位置一是用户级目录~/.claude/skills/二是项目级目录.claude/skills/。用户级的对所有项目生效项目级的只对当前项目生效后者的优先级高于前者。手动安装一个GitHub Skills的流程非常简单以装一个叫frontend-review的技能为例# 1. 克隆仓库到本地临时目录 git clone https://github.com/yourname/frontend-review.git /tmp/frontend-review # 2. 在Claude Code用户技能目录下创建目标文件夹 mkdir -p ~/.claude/skills/frontend-review # 3. 把仓库内容复制过去只需要SKILL.md和必要资源 cp -r /tmp/frontend-review/* ~/.claude/skills/frontend-review/ # 4. 验证加载 claude skills list有些仓库结构里不止一个技能比如一个仓库里同时有review、fix、refactor三个目录那就每个目录单独复制到对应的技能目录里# 多技能仓库的复制方式 cp -r /tmp/frontend-skills/review ~/.claude/skills/ cp -r /tmp/frontend-skills/fix ~/.claude/skills/不需要重启终端Claude Code在下次对话时会自动扫描技能目录。我建议每次安装后都跑一次claude skills list确认技能已被识别并且看一眼里面显示的description如果描述跟你预期不符说明frontmatter解析可能出了问题。3.2 Codex CLISkills如何挂进codexOpenAI家的Codex CLI也加入了Skills机制整体思路跟Claude Code类似本质就是约定一个目录放SKILL.md。我用过的版本里Codex的技能目录一般在配置目录下比如~/.codex/skills/也有项目级.codex/skills/的用法。手动安装流程# 1. 建立技能目录 mkdir -p ~/.codex/skills/code-review # 2. 写入SKILL.md可以是从GitHub下载的也可以是自己写的 curl -fsSL https://raw.githubusercontent.com/example/code-review-skill/main/SKILL.md \ -o ~/.codex/skills/code-review/SKILL.md # 3. 确认文件内容可读 cat ~/.codex/skills/code-review/SKILL.mdCodex CLI对技能目录的具体位置在不同版本上有过调整如果你发现放进去之后Agent完全没反应先去翻官方文档确认当前版本的默认路径。我自己的排查习惯是先ls看目录在不在再直接跑一个明确的任务比如用code-review技能检查当前目录代码看输出里有没有出现技能内部特有的指令或格式。技能如果生效输出行为和普通对话会有明显差异。3.3 OpenCode配置目录与服务端SkillsOpenCode是另一个很受欢迎的开源Agent工具它的Skills机制跟Claude Code类似也遵循目录 SKILL.md的约定。项目根目录下的.opencode/skills/和用户全局目录都可以放技能包。mkdir -p .opencode/skills/commit-writer # 把SKILL.md放进去 cp ~/downloads/commit-writer/SKILL.md .opencode/skills/commit-writer/安装之后可以在OpenCode交互界面里直接用斜杠命令或者自然语言触发。它比较适合团队场景把一些标准流程提交信息规范、代码审查清单、接口文档生成方式做成项目级技能跟着仓库走团队成员共享同一套行为标准。3.4 安装完必须做的验证动作很多人装完技能就以为完事了结果跑了两天发现Agent根本没鸟这个技能回头才查原因。我的标准验证流程有三步每次都花不了两分钟第一步确认目录和文件完整。用ls -R看一下技能目录确保SKILL.md在根目录而不是嵌套在某个子文件夹里。很多人克隆仓库后直接复制了整个外层目录导致结构变成skills/frontend-review/frontend-review/SKILL.md多套了一层Agent根本读不到。第二步看清单输出。Claude Code看claude skills listCodex和OpenCode也有对应的技能列表命令。如果列表里都没有别纠结文件内容先解决路径问题。第三步做触发实验。故意给一个非常明确的任务比如直接说请使用前端审查技能检查src/App.tsx。如果Agent开始输出你技能里特有的分步结构说明触发成功如果它还是按普通对话模式胡答回去翻description是不是写得太泛。4. 手写一个自己的Skills从Markdown到可复用的完整流程装别人的Skills用一段时间后大概率会冒出我自己写一个的念头。这是很自然的过程因为每个人手头的工作流都是独特的现成的技能包很难完全贴合。而且写Skills的难度其实比想象中低很多——不需要懂编程只需要把你脑子里的做事方法结构清楚。4.1 SKILL.md的frontmatter与正文骨架怎么搭先写骨架一个标准的SKILL.md由两部分组成YAML frontmatter和Markdown正文。--- name: 技能名称英文短横线命名 description: 一句话说明这个技能在什么情况下、解决什么问题 --- # 技能标题 ## 触发条件 在什么输入下启动该技能什么情况下不要用 ## 操作步骤 1. 第一步做什么 2. 第二步做什么 ## 输出规范 最终产出的格式要求、检查清单 ## 示例 一个完整的输入输出示例frontmatter里description的地位怎么强调都不过分。它决定了Agent什么时候加载这个技能。一个合格的description要回答四个问题这个技能做什么、在什么输入场景下使用、输入是什么、输出长什么样。比如下面这两个description效果天差地别# 差太泛 description: 帮助审查代码质量 # 好明确触发条件和输入输出 description: 审查前端React组件代码发现状态管理、依赖引用、潜在渲染性能问题。当用户要求检查代码看看有没有bugreview一下组件时使用。输入为文件路径输出为按严重程度分级的问题清单。“差”的描述放到技能列表里会被淹没Agent很难在需要时想起它“好”的描述把触发场景都画出来了匹配率会明显提升。4.2 实战示例写一个前端代码审查Skills我拿自己写过的frontend code review来拆一个最小完整版。这个技能的核心诉求是让AI按团队标准检查React代码输出可以直接传到MR里的审查意见。--- name: react-code-review description: 对React组件代码进行结构化审查。当用户要求检查React/Typescript代码、提交MR前自查、或反馈页面出bug了帮我查原因时使用。输入为组件文件路径或代码变更输出为P0/P1/P2分级问题清单。 --- # React组件代码审查 ## 触发条件 - 用户要求审查React组件代码 - 用户准备提交代码合并请求 - 用户反馈组件渲染异常 ## 审查步骤 1. 读取目标组件文件列出组件使用的props、state、hooks 2. 逐个检查 - useEffect的依赖数组是否完整 - 状态更新是否会造成额外渲染 - 事件处理函数是否存在内存泄漏 - 是否有不必要的useMemo 3. 检查样式是否引用项目主题常量避免魔法颜色值 4. 检查可访问性按钮是否有aria-label图片是否有alt ## 输出规范 按以下格式输出 **P0必须修复**会导致崩溃、数据错误的问题 **P1建议修复**影响性能或可维护性的问题 **P2可选优化**代码风格、命名优化建议 每个问题请给出对应代码片段和修复方向不要只给结论。 ## 示例 用户输入审查 src/components/UserCard.tsx 输出...给出一个带P0/P1/P2分级的完整示例让AI模仿格式这个结构里审查步骤是核心它把AI的工作流程从随便看看变成了按清单逐项执行输出规范约束了回答格式让结果可以直接用示例则给了AI一个模仿的模板。一个好的示例非常关键——AI在少量示例下会本能地模仿示例的输出风格和完整度所以示例宁可多写两行也不要给一个半成品。4.3 设计Skills时的三条铁律写多了之后我把自己的教训总结成三条铁律给准备自己动手写的人参考。铁律一描述是技能的入口写不好等于技能不存在。我自己曾经写了一个很完整的日志分析技能结果description写的是分析日志文件帮助排查问题跟另一个错误诊断技能含糊撞车。实际使用中Agent十个请求里有八个选了错误的技能。后来我把描述改成当用户提到线上报错、查询日志、排查生产环境异常时使用触发准确率立刻上来了。花在description上的时间值回票价。铁律二示例必须真实、完整、可模仿。很多人在SKILL.md的示例部分随手写两行这完全浪费了示例的价值。AI模仿示例的能力很强它会参考你给出的输入输出对来生成自己的回答。示例越是接近你的真实任务、输出越完整AI后面每一次的表现就越贴近你的预期。我在review技能里放了一条完整到可以直接贴去MR的审查输出效果比我在步骤里写了十行规则都好。铁律三步骤要细到傻子都能照做但这个傻子是AI。写步骤时容易犯的错是写得太宏观比如检查代码可维护性——这句话等于没说。要拆到检查组件内的state是否超过3个超过则建议拆分子组件这种颗粒度。AI需要的是相对明确的执行指令不是给人类看的抽象原则。5. Skills的清理、调试与维护用得越久越要会做减法如果说前面讲的都是怎么加那这一节是我最想强调的怎么减。我见过太多人包括我自己装Skills时满怀热情一个接一个地加最后技能列表长得像超市货架。然后突然发现Agent反而变笨了原来很听话的输出开始跑偏甚至明明该用某个技能的任务它视而不见。这往往不是Agent退化而是技能过载引发的混乱。5.1 为什么Skills过多反而会拖垮Agent判断可以这样理解每次对话开始Agent要把你的请求和每个技能的description做匹配。技能数量少的时候匹配几乎是瞬间完成技能多起来之后多个描述之间会产生干扰。比如你装了前端代码审查、React代码审查、TS代码审查三个高度重叠的技能Agent面对一条请求时就得做一道三选一的选择题选错了表现自然差。更隐蔽的问题是很多技能包为了功能强大会在SKILL.md里写特别多的步骤和规则。当技能被加载后这些内容会占用宝贵的上下文空间。如果一个任务只需要走三个步骤技能却写了二十条检查项AI很容易把注意力分散到那些无关紧要的项上输出反而显得啰嗦且偏离重点。技能的优化方向应该是精准地少不是努力得多。5.2 清理口径与实操方法参考tibo的清理思路圈内有一个流传很广的清理思路大家习惯叫它tibo的清理方法核心就是定期给技能集做减法。我参考这套思路结合自己的习惯整理了一套可落地的清理流程。第一步盘货。把你所有的技能目录列出来看清楚自己到底装了多少# Claude Code ls ~/.claude/skills/ # Codex CLI ls ~/.codex/skills/ # 项目级技能 ls .claude/skills/ 或 ls .opencode/skills/第二步按使用热度分档。回顾过去两周哪些技能是你真正会主动提到的哪些技能你甚至忘了它存在对于后者先别急着删考虑一个问题是技能不行还是你的工作流根本不需要它如果是后者果断删掉或禁用。第三步合并同类的技能。比如你有三个审查类技能与其忍受它们互相打架不如花两小时把它们合并成一个把不同框架的检查项作为分节写在一个SKILL.md里触发条件统一。第四步删除后做回归验证。删掉一批技能后把之前跑不过的任务重新测一遍重点看有没有因为技能缺失导致输出质量下降。如果确实没影响说明删对了。这套流程建议每两个月做一次。Skills不是收藏品是工具工具就该保持随时能拿到趁手的那件的状态。5.3 症状驱动的Skills调优清单做久了之后我逐渐发现Skill的常见问题其实都有比较固定的症状可以用一个症状清单来快速定位。下面是我常用的排查表症状可能原因处理方式技能完全不生效Agent没用任何技能里的指令技能目录路径不对或description没有覆盖触发词检查目录层级用精确指令复测改写description技能被触发但输出的内容跟技能要求的不像技能正文里的步骤写得模糊或者示例缺失细化步骤补一个高质量示例多个技能互相抢任务行为不稳定技能描述重叠触发条件模糊合并技能或补充什么情况下不要用本技能对话变慢、token消耗明显上升技能数量过多、单个技能过于臃肿做减法精简步骤删除冗余技能包技能在其他项目失效技能装在项目级目录但没进全局目录把需要跨项目的技能移到用户级目录最后再分享一个我自己经常用的小技巧如果你想测试一个技能写得清不清楚可以故意不告诉AI用哪个技能而是直接把你的真实需求丢给它。如果它能自己找到正确的技能并执行得像预期一样说明trigger逻辑是通的如果它找到了但执行歪了问题多半出在正文步骤如果它压根没找那就是description的锅。用这种方法你能在一轮对话里快速定位问题出在哪个环节不用靠猜。