1. mattpocock/skills到底是什么先说清楚它解决的问题第一次看到这个名字很多人会以为它跟招聘网站上的“技能树”或者某种在线课程有关。实际上mattpocock/skills 是 TypeScript 社区知名开发者 Matt Pocock 在 GitHub 上维护的一个开源项目核心是一套可以复用的AI 编程技能包Skill集合。它的出现背景很直接现在大家用 Codex、Claude Code 这类命令行 AI 编程助手时每次都要在对话里反复描述“我是做什么的、项目结构是什么、你应该按什么规范来改代码”既啰嗦又容易让 AI 理解跑偏。mattpocock/skills 的思路是把这些“上下文”和“操作规则”固化成一个个可复用的文件让 AI 助手在开工前自动加载相当于给你的 AI 编程工具装了一套“岗位说明书”。这个仓库里装的东西本质上是一组 SKILL.md 格式的指令文件每一个 skill 针对一个具体场景比如“TypeScript 类型安全审查”“React 组件重构”“Node.js 错误处理”等。使用的时候你只需要在项目里引入对应 skillAI 助手读取到这些文件后就会按照文件里定义好的规则、步骤、示例来执行任务。我把话说直白一点它就是把“你希望 AI 怎么干活”这件事从每次口头交代变成了版本化管理、可共享的标准化文件。从适用范围来说这篇文章适合三类人第一类是用 Codex CLI、Claude Code 或其他命令行 Agent 写代码但总觉得 AI“不够听话”的人第二类是团队里希望统一 AI 编程规范、减少重复沟通成本的技术负责人第三类是刚接触 AI 编程工具、想知道它们除了聊天还能怎么用的新手。如果你属于其中任何一类花十分钟把这套东西跑通后续省下来的时间远不止十分钟。有一点需要提前说明mattpocock/skills 不是某个具体的编译器或框架它更像是一套“说明书 示例集”的组合。它的价值不在代码量有多少而在于它提供了一种组织 AI 指令的方式——这种方式从设计上避免了“提示词写在一段对话里用完就丢”的浪费。1.1 为什么会出现 skills 这种模式要理解 skills 的定位得先看 AI 编程助手的使用痛点。以 Codex CLI 为例它在执行任务时会把当前仓库的代码读进去但“读代码”和“懂你的意图”是两码事。比如你让它“帮我修一下登录模块”它可能不知道你的登录模块用的是 session 还是 JWT不知道你的错误处理规范是抛出异常还是返回 Result 对象更不知道你希望它改完之后跑哪些测试。这些信息不是你不想告诉它而是每次都要从头交代一遍太累了。Skills 的方案就是把这些“背景知识”外置成一个文件。AI 助手启动时优先扫描 SKILL.md把文件里的内容当作最高优先级的系统指令。这就像给新员工发了一本入职手册而不是每次干活前都口述一遍公司规矩。Matt Pocock 在设计这套东西时特意把规则写得非常具体甚至包含代码示例和反例目的就是减少 AI 的“自由发挥”空间。1.2 它和普通提示词Prompt的区别在哪里很多人问我不就是把提示词写下来每次粘贴吗这跟 SKILL.md 有什么区别区别主要在三点。第一加载方式不同。普通的提示词是你在对话里粘贴属于“一次性消费”SKILL.md 是 AI 工具主动扫描加载的属于“持久化配置”。你可以把它放进项目的 .claude/skills 目录也可以放到全局的 ~/.codex/skills 目录工具会自动发现。第二优先级不同。Codex CLI 对 SKILL.md 的处理是把它当作指令集合并进系统消息优先级比你在对话里的普通要求更高。这就避免了“明明在提示词里写了但 AI 还是按照自己的习惯来”的尴尬。第三可维护性不同。提示词改一次就要重新粘贴一遍SKILL.md 改一次就全局生效。团队协作时一个维护良好的 skills 仓库就是团队的“AI 编程公约”任何人拉下来都能获得一致的 AI 行为。2. 安装前的准备你手头需要有什么在动手装 mattpocock/skills 之前先检查一下自己的环境。这套东西不是独立运行的软件它依赖一个能读取 SKILL.md 的 AI 编程助手。目前支持得最好的是 OpenAI 的 Codex CLIClaude Code 也能用只是目录约定上略有差异。我这里以 Codex CLI 为主讲因为它的配置机制最直观。2.1 基础环境清单按顺序检查以下四项缺哪个补哪个。实测下来环境问题占了新手失败原因的七成。Node.js 18 及以上Codex CLI 本身是基于 Node.js 的mattpocock/skills 里的示例也大量用到 npm 命令。用node -v检查版本如果没装去 Node.js 官网下载 LTS 版本即可。Git虽然可以用网页端直接下载文件但用 Git 克隆仓库是最方便更新方式。git --version确认已安装。Codex CLI这是运行 skills 的主程序。安装命令是npm install -g openai/codex装完跑codex --version验证。如果网络环境不太理想可以考虑配置 npm 镜像源但这是常规操作不展开说。一个真实的项目建议拿一个你自己正在写的、结构不太复杂的代码仓库来测试。不推荐直接在空目录里跑因为没有上下文skills 的效果体现不出来。2.2 获取 mattpocock/skills 仓库获取仓库本身很简单两条路任选。# 方式一克隆到本地方便更新 git clone https://github.com/mattpocock/skills.git # 方式二只查看内容不下载 # 直接浏览器打开 GitHub 仓库页面浏览我建议用方式一因为后续你可能想把里边的某些 skill 拷到自己的项目里用本地有一份拷贝会方便很多。克隆完成后进入目录看一眼结构cd skills ls -la你会看到一系列以 SKILL.md 结尾的文件或者按场景划分的子目录。这个仓库的结构不算复杂每一个 skill 就是一个 Markdown 文件文件名即技能名。2.3 把 skills 放到 Codex CLI 能扫描到的位置这一步是关键也是很多人卡住的地方。Codex CLI 默认会扫描两个位置全局目录和项目目录。全局目录~/.codex/skills/这个目录下的 skills 对你机器上的所有项目生效。项目目录.codex/skills/注意是项目根目录下的隐藏文件夹只对当前项目生效。把 mattpocock/skills 里的文件复制到这两个位置AI 助手才能自动发现。举个例子你想全局启用 TypeScript 相关的 skill就这么操作# 创建全局 skills 目录 mkdir -p ~/.codex/skills # 把仓库里的 TypeScript skill 复制过去文件名字以实际为准 cp skills/typescript-safety/SKILL.md ~/.codex/skills/复制完之后建议跑一下codex进入交互界面输入一句话测试 AI 是否读到了新指令。比如你随便问一个当前项目相关的问题观察它的回答风格有没有变化。如果没有任何变化大概率是路径不对或者文件格式不符合约定后面第五节我会讲怎么排查。3. 手把手跑通第一个 skill以 TypeScript 审查为例理论讲得再多不如亲手跑一遍。这一节我用一个非常典型的场景——让 AI 按 mattpocock 的 TypeScript 风格规范审查并修正代码——带你完整走一遍流程。这个示例选得好不好直接决定了你对 skills 的第一印象所以我特意挑了一个最有代表性的。3.1 场景设定一段“能跑但有隐患”的 TypeScript先准备一段测试代码。这段代码故意写得不好里面存在几个常见问题使用了any类型、函数参数没有明确的类型注解、错误处理靠console.log而不是类型安全的方式。代码如下// src/user.ts export function getUser(id: any) { if (!id) { console.log(no id provided); return null; } const user fetchUserFromDb(id); return { id: user.id, name: user.name, age: user.age, }; } function fetchUserFromDb(id: any) { // 模拟数据库查询 return { id, name: Alice, age: 30 }; }这段代码在 JavaScript 运行时没有任何问题但在 TypeScript 严格模式下是不过关的——any满天飞返回类型是推断出来而不是显式声明的而且没有处理fetchUserFromDb可能返回undefined的情况。这就非常适合用来测试 skills 的效果。3.2 在项目里启用相关 skill现在假设我已经把 mattpocock/skills 仓库里负责 TypeScript 规范的那个 skill 复制到了当前项目的技能目录。具体操作是# 在当前项目下创建 .codex/skills 目录 mkdir -p .codex/skills # 从克隆下来的仓库中复制对应 skill cp ~/skills/typescript-safety/SKILL.md .codex/skills/然后启动 Codex CLI进入项目目录开始对话。注意一点启动 Codex 之前建议先看一眼 SKILL.md 文件的内容了解它到底定义了什么规则。以我在实际项目中的使用经验mattpocock 的 TypeScript skill 通常会要求 AI 做到几件事禁止新增any类型、必须显式标注函数的返回类型、优先使用unknown而不是any、错误处理要显式返回Result或抛出明确的异常。这些规则会在对话中体现出来。3.3 观察 AI 的行为变化启动 Codex 后输入这样的指令请审查 src/user.ts找出类型安全问题并按照我们的代码规范修复它。没有启用 skill 之前AI 可能会给出一个“改得差不多”的版本把any换成unknown加几个类型注解但是否符合项目规范全看运气。启用 skill 之后AI 的处理逻辑会明显不同。我实测的效果是它先会读一遍项目里的 .codex/skills/SKILL.md然后在回应里主动说明自己将按照哪几条规则来修改。修改后的代码大致长这样// src/user.ts type User { id: string; name: string; age: number; }; export function getUser(id: string): User | null { if (!id) { return null; } const user fetchUserFromDb(id); if (!user) { return null; } return { id: user.id, name: user.name, age: user.age, }; } function fetchUserFromDb(id: string): User | undefined { const users: Recordstring, User { default: { id, name: Alice, age: 30 }, }; return users[id]; }有没有发现差别AI 不再只是机械地替换类型而是主动定义了User类型、明确了fetchUserFromDb可能返回undefined、把错误处理从console.log改成了真实可判断的返回值。这不是 AI 变聪明了而是 SKILL.md 里的规则把它的“行为偏好”拉到了正轨上。3.4 验证效果如何确认 skill 真的生效了跑完上面的示例后你可以做个简单验证确认 skill 不是“假装生效”。方法是在对话里直接问 AI请列出你在处理这个任务时使用到的规范条例并指出对应来源。如果 skill 生效AI 会明确引用 SKILL.md 里的原文。如果它支支吾吾答不上来说明要么文件位置不对要么工具版本还不支持自动加载。另一个验证方式是把 SKILL.md 临时改名再跑同样的指令对比回答风格差异。这套“对照实验”的思路不只适用于验证后期你自己编写 skill 时也能用上。4. 自定义 skill把你自己团队的经验固化下来mattpocock/skills 对我来说最大的价值不是直接用现成的几个技能而是提供了一个可以参照的模板。你能照着它的结构把你团队里散落在口头、文档、代码 review 留言里的“最佳实践”固化成一个 SKILL.md 文件。这一节详细讲怎么写一个高质量的 skill 文件。4.1 SKILL.md 的结构一个标准模板从 mattpocock/skills 仓库里随便翻开一个 SKILL.md你会发现它并非乱写而是有清晰结构。我归纳出来的骨架大概是这样# 技能名称 ## 适用场景 描述这个技能什么时候该被触发。 ## 核心规则 列出 AI 在处理任务时必须遵守的几条硬性规定每条都要具体。 ## 步骤 定义处理任务的完整步骤按先后顺序排列。 ## 示例 提供至少一个正面示例和一个反面示例告诉 AI “做对了长这样做错了长那样”。 ## 检查清单 AI 完成任务后需要自查的项目。这个结构看起来简单但写起来有讲究。核心规则不能太抽象比如“代码要优雅”这种就废了AI 无法量化操作。“不要使用 any 类型除非有显式的类型断言并注释说明原因”这才是合格的规则。示例部分更是关键AI 的模仿学习能力极强一组好例子胜过十句描述。4.2 用自己的项目内容写一个最小 skill 实例我拿一个常见的场景举例——团队规定所有接口错误必须统一返回{ code, message }结构禁止直接抛异常给前端。以前这个规则写在 README 里新人经常不看导致代码风格混乱。现在可以把它写成 skill# api-error-handling ## 适用场景 当 AI 需要新增或修改 API 错误处理逻辑时触发。 ## 核心规则 1. 所有 API 错误必须返回统一的错误结构{ code: string, message: string }。 2. 禁止在 Controller 层直接抛出未捕获的异常。 3. 错误的 code 必须语义明确使用大写和下划线如 USER_NOT_FOUND。 4. 日志记录必须包含请求 ID方便排查链路。 ## 步骤 1. 识别当前改动的 API 是否有错误处理逻辑。 2. 若无则按上述结构补充错误返回。 3. 若有检查是否符合规则不符合则重构。 4. 运行相关测试确保行为未改变。 ## 示例 正确 typescript return res.status(404).json({ code: USER_NOT_FOUND, message: The user with the given id does not exist., });错误throw new Error(user not found);检查清单[ ] 所有返回的错误是否都是{ code, message }结构[ ] 是否还有未捕获的异常[ ] 是否记录了请求 ID把这个文件保存为 .codex/skills/api-error-handling/SKILL.md注意按目录组织一个技能一个文件夹然后在 Codex 里让它“给用户接口加上错误处理”观察它的输出是否符合规范。我实测下来这种明确到“长什么样算对”的 skill比任何口头叮嘱都管用。 ### 4.3 如何维护 skill像维护代码一样维护规则 Skills 文件一旦多起来就会面临版本管理和规则冲突的问题。我的经验是把它纳入 Git 仓库管理并且把评审的流程走起来。mattpocock/skills 本身就是一个很好的参照——它把技能公开出来给全球用户用靠的就是标准化的文件格式和清晰的维护流程。 维护 skill 时有几个容易踩的坑要提醒你 - **规则之间不要互相矛盾**。比如一个 skill 说“所有函数必须显式标注返回类型”另一个 skill 说“回调函数可以省略返回类型”AI 遇到这种情况会不知道该听谁的行为可能随机。 - **不要写太多规则**。一个 skill 聚焦一个场景规则控制在 5 到 10 条。超过 20 条之后 AI 的遵循率会明显下降这跟人的注意力是一样的。 - **定期检查是不是过时了**。技术栈升级之后旧规则可能不再适用要及时更新。 ## 5. 排错指南skills 不生效的时候怎么排查 安装和使用 skills 的过程中最难熬的往往不是概念不理解而是“明明都按步骤做了AI 怎么还是无视我的 SKILL.md”。这一节把我踩过的坑、以及排查的思路完整梳理一遍。你照这个顺序查大概率能定位问题。 ### 5.1 定位问题先分清是“没加载”还是“加载了但不听” 遇到技能不生效先别急着改文件。第一步要判断是“AI 根本没读到这个文件”还是“读到了但没按规则执行”。区分方法很简单在对话里直接问 text 你当前的系统指令里有没有来自 SKILL.md 的内容如果有请概括一下。如果 AI 明确回答“没有检测到 SKILL.md 或额外指令”那就是文件没被加载问题出在路径或格式上。如果它能概括出规则但实际行为没有遵循那是“优先级”或“指令冲突”的问题处理思路完全不同。5.2 路径写错的几种情况这是最常见的问题。Codex CLI 对 skill 文件的存放位置有严格约定放错地方就是读不到。检查以下几点全局目录是不是~/.codex/skills/注意不是~/.codex/skill/少一个 s 都不行。项目目录是不是.codex/skills/注意是项目根目录不是src/.codex/skills/。文件命名必须是SKILL.md全大写实测 Codex 对大小写不敏感但为了跨工具兼容建议统一用大写。是不是把 SKILL.md 直接放到了.codex/目录下这也不行必须有skills这一层子目录。我用一句话总结正确姿势文件路径必然是.codex/skills/某个技能目录/SKILL.md目录层级不能省略。5.3 文件编码和格式问题有时候路径没问题但文件内容编码有坑。比如你在 Windows 上记事本编辑 SKILL.md保存成了带 BOM 的 UTF-8 格式AI 解析时可能把 BOM 当成乱码字符导致规则识别异常。建议用 VSCode 或任何支持编码选择的编辑器统一保存为无 BOM 的 UTF-8。另外Markdown 格式错误也可能导致解析中断。比如没有用#开头写技能名称、或者语法块里的反引号没配对。mattpocock/skills 仓库里的文件都经过验证如果你自己写的 skill 不生效可以先拿仓库里现成的文件替换测试排除格式问题。5.4 指令优先级冲突AI 读到了但“不听劝”有一种隐蔽情况你的 SKILL.md 写得很清楚但 Codex CLI 本身内置了安全规则或行为准则两者冲突时AI 可能更倾向于遵守内置规则而不是你的自定义文件。比如你在 skill 里说“遇到任何错误都直接抛出”但工具内置规则要求“所有异常必须被捕获并记录”AI 大概率会优先内置规则。解决办法不是硬刚而是调整表达方式。把规则从“不许”改成“优先”。举个例子与其写“禁止使用 any”不如写“定义类型时优先使用具体类型别名如果确实无法避免 any必须在后续注释中说明原因并给出替代方案”。这种表达既遵守了工具的安全设定又能表达你的核心诉求。5.5 版本兼容性工具更新后技能失效Codex CLI 迭代速度很快每隔几周就可能更新一次SKILL.md 的解析规则也可能跟着变。如果某天你发现之前一直好用的技能突然不灵了先查一下 Codex CLI 的更新日志。有一个笨但有效的方法把 mattpocock/skills 仓库拉到最新用他们维护的文件替换自己的自定义文件。如果替换后恢复了说明是格式变化导致的不兼容照新的格式调整即可。6. 进阶玩法把 skills 接入团队协作流如果你已经跑通了单人使用接下来值得思考的是怎么让 skills 成为团队协作的一部分。毕竟单打独斗的 AI 再听话也只是个人效率工具一旦团队所有成员共享同一套技能就等于给整个团队的 AI 编程行为装上了统一的质量标准。6.1 用 Git 仓库管理团队技能集最简单起步方式单独建一个仓库命名为team-ai-skills把 mattpocock/skills 作为上游定期同步然后团队自研的 skill 也放进这个仓库。每个成员的本地操作是# 拉取技能集最新版本 git clone gityour-git-server:your-team/team-ai-skills.git ~/team-skills # 在项目里启用其中一个技能Linux/macOS ln -s ~/team-skills/typescript-safety .codex/skills/typescript-safety # Windows 可以用复制命令替代软链接用软链接而不是复制好处是技能集更新后项目里不用重复替换。这个模式等于把“AI 行为规范”当作代码依赖来管理有版本、有变更记录、有 review 记录跟管理 npm 包没有本质区别。6.2 编写团队专属 skill 时这三条经验最值钱第一让 AI 先总结规则再执行任务。在 skill 里加一条“在开始任务前请先概述你要遵循的规则并在回复开头用引用块展示”这能迫使 AI 明确意识到自己在按什么标准干活遵循率能提升不少。第二规则要配“反例”。正面例子告诉 AI 该怎么做反面例子告诉它“别踩这个坑”。反面例子往往更有说服力。建议每个核心规则都配一个反例这是从 mattpocock 仓库学到的写法效果很好。第三每个 skill 只负责一件事。很多团队喜欢把一个技能文件写成“全能手册”什么都管结果 AI 面对几十条规则时选择了其中一部分执行其他“选择性遗忘”。拆分成小技能的好处是职责单一AI 加载时目标明确遵循率也更高。6.3 设置简单的效果评估机制如果你负责团队里 AI 编程效能的推进应该对 skill 的效果有量化评估。我给一个简单可落地的方案找 10 个典型的代码任务每个任务分别在有 skill 和没有 skill 的情况下让 AI 完成然后由人工评审打分维度包括“是否符合团队规范”“代码可维护性”“注释质量”。这个测试不需要很复杂两周做一次即可重点看趋势变化。我实测下来一个好的 skill 能把“AI 产出代码符合团队规范”的比例从三四成提升到七八成效果非常直观。7. 写在最后的实操体会mattpocock/skills 这个项目最打动我的地方是它把“教 AI 干活”这件事从玄学变成了工程。以前大家调提示词靠的是感觉和运气现在有了可复用、可版本管理、可共享的 SKILL.mdAI 的行为可以被稳定约束团队的经验可以被沉淀传承。这种从 prompt engineering 到 prompt management 的转变是 AI 编程工具走向成熟的标志之一。最后再分享两个我实际使用中总结的小技巧。一个是在 Codex 里测试新 skill 时别用太复杂的任务拿一小段代码做“冒烟测试”就够了——比如让 AI 改一个函数的类型定义观察它有没有遵循规则。另一个是如果你发现自己反复在对话里说同一句话比如“记得用 unknown 而不是 any”这就是一个信号该把这个要求写成 skill 了。把这些重复劳动沉淀下来才是这套东西真正值钱的地方。