看到skills这个词最近在多个技术社区里被反复提及从前端开发skills到codex skills再到claude agent skills: a first principles deep dive我就知道这波AI Agent的技能热潮已经挡不住了。我在实际使用Claude Code和Codex跑项目的过程中确实被Skills这种新范式震撼到了——它不是简单的提示词封装而是把模型从每次都要重新教一遍的状态解放成看一眼就能自动进入工作流的状态。这篇文章就把我这几周折腾Skills的完整心得、底层原理和踩坑记录都摊开讲希望能帮你少走点弯路真正把这项能力变成自己的超级技能。1. Skills不是普通提示词它到底改变了什么先说个我自己的例子。我长期维护一个前端项目代码规范、提交格式、测试覆盖率要求都写在一个几千字的文档里。以前用Claude Code干活每次开新会话都得把那套规范重新粘贴一遍模型倒是听话可一旦项目复杂度上去规范文档占用的上下文太长真正干活的注意力就被挤掉了。后来我把这套规范做成了项目里的一个Skill变化是质的模型在需要修改代码时会主动去加载这个技能包按里面的流程一步步执行而我只需要在关键决策点给个方向就行。很多人会问这不就是把提示词写进文件里吗还真不是。区别至少有三个方面。第一注入时机完全不同。提示词是一上来就把所有规则塞进上下文无论这轮对话用不用得上模型都得背着这堆信息Skills则是懒加载机制平时只是知道有这个技能存在只有当任务场景匹配时系统才会把完整的技能正文加载进上下文。这相当于把随身携带百科全书改成了需要查哪页再翻哪页。第二描述与内容的分离设计。每个Skill都有独立的描述信息这段描述是模型的检索索引决定它什么时候该启用这个技能。也就是说模型先读的是技能的简历觉得应聘者合适才把完整作品集拿出来看。这就让技能的触发变得非常精准——描述写得好的Skill几乎不会误触发也不会漏触发。第三可维护性和复用性。提示词是写一次用一次的消耗品Skills则是可以反复迭代的资产。我改造前端规范Skill的时候只需要改那个SKILL.md文件里对应的章节下一次调用自动就是新逻辑不需要在旧会话里翻了半天再补一句前一个规则作废。顺着这个思路往下走superpower skills、skills大全这些热词背后其实是在说一件事大家已经不再满足于这个模型聪明不聪明而是开始通过Skills把聪明用在刀刃上——让模型在正确的时间、用正确的方法、做正确的事情。这也是为什么我看完社区里那些号称打开新世界的反馈后会觉得眼下的Skills生态本质上是在给AI做职业培训让通用模型变成某一领域的熟练工。2. 底层机制拆解Claude与Codex是如何把技能喂给模型的要真正用好Skills光知道它很神奇是不够的还得理解各家实现机制上的差异。目前主流的两套体系一套是Claude这边的Agent Skills一套是OpenAI Codex引入的Skills机制两者思路有交集但实现细节差别很大。Claude的Agent Skills走的是文件系统探测 按需加载的路子。你会在项目或全局目录下看到一个SKILL.md文件它通常放在skills/或者./claude/skills/这样的约定目录里。当模型开始干活时它并不会一次性把所有SKILL.md都读进来而是在理解用户请求后根据每个Skill的description字段去判断这个任务是不是该用这个技能。一旦命中系统就把整个SKILL.md丢进上下文里面可以包含详细的步骤、示例代码、验收标准甚至还能引用同目录下的脚本和资源文件。我实际测试下来Claude对Skill体量的容忍度极高。一个SKILL.md写到3000行都没有问题因为它只有在被调用时才会占用上下文平时只是个档案条目。再来看Codex这边它的Skill机制更偏向检索型。Codex通过AGENTS.md文件体系管理项目知识而Skills部分则类似一个检索库系统根据任务关键词去匹配技能内容匹配到之后把相应段落注入到上下文中。这套设计的好处是它能处理数量巨大的技能集合——假如你往仓库里塞了上百个技能文档Claude的看简历模式会先挑花眼而Codex的检索模式可以快速定位。我整理了一张对比表方便你直观感受差异对比维度Claude Agent SkillsCodex Skills触发机制基于description语义匹配基于关键词与向量检索加载时机模型自主判断后按需加载系统预处理后增量注入文件主角SKILL.md含frontmatter.md文档 AGENTS.md索引扩展性适合几十个以内的技能集适合大规模技能库资源引用支持同目录脚本、模板、图片以文本检索为主注意一个容易迷惑的地方MCPModel Context Protocol和Skills的关系。很多人把二者对立起来其实它们是搭档。MCP解决的是模型如何调用外部工具和实时数据比如查数据库、调接口、读文件Skills解决的是模型如何组织行为和思考步骤比如按规范走完一段代码审查流程。我的经验是可以先做一个Skill来定义流程然后在SKILL.md里写明执行过程中调用某某MCP工具获取数据两者协同效率最高。另外Skill的加载时机和上下文预算也有讲究。Claude在模型判断这个任务要用技能A之后会暂停当前推理先把A的正文加载进来再继续推理。这看起来多了一步但实测下来对响应速度的影响很小原因是模型的上下文窗口足够大一次加载几百行技能文本也就几秒钟的事。真正需要担心的是另一个问题如果技能描述写得太过宽泛导致模型在无关任务上也频繁触发加载那既浪费token又会打断思路。这个坑后面专门讲。3. 手写第一个SKILL.md从零构建专属技能包的完整过程理论说完了直接上手。我习惯把技能分成两类一类是全局技能放在~/.claude/skills/下任何项目都能用另一类是项目级技能放在项目的.claude/skills/下只有这个项目能访问。这个区分很关键——全局技能放通用方法论代码审查、周报写作项目级技能放业务上下文这个项目的部署流程、接口签名规范。下面以一个最常用的场景——前端代码审查Skill为例带你走一遍完整创建过程。第一步创建目录结构。我用zsh做示例mkdir -p ~/.claude/skills/frontend-code-review touch ~/.claude/skills/frontend-code-review/SKILL.md这里有个命名习惯目录名建议用短横线连接的英文比如frontend-code-review不要用中文或空格否则部分工具解析路径会出问题。第二步写SKILL.md的YAML frontmatter。这部分是技能的门面一定要认真写。--- name: frontend-code-review description: 对前端代码进行系统性审查检查React组件性能、样式规范、可访问性、依赖安全等维度输出结构化评审报告。适用于代码提交后的Review场景。 ---description就是前面说的简历它决定了模型认不认得这个技能。我写description的经验是至少包含三要素——这个技能干什么、在什么场景用、它和别的技能有什么区别。如果你发现两个技能的description描述重叠模型就很容易混淆触发错误的那个。比如你还有个代码重构技能那就要在description里明确写本技能只做审查与报告输出不直接修改代码避免模型把评审当成重构来执行。第三步写正文。这是核心结构上我推荐包含四块内容适用边界、执行流程、评审维度、输出模板。# 前端代码审查技能 ## 适用边界 - 仅用于审查代码质量不自动修改代码 - 覆盖语言TypeScript / JavaScript / React / Vue - 不适用于后端代码、数据库脚本 ## 执行流程 1. 读取待审查文件的完整内容 2. 逐文件进行静态分析重点关注性能瓶颈和状态管理 3. 检查样式代码是否违反项目Prettier/ESLint配置 4. 检查可访问性图片是否缺失alt、交互元素是否有键盘支持 5. 汇总所有发现形成分级报告 ## 评审维度清单 - 性能React使用memo/useMemo的必要性、大数据列表是否虚拟化 - 状态是否直接修改props、副作用是否放在合适的生命周期 - 样式是否使用魔法数字、类名是否符合BEM规范 - 安全是否存在XSS风险dangerouslySetInnerHTML滥用 - 依赖是否有已知漏洞版本参考npm audit结果 ## 输出模板 对每个问题输出 - 严重级别Critical / Warning / Suggestion - 文件与行号 - 问题描述与实际代码片段 - 修复建议可执行的具体改动描述第四步测试加载。在Claude Code里输入/skills如果能列出frontend-code-review这个名字说明目录和frontmatter解析成功。然后随便写一行带Bug的React组件再输入帮我对这个组件做代码审查看看模型是否自动加载了技能并按照流程输出。如果你发现模型回答得像一个普通工程师发散评价而不是按模板给报告八成是description写得不到位或者技能正文的指令不够结构化。这个过程中有一个特别妙的细节Skills正文里还可以插入示例对话。我在技能末尾放了两组示例一组是好输出的样子一组是坏输出的样子。实测下来这比任何抽象描述都管用模型输出格式的稳定性直线提升。你可以理解为给模型看了样板间它照着装修自然不容易跑偏。4. 安装与选型实操官方市场、社区仓库和离线部署的取舍我猜你刷热搜时看到过codex好用的skills和claude 国内安装skills 官方市场这类词说明你已经不满足于手写想直接抄现成的作业。这个思路没错但Skills的安装渠道比较分散选不好容易装一堆垃圾技能。目前的获取渠道主要有三类。第一类是官方市场与官方仓库。Anthropic官方维护了Claude Skills的开源仓库和官方市场里面的技能质量相对有保障比如文档处理、数据分析这些基础技能经过了比较充分的测试。不过官方市场的技能偏向通用场景针对特定业务比如你公司的私有协议解析基本没有覆盖。安装方式很简单在Claude Code的交互界面输入/plugin install 技能名称或者直接在配置文件的skills路径下执行git clone。第二类是社区仓库。GitHub上有大量打上awesome-claude-skills标签的聚合仓库比如社区里传的superpower skills就是一套含几十个技能的高质量合集。下载这类技能包的时候我建议重点看三样东西仓库最近更新时间、README里的使用案例、以及SKILL.md的frontmatter是否规范。我见过不少把Prompt硬改成SKILL.md格式的伪技能本质上只是换了个壳描述写得含糊不清实际用起来效果很差。第三类是离线安装。skills安装包下载这个词条对应的就是这类需求。很多团队在生产环境里无法直连外部市场需要在内网离线部署。方法也不复杂在一台有网的机器上把这些Skills目录整个打包传到内网机器后放到~/.claude/skills/下。这里有个隐藏的小问题——Skills引用的一些外部依赖比如特定的Python脚本打包时容易漏掉所以我每次离线部署前会逐个检查技能目录里是否有requirements.txt、package.json等依赖清单有的话一起打包并植入安装说明。统计下来我日常用的Skill数量长期保持在15个左右。曾经有一阵我见了技能就想装很快就发现自己陷入了技能膨胀——模型每次权衡该用哪个技能都要犹豫半天有些技能description互相踩踏反而拖慢了响应速度。后来我立了一条规矩一个技能如果在两周内没有被实际触发过就该归档或者删掉。这跟打扫房间是一个道理东西少了每件才更管用。另外提醒一个细节安装完新技能后最好重启一下Claude Code会话让它重新扫描技能目录。有时候你明明放对了文件但列表里就是不出现十有八九是缓存没刷新。手动清缓存的方法是找到~/.claude/skills/_cache这类目录删掉再重新打开工具。5. 高频踩坑与兼容性排查我走过的弯路你都别再走Skills用起来顺手但它毕竟是个新东西坑也不少。我把自己踩过的、以及在社群里看别人踩过的高频问题整理了一下按严重程度排个序。先说一个最隐蔽的坑技能目录的命名与frontmatter里的name不一致。有一次我把目录命名为code-review-ts但frontmatter里的name写的是code-review结果模型加载技能后在对话里展示的技能名始终是目录名而引用内容时却按frontmatter来逻辑就乱了。后来我统一了规范目录名、frontmatter的name字段、description里提到的技能自称三者必须完全一致。再一个坑是描述过于宽泛导致的误触发。我写过一个docx格式转换的技能description写的是处理常见文档格式结果模型帮用户写周报时也把这个技能加载进来了白白占了不少上下文。后来我把description改成仅将Markdown/HTML转换为Docx不处理PDF与XLSX误触发率立刻降至零。这里的关键是负向边界信息一定要写进description不做什么有时候比做什么更能帮模型做判断。还有一个容易忽略的实际问题技能的版本管理。我一开始是把SKILL.md放在个人目录里随手改改了几版之后完全记不清哪个版本的流程在生效。后来我引入了版本号机制在frontmatter里加入version: 2.1.0这样的字段同时在正文末尾维护变更日志。这么做还有个额外的好处当Claude说我找不到这个信息的时候你能快速确认是不是正在用旧版本的技能。最后是兼容性问题。不同编码环境下中文乱码是最常见的事——我发现部分工具在读取SKILL.md时对UTF-8 with BOM和纯UTF-8的处理不一致如果文件带BOMfrontmatter解析可能失败。我的做法是所有SKILL.md一律用无BOM的UTF-8保存并且用命令行确认编码格式file SKILL.md如果输出中看到with BOM字样就用sed -i 1s/^\xEF\xBB\xBF// SKILL.md去掉它。还有一个热词叫自动挖洞skills其实只说明了一个现象Skills的应用范畴已经远远超出了编程任务连渗透测试社区都在做自己的技能包。但我不建议在这个方向上投入太多精力一方面法律风险非常高另一方面这类技能在模型侧本来就有安全过滤实际跑起来效果也打折扣。做AI能力的正向应用收益和持续性都强得多。6. 让模型带着方法论干活Skills在复杂任务中的实战价值Skills最大的价值其实是在那些步骤多、流程长、容错率低的任务里发光。我自己做数据迁移的时候感受特别深那项工作需要把旧系统的MySQL表结构迁移到新的PostgreSQL数据库涉及的步骤包括字段类型映射、约束定义、外键关系重建、还有基于业务规则的清洗逻辑。以前用Claude干这种活我必须在每次对话里把步骤重新梳理一遍中间一旦换了会话就得重新教。后来我直接把整个迁移流程写成了一个Skill--- name: db-migration-pgsql description: 将MySQL数据库迁移到PostgreSQL。处理表结构转换、字段类型映射、索引与约束重建、数据清洗规则。仅适用于关系型数据库不适用于MongoDB等非关系型库。 ---正文里记录了完整的工作流甚至包括不同数据类型在MySQL和PostgreSQL之间的等效映射表。调用这个Skill之后模型的行为方式立刻从你说一步我做一步变成了按标准工作流推进遇到偏离库标准的地方暂停确认。这种体验用一句通俗的话说原来你是在指挥一个实习生现在你给实习生发了一本SOP手册他只在真正拿不准的时候问你。这个模式特别适合团队内部推广。比如你们团队有一个发布上线检查单涵盖了构建、跑测试、打镜像、灰度发布、监控告警配置这些环节。把它做成Skill之后任何成员发起准备上线的请求模型都会严格按照这个Skill的流程走该执行的命令执行该确认的配置确认遗漏一个步骤模型会主动提醒。我后来还把这种方式延伸到了周报写作和数据分析上。周报Skill里我定义了固定的几个维度本周产出、数据变化、风险事项、下周计划。模型每周自动按这个结构组织我再补充具体细节就好。数据分析Skill里我规定了数据清洗的每一步必须记录操作日志方便后续审计。这些听起来都是小事但正是这些小事把我从重复指挥模型的过程中解放出来了。说到这我要特别提醒一下不要指望一个Skill包治百病。我见过有人试图做一个万能超级技能里面塞了开发、运维、写作、设计结果模型每次面对任务都要做一轮极其纠结的筛选响应速度肉眼可见地变慢。Skill的正确打开方式是把它做成单一职责、内聚性强的小工具。十个职责清晰的小技能远比一个包罗万象的巨无霸技能好用。从skills推荐到skills大全再到今天学会了skills打开新世界搜热词的这批人里不少人正处在从被AI辅助到训练AI为自己所用的转变节点上。Skills就是这座桥。我在实践中学到的最重要的一课是真正厉害的Agent不是模型本身厉害而是你通过Skills让它做事的方式足够系统。这跟带团队一模一样——给成员足够清晰的流程和标准他就能稳定交付流程含糊天才也得靠运气。我最近在做的项目已经习惯在开工之前先花十几分钟想一想这个任务能不能沉淀成一个Skill如果答案是肯定的那就先做技能再做任务。短期看好像多花了时间长期算下来每一次同类任务都被加速而且质量越来越稳定。这一开始只是我的个人习惯后来变成了团队的工作方式效果确实立竿见影。如果你也打算入坑Skills建议你从自己的工作里挑一个高频、重复、步骤多的场景花一个下午把技能写出来跑通一次。相信你很快就会理解为什么大家都说打开新世界了。