写Skills和提示词、插件之间差别的时候我习惯用一个类比提示词像你发给外包的一句话需求插件像你买回来的现成工具而Skills更像你给外包准备的完整SOP加专用表格——它既告诉AI该做什么还给它检查清单、参考样例甚至让它调用脚本去执行重复劳动。Matt Pocock这个项目能火起来恰好是因为他把这件事做得很扎实。他本人是Total TypeScript的作者常年教前端开发者怎么写类型安全的TypeScript在AI编程工具爆发之后他把“如何教AI写出高质量代码”这套方法论沉淀成了Skills仓库也就是热词里反复出现的typesafe-ai/skills。这个仓库对很多人的意义在于它不是给你一堆孤立提示词而是给你一套可以放进Claude Code、Codex等AI编程工具的技能包格式你拿过来就能用也能照着写自己的技能。这篇文章我不打算只做目录翻译式介绍而是把我实际把玩这些Skills、手动安装、自己动手写、再踩坑调试的完整过程摊开讲覆盖从概念到安装再到自研的完整链路。没有经验的初学者可以跟着一步步走有基础的人可以直接跳到后面的踩坑经验看。1. 先把概念对齐Skills到底是什么值得你花时间折腾吗很多人第一次看到Skills这个词第一反应是“这不就是预设提示词吗”。我第一次接触的时候也这么想直到打开一个真正的技能包目录发现事情没那么简单。1.1 Matt Pocock到底做了什么Matt Pocock在前端圈子里名气不小他做了一套TypeScript课程也长期在YouTube上教类型体操后来开始研究怎么让AI编写更可靠的代码。他维护的typesafe-ai/skills仓库核心思路是把过去散落在各处、口头叮嘱AI的规则和技巧整理成机器可读的技能文件让AI根据文件名、描述和指令自动在合适的场景调用合适的知识。举个例子。你让AI帮你审查TypeScript代码如果没有技能它可能只是泛泛地检查语法问题碰到类型推断不合理的地方也就放过去了。但如果你给它挂上一个“代码审查专家”技能这个技能内部可能包含一套审查清单、常见类型漏洞案例、推荐的错误处理写法。AI在工作时会读取这个技能按照里面写的流程来审查输出质量明显不同。这种效果之所以能实现关键在于技能文件不是简单的一句话而是有结构化信息的。每个技能都有一个SKILL.md入口文件里面通过描述区告诉AI这个技能适合处理什么任务在什么条件下触发正文里再给出具体的执行步骤和标准。AI工具的调度层会根据用户请求判断要不要加载对应技能然后把技能内容注入到模型上下文中。1.2 拆个包一个Skills目录里装的是什么为了搞清楚结构我自己从typesafe-ai仓库里下载了几个技能包逐个打开看过。一个标准技能包的目录通常长这样my-skill/ ├── SKILL.md # 技能入口AI读这个文件来决定用不用 ├── references/ # 参考资料可以是文档、示例代码片段 ├── scripts/ # 可选放可执行的脚本比如格式化、批量处理 └── assets/ # 可选放图片或模板文件最关键的是SKILL.md。它的基本结构是YAML格式的元信息加Markdown正文大概长这样--- name: code-reviewer description: 用于TypeScript项目代码审查关注类型安全、边界条件和性能隐患。当用户请求review、审查代码或检查PR时优先触发。 --- # 代码审查技能 你是一名资深TypeScript架构师审查代码时需要遵循以下步骤 1. 先分析类型定义是否与业务语义一致 2. 检查是否能通过更窄的类型约束减少运行时判断 3. 关注未被处理的边界条件 4. 最后给出具体的修改建议不要只抛结论注意这里description的写法。很多AI工具是靠这段描述调度技能的用户提到“审查代码”这个词工具就大概率把这个技能拉进来。所以技能不是靠文件名生效的而是靠这段描述和正文的质量生效的。那么Skills和普通提示词到底差在哪普通提示词是写一次用一次每次都要手工粘贴Skills则是把整套指令、参考、脚本打包好放在固定目录让工具自动化调度。这就有点像把随手记的备忘整理成可以随时调用的标准流程文件。搞懂这个底层逻辑之后你已经知道这东西值不值得折腾了。如果你经常用AI编程工具处理重复度较高的任务比如审查代码、写测试、做周报那它非常值得。如果你只是偶尔玩一下AI那先把安装流程跑通跑一个简单的技能感受一下调度机制也算开了眼界。2. 手动安装GitHub上的Skills这是大部分人卡住的第一关热词里有一条“claude code怎么手动装github上的skills”问的人特别多。原因很简单目前大部分AI编程工具还没有统一的技能市场你在GitHub上找到技能仓库后得自己想办法把它放到工具能读取的目录里。2.1 给Claude Code装Skills的完整流程先说大多数人用得最多的Claude Code。它读取技能的路径有全局和项目级两种全局技能放用户主目录项目技能放项目根目录。手动安装的核心操作就一句话把GitHub仓库里的技能文件夹复制到对应路径。具体步骤如下先确定你的用户主目录下有没有.claude文件夹。在终端里执行ls -a ~/.claude没有的话就创建它。在.claude文件夹下创建skills目录mkdir -p ~/.claude/skills把你从GitHub下载或克隆的技能包放进去。推荐用git clone方式方便以后拉更新cd ~/.claude/skills git clone https://github.com/你的目标仓库/某个技能.git确认最终路径是这样的结构~/.claude/skills/code-reviewer/SKILL.md关键就在这里AI工具扫描的时候认的是SKILL.md文件不是认文件夹本身。如果你把技能文件直接丢进skills目录但没有保持“技能名/SKILL.md”的结构它就不会被识别。如果网络状态不好下载仓库时可能会很慢甚至失败。这种情况我的建议是优先用镜像站或者直接在GitHub网页上下载该文件夹对应的ZIP压缩包解压后再放进去不一定非要clone整个仓库。关于网络这块我只多说一句保证你自己能正常访问GitHub其余细节和你的网络环境强相关不同地区差异很大。2.2 给Codex和Copilot装Skills的差异接着说说Codex。OpenAI Codex的Skills目录一般是在用户主目录下的.codex/skills操作逻辑和Claude Code差不多mkdir -p ~/.codex/skills cd ~/.codex/skills git clone 技能仓库地址但有一点不一样Codex对技能命名的约定更严格它要求每个技能文件夹里必须有SKILL.md并且name字段要和文件夹名保持一致否则调度阶段可能出现匹配不到的情况。GitHub Copilot那边也有自己的技能体系路径通常跟着系统配置目录走。在不同版本里路径有差异一个比较常见的做法是在项目根目录下建.github/skills让技能跟着仓库走团队协作时更统一。无论哪个工具手动安装的本质都是一样的把远程仓库里的技能内容放到本地工具约定读取的目录里。这中间最不起眼也最容易出错的就是路径问题多一次确认省下来的是后面的摸索时间。2.3 装完之后怎么确认它真的生效了装好技能不等于万事大吉我见过好几个人技能装好但一直没触发还以为是工具的问题实际是路径或者描述的问题。你得先确认AI工具确实加载了这个技能。确认方式取决于具体工具。Claude Code里你可以直接问它“你现在可以看到哪些skills”如果加载正常它会列出可用的技能列表。也可以更直接一点提出一个和技能描述高度相关的任务观察模型响应是否符合技能里的步骤。比如你装了代码审查技能那就让它审一段有明显类型问题的代码如果AI能主动引用技能里的审查清单说明调度成功。还有个细节很多人会忽略重新加装技能之后需要重启会话或者刷新工具配置才能真正生效。因为工具可能在启动时才扫描一次技能目录你刚把文件夹放进去它还没读到。不用因为这个怀疑自己没装对先重启一次再说。3. 真正值得下载的几类Skills和选型思路GitHub上Skills仓库不少但水平差异悬殊。有Matt Pocock这种质量很稳的类型安全向技能也有大量半成品。我按使用场景把它们分了几个大类方便你选。3.1 通用型能帮你干粗活的技能通用型技能覆盖面大适合日常编码时的各种常见任务。比如typesafe-ai仓库里那类代码审查、测试生成、文档维护技能都属于这类。以测试生成为例。普通情况下你让AI写测试它可能给你写几个开心路径就算了。但挂了专门技能后它会按技能内步骤先明确被测模块的边界再列出断言清单最后补齐边界用例和异常路径。我拿一个真实的工具函数试过没用技能时它写了6个用例挂了技能之后直接给出11个其中两个边界条件是我自己都没立刻想到的。通用型技能的选取标准我自己的经验是看三点维护频率、示例数量、是否依赖具体模型版本。GitHub仓库能看出最后一次提交时间半年没更新的慎用因为大模型更新很快旧的指令写法可能已经不好使。示例数量也很关键技能里要是带完整示例或者测试用例可信度会高很多。还有一点如果技能里明确写了针对某个模型版本优化你用的不是那个模型效果会打折扣。3.2 领域型建模、漫剧这类垂直玩法热词里冒出“数学建模skills”“AI漫剧常用skills”说明大家已经在往垂直领域钻了。这类领域型技能的思路是把某个专业场景下的流程、规范、产出模板固化下来让AI按套路出牌。打个比方数学建模比赛里经常需要处理“问题分析到模型建立到结果可视化”的整套流程。如果有一个建模技能里面内置了常用模型库说明、论文排版规范、绘图代码模板AI在辅助你的时候就不会东一榔头西一棒子而是按赛题做层层展开。领域型技能的下载判断比通用型更难因为你得自己先懂那个领域的常识。我的建议是只看两类仓库一是粉丝数达到一定量级的说明有人真的在用二是作者本身在领域内有专业身份比如数学建模奖项得主、漫剧制作人自己做的技能这种通常带着实战经验。3.3 别贪多一次装太多技能的隐性成本最初接触Skills时我疯狂收藏装了几十个最后发现副作用很明显。每个技能都要占用模型上下文装得越多工具在调度时要扫描的文件越多AI的理解负担越大。有些技能描述写得过于宽泛用户随口一句话就可能触发好几个不相关的技能导致AI响应变得非常啰嗦。更现实的问题是你自己记不住装了哪些某个技能行为和预期不一致时根本想不起来是哪个包影响的。我现在个人机器上的技能数量控制在10个以内且每个技能都明确标注了适用场景。团队项目里再额外挂项目专属技能。这个“清理技能”的思路热词里也有人提到tibo推荐的那类清理方法核心就是定期删除无用技能并压缩描述长度让调度更精准。我自己的做法是每两周看一次技能目录凡是近两周没用过的直接移到备份目录需要时再从备份拷回来二次验证它确实有用再说。4. 自己写Skills从会用到会造只会装别人的技能永远没法解决你的特定问题。真正让Skills发挥作用的时候是你把自身重复劳动整理成技能的那一刻。这一节我拿一个可复现的示例走一遍完整开发过程。4.1 SKILL.md的结构标题、描述、指令一个技能文件的核心骨架我总结下来就三段名字、描述、正文指令。名字要短且能自然出现在工作场景中。比如你要做一个“写周报”技能名字就叫weekly-report别起什么my-powerful-weekly-report-skill-v2这种又长又冗余的AI工具匹配文件名之后还会把它传给模型名字越简洁留给指令的上下文越多。描述是技能的生命线。写的时候要站在工具调度者的视角它会根据用户的输入来找描述匹配的技能。所以描述里一定要包含触发词和场景词。比如这样写description: 根据本周git提交记录生成结构化周报输出格式为“本周进展/风险与问题/下周计划”。当用户提到周报、weekly report、本周工作时触发。这样写的好处是明确告诉工具“什么该触发我”。太模糊的描述会导致误触发比如你只想写一次真实周报AI却把周报技能当成任务交接模板给你套进来。正文指令部分是给模型看的建议把步骤拆到可执行粒度并给出输出模板。模型只会按照它理解到的信息执行如果你的指令是“帮忙写一份周报别废话”它确实不会废话但也不会主动帮你结合git提交记录因为你在指令里没给它这个动作依据。4.2 命名和时机控制为什么技能不是万能的我自己试写过几个技能一个很深的体会是技能适合“确定性流程”不适合“开放式创造”。什么意思呢技能的本质是约束模型行为按步骤走、按格式输出、按边界收敛。适合技能化的任务是流程固定、输出格式清晰、质量指标明确的工作比如做周报、写单元测试、整理发布日志、做代码审查。但如果你让技能去指导AI“制定产品策略”或者“头脑风暴创意点子”它其实帮不上什么忙反而因为约束过多限制了模型发挥。所以设计技能前先问自己一个问题这个任务我是否愿意重复做十次如果答案是肯定的并且十次的做法基本一致那就值得做成技能。如果每次的做法差异很大那技能只会成为你的负担。首次开发技能时不要想着一步到位。可以先写一个只有描述和正文的极简版测两三次后再逐步补充脚本和参考资料。脚本不是必须的但它可以弥补模型执行环境能力的不足。比如周报技能里配一个generate_log.sh脚本AI在生成周报前先运行脚本拿到git提交记录输出质量会完全不一样。4.3 一个可以抄作业的示例写周报场景我把周报技能的完整示例写在这里你想试可以直接照着建。先建目录结构weekly-report/ ├── SKILL.md └── scripts/ └── collect_git_log.shSKILL.md内容--- name: weekly-report description: 根据git提交记录生成结构化周报输出包含本周进展、风险问题、下周计划。当用户提到周报、工作汇报、weekly report时使用。 --- # 周报生成 你是一名注重效率和准确性的技术团队助理负责把git提交记录整理成可读的周报。 操作步骤 1. 如果项目是git仓库先运行 bash scripts/collect_git_log.sh 获取本周提交列表。 2. 将提交记录按模块分组例如前端、后端、基建、文档。 3. 每组提炼为本周进展用3-5条短句描述。 4. 从提交信息中识别风险点例如未完成功能、废弃接口、待修复的TODO。 5. 对比本周进展从当前TODO和未解决问题中推断下周计划。 输出模板 ## 本周进展 - ... ## 风险与问题 - ... ## 下周计划 - ...collect_git_log.sh内容#!/bin/bash git log --since7 days ago --prettyformat:%h - %s (%an) --no-merges这个技能我最开始写的版本没有脚本AI生成周报全凭猜。加了脚本之后它真的会先去运行命令拿到真实提交记录再按模板整理可信度提升了一大截。这就是脚本对技能的价值让AI调用真实环境数据而不是凭空捏造。5. 实践中的几个坑和我的调试经验技能开发和安装过程中踩过的坑我挑四个最有代表性的说明都是文档里不会细说但实战经常碰到的问题。5.1 描述和触发时机不匹配这是最隐蔽也最影响体验的问题。我有一个技能描述写得特别宽泛里面包含“优化”两个字结果用户让AI“优化一下这段代码”时它就被错误触发输出了一堆模板化的建议而用户其实只想问语法问题。排查这类问题的方法是开启工具的verbose日志模式观察每一次请求到底加载了哪些技能。如果发现误触发就改描述把触发词收敛得更具体。反过来如果某个技能一直不触发基本是描述里的触发词和真实用户的表达方式差太远。比如你写的触发词是“构建发布日志”但用户习惯说“帮我整理一下changelog”那就匹配不上。正确做法是描述里把同义触发词都列全。5.2 技能文件冲突和优先级装了多个技能时可能会出现两个技能的描述覆盖了同一类任务。比如有一个叫“code-reviewer”的技能还有一个叫“typescript-architect”的技能两者都想处理代码审查。AI调度时加载了后写的或描述更长的那个导致你以为自己在用A技能实际生效的是B技能。检查方法是逐个看技能目录把描述任务重叠的技能合并或者区分场景。把code-reviewer聚焦到Pull Request审查把typescript-architect聚焦到架构方案设计两者就互不干扰了。优先级这个事不要把希望寄托在AI判断上最好在文件层面就把职责边界划清楚。5.3 团队共享和版本管理团队里用Skills最大的问题就是版本漂移。你今天觉得某个技能的提示写法不错改了一版推到公共仓库队友那边没同步然后大家分析半天为什么行为不一致。技能本质上是代码得用管理代码的方式管理它。至少要做到两点技能目录纳入git版本管理技能包内写CHANGELOG记录变化。更省事的方案是让技能文件夹跟随项目仓库走队友拉代码时一起拉下来这比各搞各的、手动同步强得多。如果团队对技能质量要求高可以约定一个评审流程先在一个分支上试运行一两周再合并主线避免直接在生产项目里翻车。5.4 技能内容里的过期信息这个问题比较隐性。给AI技能时会写很多参考资料和示例片段但大模型知识更新很快你技能里写的“推荐使用某个库的某个API”可能下个月就废弃了。AI不会主动质疑你给的资料它会照着你写的错误信息往下走最后产出一堆带过期API的代码。我现在的做法是技能里有涉及库版本、API名称、命令参数的内容都会标注“使用前请先确认版本”。更精细的做法是给技能配一个检测脚本定期检查依赖版本。虽然麻烦了点但如果你要做的是正经长期使用的技能这个成本值得花。6. 关于进一步扩展的一点想法技能这个东西装的人多会写的人少。我自己从只装别人的技能到给团队写内部技能最大收获不是效率提升多少而是逼着自己把过去靠感觉做事的流程显性化。你把写周报的流程、审查代码的要点、发版前的检查项一条条写出来时其实也在重新审视自己的理解是否清晰。如果你现在才开始接触Matt Pocock的Skills体系我的建议很简单先选一个最常用的重复场景装一个现成技能跑通整个链路再尝试改动它来适配自己的习惯最后才从零手写一个新的技能。不推荐一上来就写了一堆自己都不知道何时触发的技能那只会让上下文变得更混乱。我个人比较期待的方向是脚本和技能的进一步融合。现在的技能大多还是文本指令为主真正让AI跑脚本、处理数据、自动做验证的场景还没完全普及。等工具对技能内脚本的安全权限做得更成熟技能就不再是“指导手册”而是真正能动手干活的自动化单元了。那时候回头再看现在这些手工安装、手动调试的过程会觉得自己见证了技能从雏形走向工程化的那一段路。