1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术社区还是开发者群聊里“skills”这个词出现的频率高得离谱。你随便翻翻热搜词列表就能看到claude code skills、codex skills、agent skills测试、好用的skills、skills开发、写论文的skills……一大堆。很多人第一次看到会懵——skills不是“技能”吗怎么跟代码、AI、agent扯上关系了我刚开始接触的时候也犯嘀咕。后来用多了才明白这里的skills指的是一套给AI编程助手比如Claude Code、Codex这类工具用的可复用能力包。你可以把它理解成给AI装的“插件”或者“技能卡”AI本身是个通用大脑但你要它干具体的活——比如按你团队的规范写React组件、自动生成数据库迁移脚本、或者把一段自然语言需求转成单元测试——光靠默认能力不够稳定。skills就是把这些特定场景下的操作流程、约束条件、输出格式打包成一个独立模块让AI在需要的时候调用。这玩意儿解决的核心痛点是一致性和可复用性。没有skills的时候你每次让AI写代码都得把要求重复一遍“用TypeScript、用函数式组件、样式用tailwind、错误处理要加try-catch……”说多了烦而且AI偶尔会漏掉一两条。有了skills你把这些规则写进一个文件里AI每次执行相关任务时自动加载输出质量立刻稳定下来。适合谁看三类人一是日常用Claude Code或Codex写代码的开发者想提升AI输出的可控性二是团队技术负责人想把团队规范固化到AI工作流里三是对agent开发感兴趣的人想理解skills的底层机制然后自己写。不管你是刚装好Claude Code的新手还是已经在用Codex接入DeepSeek的老手下面这些内容都能直接抄作业。2. skills的核心机制与方案选型逻辑2.1 skills的本质给AI的“操作手册”而不是“知识库”很多人容易把skills和RAG检索增强生成搞混。我一开始也以为skills就是往向量数据库里塞文档让AI去查。实际用下来发现完全不是一回事。RAG解决的是“AI不知道某个事实”的问题——比如你问它公司内部API的返回格式它没学过你得把文档喂给它。而skills解决的是“AI知道怎么做但做得不够好”的问题。举个例子AI肯定知道怎么写Python函数但它不知道你们团队要求所有函数必须加类型注解、必须用logging而不是print、异常必须包装成自定义错误类。这些规则不是知识是操作规范。skills就是把这些规范写成AI能理解的指令集在特定任务触发时注入到上下文里。从实现上看一个skill通常包含三部分触发条件什么时候用这个skill、执行指令具体步骤和约束、输出模板期望的格式。有些高级的skill还会附带脚本或工具调用比如自动运行lint检查。2.2 为什么选skills而不是直接写prompt你可能会问我直接在对话里把要求说清楚不就行了干嘛还要搞个skill文件我实测下来的感受是短对话可以长项目不行。当你一个会话要处理十几个文件、来回几十轮对话时上下文窗口会被大量无关信息占满你最开始说的那些规范早就被挤到边缘了AI很容易“忘记”。skills的机制是在需要的时候才加载不占用常驻上下文而且可以跨会话复用。另一个原因是团队协作。你把规范写在prompt里只有你自己用。写成skill文件放到项目仓库里团队所有人以及所有人的AI助手都能用同一套标准。新人入职第一天装好Claude Codeskills自动生效写出来的代码风格跟老员工一致。这个价值比省几句打字时间大得多。2.3 Claude Code与Codex的skills生态差异目前skills主要围绕两个工具生态Anthropic的Claude Code和OpenAI的Codex。两者思路相似但细节不同。Claude Code的skills更偏向文件系统驱动。你可以在项目根目录建一个.claude/skills/文件夹里面放Markdown格式的skill定义。Claude Code启动时会扫描这个目录根据当前任务自动匹配。官方市场里也有大量现成的skills可以直接下载比如claude 国内安装skills 官方市场这个热搜词就说明很多人卡在安装环节。Codex的skills则更依赖配置文件。你需要在codex.config或者项目级的配置里声明skill的路径和触发规则。Codex接入DeepSeek之后skills的加载逻辑会走本地模型响应速度更快但需要自己调优。热搜里codex无法加载组织设置、codex is ignoring 1 unrecognized configuration setting这些问题多半是配置文件格式或路径写错了。选哪个我的建议是如果你主要用Claude Code写前端或全栈优先用Claude Code的skills生态现成资源多。如果你在用Codex配合本地模型比如通过LM Studio那Codex的skills更灵活但需要自己折腾配置。3. 手把手搭建你的第一个skill从零到可用3.1 环境准备Claude Code与Codex的安装避坑在写skill之前得先把工具装好。热搜里claude code安装、codex安装教程、codex安装包这些词热度很高说明安装环节卡了不少人。我把自己在Windows和Ubuntu上装的过程捋一遍。Claude Code安装Windows确保Node.js版本在18以上用node -v检查。通过npm全局安装npm install -g anthropic-ai/claude-code。安装完成后运行claude命令会提示你登录。如果你在VSCode里用搜claude code for vs code插件装好后在设置里填API key。常见坑your organization has disabled claude subscription access for claude code这个报错通常是因为你的账号类型不对需要用个人账号或者让管理员开通权限。Codex安装UbuntuCodex现在主要通过codex命令行工具使用安装方式看官网文档。如果你要接入DeepSeek需要在配置里指定base_url和api_key。热搜里codex接入deepseek的教程很多核心就是改~/.codex/config.json。codex登录失败的话检查网络和API key权限。codex无法加载组织设置一般是配置文件里的org_id写错了。注意安装过程中如果遇到cc switch local proxy failed while handling codex endpoint /responses这类报错大概率是本地代理端口冲突。检查一下有没有其他程序占用了同一个端口换个端口号试试。3.2 编写一个“React组件生成”skill的完整过程假设我们团队用ReactTypeScriptTailwind要求所有组件必须函数式、有Props类型定义、默认导出、样式用className、错误边界用try-catch包裹。我来写一个skill。首先在项目根目录创建.claude/skills/react-component.md内容如下--- name: react-component-generator description: 当用户要求创建新的React组件时触发 trigger: - 创建组件 - 新建React组件 - generate component --- # React组件生成规范 ## 必须遵守的规则 1. 使用函数式组件禁止class组件 2. Props必须用TypeScript interface定义命名格式为[组件名]Props 3. 组件必须默认导出 4. 样式统一使用Tailwind的className禁止内联style 5. 所有可能抛错的操作必须用try-catch包裹catch里用console.error记录 ## 输出模板 tsx import React from react; interface ComponentNameProps { // props定义 } const ComponentName: React.FCComponentNameProps (props) { try { return ( div className... {/* 组件内容 */} /div ); } catch (error) { console.error(ComponentName error:, error); return div classNametext-red-500组件加载失败/div; } }; export default ComponentName;示例用户说“创建一个用户卡片组件接收name和avatar两个prop”你应该输出符合上述模板的完整代码。这个文件写好后Claude Code在检测到“创建组件”相关指令时会自动加载。我实测下来输出的一致性提升非常明显——以前十次有三次忘记加try-catch现在基本不会漏。 ### 3.3 skill的触发条件怎么写才精准 触发条件是skill好不好用的关键。写得太宽AI动不动就加载浪费上下文写得太窄该用的时候不触发。 我的经验是**用动词名词的组合避免单个关键词**。比如trigger: [创建组件]就比trigger: [组件]好因为后者在讨论组件设计模式时也会误触发。 另外可以利用文件路径做触发。比如你写一个“数据库迁移”skill可以设置trigger_path: [migrations/**]这样只有当AI操作migrations目录下的文件时才加载。这个技巧在Codex里特别有用因为Codex的配置文件支持glob模式。 还有一个进阶玩法**条件触发**。比如“只有当用户明确说‘按团队规范’时才加载”。这适合那些约束特别严格、平时不想被干扰的skill。 ## 4. 实操全流程从需求到skill落地 ### 4.1 需求分析什么场景值得做成skill 不是所有事情都值得写成skill。我踩过的坑是一开始兴奋把什么都往skill里塞结果维护成本比收益还高。后来总结了一个判断标准——**高频、有明确规范、容易出错**这三个条件同时满足才做。 高频一周至少用三次。偶尔用一次的东西直接写prompt就行。 有明确规范规则能写清楚不是“写得好一点”这种模糊要求。 容易出错AI默认行为经常偏离你的期望需要反复纠正。 举个例子“写论文的skills”这个热搜词。写论文算高频吗对研究生来说算。有明确规范吗有——引用格式、章节结构、学术语气。容易出错吗非常容易AI经常编造参考文献。所以这个场景适合做skill。具体可以写一个“学术写作”skill规定引用必须用真实可查的文献、禁止编造DOI、段落之间要有逻辑连接词。 ### 4.2 编写与调试让skill真正生效 写完skill文件只是第一步调试才是重头戏。我的流程是 1. **最小化测试**先写一个最简单的skill只包含一条规则看AI是否遵守。 2. **逐步加规则**确认第一条生效后再加第二条。每次加完都测试。 3. **边界测试**故意给一些模糊指令看AI会不会误触发或者漏触发。 4. **冲突测试**同时加载两个skill看规则冲突时AI怎么处理。 调试Claude Code的skill时可以用/skills命令查看当前加载了哪些skill。Codex的话在配置文件里加debug: true可以看到skill加载日志。 实操心得skill文件里的规则不要超过7条。超过7条AI的遵守率会明显下降。如果确实有很多规则拆成多个skill用不同的触发条件区分。 ### 4.3 版本管理与团队共享 skill文件应该跟代码一起进Git仓库。我建议的目录结构是project/ ├── .claude/ │ └── skills/ │ ├── react-component.md │ ├── api-endpoint.md │ └── db-migration.md ├── src/ └── ...每个skill文件头部用YAML frontmatter写元信息name、description、trigger正文写具体规则。这样既方便AI解析也方便人阅读。 团队共享时在README里加一段说明“本项目使用Claude Code skills请确保你的Claude Code版本在1.2以上启动时会自动加载.claude/skills/目录。”新人照着做就行。 如果团队用Codex把skill路径写进codex.config的skills_dir字段。热搜里idea设置plugin中插件仓库地址、idea使用skills这些词说明很多人想在IDE里集成目前VSCode的Claude Code插件支持最好JetBrains系列还在完善中。 ## 5. 常见问题与排查技巧实录 ### 5.1 skill不生效的排查清单 | 现象 | 可能原因 | 解决方法 | |------|----------|----------| | AI完全不遵守skill规则 | skill文件路径不对 | 确认文件在.claude/skills/目录下扩展名是.md | | 偶尔生效偶尔不生效 | 触发条件太模糊 | 把trigger改成更具体的动词名词组合 | | 规则冲突导致输出混乱 | 多个skill同时加载 | 检查trigger是否有重叠拆分或合并skill | | Codex报unrecognized configuration setting | 配置文件字段名拼写错误 | 对照官方文档检查字段名注意大小写 | | Claude Code提示组织设置问题 | 账号权限不足 | 换个人账号或联系管理员开通 | ### 5.2 那些热搜词背后的真实问题 翻一遍热搜列表我发现几个高频问题值得单独说。 cc switch local proxy failed while handling codex endpoint /responses——这个报错我遇到过。原因是Codex在本地起了个代理服务但端口被占了。解决方法在配置里改proxy_port换个不常用的端口比如34567。 codex is ignoring 1 unrecognized configuration setting——Codex的配置文件对字段名很严格。比如你写了skill_dir但正确写法是skills_dir它就会忽略并警告。仔细对照文档一个字母都不能错。 your organization has disabled claude subscription access for claude code——这个跟账号类型有关。个人版一般没问题企业版需要管理员在后台开通Claude Code权限。 cursor 怎么设置初始化默认打开时 windows 而不是agents——这是Cursor编辑器的设置问题跟skills无关但说明很多人同时在用多个AI工具配置容易搞混。建议每个工具单独建一个配置文件别混在一起。 ### 5.3 进阶技巧让skill更智能 用了几个月之后我摸索出几个让skill更好用的技巧。 **技巧一用变量占位符**。在skill模板里用{{component_name}}这样的占位符AI会自动替换成实际值。这样同一个skill可以适配不同组件。 **技巧二加负面示例**。除了告诉AI“应该怎么做”再告诉它“不要怎么做”。比如“不要使用any类型”“不要用index作为key”。负面示例对纠正AI的坏习惯特别有效。 **技巧三定期清理**。项目迭代后有些skill的规则可能过时了。我每个月会花十分钟过一遍所有skill删掉不再适用的合并重复的。保持skill库精简AI的遵守率反而更高。 **技巧四用skill组合**。比如“创建API端点”这个skill可以调用“数据库迁移”skill和“错误处理”skill。Claude Code支持skill之间的引用在文件里写include db-migration就行。这样规则可以分层复用不用每个skill都重复写一遍。 ## 6. 从skills看AI编程工具的未来走向 我用了大半年skills最大的感受是**AI编程工具正在从“通用助手”变成“可编程平台”**。以前我们只能被动接受AI的输出现在可以通过skills主动塑造它的行为。这个转变有点像从“用现成软件”到“自己写脚本”——掌控感完全不一样。 热搜里agent skills测试、skills开发、人工智能skills这些词越来越多说明大家已经不满足于“能用”开始追求“好用”和“可控”。langchain deep agents、agentpoison: red-teaming llm agents via poisoning memory or knowledge ba这些偏研究的方向也在探索skills的安全性和鲁棒性。可以预见未来skills会像npm包一样形成一个庞大的生态——有人专门写skill卖钱有人开源共享有人做skill市场。 对于普通开发者来说现在正是学skills的好时机。门槛不高一个Markdown文件就能起步收益很直接AI输出质量立刻提升。我建议你从自己最常重复的那条指令开始把它写成skill用一周试试。大概率你会像我一样再也回不去了。 最后分享一个我最近在用的skill——**“代码审查”skill**。规则很简单每次我让AI审查代码时它必须按“安全性、性能、可读性、测试覆盖”四个维度逐条检查每个问题必须给出具体行号和修改建议。以前AI审查就是泛泛说“看起来不错”现在能揪出useEffect缺少依赖项、async函数没加try-catch这种实际问题。这个skill我放在GitHub上了搜“code-review-skill”就能找到。你也可以根据自己的需求改比如加上团队特有的lint规则。 写skill这件事投入产出比高得离谱。花半小时写一个后面几个月都受益。如果你还没开始今天就可以动手。