最近小半年技术社区里讨论热度最高的一个词大概就是skills了。不夸张地说Claude Code、Codex、OpenCode 这几个主流的 AI 编码工具都在把自己的技能体系往 skills 方向收拾。这篇文章写给三类人在 GitHub 上看到 skill 仓库但不知道怎么手动装进去的人想自己写一套 skill 把高频工作模板化的人还有看到“前端开发 skills”“数学建模 skills”“AI 漫剧 skills”这些推荐词一脸懵、想找现成技能包的人。我会按实际项目经验讲清楚 skills 是什么、怎么装、怎么写以及装上之后最容易踩的坑。所有内容都是我实际动手搞过、验证过的不是概念搬运。1. skills 到底是什么为什么一夜之间大家都在聊1.1 一个类比给 AI agent 装的“岗位说明书”群里经常有人问“skills 和 prompt 到底有啥区别”这个问题其实问到点子上了。prompt 是你临时说一句话让 AI 干活skills 则是提前放在它“工位抽屉”里的一整套资料什么时候翻、第一步做什么、做到什么标准可以提交、哪些事绝对不能干。我习惯把它类比成新员工入职培训包——里面有岗位职责、SOP 手册、质量红线、常用工具清单。AI agent 每次接到任务时会根据任务的描述自动检索这套资料里跟任务最匹配的那一份然后照着手册走完整流程。这样做最大的好处是你不必在每次对话里把流程重复一遍。比如你让 AI 写一个前端组件不用每次都说“先做设计评审、再列接口、再写代码、最后补测试”只要装了一个frontend-dev之类的 skill它自己就会按这套流程推进。对团队来说经验被沉淀成了一个个文件而不是散落在聊天记录里换模型、换机器、来新人拿过来就能用。skills 能火起来很大程度是因为 Claude Code 和 Codex 相继官方支持了这个机制加上社区里一个叫 Superpowers 的项目把怎么组织 skill 文件的方法论做成了模板大量开发者跟着“抄作业”GitHub 上的 skills 仓库才越来越多。现在前端开发、数学建模、AI 漫剧这些垂类场景里几乎都能找到现成的技能包。1.2 skills 和 MCP 的区别一个给脑一个给手脚很多人第一次接触 skills 时会跟 MCPModel Context Protocol搞混我最初也混淆过直到实际配置才发现这两个是完全不同层的东西。MCP 是给 AI agent 提供“手脚”也就是真实的程序调用能力比如读取数据库、调用外部 API、操作浏览器skills 给的是“脑子”也就是处理任务的流程、标准和知识边界。说直白点一个 MCP server 可以让 AI 访问某个文件系统或某个设计稿工具而一个 skill 会让 AI 在拿到任务后先说“我理解了需求以下是拆解和方案”再进入实现最后用检查清单自检一遍。前者解决“能不能碰到数据”的问题后者解决“碰到数据之后怎么把事做好”的问题。配置上两者也有明显差异。MCP 一般要配置服务的地址、端口、认证信息更像“接入一个外部系统”skills 则只需要放在本地的技能目录里不需要起服务、不需要监听端口。你从 GitHub 下载一个 skill 仓库时里面通常只有 markdown 文件没有可执行文件也不产生任何外部副作用它只影响 AI 的推理路径。这也是 skills 相对插件更安全、更容易做代码审查的原因——你完全可以在 merge 之前把每个 SKILL.md 都读一遍看它到底在引导模型做什么。1.3 主流工具的 skill 目录支持现状到目前我实际用过的工具里对 skills 的支持大致是这样工具默认技能目录配置方式Claude Code~/.claude/skills或项目目录.claude/skills直接放文件夹CodexOpenAI~/.codex/skills或项目目录.codex/skills直接放文件夹OpenCode~/.config/opencode/skills直接放文件夹不同版本偶尔会调整路径建议安装前先用官方文档确认一下。实测下来最简单可靠的方式是在用户主目录下建好对应目录把下载的 skill 文件夹整体放进去重启工具会话就生效了。有一个细节值得注意项目级目录的优先级通常高于全局目录。也就是说同一个 skill项目里放了一个版本、全局挂着一个版本工具会优先使用项目里的。这个机制非常适合团队协作——项目仓库里放一份管用的全局那份只做兜底。在动手装之前先判断一件事这个 skill 值不值得装。看仓库里是否包含SKILL.md。这是整个 skills 体系的核心入口所有能称为 skill 的项目都必须有这个文件。如果仓库里只有一堆零散的 markdown但没有 SKILL.md那它大概率只是文档不是可加载的 skill。这是我踩过的第一个坑后面排查部分还会细说。2. 手动安装 GitHub 上的 skills我试过的三种途径2.1 为什么需要手动装虽说现在不少工具已经开始支持自动订阅技能市场但绝大多数 GitHub 上的 skills 还依赖手动安装。原因很现实skills 的文件结构比较自由自动安装器很难保证每个仓库的目录规范一致而且有些仓库设计成 monorepo一个仓库里塞了十几个 skills自动安装器根本不知道你要装哪一个。我一开始也幻想过“一条命令装完所有 skill”用几次之后就放弃了还是手动最稳。所谓手动安装其实就三件事把文件放对位置、让目录结构符合工具预期、重启会话。下面三种途径任选。2.2 途径一直接 clone 到技能目录最直接的方式以 Claude Code 为例mkdir -p ~/.claude/skills cd ~/.claude/skills git clone https://github.com/someuser/some-skill.git装完重启 Claude Code在会话里输入任务描述时技能会自动被检索到。这里有个关键点工具一般通过目录名来识别 skill 的 name所以 clone 完不要随便改目录名。我曾在装一个前端 skill 时把目录改成了fe结果模型怎么都不触发折腾了半小时才反应过来是名字的问题。如果只给某个项目装不进全局那就在项目目录下建.claude/skills放进去。这样换电脑、删目录后技能不会残留在全局环境里尤其适合团队协作场景。2.3 途径二软链接管理方便随时升级用得多了以后我更喜欢软链接方式。先在别处把仓库 clone 一份再链接到技能目录git clone https://github.com/someuser/some-skill.git ~/dev/skills/some-skill ln -s ~/dev/skills/some-skill ~/.claude/skills/some-skill好处是升级零成本以后只需要在~/dev/skills/some-skill里git pull本地的链接自动指向新内容不用反复复制粘贴。不想要了直接删软链接零残留。唯一需要注意的平台坑是 Windows建符号链接需要开发者模式或管理员权限Git Bash 里ln -s有时会悄悄退化成复制而不是建链接建议用 cmd 的mklink /D来做。2.4 途径三curl 拉取单文件有些 skill 其实就是一个 SKILL.md 加一两个辅助脚本没必要把整个仓库 clone 下来。这种情况我直接用 curl 拉取mkdir -p ~/.claude/skills/my-skill curl -L https://raw.githubusercontent.com/someuser/some-skill/main/SKILL.md -o ~/.claude/skills/my-skill/SKILL.md这种方式的维护性差一些但如果只是临时试用、或者仓库本身长期不更新完全够用。我一般只用它拉取一些社区里知名作者的单文件型 skill比如某种代码审查规范、commit message 规范之类的。方便是方便但记得自己留个原仓库地址方便后面追更新。3. 自己动手写一个 skill核心结构与流程设计3.1 SKILL.md 入口文件与 frontmatter自己写 skill 之前先理解它运行时的加载机制。当用户提出一个任务agent 会先根据任务描述去匹配技能清单匹配靠的就是 SKILL.md 顶部的 YAML frontmatter。这个部分包含name、description有些还允许加version、allowed-tools等字段。name必须简短清晰不要带空格尽量用小写连字符比如frontend-dev、math-modeling-assistant。description是决定“触发不触发”的关键要写成“当……时使用本技能”并覆盖多种同义表达。一个前端开发相关 skill 的 frontmatter 可以长这样--- name: frontend-dev description: 当需要开发、修复或重构网页组件、页面或前端工程时使用。适用于 HTML、CSS、JavaScript、React、Vue 等场景。 ---如果你写的是“帮助我写代码”那等于没写AI 可能每次都想加载它导致技能之间互相打架如果写得太窄比如“只在用户明确提到 React 组件拆分时使用”那平时很多前端任务又不会触发。这个度要靠观察实际对话记录来反复调整。3.2 渐进式披露别把文档写成一本字典新手写 skill 最容易犯的错是把所有内容塞进一个超长 SKILL.md。看起来信息量很大实际效果很差上下文窗口有限模型读大文档时会漏掉关键信息还会拖慢响应。社区标准做法是渐进式披露progressive disclosure意思是最外层文件只放概览和索引深层细节放在子文件里等真正需要时再让模型去读对应文件。推荐目录结构my-skill/ SKILL.md reference/ design-guidelines.md accessibility-checklist.md common-errors.md scripts/ lint.shSKILL.md 里写清楚这个 skill 做什么、启动时第一步是什么、关键节点要看哪个文件。例如# Frontend Dev Skill 负责在完成前端任务时执行以下流程 1. 阅读 reference/design-guidelines.md 了解设计规范 2. 按照工作流完成实现 3. 用 reference/accessibility-checklist.md 做自检 只有在一个步骤真正需要时才打开对应的 reference 文件。这样模型在大多数情况下只需要读几百行效率会高很多。调试时你会发现响应质量有明显提升这正是渐进式披露的核心价值。别贪多一个 skill 覆盖一个场景就好拆成多个 skill 往往比一个大而全的更好维护。3.3 工作流、质量标准与输出格式skill 真正值钱的部分不是基本信息而是工作流。我写 skill 时一般会明确列出步骤并给出判断标准。比如代码审查 skill 的工作流是先读 diff再根据 commit 类型确定审查重点然后按 5 个维度逐项检查最后输出固定格式的报告。格式一定要用模板模板里包含“问题严重级别、文件位置、修改建议”这些字段。这样 AI 的输出稳定方便你在 CI 或 review 流程里继续解析。不要忘了写“不要做什么”。“不要做什么”的效果常常比“要做什么”更显著。但这里有个技巧模型对否定指令的执行能力不如正向指令所以要把反例写成具体场景并跟正向写法配对出现。比如不要不要在没有接口定义的情况下直接写业务代码。要先确认接口字段和返回结构再开始写业务逻辑。若接口未定义先输出接口定义草案供确认。这样模型既能理解红线在哪里也知道越过红线之后正确的做法是什么。3.4 description 怎么写决定 AI 什么时候用它关于 description再补充几个我亲测有效的细节。第一动词用“开发、修复、重构、生成、检查”这类具体动作少用“帮助、支持”这样模糊的词。第二把目标用户或目标技术栈写进去比如“适用于 TypeScript 项目”会让匹配更精准。第三如果这个 skill 是给特定赛事或比赛场景用的比如数学建模的华为杯比赛description 里要包含“数学建模、华为杯、赛题分析、建模论文”等词这样对话里一出现相关关键词就能命中。一个值得注意的现象是很多数学建模相关 skills 的下载量很高正是因为描述里覆盖了“建模准备、数据预处理、模型选择、论文排版”这一整条链路。用户只需要说一句“我要参加华为杯帮我分析这道题”技能就会被命中比手动让 AI“按建模比赛流程来工作”靠谱得多。3.5 调试 skill 的笨办法边界测试与重启会话写完 skill 不是终点验证很关键。我常用的调试方法是打开 agent 的调试模式输入一个跟描述完全匹配的测试任务看系统是否加载这个 skill、加载后按了哪条路径走。如果没有触发通常就把 description 改得更宽一些再试。如果触发了但行为不理想就去检查 SKILL.md 里对应步骤那句指令写得是否足够具体。另外注意工具对 skill 的加载有缓存机制。改完 SKILL.md 后有时需要完全退出会话再进入否则模型用的还是旧版本。这是我付出过代价的改了一个错误示例连续测试两轮一直以为没改对最后才发现是没重启会话。还有一个容易被忽略的测试故意设置几个边界案例让 AI 执行一个明显不该由这个 skill 处理的任务看它是否错误加载。能正确拒绝不该做的事跟能正确接受该做的事一样重要。这个原则帮我避开了“装了一堆 skill 之后基础对话反而变傻”的尴尬场面。4. 不同场景下的 skills 推荐清单4.1 前端开发向前端是目前 skills 生态最成熟的领域之一。对应的技能包通常能帮你处理组件开发、设计规范落地、性能检查和可访问性审查这几类问题。在 GitHub 上用frontend skill SKILL.md或claude skills frontend搜索重点看有没有 accessibility 和 browser compatibility 相关的 reference 文件有的话质量一般比较高。我自己实际用过的一套前端 skill包含设计评审、实现、review 三个阶段。最打动我的是它的 review 阶段AI 会检查组件是否覆盖了 loading 态、空态、错误态还会提示按钮按下时是否有反馈动画。这些在以往的普通对话里很容易被 AI 忽略有了 skill 后稳定多了。4.2 数学建模向数学建模场景几乎是为 skills 量身定做的。因为赛题通常要求在短时间内完成问题重述、模型假设、模型构建、求解、检测、论文撰写整个链条。热词里那句“华为杯建模比赛好用的 codex skills”说明已经有选手在用 Codex 配合 skills 参加比赛了。一套数学建模 skill 通常包含赛题分析、数据清洗、模型选型、代码生成、论文排版。选型时有两点建议其一赛题分析 skill 要会引导用户明确目标和约束条件不然后续建模全跑偏其二论文排版 skill 要能输出符合比赛要求的章节目录和格式避免最后手工调整浪费时间。这类仓库大多在 GitHub 上搜“math modeling skill”或“数学建模 skills 技能库”即可。4.3 AI 漫剧内容创作向AI 漫剧是内容创作者的新方向相关技能包主要围绕分镜脚本、角色设定、画面提示词生成、对白和节奏控制来设计。一个合格的漫剧 skill应该能做到输入一个剧情梗概后输出带角色描述、场景描述、分镜编号、景别、动作、台词的分镜表。这个领域的技能质量差异比较大建议优先下载那些附带示例输出的 skill 仓库看它的输出是否结构化。如果自己写这类 skill记住一个核心让 AI 先确定角色一致性设定再生成分镜避免每帧画面里角色长得完全不一样。这也是目前 AI 漫剧制作最大的痛点之一。4.4 通用技能包与源网站通用型里比较出名的包括 Superpowers对应热词里的 “superpower skills”和 TypeSafe AI对应 “typesafe ai skills github”。Superpowers 更像一套方法论模板包含如何规划任务、如何写代码、如何做测试剪裁后就能用于自己的项目TypeSafe AI 则偏工程化适合在大型代码库上跑任务时保持类型安全的工作流。找源网站有一个习惯值得养成先搜awesome-claude-skills或awesome-codex-skills看仓库里的分类列表再顺着链接进去判断质量。判断标准还是那句看 SKILL.md 是否规范、是否有示例输出、是否持续更新。另外可以在 GitHub 上用 saved searches 保存几个关键词每周扫一眼新增的高星仓库基本不会错过好东西。5. 装了不生效完整的排查链路5.1 目录和命名检查装上不生效第一反应别去怀疑模型能力先核对目录。很多人下载完直接放在桌面或 Downloads忘记移到技能目录这是最常见的原因。其次检查目录嵌套关系。有些仓库是嵌套结构真正的 skill 在子目录里你把外层目录直接扔进技能目录当然不生效。正确做法是找到那层包含 SKILL.md 的目录把它作为 skill 根目录放进去。命名也值得反复强调大多数工具拿目录名当 skill 名如果目录名含空格、大小写异常或中文很可能匹配不到。我习惯统一为 kebab-case比如react-a11y-audit而不是react页面检查。5.2 描述质量检查如果目录没问题但 AI 就是不触发打开 SKILL.md 看 description。只看描述文本想象用户说了一句常规任务比如“给我写个搜索框组件”这句描述里有没有能跟你的 description 匹配的词没有的话说明描述写窄了。反过来如果它加载了又不干活说明描述写太宽任务被误匹配。这个问题在我遇到的排查案例里至少占一半以上。解决办法就是反复改 description改到“该触发时稳定触发、不该触发时基本沉默”为止。5.3 权限、冲突与会话状态目录和描述都检查完了还是没效果再往下看三点。第一执行权限。如果 skill 里有scripts子目录且 AI 需要运行脚本在 Linux/macOS 下记得chmod x否则脚本调用会静默失败。第二冲突。全局目录和项目目录存在同名 skill 时项目目录优先级更高如果你改了项目里的新版但全局还挂着一个同名旧版行为就会错乱。第三会话状态。有些工具对 skills 的读取只发生在会话创建阶段你中途放进去的文件当前会话不认需要新开会话或重启工具。5.4 排查顺序总结把问题简化成一张表现象最常见原因处理完全没触发skill 目录放错或目录名不对移动到技能目录规范命名偶尔触发不可控description 写得太宽加限定条件收窄触发场景触发但不干活description 太宽或 SKILL.md 指令模糊重写正文明确步骤和标准加载慢或报错子文件过多上下文过长用渐进式披露压缩首轮读取运行脚本失败权限问题或路径问题chmod x检查 shebang这套排查顺序我每次遇到“skill 不生效”都会从头走一遍十有八九是前两条。别跳步跳步只会浪费时间。6. 关于 skill 生态的一点个人体会从最早把 skills 当成“高级 prompt 文件夹”到后来真正把它当一套工程规范来设计我最大的感受是skills 的价值不在于装了多少个而在于你沉淀了什么。一个好的 skill 能把个人经验变成可复制的东西放在团队里大家都能用。下一步我想做的事情是把团队几个高频场景的 skill 统一维护到一个私有仓库用 CI 做格式校验和索引生成再用软链接统一分发到每台开发机上。这样新同事入职之后拉一次仓库、跑一个脚本就拥有了跟团队一致的编码流程和质量标准。说到底skills 就是“把老师傅脑子里的经验抄到纸上”这件事在任何行业都值得做。最后再分享一个小技巧写完 skill 后要故意设置几个边界案例去测试比如让 AI 执行一个明显不该由这个 skill 处理的任务看它是否错误加载。能正确拒绝不该做的事跟能正确接受该做的事一样重要。这一个原则帮我避开了很多“装了一堆 skill 之后基础对话反而变傻”的尴尬场面。