最近我一直在折腾 AI 编程里的 skills起因是在 GitHub 上看到 Matt Pocock 分享的 TypeScript 场景 skills。说实话一开始我以为是又一个提示词模板合集真正跑了一遍才发现skills 和普通 prompt 完全是两个物种。如果你也遇到“同一个问题每次让 AI 处理结果都不一样”的痛点这篇文章值得看完。我这份指南不是官方文档的复读而是基于我自己在 Claude Code、Cursor、Codex 这几个环境里手动安装、调试、重写 skills 的实操记录。核心会围绕 Matt Pocock 那套“把 TypeScript 最佳实践变成 Agent 技能”的思路展开也会把常见坑一起列出来。1. Skills 是什么以及为什么“Matt Pocock”这个名字会出现在这里1.1 从提示词到 skillsAI Agent 的“外挂能力”“Skills”这个词这两年从游戏系统跑到了 AI 开发圈而且一出来就把“提示词”这个概念按在地上摩擦。过去我们写提示词本质上是给 AI 一段一次性指令它回答完就没了。Skills 不一样它是一套可以长期复用、按需调用、能被 Agent 自动加载的“能力包”。我给你打个比方。普通提示词像是你临时教一个新同事“帮我检查下代码有没有问题。”他可能凭感觉看一遍给你一些正确的废话。Skills 则是你直接递给他一本《TypeScript 代码评审 SOP》里面写了先看 tsconfig、再找 any、然后查 null 判断、最后按文件行号给修改建议。他一旦识别到今天干的活属于“代码评审”就会自动把整本 SOP 翻出来执行。这套机制对前端开发尤其适用。因为前端项目的坑往往是重复的strict 模式没过、类型断言滥用、as any 满天飞、可选链判断缺失。与其每次都要重新组织语言让 AI 理解你的检查标准不如把这些标准固化成一个 skill让模型稳定执行。从提示词到 skills本质上就是从“告诉 AI 怎么做”变成“给 AI 配一套工具和方法论”。这中间的差距用过的人基本都回不去。1.2 Matt Pocock 与 TypeScript 场景里的 Skills 样本Matt Pocock 在 TypeScript 圈子里很出名是 Total TypeScript 课程的作者长期讲类型体操、泛型、strict 模式这些内容。他做的 skills 有一个非常鲜明的特点不写空话把具体检查项、示例、边界条件都写清楚。举个例子。别人写的 skill 可能说“你是一名资深 TypeScript 工程师请认真审查代码”。Matt 那类 skill 的写法是“先确认 tsconfig 是否开启 strict如果没开启建议使用npx tsc --strict --noEmit先得到错误列表再逐条处理any、unknown、null相关错误修复时保持函数签名可读性不为了过编译而乱加断言。”看到区别了吗前者是在给模型“打鸡血”后者是在给模型“写操作手册”。这也是为什么社区里很多人提到“前端开发 skills”“superpower skills”时会同时提到 Matt Pocock。不是因为他的名字有多玄而是他代表了那种真正能落地的 skills 写作风格规则具体、步骤明确、结果可验证。我在后面的章节里会直接照着这个风格给你拆一个可复用的模板。2. 上手前必须搞懂的 Skills 目录结构与运行逻辑2.1 SKILL.md 的核心name、description、body不管你用的是 Claude Code、Codex 还是 Cursorskills 最通用的载体就是一个目录里面至少要有一个SKILL.md文件。这个文件的格式类似 Jekyll 或 Hugo 的 frontmatter最核心的是三个字段name、description、body。--- name: ts-strict-review description: Use when reviewing TypeScript code for type safety issues, especially strict mode problems, any usage, or null-related errors. Suitable for front-end projects. --- # TypeScript Strict Review 1. 先读 tsconfig.json确认 strict 配置。 2. 执行类型检查收集错误列表。 3. 按严重程度逐项修复。 4. 最后用 tsc --noEmit 验证。这里有个关键点容易被忽略模型并不是先把你的 skill 全部读进脑子里而是靠 description 决定是否调用它。也就是说name 和 description 是“索引”body 才是真正干活的“操作手册”。索引没写好body 写得再漂亮也白搭。所以你在写 description 时不要写“应该怎么做”而要写“什么时候该用”。推荐用Use when...、Especially when...、Suitable for...这类句式开头让模型能在语义匹配阶段就命中正确技能。你可能会问body 里到底写多少内容合适我的经验是 300 到 800 字之间最好。太短约束不够模型还是会自由发挥太长加载进上下文会挤占 token 空间反而影响主干任务。你可以把额外的参考资料放到同目录下的其他文件里用相对路径引用而不是全堆在 SKILL.md 里。2.2 脚本、工作区与权限让 skill 真正“干活的”部分Skills 不只有文本指令它还可以带脚本、配置文件、示例代码。一个典型的技能目录长这样skills/ ts-strict-review/ SKILL.md scripts/ check-strict.sh references/ ts-best-practices.md examples/ before.ts after.ts为什么要用脚本因为有些操作是纯文本指令搞不定的。比如“运行 tsc 并解析输出”“批量检查某个目录下的文件”“统计项目里 any 出现的次数”这些需要确定性输出的工作交给脚本比让模型“看图说话”稳得多。模型可以调用脚本把脚本执行结果作为下一步决策的依据。这里有一个实际教训脚本里不要写死某个工具名。我在 CodeBuddy 和 Claude Code 共用同一套 skills 目录时踩过坑目录本身能共享但两边对工具调用的环境变量和权限处理不完全一样。脚本里如果直接写claude或依赖某个私有命令换到 CodeBuddy 就会报错。通用做法是脚本只做文件解析和标准输出把最终的判断交给模型。另外如果你把技能目录放在项目里它默认对整个项目生效适合团队协作时跟进代码规范。当我个人维护时更推荐放在用户级目录比如~/.claude/skills这样不管开哪个项目基础能力都在。注意一点同一份 skills 尽量少复制到多个位置一旦产生同名技能模型加载时会出现覆盖问题轻则行为不一致重则报错。3. 手动安装 GitHub 上的 Skills三种环境的通用做法3.1 Claude Code 的手动安装路径社区里流传的安装方法五花八门本质上都不复杂。GitHub 上的 skills 仓库大多数是若干个技能目录的集合你要做的不是把整个仓库扔进去而是把每个技能目录复制到正确的位置。我在 Claude Code 里的操作流程是这样mkdir -p ~/.claude/skills cd ~/.claude/skills git clone gitgithub.com:your-name/matt-pocock-skills.git tmp cp -r tmp/*/ ~/.claude/skills/ rm -rf tmp注意我复制的是tmp/*/也就是仓库下所有子目录。因为技能目录的标准要求是skills/技能名/SKILL.mdSKILL.md不能直接平铺在根目录。如果你把整个仓库文件夹复制进去Claude Code 会在子目录里找不到标准入口技能可能不会被加载。安装完之后重启当前会话或者在 Claude Code 里问一句“当前加载了哪些 skills”它会列出可用的技能名和描述。这一步一定要做别装了就当自己会了。3.2 Cursor 与 Codex/OpenCode 的配置方式Cursor 对 skills 的支持在不同版本里差异比较大但大方向是读取项目下的.cursor/skills目录或者用户目录下的 skills 路径。我自己用的做法是.cursor/skills/ts-strict-review/SKILL.md把技能目录放进这个位置后Cursor 会自动扫描。如果没生效优先检查一下版本号旧版可能只支持 Rules 文件需要手动把 SKILL.md 内容合并到.cursor/rules里。Codex 和 OpenCode 这类命令行 Agent 对 skills 的支持也在快速迭代中。Codex 的常见路径是~/.codex/skillsOpenCode 则更偏向通过配置文件显式声明。但不管路径怎么变核心逻辑都一样把技能目录放在 Agent 会扫描的 skills 路径下然后验证是否被加载。这里给你一个通用原则遇到不生效先确认自己的 Agent 版本是否支持 SKILL.md再确认目录层级是否多套了一层。多数“装不上”的问题都是路径层级错了。3.3 安装后的验证一个 3 分钟自测我每次装完新 skill 会做三件事你可以直接抄作业问 Agent“现在加载了哪些 skills列出 name 和 description。”用 description 里提到的触发词提一个匹配的小需求。比如装了 ts-strict-review就问“用这个技能检查一下 src 目录的严格模式问题”。观察输出风格是否改变。如果它开始按 SKILL.md 里的步骤执行说明加载成功如果还是泛泛而答说明匹配失败或者根本没加载。这个自测能帮你快速区分“技能没装对”和“技能装了但没触发”两种完全不同的故障。后面我还会专门讲排查方法。4. 自己动手写一个 Skills以“前端代码评审”为例4.1 先定场景再写描述很多人第一次写 skills 犯的错是先写 body再临时编 description。顺序反了。正确的顺序是你得先搞清楚一个精确场景再围绕这个场景设计技能入口。比如“前端代码评审”本身是个大场景不适合一个技能全包。我会把它拆成三个小技能一个是“TypeScript 严格模式检查”一个是“React 组件结构评审”一个是“a11y 可访问性检查”。每个技能只干一件事触发条件才清晰。写 description 时我习惯先用一句话说“什么时候用”再用一句话说“解决什么问题”。比如Use this skill when asked to review TypeScript code for strict mode readiness, type safety, or when fixing errors related tostrictNullChecks. It helps identify unsafeany, missing null checks, and overuse of type assertions.这句话里既包含了触发条件也包含了核心能力还带上了几个具体关键词。模型做语义匹配时命中率会高很多。4.2 以“前端代码评审”为例的完整 SKILL.md下面是我实际在用的一个简化版本你可以把它当成模板--- name: ts-strict-review description: Use when reviewing TypeScript code for strict mode readiness, type safety improvements, or fixing errors related to strictNullChecks. Suitable for front-end TypeScript projects. --- # TypeScript Strict Review ## 执行前 先找到项目的 tsconfig.json检查 strict 是否为 true。 如果 strict 未开启不要直接进入代码评审先说明开启严格模式后可能出现的错误数量变化。 ## 检查清单 1. 找出所有 any并给出替换为 unknown 或具体类型的建议。 2. 检查可选链 ?. 和空值合并 ?? 的使用是否一致。 3. 对每个显式类型断言 as判断是否真的必要如果只是为了“过编译”建议调整类型设计。 4. 检查函数返回值是否可能出现 null/undefined并确保调用处有处理。 ## 输出格式 按文件分组每个问题包含三部分 - 问题位置文件路径和大致行号 - 原因说明为什么这是一个类型安全隐患 - 修改建议给出可以直接替换的代码片段 ## 禁止 - 禁止为了通过编译而鼓励使用 ts-ignore。 - 禁止一次性抛出一堆没有优先级的问题。 - 不要省略对 tsconfig 配置的评估。这个 skill 写得很直白没有一句废话。关键是我在“检查清单”和“输出格式”里用了具体、可操作的动词比如“找出”“检查”“验证”而不是“深入分析”“全面评估”这类空话。4.3 写 skills 的几条原则写完几个技能后我总结了几条原则你可以直接拿去用少用形容词多用检查项。“优秀代码评审”这类描述没有任何约束力模型不知道什么叫优秀。把示例写进去。模型在 few-shot 上的表现远好于 zero-shot给一个 bad/good 示例比写十句规则都管用。一个技能只解决一个场景。描述相似的两个技能会互相打架导致模型随机选一个行为不稳定。把变更记录写成 changelog。Skills 是会被反复修改的今天加一条规则明天删一个步骤没有记录很容易忘记当初为什么这样设计。这些原则是我踩过几次坑后才总结出来的。一开始我也写过那种“全能技能”结果模型加载后又慢又乱最后只能拆成三个小技能立刻正常了。5. 常用 Skills 源与选型建议5.1 在哪找现成 skillsGitHub 上找 skills 最快的方式不是搜“AI skills”而是直接搜文件名in:path SKILL.md typescript用这个搜索方式你看到的都是真正包含技能定义文件的仓库而不是挂羊头卖狗肉的教程帖。另外几个方向值得关注Anthropic 官方发布的 skills 示例仓库里面有不少官方团队写的标准案例适合学习结构。Matt Pocock 这类开发者个人分享的 skills 仓库特点是场景贴近实际开发代码质量高。社区里的“awesome-skills”类聚合仓库比如很多人提到的 superpower skills 合集。superpower skills 这种聚合包的问题不是内容差而是内容太多。一次性把几十个技能全塞进 skills 目录模型的上下文会被挤爆每次对话都可能加载大量无关技能。我的做法是只挑里面真正用得上的几个子目录复制出来单独用而不是整个仓库直接挂载。5.2 不同场景选型建议我根据自己见过的项目和社区反馈把常用 skills 分了几类应用场景推荐技能方向注意事项前端日常开发TypeScript 严格模式评审、React 组件结构检查、CSS 冗余清理优先选有检查清单的技能自动化测试测试用例生成、测试报告摘要、失败用例归因不要选 all-in-one 测试技能数学建模类比赛问题分析、模型选择、论文审稿、结果可视化比赛前提前配置好别在现场找技能游戏/创意内容角色设定、分镜脚本、风格一致性检查适合“换个角色重写”这类重复工作这里特别想提一下数学建模场景。现在很多人在备赛时会找“数学建模 skills”市面上确实有把问题拆解、灵敏度分析、论文写作都封装成技能的方案。我的建议是不要找那种“数学建模全流程”的大体积技能而是分别找“论文摘要润色”“灵敏度分析模板”“图表规范生成”这种细颗粒度技能比赛时按阶段调用效果会好很多。内容创意方面我见过有人把“AI 漫剧”的分镜脚本规范做成了 skill每次生成故事板都会自动遵循固定的镜头语言和节奏要求。这种把个人审美固化成技能的做法思路和前端代码评审一模一样核心都是把重复劳动标准化。6. 常见问题与排查技巧实录6.1 Skill 被识别但没触发怎么办这是最常见的故障你装好了技能Agent 也承认加载了但实际干起活来完全没用技能。原因十有八九是 description 写得太泛。比如 description 写“TypeScript 代码评审”用户在聊天里说“帮我看下这个 ts 文件”模型可能会直接按通用能力回答而不会去匹配技能。你再想想我们前面写的 description里面多了一句“Use when... especially strict mode...”给模型提供了明确的触发锚点。解决方式很直接把触发场景相关的关键词统统写进 description包括错误类型、文件类型、用户可能的表达方式。改完之后重新开一个会话测试如果还不行检查一下是不是有其他技能也匹配同一场景两个技能打架会导致模型随机选一个。6.2 同名覆盖、权限报错、路径不生效这类问题通常不是玄学而是非常具体的工程问题。我整理了一张排查表现象常见原因处理方式技能明明存在但加载列表里找不到目录层级错误缺少技能名/SKILL.md用find ~/.claude/skills -name SKILL.md检查两个同名的技能行为混乱同名覆盖模型加载了其中一个重命名目录和 frontmatter 中的 name脚本执行报 permission denied脚本没有可执行权限执行chmod x scripts/xxxCursor 里不生效版本不支持扫描 skills 目录先更新 Cursor再确认.cursor/skills路径CodeBuddy 与 Claude Code 共用目录后报错脚本中写死了另一工具的专属命令改成通用文件解析只输出标准结果还有一个小技巧修改 skills 后一定要重启会话。很多 Agent 会在会话启动时扫描技能目录如果技能文件刚复制进去旧会话里可能还保留着旧的加载状态。这不是玄学是缓存。最后再提一个我踩过的最贵的坑不要在生产项目里直接挂载未经审核的第三方技能。技能本质上是在告诉模型如何使用你的代码和系统这里存在信任边界。自己写的也好从 GitHub 下下来的也好第一次使用前先读一遍 SKILL.md确认没有要求 Agent 执行危险命令的步骤。7. 写在最后我的实际使用心得真正跑了一周之后我对 skills 的看法发生了很大变化。它不是什么玄学魔法也不是提示词的简单升级版而是一种把经验工程化的手段。Matt Pocock 那套 skills 给我的最大启发不是某个具体模板而是他面对问题时的拆解方式少讲“要做好”多讲“先做什么再做什么遇到什么情况怎么办”。我现在的习惯是把一个技能当成一个小型项目来管理它有名字、有版本、有变更记录也有废弃标准。每加一个新技能都先问自己“这个场景我一个月内会碰到几次”如果不到三次那就先用提示词顶着不值得做成 skill。技能越多维护成本越高真正有用的技能一定是从大量重复劳动里长出来的。最后分享一个小窍门每次新装一个技能我会故意用一个很模糊的请求去测它比如“看看我这个项目哪里有毛病”。如果这种情况下它还能触发正确的技能说明描述写得足够稳。如果它没反应我就知道还要继续打磨触发条件。这套方法听起来很笨但对提升 skills 的实际可用性非常有效。