我是在一次脆弱的 React 重构翻车之后才开始认真研究 Matt Pocock Skills 项目的。当时模型给我输出的方案很漂亮但实现到一半就停下来等我确认修好一个类型错误又带出两个新的。问题不在模型参数而在于它缺少一本能从头跟到尾、自带检查和收尾动作的工作手册——这正是 Skills 要解决的。作为一个常年泡在 TypeScript 和前端生态里的人我把 Matt Pocock 的 superpowers 技能库、社区里常见的技能源网站以及 Claude Code 手动装 GitHub 技能的流程完整过了一遍。读完你会发现Skills 不是某个玄乎的新概念也不是一段花哨提示词它本质上是一套和代码仓库放在一起的过程文档。让 AI 从会聊天变成会干活靠的就是这份文档把资深工程师那些没写进代码里、但每天都在做的步骤显性化。这篇把原理、安装、编写、清理的完整链路一次讲清。1. 为什么是 Matt Pocock一条从 TypeScript 教学到技能包的路线1.1 前端开发者的老毛病模型会聊天不会干活我见过太多人吐槽AI 编程助手就是个嘴强王者。你问它一个 TypeScript 类型问题它能给你讲五分钟原理姿态非常专业但真让它把文件改完、把测试跑通、把类型错误清零它就露出原形——要么做到一半停住要么找到一个最省事的绕过方式要么改完 A 文件把 B 文件弄坏。这不是某一家模型的问题而是所有对话式模型的通病它们在单轮问答里很强在多步骤工程任务里缺乏过程纪律。为什么缺纪律因为工程任务真正难的从来不是知道正确答案而是在正确的时间按正确顺序做正确的事并且知道自己做完了没有。人类工程师是靠多年工作经验养成这套纪律的模型没有。你让它重构这个组件它知道重构的大方向但不知道应该先建基线再动手、先改类型声明再改实现、跑完类型检查还要跑测试。于是所有该有的步骤都被它省略或打乱了。这也解释了为什么单纯加提示词效果有限。提示词是临时的换个任务就失效而一个结构化的技能包能长期存在每次任务开始时自动被模型加载。我真正理解这一点是在看了 Matt Pocock 做的 superpowers 项目之后。1.2 Matt Pocock 的方法论把工程师习惯变成显式步骤Matt Pocock 在 TypeScript 社区的名声主要来自他做的 Total TypeScript 系列课程和大量类型体操教学。他常年做一件事把复杂的 TypeScript 知识拆成普通人能照着做的一步步路径。做完这些教学之后他发现一个很有意思的现象——教人和教 AI 很像。学生的问题往往不是不知道概念而是不知道从哪开始、下一步做什么、怎么判断自己做对了AI 模型的问题也一模一样。所以他做 superpowers 时核心思路不是写一段让模型更聪明的咒语而是把工程师日常工作中的隐性流程提取出来做成一份份显式的、可复现的操作手册。比如遇到 bug 应该先复现再修复写代码之前先列出验收标准每次改动后必须跑哪几条命令才能算完成——这些在经验丰富的开发者脑子里是默认的但对模型来说你不写清楚它就真的不做。这套方法论放到前端开发里尤其好用。TypeScript 的类型检查、React 的状态流、构建工具的报错链路本身就是一套非常适合步骤化的验证体系。类型错误有行号、测试有断言、构建有退出码每一步都有明确的完成定义。技能包要做的就是把这些完成定义一条条钉死让模型照着走。这也是为什么我会说学习 Skills与其说是学习一种新工具不如说是学习如何把人的经验翻译成机器能执行的流程。2. 拆开看一个 SkillSKILL.md、子目录与模型的意图匹配2.1 SKILL.md一份让模型照做的工作手册很多人第一次打开技能仓库时会懵里面没有可执行文件也没有复杂的配置最主要的是一堆 Markdown 文档。一个典型的 Skill 目录长这样skill-name/ SKILL.md references/ detailed-guide.md scripts/ validate.pySKILL.md是整个技能包的心脏。它通常由两部分组成开头一段 YAML 格式的元信息frontmatter和正文的工作流说明。元信息里最关键的是name和description——这两个字段决定模型在什么时候会想起这个技能。正文则是模型读取后照着执行的完整步骤通常包含输入输出定义、操作流程、决策分支和结尾的验证清单。理解SKILL.md的正确姿势是把它当作一份给新员工看的岗位作业指导书SOP而不是一篇技术博客。博客是给人读的可以铺垫背景、聊思路、讲原理但技能文件是给模型执行的必须直接、具体、可操作。我见过有人把几千字的设计哲学写进 SKILL.md模型读完后完全不知道第一步该干什么这不叫技能叫论文。好的 SKILL.md 我总结下来有三个特征第一步永远是最小的、可立即执行的动作每个决策点都有如果 X 就做 Y的明确分支结尾一定有一个怎么做才算完成的自检清单。有了这三样模型执行任务时的成功率和稳定性会明显上一个台阶。2.2 目录、引用文件与技能库网址从哪里找现成技能references/子目录是用来放长文档的。很多技能需要引用详细的框架文档、API 说明或示例代码但这些内容如果全部塞进 SKILL.md主文件会变得非常臃肿白白消耗上下文空间。正确的做法是SKILL.md 里只写需要时去读 references/xxx.md 的第几节让模型按需加载。这就像你在工位上放一个资料柜而不是把所有资料都贴在桌面上。scripts/目录则是给技能配的辅助工具可以放检测脚本、模板生成器或数据处理脚本。模型在执行流程的关键节点可以调用这些脚本做客观校验——比如跑一遍类型检查、格式化一个 JSON。这一步的价值是给模型一个外部校验器避免它自说自话。至于去哪找现成的技能我比较常用的几个源是Anthropic 官方的技能示例库适合入门时看官方推荐的写法、社区维护的 awesome 类技能列表覆盖各领域、TypeScript 方向有专门的 typesafe-ai 聚合仓库以及这次的主角 Matt Pocock 的 superpowers 仓库。我强烈建议下载之前先在网页上把目标技能的 SKILL.md 打开读完确认它是工作流文档而不是宣传文案再决定装不装。读一次能帮你省下后面无数次排错的时间。3. 手动装一条 GitHub skillsClaude Code 与 Codex 的实测路径3.1 为什么放 ~/.claude/skills用户级与项目级的差异先理解一个问题技能到底该装在哪一层拿 Claude Code 来说社区里最常见的做法是把用户级技能目录放在~/.claude/skills/下这里面的技能对当前用户的所有项目对话全局生效。如果你只想让某个特定项目使用技能就放到项目根目录的.claude/skills/下这样其他项目不受影响。这两者的取舍是全局技能适合那些你每天都会用到的通用能力比如类型检查流程、提交信息规范、代码审查清单项目级技能适合依赖具体技术栈的技能比如这个项目独有的构建流程这个仓库的目录约定。我个人的习惯是通用技能放全局业务相关的放项目里绝不混放。因为全局技能一旦装多了所有项目都会尝试加载模型的选择负担会变重反而干扰正常对话。Codex 那边也类似社区通行的做法是放到~/.codex/skills/。不同工具对技能目录的支持程度和具体字段要求会有差异但底层的目录组织逻辑是一致的一个技能一个文件夹里面必须有主文件附带的可选参考资料放在子目录里。3.2 手动安装与验证的五个步骤从 GitHub 手动安装一个技能完整流程其实很简单但每一步都有容易出错的地方打开目标技能仓库的 GitHub 页面在目录列表里找到你需要的技能文件夹。注意这里要挑而不是抄——很多人图省事把整个仓库 clone 下来再一股脑扔进 skills 目录后面模型读了一批无关文件输出反而更乱。把你需要的那个技能文件夹单独下载或复制到本地。如果仓库很大我一般直接在网页端进入该文件夹只下载里面的文件也可以用git clone后cp单个目录出来两种方式都行。把文件夹放到目标目录。Claude Code 就放在~/.claude/skills/下文件夹的名字最好和 SKILL.md 里的name字段保持一致。放的位置不对模型就找不到它。检查目录结构是否完整。至少确认SKILL.md在文件夹根目录而不是被多套了一层目录。references和scripts的相对路径也要注意skill 内部引用通常用的是相对自身目录的路径一旦你把文件挪出来单独用这些引用很容易断。重启 Claude Code 或新开一个对话让技能被重新扫描加载然后做一次验证。最简单的方式是直接问模型你现在能看到哪些可用技能或者让它在一个具体小任务中展示它读到的步骤。如果模型完全不知道有技能存在先回来检查路径和文件夹层级。我自己第一次装的时候就把整个仓库 clone 进了目录结果模型每次回答都要思考很久因为它看到了几十个 SKILL.md光判断该用哪个就消耗了大量上下文。后来我把不需要的技能清掉只保留真正要用的几个速度立刻恢复了。手动安装的本质是你替模型做了一次信息筛选——装什么、不装什么这个判断本身就是技能库能不能用好的关键。4. 技能包推荐清单先装哪些、按什么顺序4.1 最值得先装的四类技能包我看过不少以 Matt Pocock 的 superpowers 为代表的技能集合也和社区里几个常用仓库做过对比发现真正高频、高价值的方向高度集中在四类。第一类是编码规范类技能它们的任务是在你写代码之前先把规则立住。比如不要用 any 绕过类型检查每个公共函数必须有返回值类型声明新代码必须符合项目的现有风格。这相当于给模型装上一条底线避免它在自由度最高的地方放飞自我。第二类是调试排错类技能它们定义了遇到 bug 时的完整流程先看报错全文、再定位最小复现、然后沿着调用链分析根因最后才是动手改。这类技能的收益最立竿见影因为调试是前端日常最高频的痛点。第三类是测试驱动类技能它们会强制模型先写失败测试再写实现代码跑完测试确认变绿才收工。如果你一直烦恼模型写的代码不经过验证就交差这类技能能直接堵住这个漏洞。第四类是重构与代码审查类技能它们把怎么安全地改代码拆解为先建基线、小步改动、每次改动后跑验证、最后整体回归。这类技能对老项目的日常维护特别有用。4.2 我的实际安装顺序与使用效果我的建议是按通用 → 痛点 → 流程 → 重构的顺序装而不是看到好玩就装。先装通用编码规范因为它影响所有任务的输出质量再装调试排错用它解决你当下最频繁的烦恼然后装测试驱动把验证环节补上最后装重构审查让已有代码的演进变得安全。技能之间是有依赖关系的先装底座上面的模块才跑得稳。举一个具体的例子。我之前用一个调试类技能排查一个 React 组件的渲染卡顿技能的 SKILL.md 要求我先把性能问题转成可量化的指标组件渲染次数、每次渲染耗时再逐步注释掉可疑的子组件观察指标变化最后才定位到是某个列表组件没有 memo 化导致的。整个过程模型的每一步都有明确指令它不再东猜西猜而是按流程走完。修复后我再跑一遍指标确认有效这件事才算闭环。另外我也想提一句Skills 并不只是前端和 TypeScript 的专利。社区里已经能看到数学建模方向的技能包比如把建模竞赛的常见步骤问题分析、模型假设、求解、验证、论文写作固化成流程也有面向 AI 内容制作方向整理的技能集合把脚本生成、分镜设计、素材规范等步骤写成了可复用文档。这些例子说明 skills 的底层逻辑是通用的只要是高频、有明确步骤、需要稳定执行的任务都值得做成技能。5. 自己写一个 AI Skill从想法到验证的完整套路5.1 写 skill 的骨架frontmatter、正文与验证清单很多人问AI skills 怎么写我的回答是先别把它想得太高深它的本质就是一篇有结构的 Markdown。我写 skill 时遵循一个固定骨架可以拿这个最小案例直接改--- name: fix-wrong-type-error description: 当 TypeScript 报类型不匹配错误如 ts2322、ts2345时使用。 输入是报错信息输出是一个可运行的最小修复方案。 --- # 目标 修复当前 TypeScript 类型错误不引入新的类型问题。 # 工作流 1. 先读取完整报错信息定位报错文件与行号。 2. 检查报错位置的上下文确认是类型声明错误还是使用方式错误。 3. 优先修改类型声明或收窄类型范围禁止用 any 绕过。 4. 修改后运行类型检查命令确认没有新增错误。 # 决策分支 - 如果是库的类型声明本身出错检查依赖版本并考虑使用类型覆盖方案。 - 如果是业务代码逻辑错误修复实现而不是篡改类型声明。 # 验证清单 - [ ] 类型检查通过且无新增错误 - [ ] 没有引入 any - [ ] 相关测试仍然通过这个骨架里我最看重两处一是description必须写清楚什么时候用二是一定要有验证清单。验证清单是模型收工的标志没有它模型做完步骤之后不知道什么时候停经常多做一堆事或者提前停。写 skill 的原则是一个技能只做好一件事。如果你发现自己的 SKILL.md 里写了三种不同任务的流程立刻把它拆成三个文件。技能文件越小、主题越聚焦模型越容易正确触发和执行。我早期写的技能都是大而全结果模型每次触发都要重新判断我这次到底该走哪个分支效果远不如几个小技能各自为战。5.2 让 description 成为模型的眼技巧与反例description 是整个技能文件里最重要、但也最容易被忽视的字段。模型在接到任务时不是把硬盘上所有技能都读一遍而是先根据任务内容做意图匹配查找最相关的技能匹配的依据主要就是 description。所以这个字段写得好不好直接决定技能能不能被正确召唤。一个典型的反例是帮助开发者解决 TypeScript 问题。范围太宽了模型遇到任何一个 TypeScript 相关任务都可能触发它反而让技能失去聚焦。相比之下当 TypeScript 报 ts2322 时定位类型不匹配的根因并给出最小修复这种写法要精准得多它包含触发条件报错码、任务边界定位根因、交付物最小修复方案模型一看就知道这个技能是干什么的、什么时候该用。写 description 还有一种技巧是从用户视角描述场景而不是从功能视角描述能力。比如不要写本技能提供代码审查功能而是写当你需要给一次修改做代码审查时使用它会根据项目的类型安全、可读性、测试覆盖三个维度给意见。前者是菜单后者是场景模型的意图匹配需要的是场景。这条经验算是 AI skills 怎么写这个问题的核心答案。6. 技能库膨胀与清理装了一堆之后踩过的坑6.1 触发太频繁和完全触发不了的背后原因技能装多了之后你会遇到两类相反的问题一个是某个技能太容易被触发什么任务都来插一脚另一个是技能明明装好了模型却像没看见一样。这两类问题我都踩过。触发过于频繁的根子九成在 description 写得太宽。帮助开发者写代码这种描述模型会在写任何代码时都认为相关结果你的技能库变成一场噪音大会。修法很简单把描述改写得更具体尽量包含触发条件、报错类型或任务边界词比如仅当 X 出现时使用。完全不触发通常有三个嫌疑。一是路径不对文件夹没有放在约定的目录下比如技能放进了~/.claude/而不是~/.claude/skills/。二是结构不对SKILL.md 没有放在技能文件夹的根目录被外层套了一层多余目录。三是格式不对frontmatter 的写法出错导致解析失败。排查顺序建议是先确认目录位置再确认文件结构最后确认元信息格式。我见过不少人把第三种情况当成模型 bug 排查半天其实只是少了一个冒号。还有一个隐蔽问题文件太大。如果 SKILL.md 加上 references 里的文档动不动好几万字模型加载时会占用大量上下文。更麻烦的是很多工具对技能加载有长度限制超长的技能可能会被截断而截断的位置往往刚好在关键步骤上。我的经验是主文件控制在两千行以内长内容尽量拆进 references让模型按需读取。6.2 清理思路为每个技能建立留存标准技能库和衣柜一样不清理就会膨胀。我给自己定了一条留存标准一个技能要留在库里必须同时满足三条——最近两周内真的被触发并帮助完成任务它解决的是一个持续高频的问题而不是一次性需求以及这件事没法用更简单的配置或默认行为替代。三条里有任何一条不满足我就把它移出全局技能目录最多放到某个特定项目的目录下备着。社区里有一种清理方法我觉得很实用定期列出所有技能然后只保留你最近用得最多的前五个其余全部移走或者归档。这听起来激进但实际效果很好因为前五个技能通常已经覆盖你 80% 的重复性工作。移除并不是删除只是把它们移出全局扫描路径需要时再挪回来就行。清理这件事最容易被忽略的原因是技能不像是依赖包那样会报错、会有版本冲突你感觉不到它们的存在但它们一直在悄悄占用模型的注意力。每装一个技能都是在累积一笔上下文债务。所以现在每当我想要添加一个新技能时都会先问自己一个问题这个问题真的高频吗如果答案模棱两可就不装。这种克制可能是比任何安装技巧都重要的一条经验。