1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术社区还是开发者群聊里“skills”这个词出现的频率高得离谱。你随便翻翻热搜榜能看到claude code、codex、plugin、agents这些词跟skills绑在一起反复出现。很多人第一次看到“skills”会以为是某种技能培训或者游戏里的天赋树但在当前的技术语境下它指的是一套让 AI 编程助手真正“能干活”的能力封装机制。说白了skills 就是给 AI 编程工具装上的“操作手册”和“工具箱”。你平时用 Claude Code 或者 Codex 这类工具写代码默认状态下它们只能根据你的自然语言指令去猜你想干什么。但如果你给它挂载一个 skill它就知道“哦原来在这个项目里部署要用这个命令测试要跑那个脚本代码风格要遵循这套规则”。这就像你新招了一个员工他技术底子不错但完全不了解你们公司的内部流程。skills 就是那份写得清清楚楚的《员工入职指南》让他第一天就能按规矩干活。我刚开始接触这个概念的时候也觉得不就是写个配置文件嘛能有多大差别。但实际用下来发现有没有 skills 的 AI 编程体验完全是两个量级。没有 skills 的时候你每次都要重复交代“用 pnpm 不要用 npm”“测试文件放在tests目录下”“提交前先跑 lint”说多了自己都烦。有了 skills 之后这些规则被固化下来AI 自动遵守你只需要关注真正需要创造力的部分。这篇文章适合几类人看一是刚听说 Claude Code 或者 Codex 但还没搞明白 skills 怎么用的新手二是已经在用这些工具但觉得“好像没那么神”的中级用户三是想自己开发 skills 给团队用的技术负责人。我会从核心思路、实操步骤、常见坑点几个角度把 skills 这件事讲透。2. skills 的核心设计思路与方案选型2.1 为什么是“技能包”而不是“配置文件”很多人第一次接触 skills 会有一个疑问这不就是以前那种.editorconfig或者.eslintrc的升级版吗我直接写个配置文件不就行了为什么要搞一个叫“skill”的东西这个问题的答案藏在skills 的设计哲学里。传统的配置文件是“声明式”的你告诉工具“我要什么结果”工具自己去想办法。但 skills 是“程序式”的它不仅告诉 AI 要做什么还告诉它怎么做、什么时候做、做的时候注意什么。举个例子一个部署 skill 不只是写“部署到生产环境”它会包含先跑测试、再构建、检查构建产物大小、如果超过阈值就告警、然后才执行部署命令、部署后还要验证健康检查接口。这一整套流程用配置文件很难表达清楚但用 skill 就可以。从热搜词里能看到claude agent skills: a first principles deep dive这样的内容说明已经有人在从第一性原理层面分析这件事了。我的理解是skills 的本质是把“隐性知识”显性化。团队里那个最资深的工程师他知道部署的时候要先看某个监控指标知道某个接口在高峰期不能重启这些知识以前只存在他脑子里。现在通过 skills这些知识被写下来AI 能执行新人也能看懂。2.2 Claude Code 与 Codex 的 skills 机制差异目前市面上讨论最多的两个支持 skills 的工具是 Claude Code 和 Codex。虽然都叫 skills但两者的实现方式和适用场景有明显区别。Claude Code 的 skills 更偏向项目级的能力扩展。你可以在项目根目录下创建一个.claude/skills文件夹里面放上 Markdown 格式的 skill 定义文件。每个 skill 文件包含触发条件、执行步骤、注意事项。Claude Code 在运行时会自动扫描这些文件根据当前任务匹配对应的 skill。这种设计的好处是跟项目绑定你换一个项目skills 也跟着换不会互相干扰。Codex 的 skills 则更强调跨项目的通用能力。从热搜词codex skills和codex好用的skills能看出来大家更关心的是“有哪些现成的 skill 可以直接用”。Codex 的 skills 通常以插件的形式分发你可以通过包管理器安装然后在多个项目里共享。这种设计适合那些有统一技术栈的团队比如所有项目都用 React TypeScript那就可以共享一套前端开发的 skills。我个人的建议是如果你主要用 Claude Code就从项目级的 skills 开始写起先解决自己项目里的重复劳动问题。如果你用 Codex 比较多先去社区找现成的 skills 安装站在别人的肩膀上起步。2.3 一个 skill 的典型结构长什么样说了这么多一个 skill 到底长什么样我用一个实际例子来说明。假设我们要写一个“前端组件生成”的 skill它的结构大概是这样的--- name: generate-component description: 当用户要求创建新的 React 组件时触发 trigger: 用户提到创建组件、新建组件、add component --- ## 执行步骤 1. 询问组件名称和存放路径如果用户没有明确指定 2. 检查目标路径下是否已存在同名组件 3. 按照项目规范生成组件文件包含 - 组件主体函数式组件 TypeScript - 样式文件CSS Modules - 测试文件React Testing Library - 导出文件index.ts 4. 运行 lint 检查确保代码风格符合项目规范 5. 输出生成的文件列表和下一步建议 ## 注意事项 - 组件名称必须使用 PascalCase - 如果组件需要接收 props必须定义 TypeScript 接口 - 测试文件至少包含一个渲染测试这个结构里frontmatter 部分定义了 skill 的元信息包括名称、描述和触发条件。下面的正文部分就是具体的执行指令。Claude Code 或 Codex 读到这个文件后就知道当用户说“帮我创建一个 Button 组件”时它应该按照这五步来执行而不是随便生成一个文件就完事。3. 从零开始搭建你的第一个 skill3.1 环境准备与工具安装在开始写 skill 之前你得先把基础环境搭好。根据热搜词里claude code安装、codex安装教程、vscode配置claude code这些高频搜索我判断很多人卡在第一步。这里我分别说一下两个工具的安装要点。Claude Code 的安装相对直接。如果你在 macOS 或 Linux 上可以通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后在项目目录下运行claude命令就能启动。Windows 用户需要注意官方推荐在 WSL2 环境下运行原生 Windows 的支持虽然有了但偶尔会遇到路径分隔符的问题。热搜词里claude code windows和ubuntu配置claude code同时出现说明跨平台配置确实是个痛点。Codex 的安装稍微复杂一点因为它有不同的发行版本。从热搜词codex安装包、codex下载、codex官网下载来看很多人找不到正确的下载渠道。我的建议是直接通过官方文档提供的包管理器安装不要从第三方站点下载安装包避免版本不一致和安全风险。安装完成后你需要配置 API 密钥或者登录账号。热搜词里codex登录和your organization has disabled claude subscription access说明登录环节也容易出问题。如果遇到组织策略限制需要联系管理员确认你的账号是否有权限使用相关服务。3.2 创建你的第一个 skill 文件环境准备好之后我们来动手写第一个 skill。我建议从最简单的开始比如一个“代码格式化”的 skill。这个 skill 的作用是当用户要求格式化代码时自动按照项目规范执行。首先在项目根目录下创建 skills 文件夹mkdir -p .claude/skills然后创建一个名为format-code.md的文件--- name: format-code description: 按照项目规范格式化代码 trigger: 用户提到格式化、format、整理代码 --- ## 执行步骤 1. 确认当前项目使用的格式化工具检查 package.json 中的 prettier 或 eslint 配置 2. 对指定文件或目录运行格式化命令 3. 如果格式化后有文件变更输出变更摘要 4. 提醒用户检查变更内容 ## 注意事项 - 不要格式化 node_modules 或 dist 目录 - 如果项目没有配置格式化工具先询问用户是否要初始化配置 - 格式化前建议先提交当前更改方便回滚这个 skill 虽然简单但它包含了 skill 的核心要素触发条件、执行步骤、注意事项。写完之后你在 Claude Code 里输入“帮我格式化一下 src 目录下的代码”它就会自动匹配到这个 skill 并按照步骤执行。3.3 调试与验证 skill 是否生效写完 skill 之后怎么知道它有没有生效这里有几个验证方法。最直接的方式是观察 AI 的输出行为。如果 skill 生效了AI 在执行任务时会按照你定义的步骤来而不是自由发挥。比如上面的格式化 skill如果生效了AI 会先检查 package.json再运行命令最后输出变更摘要。如果没生效它可能直接就运行一个prettier --write .就完事了。另一个方法是查看日志。Claude Code 在启动时会扫描 skills 目录如果有语法错误或者格式问题会在日志里输出警告。你可以通过claude --debug启动来查看详细的加载信息。还有一个技巧是故意写一个触发词很窄的 skill然后测试它是否只在特定条件下触发。比如你把 trigger 写成“当用户说‘香蕉’时触发”然后输入“香蕉”看 AI 的反应。这样可以验证 skill 的匹配机制是否正常工作。注意skill 文件的 frontmatter 格式必须严格遵循 YAML 规范冒号后面要有空格缩进要一致。我见过很多人因为 frontmatter 格式错误导致 skill 完全不生效排查了半天才发现是少了一个空格。4. 进阶玩法让 skills 真正融入开发流程4.1 组合多个 skill 完成复杂任务单个 skill 能解决的问题有限真正体现 skills 价值的地方在于组合。举个例子一个完整的“新功能开发”流程可能涉及多个 skill需求分析 skill、代码生成 skill、测试编写 skill、代码审查 skill、提交信息生成 skill。这些 skill 各自负责一个环节串联起来就是一条完整的流水线。我自己的项目里有一套“发布准备”的 skill 组合。第一个 skill 负责检查所有测试是否通过第二个 skill 负责更新版本号和 changelog第三个 skill 负责构建产物并检查体积第四个 skill 负责生成发布说明。以前这些步骤我要手动跑四五个命令现在只需要说一句“准备发布”AI 就会按顺序执行所有 skill。组合 skill 的关键是定义好输入输出。每个 skill 应该明确自己需要什么输入、产生什么输出这样下一个 skill 才能顺利衔接。比如代码生成 skill 的输出是文件路径列表测试编写 skill 的输入就是这些文件路径。这种契约式的设计让 skill 之间可以灵活组合。4.2 团队协作中的 skills 管理如果你在一个团队里推广 skills管理就成了一个大问题。每个人的 skill 放在自己电脑上版本不一致新人来了不知道用哪个这些都是常见的痛点。我的做法是把 skills 纳入版本控制。在项目仓库里创建一个skills目录所有 skill 文件都提交到 Git。这样每个人拉取代码后自动获得最新的 skills。同时在 README 里写清楚每个 skill 的作用和使用方法新人入职第一天就能上手。对于跨项目的通用 skills可以单独建一个仓库通过 Git submodule 或者包管理器的方式引入。热搜词里idea设置plugin中插件仓库地址和dsh plugin --profile web add dshmarket说明大家也在探索插件化的管理方式。目前 skills 的生态还在早期没有形成统一的标准但把 skills 当作代码来管理这个思路是没错的。还有一个经验是给 skill 写测试。听起来有点夸张但确实有用。你可以写一个简单的脚本模拟用户输入检查 AI 是否按照预期触发了 skill。虽然不能做到完全自动化但至少能保证 skill 文件没有语法错误触发条件没有写错。4.3 常见问题与排查技巧实录在实际使用 skills 的过程中我踩过不少坑。这里整理一个速查表方便你遇到问题时快速定位。问题现象可能原因解决方法skill 完全不生效frontmatter 格式错误检查 YAML 语法确保冒号后有空格skill 触发太频繁trigger 条件太宽泛收窄触发词增加限定条件skill 执行步骤混乱步骤描述不够明确把每一步拆细避免模糊指令多个 skill 冲突触发条件重叠调整优先级或合并 skillskill 加载报错文件编码问题确保文件是 UTF-8 编码AI 忽略 skill 指令skill 内容太长精简 skill只保留核心指令还有一个容易被忽略的问题是skill 的命名。我建议用动词开头比如generate-component、run-tests、deploy-staging这样一看就知道这个 skill 是干什么的。避免用component-helper这种模糊的名字。提示如果你发现 skill 偶尔生效偶尔不生效大概率是触发条件写得不够精确。AI 的匹配机制是基于语义的不是精确字符串匹配。所以 trigger 里要写清楚“当用户明确要求做某事时触发”而不是只写一个关键词。5. skills 生态的现状与未来可能性5.1 社区里有哪些好用的 skills从热搜词skills推荐、codex好用的skills、find skills能看出来大家很关心有没有现成的 skill 可以直接用。目前社区里比较受欢迎的 skills 主要集中在几个方向前端组件生成、API 接口联调、数据库迁移、代码审查、提交信息规范化。前端方向的 skills 尤其多因为前端开发的重复性工作比较多。比如superpower skills这个热搜词我理解可能是指某些功能特别强大的 skill 集合。这类 skill 通常会把组件生成、样式处理、路由配置、状态管理这些环节都封装进去一句话就能生成一个完整的页面模块。不过我要提醒一句不要盲目安装太多 skill。skill 多了之后AI 的决策负担会加重有时候反而不知道该用哪个。我的建议是先从三五个核心 skill 开始用顺了再逐步增加。5.2 自己开发 skill 的注意事项如果你打算开发自己的 skill有几个原则值得遵守。第一保持 skill 的单一职责。一个 skill 只做一件事不要试图把多个功能塞进一个文件。这样既方便调试也方便复用。第二写清楚边界条件。什么情况下不应该触发这个 skill什么情况下需要询问用户确认这些都要写明白。比如一个删除文件的 skill必须写明“删除前必须让用户确认”。第三定期更新。项目在变化skill 也要跟着变。我习惯每个月 review 一次项目里的 skills把过时的删掉把新出现的重复劳动补充进去。第四注意安全。skill 里不要写任何敏感信息比如 API 密钥、数据库密码。这些应该通过环境变量注入而不是硬编码在 skill 文件里。5.3 从 skills 到 agents 的演进路径热搜词里agents、langchain deep agents、agents anywhere这些词频繁出现说明 skills 只是更大图景的一部分。skills 是 agents 的基础能力单元一个 agent 可以看作是一组 skills 的编排和调度。打个比方skills 是乐高积木agents 是用积木搭出来的机器人。你可以用同样的积木搭出不同的机器人每个机器人负责不同的任务。目前 Claude Code 和 Codex 更像是“通用机器人”什么都能干一点但什么都不精。未来的趋势可能是出现更多“专用机器人”比如专门做前端开发的 agent、专门做数据处理的 agent每个 agent 背后都有一套精心设计的 skills。对于普通开发者来说现在把 skills 用好就是在为未来的 agent 时代做准备。因为不管工具怎么变把重复劳动封装成可复用能力这个思路是不会变的。6. 我个人的实操心得与避坑建议用了大半年 skills有几个体会特别深。第一个是不要追求大而全的 skill。我一开始写了一个“万能前端开发 skill”想把所有前端相关的事情都塞进去。结果这个 skill 文件超过 500 行AI 读起来很吃力执行的时候经常漏步骤。后来我把它拆成了五个小 skill每个只负责一件事效果反而好得多。第二个是skill 的触发词要符合你的说话习惯。如果你平时说“帮我搞个组件”那 trigger 里就要写“搞个组件”而不是写“创建组件”。AI 的语义匹配虽然智能但越贴近你的真实表达触发越准确。第三个是定期清理无效 skill。项目里经常会有些 skill 是临时写的用完就忘了。这些 skill 留在那里会干扰 AI 的判断。我现在的做法是每个 skill 文件头部加一个last_used字段每个月检查一次超过两个月没用过的就归档。第四个是不要完全依赖 skill。skill 是辅助工具不是万能药。有些任务就是需要人工判断硬要用 skill 去自动化反而容易出问题。比如代码审查skill 可以帮你检查格式和明显的错误但架构层面的问题还是得人来判断。最后分享一个我最近在用的技巧用 skill 来记录项目决策。比如为什么选了这个数据库、为什么用了这个状态管理方案这些决策背景写在 skill 里AI 在生成代码时就会考虑这些约束不会给你推荐一个跟项目决策相悖的方案。这个用法我觉得挺有意思的相当于把架构决策文档变成了可执行的约束条件。