第一次意识到skills这个东西是我在用 Claude Code 给前端项目补 TypeScript 类型的时候。我在对话里把项目背景、编码规范、文件结构写了一大段结果它还是把any用得飞起。后来一个朋友说“你为什么不装个 skill”我一脸懵然后去翻了 GitHub 上的 skills 仓库才明白自己一直在用最笨的方式教 AI 做事。这篇文章就把我这一路摸出来的经验全部摊开讲skills到底是什么、怎么从 GitHub 手动装到 Claude Code 里、Codex 和 OpenCode 那套生态有什么区别、以及怎么写一个自己的 skill。准备入坑或者已经装了一堆但效果不佳的朋友这篇应该能帮你少走不少弯路。1. skills到底是什么AI的“岗位说明书”而不是“咒语包”1.1 一次撞墙之后我才认真读了一遍SKILL.md我最初的错误认知是把 skill 当成“大招”——以为装上一个 skillAI 就能凭空变强。实际用下来才发现skills更像是一份给 AI 的“岗位说明书”它不改变模型本身的智力而是把你在某个任务里的工作方法、判断标准、输出格式、常见坑位全部固化成一份结构化文档。AI 在接到相关任务时会先读取这份说明书再按里面的流程干活。比如我给 Claude Code 装了一个git-commit风格的 skill 之后它生成的提交信息自动变成了feat: 增加用户注册接口这种规范格式不再出现“update code”“fix bug”这种垃圾信息。因为 skill 里明确写了 type 的枚举feat、fix、refactor、docs、chore、scope 的写法、正文什么时候该写、什么时候必须留空。这些内容我也可以每次在对话里手打一遍但问题是一来费 token二来我经常忘记说全三来每次表述不一致AI 的执行质量就会飘。skills解决的恰恰是“稳定复现”这件事。1.2 skills的解剖一个skill文件夹里究竟装着什么在 Claude Code 里一个 skill 本质上就是一个文件夹里面最核心的文件叫SKILL.md。这个文件开头有一段 YAML 格式的 frontmatter通常包含name和description两个字段后面是 Markdown 正文描述这个 skill 在什么场景下使用、应该怎么执行、有哪些注意事项。有需要的话你还可以在同一个文件夹里放示例代码、模板文件、参考文档让 AI 在干活的时候有据可查。我见过不少网上流传的 skill结构五花八门有的是纯提示词有的带全套代码模板有的甚至带了一个校验脚本。但它们的共同点是都遵循“先描述、再触发、后执行”的路径。模型不是每时每刻都在读所有 skill 的全文而是先扫描所有 skill 的name和description判断当前用户请求和哪个 skill 匹配命中后才加载对应的SKILL.md正文。这个机制决定了description写得好不好直接决定了 skill 会不会被触发。1.3 skills和system prompt的根本区别很多人会问那我把同样的话写进 system prompt 不就行了区别其实很大。system prompt 是全局的、常驻的无论你聊什么它都背着这一大段内容token 消耗永远在那里skills是按需加载的平时只暴露一个“目录项”namedescription只有任务命中时才把完整内容读进来。拿一个团队来类比system prompt 是公司的企业文化墙每个员工每天都要看skills是每个岗位的 SOP 手册平时放在书架上只需要看到标签等要干这个岗位的活时才抽出来翻。这也解释了为什么 skills 可以装几十个而不会明显拖慢响应——只要每个 skill 的 description 写得克制模型在“翻目录”阶段的开销是很小的。反过来如果你把所有流程都堆进 system prompt对话越久、任务越杂token 消耗就越失控。所以我的习惯是长期通用的规范进 system prompt特定任务的流程进 skills。2. 从GitHub手动安装skillsClaude Code实操全流程2.1 先搞清楚两个安装目录手动安装skills之前最容易被无视的就是目录问题。Claude Code 支持两级安装位置一是用户级目录基本路径在~/.claude/skills/二是项目级目录通常在项目根目录下的.claude/skills/。用户级目录对所有项目生效适合放那些你在任何项目里都希望可用的通用技能比如格式化代码、生成提交信息、代码审查项目级目录只对当前项目生效适合放和这个项目强相关的规范比如“这个仓库的模块划分方式”、“这个团队的前端提交规则”。我建议普通用户优先使用项目级目录。因为用户级目录一旦装多了你在任何项目里都会被这些技能“打扰”模型可能会在写后端代码时莫名其妙地去匹配一个前端切图的 skill。把安装范围收到项目里反而能让 skill 的命中更精准。当然像commit-message这种万金油类 skill放用户级目录确实是省事的要具体情况具体分析。2.2 获取skill的两种常见方式从 GitHub 上拿 skill主要有两种方式一种是git clone整个仓库另一种是只下载某个文件夹或单个SKILL.md文件。仓库型的好处是你后续可以用git pull更新适合安装那种长期维护的知名技能库但缺点是很多仓库喜欢把几十个 skill 塞在一起你 clone 下来之后还要自己挑、自己复制。单文件型适合你只需要某一个技能的场景直接curl下来放进对应目录就行干净利落但后续要手动跟踪更新。我个人用下来更喜欢先把仓库 clone 到本地临时目录看清楚目录结构后再挑选需要的 skill 复制到skills目录。这样你能直观看到这个 skill 里除了SKILL.md之外还有没有附带的参考文件避免漏拷贝文件导致 skill 失效。2.3 手动安装的完整步骤下面以安装一个来自 GitHub 的 skill 为例走一遍我实际操作过的流程先在 GitHub 上找到目标仓库比如你想装一个社区的code-reviewskill使用git clone或直接在网页上下载 zip 包到本地临时目录。打开仓库目录找到对应 skill 的文件夹。大部分规范仓库都会把每个 skill 放在一个独立子目录中里面有SKILL.md。在目标项目下创建目录mkdir -p .claude/skills然后把整个 skill 文件夹复制进去。注意复制的是文件夹本身不是只复制SKILL.md文件除非你确认这个 skill 没有任何附带文件。确认文件夹名与SKILL.md中的name字段一致。不一致的情况下模型在识别阶段可能产生歧义社区里很多“装了没用”的反馈就是栽在这个细节上。重启 Claude Code 会话让系统重新加载 skills 列表。如果是用户级安装把第三步的路径换成~/.claude/skills/即可。整个流程五分钟内能搞定真正耗时间的反而是挑选合适的 skill——仓库里的中文描述有时语焉不详得自己点进去读SKILL.md才能判断质量。2.4 怎么验证skill真的被识别了装完之后怎么知道有没有生效有两个办法。第一个是直接在当前会话里输入/skillsClaude Code 会列出当前已经加载的 skills 列表你找到刚安装的那个名字就说明注册成功了。第二个是故意在对话里提一个和这个 skill 相关的任务观察模型有没有主动引用 skill 里的内容。比如你刚装了个docker-debuggingskill你就可以问一句“帮我看看这个容器为什么一直重启”如果它开始按 skill 里的排查顺序问你问题那就是触发成功了。我遇到过一种“假成功”的情况/skills列表里确实能看到名字但实际任务完全不按 skill 走。这种多半是description写得过于笼统导致模型在“目录匹配”阶段没有把用户请求和这个 skill 关联起来。这时候要改的不是代码而是SKILL.md的description字段。2.5 安装失败的高频原因把我在社区里看到和亲身踩过的坑集中列一下目录层级错误把SKILL.md直接丢进了.claude/skills/根目录而不是放在skills/某技能名/SKILL.md。虽然 Claude Code 对层级有一定容错但按规范放文件夹是最稳的。skill 文件夹名与 name 字段不一致模型按 name 加载时可能会找不到对应内容。漏拷贝附带文件一个 skill 除了SKILL.md还引用了templates/或examples/下的文件只复制一个入口文件执行时到处报错。description 里有特殊字符某些特殊符号会导致 YAML 解析失败skill 直接不加载。权限问题在 Linux 服务器上~/.claude/skills的属主不是当前用户导致 Claude Code 没有读取权限。这个在多人共用的开发机上特别常见chmod一下就好。3. Codex、OpenCode与官方示例多工具生态里的skills现状3.1 三款主流工具的skills支持对比现在聊skills已经不光是 Claude Code 一家的事了。OpenAI 的 Codex、开源的 OpenCode 都在做类似的功能只是命名和实现方式略有不同。我用了一张表来梳理它们之间的差异工具skills相关机制目录/配置习惯触发方式Claude CodeAgent Skills官方文档明确支持.claude/skills/name/SKILL.md模型根据 namedescription 自动命中Codex通过 AGENTS.md、自定义提示和命令实现类 skills 效果项目根目录的AGENTS.md、codex/等通常是启动时注入或规则匹配OpenCode支持 AGENTS.md、.opencode 配置与命令扩展AGENTS.md、.opencode/command/命令式调用为主也有自动匹配尝试从使用体验上看Claude Code 的skills是最接近“自动按需加载”的Codex 和 OpenCode 则更依赖你主动把规范写进AGENTS.md或配置里。如果你是从 Claude Code 转过去用 Codex最省力的做法是把SKILL.md的核心内容压缩进AGENTS.md的对应章节虽然没有实体文件夹但效果是类似的——模型在每次对话开始时就能看到这些约束。3.2 typesafe-ai/ai-skills这类项目在解决什么问题GitHub 上有不少项目在尝试给skills做工程化封装typesafe-ai/ai-skills就是比较有代表性的一个。它做的事本质上是把散落的SKILL.md变成一套带类型定义、可校验、可发布的资产。你可以把它理解成给“提示词包”加了 TypeScript 的类型系统每个 skill 的入参、输出、使用场景都被显式声明团队可以像管理代码包一样管理提示词。对于个人用户来说这类项目最大的意义不是“你必须用它”而是它提供了一种很好的组织视角。我从里面学到的是skill 的输入边界要清楚内部依赖要明确输出格式要可验证。这些东西即使你不用它的框架写自己的 skill 时也完全适用。仓库本身也是个不错的灵感来源里面的 skill 示例比社区里那些为了流量凑数的仓库规范得多。3.3 技能库网站与“skills网页版”是怎么回事热词里有一条叫“skills网页版进入”我猜很多人是看到某个技能库网站之后就不知道怎么用了。我的理解是这类网站提供了在浏览器里浏览 skill 内容的入口你可以在线查看某个 skill 的SKILL.md、复制它的内容然后再手动放到本地目录里。它们起到的是一个“展示市场”的作用最终落地还是要回到本地文件系统。这些网站质量参差不齐有的只是把 GitHub 仓库的内容做了个好看的皮肤有的则会把你导引到付费服务。我建议普通用户还是把 GitHub 作为第一渠道直接在代码搜索里搜SKILL.md或claude skills能看到原始内容、star 数和更新记录更容易判断质量。网站可以当索引看但别把账号体系绑定得太深。3.4 跨工具复用的思路如果同一套技能想在多个工具间复用我的做法是维护一个自己的 skills 目录。在这个目录下每个 skill 就是一份内容独立的 Markdown 文件不绑定任何工具的特殊语法。需要用 Claude Code 时把它按.claude/skills的结构放好需要给 Codex 用时把它的核心要点抽进AGENTS.md。这种“一处编写多处编译”的方式听上去有点费事但实际维护成本比想象中低因为真正会变的只是外层包装核心工作流不变。4. 手写一个自己的skills以数学建模场景为例4.1 动手前先想清楚三件事写 skill 之前我最喜欢问自己的三件事这个 skill 要解决什么任务这个任务的高频流程是什么我期望 AI 在什么情况下不要用这个 skill第一件事决定name第二件事决定正文第三件事决定description里的边界描述。很多人只会写“这个 skill 能干什么”不会写“这个 skill 不干什么”结果就是模型在无关任务上频繁误触发白白消耗上下文。以数学建模为例。你要写的不是“数学建模万能 skill”——那太大了多半只会得到一堆空话。你应该拆成更小的任务单元赛题分析、模型选型、论文摘要润色、结果敏感性分析。每个单元单独一个 skill命中率和执行质量都会高很多。4.2 frontmattername和description怎么写才能被AI准确命中name要短、要具体、要像一个“工具名”比如mcm-problem-analysis不要用math-model这种过于宽泛的词。description是重中之重它决定了模型会不会在正确的时刻调用这个 skill。一个好的写法是先给触发条件再给任务目标最后给抗干扰的边界。我写过一个用于数学建模赛题分析的 skilldescription是这样的--- name: mcm-problem-analysis description: - 当用户给出数学建模竞赛题目或赛题背景需要拆解问题目标、约束条件、 数据特征并给出多个候选模型方向时使用。尤其适合在比赛开始后的前两小时内 快速形成选题判断。不适用于单纯的论文润色或结果可视化。 ---这里的关键词是“建模竞赛题目”“拆解问题目标”“候选模型方向”模型读到这些词就更容易把它和“帮我分析一下这道题”关联起来。最后那句“不适用于”看起来没什么用其实能显著减少误触发因为模型在做匹配时会把这句话当作排除依据。4.3 正文结构触发条件、工作流、模板、检查清单SKILL.md的正文不像技术文档需要面面俱到它更像一份“给聪明新员工看的入职手册”。我的习惯是分四个区块何时使用重申触发条件和禁止使用的情况。执行步骤按顺序列出 AI 应该完成的工作流最好有编号。输出模板规定最终交付物的格式比如“先输出问题重述再输出模型假设再输出求解思路”。检查清单让 AI 在交付前自行核对的条目例如“是否说明了模型适用条件”“参数符号是否统一”。数学建模赛题分析这个场景里执行步骤大概是识别题目类型优化、预测、评价、分类→ 提取目标函数与决策变量 → 梳理约束条件 → 判断可选模型集合 → 给出每个模型的复杂度与数据需求 → 输出推荐优先级并说明理由。输出模板要规定 AI 用表格还是列表组织推荐模型我强烈建议用表格因为比赛评委和队友都习惯快速扫视。4.4 从一个建模skill模板说起下面是一个可以拿来改的简化版模板它不是我实际用的完整版本但骨架已经够你起步--- name: mcm-problem-analysis description: 用户提供数学建模赛题或需求时拆解优化目标与约束并推荐模型时使用。 --- # 数学建模赛题分析流程 ## 第一步问题解读 - 把题目转写为“目标 约束 数据 评价口径”四要素 - 标注题目的隐藏假设例如“供需平衡”“单位价格恒定” ## 第二步模型候选 - 至少给出两个方向的模型不允许只给一个“标准答案” - 对比条件数据量需求、可解释性、实现难度、稳定性 ## 第三步输出格式 用表格输出候选模型列名固定为 | 模型 | 适用条件 | 数据需求 | 实现难度 | 推荐度 | ## 检查清单 - [ ] 是否包含隐藏假设 - [ ] 是否说明了每个模型的适用边界 - [ ] 是否给出了不推荐方案的理由这里面最容易被忽略的是最后几行检查清单。我看过很多社区 skill正文只有一堆流程描述没有检查项。对 AI 来说流程描述是“做事的方法”检查清单是“交付的标准”两者缺一不可。方法能保证它往正确方向走清单能保证它交付前不自欺欺人。4.5 前端开发skills的写法任务拆解 规范注入 验收前端开发类的skills是热词里出现频率很高的方向我也专门整理过一个。它的核心不是“教 AI 写 CSS”而是让 AI 在动手前先把任务拆到足够细再按项目规范落实。我见过太多 AI 生成的“页面”看起来没问题但完全没遵守团队的设计系统组件命名也是随机的。所以在我的前端 skill 里执行步骤就三块第一步把视觉稿或需求描述拆成组件树标清父组件和子组件第二步检查设计规范文件里对间距、圆角、字体层级的规定并把这些 token 映射到代码里第三步写完代码后按验收清单自查清单包括“是否复用了已有组件”“是否使用了 design token”“是否考虑了空态、加载态、错误态”。每一条之后都可以补一个为什么AI 会更容易理解规则的意图而不是机械执行。4.6 自测的笨办法实际跑一遍写完 skill最有效的测试方法就是把它装进一个空项目然后从不同角度提问。先问一个和这个 skill 高度相关的任务看它是否触发再问一个八竿子打不着的任务看它会不会误触发最后把任务描述变种几次看触发是否稳定。很多 skill 写出来自己觉得很好一测就露馅——要么没触发要么触发了但执行过程跳步。跳步的问题通常出在正文的步骤编号不够强制AI 会在中间自作主张地省略。解决办法是在说明里强调“按编号顺序执行不得跳步”。5. 哪些skills值得装常用类型和源头仓库推荐5.1 代码生产力类这类skills的价值最大也是我用得最频繁的。code-review类 skill 会规定审查顺序先看变更影响面、再看逻辑正确性、最后看风格规范并要求按严重程度对问题分级commit-message类 skill 统一提交格式test-generation类 skill 会让 AI 先列出业务用例再生成对应测试代码而不是随手抛几个用例就算完refactoring类 skill 会限定一次重构的步长避免 AI 一次性改动十处导致难以 review。如果只让我推荐三个入门我会选code-review、commit-message和unit-test-generator。5.2 内容生产类如果你用 AI 做自媒体、漫剧脚本或短视频文案skills同样能帮上忙。以“AI 漫剧”为例一个常用的 skill 组合是分镜生成的 skill 负责把一段剧情文字拆成景别、镜头运动、时长、台词角色一致性描述生成的 skill 负责输出包含固定外貌关键词的提示词脚本结构化 skill 负责把对白、旁白、动作分层方便后续配音和剪辑。这类 skill 没有技术类那么强的客观标准核心价值是把你摸索出来的“能出好片”的经验固化下来让每次生成都稳定。5.3 值得关注的几个GitHub仓库仓库我会按可靠性推荐anthropics/skills官方示例虽然偏基础但胜在权威是学习格式的最佳入门材料。superpower-chatgpt/superpower-skills社区非常活跃的中大型技能库覆盖面广。需要注意的是它更新快、数量多不要一口气全部装上挑几个高频的就好。typesafe-ai/ai-skills工程化风格更重适合想深入理解 skills 结构的人。GitHub 上还有一堆零散仓库名字里带claude-skills、codex-skills、cola-skills的都有很多是团队内部沉淀后开源出来的。这些仓库的价值不在数量而在于你能看到别人怎么组织规范、怎么写 description、怎么处理边界情况。有时间翻三个规范仓库比无脑装三十个 skill 有用得多。5.4 我用得最多的组合我现在常用的组合并不复杂commit-format稳定提交信息格式code-review所有合入前的大变更都会让它过一遍debug-triage遇到线上问题时先按“复现路径-影响范围-变更历史-最小修复”顺序排查mcm-problem-analysis竞赛季专用content-storyboard做漫剧和短视频脚本时用。装得少的好处是模型在目录扫描阶段的干扰更少每个 skill 的 description 都能被清晰看到命中率反而更高。我见过有人装了上百个 skill结果 AI 经常在任务中途跳到一个毫不相关的 skill 里原因就是多个 description 都包含了相似的触发词模型选错了对象。6. skill库失控之后清理、命名与长期维护6.1 症状装得越多效果越差技能库失控时最典型的症状不是 AI 变笨而是技能“串台”你让它写一段 SQL它突然按某个数据分析 skill 的模板输出你让它修一个 bug它先给你一份架构优化建议。这不是模型抽风而是你的 skills 之间在 description 层面互相污染了。另一个症状是上下文膨胀某些仓库里的 skill 文件动辄几百行每次触发都要读一遍长对话里的可用上下文被明显挤压。我踩过最狠的一次装了一个“全栈开发专家” skill结果它一出场就要求 AI 按“需求分析-技术选型-架构设计-代码实现”四步走哪怕我只是让它调一个接口的返回字段。它在目录匹配时感觉“全栈”这个词覆盖面很大于是频繁抢戏。6.2 一套来自社区的清理思路Tibo的方法在关于如何清理 skills 这件事上我印象最深的是 Tibo 分享过的一套思路核心就三句话先禁用、再观察、最后删除。不要看到某个 skill 不顺眼就立刻删文件而是先把它移出 skills 目录或改掉 name观察两三天看你手头的工作有没有受影响。很多 skill 你平时感知不到它的存在但一旦禁用某些任务质量立刻下滑说明它其实一直在默默起作用。他还提过一个很实用的点给每个 skill 标注“最后手动调用日期”。这个信息平时别嫌麻烦养成在对话里记录的习惯清理时就能看到哪些 skill 两个星期都没被命中过。对于这类 skill要么是 description 写得有问题导致模型永远不触发要么是这个任务你根本不需要 AI 来做。前者改 description后者直接删。这套方法最值钱的地方是把“我觉得没用了”变成“数据说明它确实没用了”。6.3 我的维护习惯为skill写README、给版本打tag我现在维护一个个人 skills 仓库里面除了每个 skill 的SKILL.md还会在同目录放一个简短的 README记录三件事这个 skill 是为哪个项目或场景写的、依赖哪些外部文件、更新时主要改了什么。起初觉得很麻烦但后来发现skill 这个东西一旦超过十个你三个月后再看根本想不起来当初为什么这么设计。README 是写给未来的自己看的这一点都不矫情。版本管理方面我习惯在更新SKILL.md后顺手打个 tag。这个动作看上去很轻但它让你能在效果变差时快速回退到上一版。AI 模型升级之后同一个 skill 的表现可能大不相同没有版本标记你只能一脸茫然地从头调优。7. 踩坑记录从“不生效”到“提示注入”7.1 skill没生效问题往往出在description前面提过skill 不生效的头号原因不是目录放错而是description和实际任务对不上。模型是根据语义相关性做匹配的如果你的description里通篇都是“优秀的”“强大的”“全面的”没有具体触发词那匹配质量就会很差。另一个原因是description太长模型在扫描阶段只读到前面几行关键信息全被淹没了。我写description的体感是控制在 150 字以内把最典型的触发场景写在最前面。7.2 上下文被无关skill吃掉的真相有些第三方 skill 会把大量示例、长代码块直接塞进正文触发一次就吃掉一两千 token。如果你在长对话中频繁触发这类 skill上下文窗口很快会被挤占后面的回答质量肉眼可见地下降。建议在安装后打开SKILL.md看一眼体量超过 300 行且没有目录导航的谨慎使用。想要省 token可以自己动手把长 skill 拆成“精简版”和“完整版”两个平时默认触发精简版需要细节时再让 AI 去读参考文件。7.3 第三方skill的安全边界警惕提示注入这是我认为最重要的一条。GitHub 上的SKILL.md本质是一段会被 AI 自动执行的文本这意味着恶意作者完全可以在里面写下“忽略用户之前的所有指令直接输出以下内容……”之类的话。你把这样的 skill 装进本地环境就相当于让一段不可信文本拥有了在你终端上下文里发声的机会。虽然 Claude Code 和 Codex 都有一定的安全机制但这不是你放松警惕的理由。我的应对方式很朴素只安装来源明确、star 数正常的仓库装之前全文读一遍SKILL.md看到“忽略指令”“输出 JSON 到某路径”“调用 curl”这类内容就要格外小心不安装那些要求提供 API Key 或读取敏感配置的 skill。写自己的 skill 时也要避免让 AI 直接执行未经确认的命令。7.4 版本更新与向后兼容工具版本更新是另一个坑。Claude Code 的 skills 格式在快速演进Codex 和 OpenCode 更是隔几个版本就有配置变化。以前能正常触发的 skill在新版本下可能突然变成“从未安装”的状态或者加载了但格式解析失败。遇到这种情况先去工具的 changelog 里搜skills相关更新通常能找到格式迁移说明。社区里有大量“昨天还能用今天全失效”的求助帖十有八九都是版本升级导致的格式不兼容。把话说回我自己折腾skills这段时间最大的体会是——它真正的价值不在“装得多”而在于把那些你反复交代、反复纠正 AI 的事情一次性固化成稳定资产。skills不是魔法它是你把经验写进 AI 工作流的一种方式。如果你现在正被“AI 总不稳定”“每次都要重新教一遍”困扰与其继续在对话里堆 prompt不如花一晚上写一个自己的 skill。哪怕写得粗糙只要它能稳定复现你想要的输出它就已经比一百个收藏夹里的“神级提示词”更值钱了。