1. 从“skills”这个关键词说起为什么它突然成了AI编程工具链里的高频词如果你最近在AI编程工具的社区里泡过大概率会反复看到一个词skills。它有时候出现在Claude Code的配置目录里有时候出现在Codex的插件市场中有时候又变成“superpower skills”“agent skills测试”这样的组合词。很多人第一次看到这个词的反应是懵的——它到底是一个功能、一个文件格式、还是一套方法论我先给一个最直白的定义skills本质上是一种可复用的能力封装单元。你可以把它理解成给AI编程助手准备的“技能卡片”或者“操作手册”。一张skill卡片里通常包含一段结构化的说明告诉AI在遇到某类任务时应该怎么做、按什么步骤做、注意哪些坑。它不依赖某一次对话的上下文而是可以被反复调用、跨项目复用。这个概念的流行和Claude Code、Codex这类终端型AI编程工具的普及直接相关。早期的AI编程助手更多是“你问我答”的模式每次都要重新解释需求。但当开发者开始用这些工具处理真实项目时问题就暴露了同一个项目里代码规范、目录结构、构建命令、测试流程都是固定的每次对话都重复交代一遍效率极低。skills就是为了解决这个重复劳动而出现的——把项目级的约定和操作流程固化下来让AI每次进入项目时自动加载。适合读这篇内容的人有三类第一类是刚开始接触Claude Code或Codex还没搞清楚skills是什么、怎么用的新手第二类是已经在用这些工具但skills都是零散配置、没有形成体系的开发者第三类是对agent能力扩展感兴趣想了解skills设计思路的技术负责人。不管你属于哪一类接下来的内容都会从概念到实操、从单点配置到体系化管理把skills这件事讲透。需要提前说明的是skills的具体实现方式在不同工具里差异很大。Claude Code的skills偏向文件系统层面的约定Codex的skills更接近插件市场的分发模式而社区里说的“superpower skills”往往指的是第三方整理的能力包。我会尽量把通用逻辑和工具差异分开讲避免你把某个工具的特定做法当成通用标准。2. skills的核心设计逻辑为什么是“技能卡片”而不是“提示词模板”2.1 从提示词工程到技能封装的演进路径要理解skills为什么长成现在这个样子得先看它解决了提示词工程的哪些痛点。早期大家用AI编程工具习惯把要求写在一段长长的提示词里比如“你是一个资深前端工程师请按照以下规范写代码使用TypeScript严格模式、组件用函数式写法、样式用CSS Modules……”。这种做法在单次对话里有效但有几个致命问题。第一个问题是上下文漂移。对话轮次一多AI对早期提示词的注意力会下降写着写着就忘了规范。第二个问题是不可复用。换个项目、换个对话窗口同样的规范要重新粘贴一遍。第三个问题是无法版本化。提示词散落在聊天记录里改了什么、谁改的、为什么改完全追溯不了。skills的设计思路是把这些规范从“对话内容”变成“项目资产”。它通常以文件的形式存在于项目目录中比如.claude/skills/或者类似的路径下每个skill是一个独立的文件或文件夹。这样做的好处很直接可以用Git管理、可以Code Review、可以按项目定制、可以在团队内共享。AI工具在启动时会扫描这些文件把skill内容加载进上下文相当于每次对话都自动带上了项目规范。注意不同工具对skills的加载时机不一样。有的在会话开始时一次性加载有的在检测到相关任务时才动态加载。这个差异会直接影响你写skill时的粒度设计后面会详细说。2.2 skills、plugins、agents三者的关系拆解社区热词里经常把skills、plugin、agents混在一起说很多人搞不清它们的边界。我用一个类比来解释把AI编程工具想象成一台电脑agents是操作系统负责调度和决策plugins是驱动程序负责连接外部能力skills是应用程序负责完成具体任务。agents是最高层的概念指的是具备自主决策能力的AI实体。它决定什么时候调用什么工具、按什么顺序执行任务。plugins是扩展机制让agent能访问外部资源比如数据库、API、文件系统。skills则是知识层面的封装告诉agent“这类任务应该怎么做”。三者是协作关系不是替代关系。一个典型的场景是agent接收到“帮我重构这个模块”的指令它调用plugin读取代码文件然后加载对应的refactoring skill来获取重构步骤和规范最后按skill的指引执行操作。理解这个分层你在配置时就不会把该写在skill里的内容塞到plugin配置里也不会把该由agent决策的事情硬编码进skill。2.3 什么样的任务适合封装成skill不是所有东西都值得做成skill。我踩过的坑是早期把太多琐碎的东西都写成skill结果维护成本比收益还高。经过一段时间实践我总结出适合封装成skill的任务有几个特征。高频重复是第一个特征。如果一个操作你每天都要做、每次都要跟AI解释一遍那就值得封装。比如“新增一个API接口”这种任务涉及路由注册、参数校验、错误处理、单元测试等多个步骤每次都说一遍很累写成skill后一句话就能触发。步骤固定是第二个特征。skill的本质是流程固化如果任务本身每次都不一样封装的意义就不大。比如“帮我优化这段代码”这种开放式任务更适合让agent自由发挥而不是用skill限制它的思路。有明确验收标准是第三个特征。skill里写的步骤应该是可验证的做完之后能判断对错。比如“提交前必须跑lint和test”这种要求执行完就能检查是否通过。如果验收标准模糊skill就变成了摆设。反过来那些一次性的、探索性的、需要大量人工判断的任务就不适合做成skill。我见过有人把“帮我设计数据库表结构”做成skill结果每次生成的表结构都不符合实际业务需求因为这种任务需要结合具体业务上下文不是固定流程能覆盖的。3. Claude Code中skills的落地实操从目录结构到触发机制3.1 安装Claude Code与初始化项目配置在讲skills之前先把基础环境搭好。Claude Code的安装方式根据操作系统不同有差异Windows用户和Ubuntu用户的步骤不完全一样。我分别在两个环境里装过把关键点说一下。Windows环境下官方推荐的方式是通过包管理器安装。如果你用的是winget可以直接搜索对应的包名安装。安装完成后需要在终端里验证版本确认安装成功。这里有个常见坑Windows的终端编码默认可能是GBK导致Claude Code输出中文时乱码。解决办法是在终端设置里把编码改成UTF-8或者在启动脚本里设置环境变量。Ubuntu环境下安装相对直接但要注意权限问题。如果你用sudo安装后续配置文件可能会写到root目录下导致普通用户运行时读不到配置。我的建议是用用户级安装把可执行文件放到用户目录的bin下然后把这个目录加入PATH。安装完成后进入你的项目目录执行初始化命令。这一步会在项目根目录下生成配置文件夹skills就放在这里面。初始化时它会问你一些偏好设置比如是否启用自动格式化、是否在提交前运行测试等。这些设置后续都可以改不用太纠结。提示初始化生成的配置文件建议加入版本控制但其中可能包含你的个人偏好设置。团队协作时可以把个人偏好和项目规范分开管理项目规范进Git个人偏好放本地忽略文件。3.2 skills目录结构与文件格式详解Claude Code的skills通常放在项目根目录下的特定文件夹里每个skill是一个独立的Markdown文件或者一个包含多个文件的文件夹。文件格式上一般包含元信息头和正文两部分。元信息头用YAML格式写在文件开头用三个横线包裹。里面通常包含skill的名称、描述、触发条件等字段。名称要简短好记描述要写清楚这个skill是干什么的触发条件决定了AI在什么情况下会加载这个skill。正文部分就是具体的操作指引。我建议按“适用场景-前置条件-操作步骤-验收标准-常见问题”的结构来写。适用场景说明什么时候用这个skill前置条件列出执行前需要满足的条件操作步骤是核心内容验收标准告诉AI怎么判断做完了常见问题提前把坑填上。这里有个细节很多人忽略skill的正文要写给AI看不是写给人看。所以语言要精确、无歧义避免“适当调整”“根据情况处理”这种模糊表述。能用命令行的就用命令行能用代码示例的就用代码示例。AI对结构化、确定性的内容理解得更好。3.3 触发机制与加载优先级skills的触发机制是很多人困惑的地方。为什么我写了skill但AI好像没用到这通常和触发条件的设计有关。Claude Code加载skills的时机一般有两种一种是在会话开始时扫描所有skill把元信息加载进上下文当检测到用户请求匹配某个skill的触发条件时再把完整内容加载进来另一种是每次请求都重新匹配。具体行为取决于版本和配置。触发条件的写法很关键。我见过有人把触发条件写成“当用户需要帮助时”这等于没写因为几乎所有请求都符合。好的触发条件应该是具体的、有区分度的比如“当用户要求新增React组件时”或者“当用户提到数据库迁移时”。加载优先级方面项目级skill通常优先于用户级skill。也就是说如果项目里定义了一个skill用户目录下也有同名skill项目级的会覆盖用户级的。这个机制的设计意图是让项目规范优先于个人习惯符合团队协作的需求。还有一个容易踩的坑skill之间的依赖关系。如果一个skill的步骤里引用了另一个skill要确保被引用的skill也能被正确加载。我建议尽量避免skill之间的交叉引用保持每个skill的独立性降低维护复杂度。4. Codex中skills的配置与插件生态和Claude Code有什么不同4.1 Codex安装与登录流程中的关键节点Codex的安装流程和Claude Code有相似之处但细节差异不小。安装包获取渠道上Codex更依赖官方分发的安装包社区里流传的“codex安装包”“codex下载”很多是第三方打包的版本参差不齐。我的建议是始终从官方渠道获取避免版本兼容问题。安装完成后需要登录。Codex的登录机制和账号体系绑定如果你所在的组织禁用了某些访问权限可能会遇到“your organization has disabled claude subscription access”这类提示。这种情况不是安装问题而是账号权限问题需要联系组织管理员解决。登录过程中还有一个常见报错是“codex is ignoring 1 unrecognized configuration setting”。这个提示的意思是配置文件里有它不认识的字段通常是版本升级后旧配置没清理干净。解决办法是检查配置文件把不认识的字段删掉或者对照官方文档更新配置格式。4.2 Codex skills的插件化分发模式Codex的skills和Claude Code最大的不同在于分发模式。Claude Code的skills更偏向项目内自定义Codex的skills则有一套插件市场机制可以通过命令从市场安装skill包。这种模式的好处是生态更开放你可以直接安装别人写好的skill不用从零开始。但坏处也很明显质量参差不齐有些skill包写得很粗糙装了反而添乱。我的做法是只装那些有明确文档、有版本更新记录、有实际使用反馈的skill包。安装命令的格式一般是dsh plugin --profile web add加上包名。这里的--profile参数指定了安装到哪个环境web表示Web开发相关的skill集合。安装完成后需要重启Codex或者重新加载配置才能生效。注意从市场安装的skill包会放在全局目录下对所有项目生效。如果你只想在特定项目里用某个skill需要手动把它复制到项目目录或者用项目级配置覆盖全局配置。4.3 本地模型接入与skills的兼容性处理Codex支持接入本地模型社区里讨论比较多的方案是接入LMStudio运行的本地模型。这个场景下skills的行为会有变化因为本地模型的能力和云端模型有差距对skill指令的理解可能不够准确。我实测下来的经验是接入本地模型时skill的写法要更“啰嗦”一些。云端模型能理解的简略指令本地模型可能需要展开写。比如“按项目规范格式化代码”这种指令本地模型可能不知道“项目规范”具体指什么需要把规范内容直接写进skill里。另外本地模型的上下文窗口通常比云端模型小skill内容太长可能被截断。解决办法是把大skill拆成多个小skill按需加载而不是一次性塞进去。这个思路其实对云端模型也适用只是本地模型对长度更敏感。5. skills开发与测试的完整工作流从草稿到稳定复用5.1 需求识别什么场景值得写一个skill写skill的第一步不是动手写而是判断这个场景值不值得写。我的判断标准是“三次法则”同一个操作如果重复了三次以上而且每次都要跟AI解释那就值得封装成skill。具体识别方法上我会在平时使用AI工具时留意那些“又要说一遍”的时刻。比如每次新建组件都要说“用函数式写法、样式用CSS Modules、导出用named export”说到第三次的时候我就知道该写skill了。还有一种情况是团队协作中的规范传递。新人加入项目时需要了解项目的各种约定这些约定如果写成skill新人只要用AI工具就能自动获得指引减少沟通成本。这种场景下skill的价值不只是提效还有知识沉淀的作用。5.2 草稿编写把操作步骤拆解到可执行粒度写skill草稿时我习惯先把操作步骤在脑子里过一遍然后写成一个有序列表。每个步骤要具体到“执行什么命令”“修改哪个文件”“检查什么结果”这个粒度。举个例子写一个“新增API接口”的skill步骤可能是这样的第一步在路由文件里注册新路由第二步在控制器目录下创建对应的处理函数第三步在参数校验文件里添加校验规则第四步在测试目录下创建测试文件第五步运行测试命令确认通过。每个步骤后面可以附上代码示例或者命令示例。代码示例不用完整关键部分写清楚就行。命令示例要写完整包括参数和预期输出。草稿写完后我会自己先按这个步骤走一遍看看有没有遗漏或者顺序不对的地方。这个“自己走一遍”的步骤很重要很多问题只有实际操作才能发现。5.3 测试验证怎么判断一个skill是否生效skill写完不是就完了得验证它是否真的能被AI正确加载和执行。我的验证方法是设计几个测试用例覆盖正常场景和边界场景。正常场景就是按skill设计的触发条件发起请求看AI是否按skill里的步骤执行。比如触发条件是“新增组件”我就说“帮我新增一个Button组件”观察AI是否按skill里的规范来写。边界场景是测试触发条件的准确性。比如skill的触发条件是“新增React组件”我说“新增一个Vue组件”看AI是否会错误地加载这个skill。如果加载了说明触发条件写得太宽泛需要收紧。还有一个验证点是skill的鲁棒性。如果skill里的某个步骤依赖外部条件比如某个文件必须存在那当这个条件不满足时AI是否能正确处理我通常会在测试时故意制造一些异常情况看看skill的表现。5.4 迭代优化根据实际使用反馈调整skill内容skill不是写完就固定不变的需要根据实际使用反馈持续迭代。我一般会在使用过程中记录两类问题一类是AI没有按skill执行的情况另一类是AI按skill执行了但结果不对的情况。第一类问题通常出在触发条件上可能是条件写得太窄导致该触发时没触发也可能是写得太宽导致不该触发时触发了。调整方法就是修改触发条件的描述让它更精确。第二类问题通常出在步骤描述上可能是步骤不够具体也可能是步骤顺序有问题。调整方法就是把模糊的描述改具体把顺序重新排列。有时候还需要补充一些“如果遇到X情况则执行Y”的分支逻辑。迭代频率上我建议新skill在最初一周内频繁调整稳定后就可以降低频率。如果一个skill超过一个月没有修改说明它已经比较成熟了。6. 常见问题与排查技巧实录6.1 skills不生效的排查思路skills不生效是最常见的问题排查时我一般按这个顺序来先确认skill文件是否在正确的目录下再确认文件格式是否正确然后确认触发条件是否匹配最后确认工具版本是否支持。目录问题最常见。不同工具对skill存放位置的要求不一样有的要求放在项目根目录的特定文件夹有的要求放在用户目录。放错位置工具就扫描不到。解决办法是对照官方文档确认目录结构。格式问题也很常见。元信息头的YAML格式对缩进敏感多一个空格少一个空格都可能导致解析失败。我建议用支持YAML语法高亮的编辑器来写能及时发现格式错误。触发条件问题需要实际测试。可以故意用不同的表述发起请求观察哪些能触发、哪些不能。如果发现触发范围不对就调整条件描述。6.2 配置冲突与优先级问题处理当多个skill同时匹配一个请求时就会出现配置冲突。工具通常有默认的优先级规则比如项目级优先于用户级、具体匹配优先于模糊匹配。但有时候默认规则不符合预期需要手动调整。我遇到过一个典型场景项目里有一个“代码格式化”skill用户目录下也有一个同名的。项目级的规范是缩进2空格用户级的是4空格。实际执行时发现用的是用户级的配置原因是用户级skill的触发条件写得更具体匹配优先级更高。解决办法是统一命名规范避免不同层级的skill重名。如果确实需要覆盖就在项目级skill里显式声明覆盖关系或者在配置里指定优先级。6.3 跨工具迁移skills的注意事项有时候需要把Claude Code的skill迁移到Codex或者反过来。这个过程不是简单复制文件就行因为两个工具对skill格式的要求有差异。主要差异在元信息字段上。Claude Code可能用trigger字段表示触发条件Codex可能用when字段。迁移时需要对照两个工具的文档做字段映射。正文部分的差异通常不大但命令示例可能需要调整因为两个工具支持的命令不完全一样。迁移后一定要重新测试不能假设复制过去就能用。我一般会先在测试项目里验证确认没问题再迁移到正式项目。6.4 常见问题速查表问题现象可能原因排查方法解决方式skill完全不生效文件位置错误检查目录结构是否符合文档要求移动到正确目录skill偶尔生效触发条件不稳定用不同表述测试触发情况调整触发条件描述skill执行结果不对步骤描述模糊逐步骤检查是否有歧义补充具体命令和示例多个skill冲突命名或触发条件重叠检查是否有同名或相似skill重命名或调整优先级迁移后不生效字段格式不兼容对照目标工具文档检查字段做字段映射转换本地模型下skill失效模型理解能力不足简化skill内容后测试拆分skill或展开描述7. 我个人的一些实操体会写了这么多skill之后我最大的体会是skill的价值不在于多而在于精。我见过有人项目里塞了几十个skill结果AI加载时互相干扰效果还不如不写。我的建议是从最核心的两三个场景开始用顺了再逐步扩展。另一个体会是skill要跟着项目走不要跟着个人走。个人习惯性的东西放在用户级配置里项目规范性的东西放在项目级配置里。这样换项目时不会带着一堆无关的skill团队协作时也能保证规范统一。最后分享一个小技巧写skill时可以在正文末尾加一段“如果本skill的步骤与实际项目情况不符请以项目实际情况为准并提示用户更新skill”。这句话能让AI在遇到skill过时的情况时主动提醒你而不是机械执行错误步骤。这个技巧我用了之后skill的维护效率提升了不少。