1. Skills 到底解决什么问题——它更像给 AI 发了一本岗位手册最近一个月我至少被问了几十次“skills 到底怎么用”——GitHub 上的 skill 怎么装进 Claude CodeCodex 能不能用自己写一个难不难装了一大堆之后怎么清理。起因是 Claude Code 把 Skills 做成一整套规范之后Codex、OpenCode、Cursor 这些工具也陆续跟上“skills”这个词一下子成了 AI 编程圈绕不开的话题。我最初觉得这只是又一个新名词直到把团队里高频重复的“代码评审”“建表脚本”“bug 复现模板”都做成了 skills才直观感受到这东西和 MCP、和普通提示词的定位完全不同它不负责连接外部系统而是负责让 AI 在特定任务里按一套靠谱的流程干活。下面这篇我把这些天折腾出来的经验完整梳理一遍覆盖怎么装、怎么写、怎么挑、怎么清理以及那些文档里不会明说的坑。1.1 从 Claude Code 到 Codex/OpenCodeSkills 是怎么火起来的2025 年 Claude Code 做了一个很有产品感的改动允许把一组“指令 脚本 参考资料”打包成一个 Skill放在项目的.claude/skills目录或全局的~/.claude/skills目录。AI 在对话里遇到相关任务时会按需加载对应的SKILL.md照着里面的步骤执行。这套东西和普通提示词最大的区别在于普通提示词是你每次临时打一段话而 Skill 是预置的、结构化的、可复用的相当于提前给 AI 发了一本岗位手册。为什么它扩散得这么快原因很朴素。一个 Skill 的最小形态就是单个 Markdown 文件成本极低同时它可以直接包含 Python、Shell 等脚本能处理真正需要计算的任务。GitHub 上很快冒出了大量 skills 仓库从代码规范检查到论文排版都有覆盖。Codex、OpenCode 这些工具跟进之后各自的目录命名和加载逻辑虽然略有差异但核心范式基本统一识别任务、加载对应技能、按技能里的 SOP 输出结果。注意我见过不少人把“给 AI 写一段好提示词”等同于“开发 skills”。不是的。提示词是一次性的skills 是可持续维护的资产。判断标准很简单如果这个任务下个月还会再做一次就值得做成 skill如果只是临时问一嘴写提示词就够了。1.2 Skills 不是 MCP也不是普通插件先泼一盆冷水很多人一上来就把 Skills 和 MCP Server 混为一谈这会导致后面选型全跑偏。MCPModel Context Protocol解决的是“AI 怎么连接外部资源和工具”的问题——查数据库、调 API、读文件都靠 MCP 暴露给模型。Skills 解决的是“AI 拿到任务之后按照什么样的专业流程来做”的问题——先干什么、后干什么、达到什么标准算完成。两者不是替代关系而是配合关系。举个实际例子一个 MCP Server 可以给 AI 提供“查询 Git 提交记录”的工具但 AI 要不要在评审每个 PR 前先拉提交记录、再按哪几个维度给意见这是 Skill 该管的事。你可以用一个 code-review 技能明确要求“第一步读 diff第二步从安全、性能、可读性、测试覆盖四个维度逐条列问题第三步给出修改示例”。MCP 负责让 AI 能拿到 diffSkill 负责让 AI 像资深工程师一样去 review。维度MCP ServerSkill技能包核心职责暴露工具和数据接口提供干活流程、专业知识和验收标准内容形态Server 代码 工具定义以 SKILL.md 说明文件为主可附带脚本典型场景查数据库、调 API、访问文件系统代码评审、写周报、拆解建模赛题、生成分镜你是否需要需要打通外部系统时需要让 AI 稳定按一套 SOP 干活时还有一层容易混淆的是“插件”。传统 IDE 插件往往深入编辑器内部提供右键菜单、快捷键、界面面板Skills 更轻本质是“文档 可选脚本”的封装不需要编译不需要权限申请丢进目录就能被 AI 读取。虽然两者都在扩展 AI 工具的能力但 skills 的迭代成本低得多。1.3 一个技能带来的实际差别以代码评审为例没有技能的时候让 Claude Code 做代码评审它经常会输出“这段逻辑看起来没问题”“建议补充单元测试”这种正确但没用的废话。评审质量完全取决于你现场临场发挥把需求和约束说得多清楚。有了 code-review 技能后输出结构会变成这样自动先列出本次变更涉及的文件与函数调用链从安全、性能、可读性、测试四个维度逐项检查每个问题标记 P0/P1/P2 严重级别每个 P0/P1 问题必须给出可落地的修改片段而不是口头建议最后输出“建议合并 / 需要修改”的结论并附上理由。同样一句“帮我 review 一下这个 PR”有技能和没技能的区别几乎是两个工程师的差距。这也解释了为什么“skills 推荐”会突然变成热搜词大家很快发现与其每次手把手教 AI不如把这个“教”的过程沉淀成可复用的资产。2. 从 GitHub 手动安装 Skills目录规则才是核心“怎么手动装 GitHub 上的 skills”可能是问得最多的问题。我的回答历来是下载本身不是难点难点是搞清楚你的工具到底从哪个目录读技能、以及目录里的结构长什么样。很多人装完不生效十有八九是目录结构不对而不是下载失败。2.1 不同工具的技能根目录先搞清楚 AI 从哪读技能以 Claude Code 为例它约定两个位置全局技能~/.claude/skills/项目级技能项目根/.claude/skills/每个技能是一个独立子目录子目录名就是技能名目录内必须有SKILL.md。Codex、OpenCode 虽然也喊“支持 skills”但实际的路径和加载优先级得看对应版本的文档不能直接照搬 Claude Code 的路径。我的建议是先跑通一个 hello world 级别的技能确认工具的技能根目录到底在哪再开始批量安装。工具技能根目录示例说明Claude Code~/.claude/skills/.claude/skills全局与项目级并存Codex 系列以官方文档为准加载方式随版本变化较快OpenCode以官方文档为准目录约定与 Claude 类似但不一定相同不要嫌这一步啰嗦。很多人图省事直接把技能仓库克隆到默认目录就完事结果工具版本升级后路径变了技能集体消失排查半天才找到原因。2.2 手动安装的最稳路径临时克隆再拷贝从 GitHub 装一个技能最稳的步骤不是“整仓克隆进技能目录”而是“先克隆到临时目录看清楚结构再把包含 SKILL.md 的那个子目录拷进技能根目录”。为什么这么绕因为大量 skill 仓库的根目录是一个合集里面塞了十几个技能、测试文件、图片素材直接整仓丢进 skills 根目录AI 可能会扫到一堆无关文件还容易和你已装的同名技能冲突。我常用的命令是这样# 方式一单技能仓库直接克隆 mkdir -p ~/.claude/skills git clone --depth 1 https://github.com/owner/repo.git ~/.claude/skills/skill-name# 方式二合集仓库找到子目录再拷贝 git clone --depth 1 https://github.com/owner/repo.git /tmp/tmp-skill ls /tmp/tmp-skill mkdir -p ~/.claude/skills cp -r /tmp/tmp-skill/实际技能目录 ~/.claude/skills/skill-name rm -rf /tmp/tmp-skill注意三点--depth 1只拉最新版本避免把仓库历史、图片、测试文件全部拖下来又快又干净。拷贝后的目录名就是技能名建议用 kebab-case小写短横线连接例如>--- name: math-modeling-breakdown description: 在拿到数学建模赛题时使用将赛题原文拆解为问题背景、决策目标、约束条件、数据清单、评价指标与可选模型最终输出一张结构化的建模思路卡。 ---很多人以为 description 是给人看的说明其实它是给 AI 做“技能检索”用的。AI 面对一个新任务时不太可能把每个技能的正文都从头读一遍它主要靠 name 和 description 判断“现在这个任务该调用哪个技能”。所以 description 要点是说清楚触发场景什么任务下用这个技能越具体越好。说清楚输入和输出输入赛题文本输出思路卡。避免抽象形容词不要写“帮助用户更好地完成建模”要写“将赛题拆成七个结构化字段”。我见过大量“装了很久但从没被触发”的技能根源几乎都是 description 含糊AI 根本不知道什么时候该用它。3.3 正文怎么写步骤、完成标准、和禁忌SKILL.md 的主体是正文写的是 AI 执行这个技能时要遵循的流程。我最推荐的结构是“步骤 完成标准 禁忌”三件套。步骤告诉 AI 先干什么后干什么完成标准告诉 AI 做到什么程度算过关禁忌告诉 AI 哪些事情绝不能做。继续以数学建模赛题拆解为例# 数学建模赛题拆解 ## 输入 用户提供的赛题原文可能包含自然语言描述和数据表。 ## 执行步骤 1. 提取问题背景用一两句话概括赛题目的。 2. 列出所有输入数据与字段含义标注缺失信息。 3. 识别决策目标将其转化为可计算的指标。 4. 梳理显式与隐式约束条件。 5. 给出 2-3 个候选模型简述每个模型的适用前提。 6. 输出一张思路卡包含背景、目标、数据、约束、指标、模型、风险七个字段。 ## 完成标准 - 七个字段全部填满没有“待补充”的甩锅式内容。 - 模型建议必须说明适用条件禁止只列模型名字。 ## 禁忌 - 不要直接给出最终公式而不解释假设。 - 不要在数据不完整时强行编造数值。这种写法为什么有效因为 AI 在自由回答时容易泛泛而谈“步骤 标准 禁忌”把所有可能跑偏的地方提前堵住了。你可以把它理解成给实习生写的 check list光说“认真一点”“专业一点”没用要说清每一步的输入输出。3.4 什么时候值得写一个脚本以及脚本接口怎么约定纯文本的 SKILL.md 适合流程类任务但有些任务需要严格计算——比如统计 CSV 缺失值、批量重命名文件、转换数据格式。这时候就应该在技能里附带脚本。什么时候值得写脚本我给自己定了一个标准任务涉及超过十行的确定性逻辑或者结果需要精确计算就不要让 AI 现场“凭感觉写代码”而是预先写好、封装成脚本。这样每次执行结果稳定不会出现 AI 这次生成正则表达式漏了个边界条件、下次又生成另一个版本的情况。脚本接口怎么约定很关键。最稳的方式是命令里把输入输出路径说清楚脚本从命令行参数读输入把结果打印到 stdoutSKILL.md 里再要求 AI 把 stdout 结果整合进最终回答。例如一个数据质量检查技能python scripts/validate_csv.py --input data.csv脚本示例#!/usr/bin/env python3 # validate_csv.py import csv import sys def analyze(path): with open(path, newline, encodingutf-8) as f: rows list(csv.DictReader(f)) fields list(rows[0].keys()) if rows else [] missing {field: sum(1 for r in rows if not r.get(field, ).strip()) for field in fields} print(f总行数: {len(rows)}) print(f字段: {, .join(fields)}) for field, count in missing.items(): print(f缺失 {field}: {count}) if __name__ __main__: analyze(sys.argv[1])SKILL.md 里就写先运行上述命令再基于脚本输出判断数据是否可用。把“确定性计算”外包给脚本把“判断和写报告”留给 AI这是目前最高效的分工。3.5 从 0 到 1 调试一个自己能用的技能写完之后怎么知道技能好不好用我的调试流程是这样的先准备一个最小测试输入不要一上来就上真实大任务。让 AI 执行这个技能观察它有没有按步骤走。如果 AI 完全没提技能优先查 description 匹配度而不是正文写法。如果 AI 提了技能但没按步骤走说明步骤文案有歧义需要更明确地写“首先”“然后”“最后”或者把“必须/禁止”直接写成强制要求。迭代两三轮后再把真实任务丢给它。对完全没写过 skills 的新人我建议的学习路径是先装几个官方示例照着抄结构选一个离自己工作最近的任务改成自己的 SOP第一版先写纯文本不用写脚本跑通后再给技能加脚本逐步复杂化。这样最不容易受挫。4. 按场景挑技能前端、数学建模、AI 漫剧与几个值得逛的合集“skills 推荐”是搜索热词说明大家真正想知道的是我到底该装哪些。技能这东西极度依赖个人工作流我不会给一份“必装清单”但可以按场景提示几类确实有通用价值的以及在哪里能找到质量好一点的。4.1 前端开发最值得装的几类技能前端圈对 skills 的接受度很高因为前端任务天然适合“规范驱动”。我见过最多人找的技能类型是页面还原与代码生成给设计稿描述输出组件级代码附带语义化标签校验。A11y 无障碍审查按 WCAG 标准逐项检查输出问题级别与修复建议。依赖升级与破坏性变更处理自动分析 changelog、标记 breaking change、给出迁移步骤。TypeScript 严格模式迁移遍历项目定位隐式 any生成逐步修复计划。typesafe 维护的 AI skills 仓库是我比较推荐的它整体偏工程化很多技能围绕 TypeScript 项目的规范、重构、类型安全展开适合前端和全栈团队拿来做基线。这类技能的好处不是让 AI 更聪明而是让 AI 输出的代码风格和团队规范保持一致减少人工挑刺的时间。4.2 数学建模与比赛场景让 AI 按流程拆题“华为杯建模比赛好用的 codex skills”能成为热搜说明真有不少人在比赛场景里用 AI 工具。建模赛的最大痛点是时间紧、题面长、思维容易乱。针对这个场景技能包可以做三件事赛题拆解技能把一段几百字的赛题转成结构化的“背景、目标、数据、约束、指标、模型候选”卡片。数据预处理技能自动检查数据缺失、异常值、量纲差异输出清洗建议。论文排版技能按模板生成 LaTeX 三线表、公式对齐、参考文献规范。这类技能的开发逻辑和前端完全不同它更偏向“把评委视角变成 check list”比如拆题时逼着 AI 把目标函数、约束条件一条条列清楚避免建模到一半发现少了变量。对于比赛场景比起让 AI 直接生成一篇“看起来像模像样”的论文更重要的是流程质量和可回溯性。4.3 AI 漫剧和内容生产角色一致性与分镜AI 漫剧是内容创作里比较新的场景用到 skills 的地方也很有意思。漫剧制作里最痛苦的两个问题一是跨画面的角色一致性二是分镜脚本的结构化。角色会随着画面数量增加而逐渐“漂移”发色、服装、标志物都会变。一个角色卡技能可以解决一部分问题它会生成一份“角色设定卡”包含角色名、发型、配色、服装、标志物、禁止改动的特征列表每次绘图前强制要求 AI 先输出角色卡再基于卡描述新画面。分镜技能也很实用输入一段文案输出按“镜号、景别、画面描述、台词、时长、转场”六个字段组织的分镜表。这本质上是把导演的工作习惯写成 SOP让 AI 每次生成的结构统一方便后期剪辑和校对。这类技能一般不依赖脚本完全靠 SKILL.md 里的规则约束非常适合新手拿来练手。4.4 值得逛的技能源与质量判断标准网上能找到技能的地方很多官方示例仓库、社区聚合站、个人维护的合集superpower、cola skills、codex nature skills 以及前面提到的 typesafe 系列。口径很乱我提供一个“值不值得装”的判断标准打开技能目录看 SKILL.md 是否完整。只有半页说明、没有步骤和完成标准的直接跳过。看最近更新时间。超过半年没动的大概率已经跟新工具版本脱节。看 description 写得好不好。连 description 都写不清楚自己适用场景的技能装上也是吃灰。看是否依赖私有脚本环境。依赖一堆私有工具的装起来成本高出了问题难查。不少聚合站还有网页版可以在线浏览技能目录、查看详情再复制安装命令回终端执行。用网页看的好处是可以先看 description 和结构再装不用一个个 clone 回来试错。5. 技能装多了的熵增问题盘点、清理和 Git 管理Skills 会越攒越多这是必然的。看到好玩的技能就装两周后你会发现~/.claude/skills底下堆了三十几个目录AI 的行为开始变得飘忽不定。这个阶段清理比安装更值得花时间。5.1 先盘库存哪些是被真正触发的盘库存我用的命令很简单ls -1 ~/.claude/skills列出所有目录之后再根据最近两周的任务记录判断哪些技能在真实对话里被触发过。很多技能可能装上之后一次都没被加载过。另外一个隐性问题是你已经忘了某些技能是干什么的如果你看着目录名还得想半天它是干嘛的说明它大概率也不是团队需要的。社区里有位我比较认可的作者tibo专门写过清理 skills 的方法核心思路就是“先记录、再判断、后归档”而不是想起来就删。他还强调每个技能都要写清楚适用边界没有边界的技能最容易在错误场景里被错误触发造成 AI 答非所问。这跟写代码注释是一个道理边界不清的模块迟早出事。5.2 技能多了的隐性成本上下文与命中率技能不是装得越多越好因为它是有隐性成本的。虽然主流工具大多是“按需加载”不会把每个 SKILL.md 的全文都塞进每次对话的上下文但候选技能一多AI 在“该不该加载这个技能”上的判断压力会变大出现两个问题命中率下降该用技能 A 的时候AI 可能错误加载了技能 B输出风格和流程都变奇怪。候选列表膨胀即使不加载全文技能的 name description 列表通常也会被扫描列表一大提取关键词的难度增加推理延迟可能变高。用概率来理解更直接候选技能增加一倍错误匹配的概率远不止增加一倍因为相近的 description 会互相干扰。不要做“技能收藏家”要做“技能即用即清”的人。5.3 清理策略归档优于删除按项目隔离清理技能我推荐“归档”而不是“删除”。在~/.claude/skills-archive建一个目录把低频技能移进去mkdir -p ~/.claude/skills-archive mv ~/.claude/skills/低频技能 ~/.claude/skills-archive/这样既不会误删以后想用的东西也不影响当前技能目录的干净程度。等归档满三个月还完全没碰过再考虑真正删除。另一个很有效的策略是按项目隔离。全局目录只放跨项目通用的技能比如代码评审、通用数据清理把垂直领域的技能放到具体项目的.claude/skills里。这样 AI 在这个项目下工作优先看到的候选技能数量会少很多命中率明显提升。我试过把一套“微信小程序开发技能”从全局挪到项目的.claude/skills后AI 反而变得更容易主动使用它了。清理的核心原则是让技能目录里的每一项都处于“本周可能用到”的状态。tibo 那个方法里最狠一条是每次开会或者项目复盘时同步做一次技能盘点当作 schedule 任务而不是等出问题再收拾。5.4 用 Git 和软链接管理自己的技能集技能攒到一定程度我强烈建议用一个 Git 仓库管理自己的技能集合。别人的技能是克隆来的自己的定制技能和常用技能可以统一放进一个my-skills/仓库my-skills/ ├── code-review/ ├──>ln -s ~/my-skills/code-review ~/.claude/skills/code-review这样做的好处有三个第一技能内容可以版本回滚改坏了随时回到上一版第二多台机器同步时只需 clone 仓库再批量建链接第三团队里可以直接共享这份仓库新同事拉下来就能拥有一致的工具能力。我自己的习惯是“仓库存真身目录放链接”这样既能用 Git 管理又不影响技能目录的整洁。注意软链接的目标路径不能是仓库整个目录而是每个技能各自的子目录否则 AI 会看不懂结构。6. 只有实际跑过才懂的 Skills 坑最后这一部分全是真实跑过之后踩出来的经验。它们不属于任何文档但几乎每天都会让我在问题出现时更淡定。6.1 description 写不好装了等于白装这是最普遍的一个坑。我见过有人花半小时写好一个技能正文description 只写了“used for code review”。结果 AI 在真正需要代码评审时完全不加载它因为任务标题里的关键词触发不了这条描述。description 要像搜索引擎的索引一样把触发它的同义词和变体都包含进去。宁可写长一点也不要让 AI“猜”。6.2 同名覆盖与项目级优先的关系同名技能会在全局和项目级之间冲突。大多数工具采取项目级优先策略也就是说你项目里放了一个code-review全局那个就被盖住了。这本身是好事但坏就坏在它“静默覆盖”你根本不知道全局那个还在不在候选中。排查诡异行为时先ls .claude/skills看看有没有同名目录这是我排过的最高频原因。6.3 跨工具兼容别把 SKILL.md 写成某个工具的私货同一个技能在 Claude Code 里好好的拿到 Codex 或 OpenCode 里可能发挥不出来。原因通常是 SKILL.md 里写了太多“某个工具专有”的东西比如特定语法、特定 MCP 工具名、特定 shell 别名。我的建议是如果技能有跨工具复用需求正文用自然语言描述步骤脚本用标准 Python 或 Node命令只用标准的python xxx.py、node xxx.js不要依赖 bash 别名和环境变量。保持工具无关性技能的可迁移性才会好。6.4 技能依赖和脚本环境AI 不会替你装环境技能带脚本意味着脚本依赖的环境必须预先装好。AI 大概率不会自动帮你pip install它只是运行命令然后读输出。我见过很典型的现场数据清理技能写得很好但执行时发现没装 pandasAI 直接在回答里报错。解决方法是安装技能之后手写一条依赖安装命令补上或者在技能里加一个requirements.txt并在 SKILL.md 里写明首次使用前需要先执行环境安装。6.5 什么场景真的不需要 Skills最后说点反方向的。Skills 不是万能的很多场景完全不需要。一次性任务、探索性极强的头脑风暴、答案没有固定标准的任务这些都不值得做技能。技能是为“重复发生 有稳定方法 期望稳定输出”的任务准备的。我个人的体会是skills 最大的价值不是让 AI 变聪明而是让 AI 对你手头这类任务始终保持在一个“熟悉流程”的状态。它像是把团队里最有经验那个人脑子里的检查清单换成了文件放在每个人都能拿到的地方。哪怕你只有一个人在用 AI 工具这套“把流程沉淀下来”的思路也值得你认真对待。