1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题很多人会懵——这词太泛了。但结合热搜词里高频出现的 Claude Code、Codex、plugin、agents 这几个词方向其实很明确这里说的 skills指的是围绕 AI 编程助手尤其是 Claude Code 和 Codex 这类 CLI Agent 工具构建的可复用能力单元。它不是某个具体软件而是一套让 AI 助手学会做某类具体事情的机制。打个比方。你雇了一个很聪明的实习生他懂很多通用知识但你让他帮你处理公司内部的报销流程他一开始是懵的。你得给他一份 SOP第一步打开哪个系统第二步填哪些字段第三步找谁审批。这份 SOP 就是 skill。AI 编程助手也一样模型本身能力很强但面对帮我按团队规范提交一个 PR帮我把这个 Flutter 项目的 Gradle 配置改成新版写法这类具体任务时它需要一份结构化的操作说明。skills 就是这份说明的标准化封装。为什么这个概念在 2024 年底到 2025 年初突然火起来因为大家发现光靠 prompt 临时描述任务重复性太高、质量不稳定。你今天写一段 prompt 让 AI 帮你做代码审查明天换个项目又得重写一遍。而 skills 把这些 prompt 固化下来变成可以跨项目、跨会话复用的资产。这就像从每次手写 SQL进化到建存储过程——一次写好到处调用。这篇文章适合谁看三类人。第一类是想搞清楚 skills 到底是什么、值不值得投入时间学的前端或后端开发者第二类是已经在用 Claude Code 或 Codex但还在靠临时 prompt 干活、效率上不去的人第三类是想自己写 skills、做团队内部能力沉淀的技术负责人。我会从概念、安装配置、实际使用、自己动手写、踩坑经验这几个角度把这件事讲透。需要先说明一点skills 目前没有统一的行业标准Claude Code 的 skills 和 Codex 的 skills 在格式和加载机制上有差异。我会分别讲但重点放在通用的思路和实操上因为底层逻辑是相通的。2. Claude Code 的 skills 机制目录结构决定一切2.1 skills 在 Claude Code 里是怎么被加载的Claude Code 加载 skills 的方式很朴素——扫描特定目录下的文件夹。每个 skill 是一个独立文件夹文件夹里必须有一个SKILL.md文件作为入口。这个文件用 Markdown 写开头是 YAML 格式的元数据frontmatter后面是具体的指令内容。一个典型的目录结构长这样~/.claude/skills/ ├── code-review/ │ └── SKILL.md ├── pr-submit/ │ └── SKILL.md └── flutter-gradle-fix/ └── SKILL.mdSKILL.md的元数据部分至少要包含name和description两个字段。description特别关键因为 Claude Code 是靠这个描述来判断当前任务该不该调用这个 skill的。描述写得含糊skill 就永远不会被触发描述写得精准命中率就高。--- name: code-review description: 对当前 git diff 中的改动做代码审查检查命名规范、潜在空指针、日志规范。当用户提到审查代码review 改动检查 diff时使用。 --- # 代码审查流程 1. 运行 git diff --staged 获取暂存的改动 2. 逐文件检查以下项 - 变量命名是否符合 camelCase - 是否有未处理的 null 或 undefined - 日志是否使用了统一的 logger 而非 console.log 3. 输出格式按文件分组每条问题标注严重级别这里有个很多人忽略的细节description 里要写触发条件而不只是这个 skill 做什么。上面例子里当用户提到……时使用这句话就是给模型的路由提示。我实测下来加上触发条件后skill 被正确调用的概率明显提升。2.2 全局 skills 和项目级 skills 的区别Claude Code 支持两个层级的 skills全局的和项目级的。全局的放在~/.claude/skills/所有项目都能用项目级的放在项目根目录的.claude/skills/只在这个项目里生效。这个设计的意义在于隔离。比如提交 PR这个 skill每个公司的规范不一样就应该放项目级而通用代码审查这种跨项目通用的放全局级。我见过有人把所有 skill 都塞全局目录结果在一个 Python 项目里触发了给 Java 项目写的检查规则输出一堆无关建议反而添乱。提示项目级 skills 建议纳入 git 版本管理这样团队每个人拉下代码就自动拥有同一套能力。全局 skills 则适合放个人习惯类的东西比如用我偏好的 commit message 格式。2.3 安装第三方 skills 的正确姿势热搜词里出现了claude 国内安装 skills 官方市场skills 推荐这类词说明很多人卡在怎么把别人的 skill 装到自己机器上这一步。其实没有想象中复杂本质就是把文件夹复制到对应目录。假设你从某个仓库拿到了一个 skill 文件夹操作步骤是确认文件夹里有SKILL.md且元数据格式正确决定放全局还是项目级复制过去cp -r ./some-skill ~/.claude/skills/重启 Claude Code 会话重要skills 是启动时扫描的用/skills之类的命令不同版本命令可能不同确认加载成功这里最容易踩的坑是元数据格式错误。YAML 对缩进极其敏感多一个空格少一个空格都会导致解析失败而失败时往往没有明显报错skill 就是静默不生效。我的习惯是装完新 skill 后先手动触发一次确认它真的被调用了再正式用。3. Codex 的 skills另一套玩法别混着用3.1 Codex 里 skills 的定位差异Codex 的 skills 机制和 Claude Code 不完全一样。Codex 更强调配置驱动很多能力是通过配置文件比如config.toml或类似的 profile 机制来定义的而不是纯靠 Markdown 描述。热搜词里dsh plugin --profile web add dshmarket这种命令反映的就是这种 profile plugin 的配置思路。这意味着什么意味着你在 Claude Code 里写好的 skill不能直接搬到 Codex 用。两者的元数据格式、加载路径、触发机制都不同。我见过有人把 Claude 的SKILL.md直接丢进 Codex 目录然后困惑为什么没反应——因为 Codex 根本不认这个格式。Codex 的 skills 更偏向工具调用和命令封装。你可以把它理解成给 Codex 注册一批自定义命令每个命令背后是一段可执行逻辑或一段指令模板。它的优势是和 shell 环境结合更紧密适合做自动化脚本类的 skillClaude Code 的 skills 则更偏向知识注入和流程指导。3.2 两个工具怎么选还是都要我的建议是看你主力用哪个。如果你日常主力是 Claude Code就先把 Claude 的 skills 体系吃透别分散精力。如果你团队统一用 Codex那就深耕 Codex 的 profile 机制。但如果你两个都用很多人确实是这样不同任务用不同工具那就要建立自己的 skill 资产库用一套源文件管理然后写脚本分别转换成两个工具需要的格式。听起来麻烦但比每次手动改两份要靠谱。我自己的做法是核心逻辑写在 Markdown 里然后用一个简单的转换脚本生成两边的配置文件。这样改一处两边同步。3.3 接入本地模型时的注意事项热搜词里有claude code 调用 lmstudio 的本地模型codex 接入 deepseek这类说明不少人想让这些工具跑在本地或第三方模型上。这里要提醒的是skills 的效果高度依赖模型的指令遵循能力。skills 本质上是给模型看的结构化指令。模型越强越能准确理解 description 里的触发条件、越能严格执行 SKILL.md 里的步骤。换成能力较弱的本地模型后常见问题是skill 该触发时不触发或者触发了但步骤执行到一半就跑偏。这不是 skill 写错了是模型能力不够。所以如果你打算用本地模型跑 skills心理预期要调整简单任务格式化、模板填充问题不大复杂多步任务跨文件重构、依赖分析成功率会明显下降。建议先用小任务验证模型对 skill 的遵循度再决定要不要把关键流程交给它。4. 一个能直接抄的 skill 实战自动生成规范的 commit光讲概念没意思直接上一个我天天在用的 skill从零到能用完整走一遍。4.1 需求拆解为什么这个 skill 值得做团队里 commit message 格式不统一是老大难。有人写fix bug有人写修复了登录页面的问题有人干脆写update。代码审查时想按 commit 追溯改动根本没法看。用临时 prompt 让 AI 帮忙写 commit message 行不行行但每次都要重新描述规范而且不同人描述得还不一样。做成 skill 之后规范固化在文件里谁用都是同一套标准这才是价值所在。4.2 编写 SKILL.md 的完整过程先建目录mkdir -p ~/.claude/skills/conventional-commit然后写SKILL.md--- name: conventional-commit description: 根据当前暂存的 git 改动生成符合 Conventional Commits 规范的提交信息。当用户提到写 commit生成提交信息commit message时使用。 --- # 生成规范 commit message ## 步骤 1. 运行 git diff --staged --stat 查看改了哪些文件 2. 运行 git diff --staged 查看具体改动内容 3. 判断改动类型从以下类型中选择 - feat: 新功能 - fix: 修复 bug - refactor: 重构不改变外部行为 - docs: 文档改动 - style: 格式调整不影响逻辑 - test: 测试相关 - chore: 构建、依赖等杂项 4. 生成格式type(scope): subject - scope 用改动最集中的模块名 - subject 用中文不超过 50 字动词开头不加句号 5. 如果改动较大在 subject 下方空一行补充 body 说明为什么改而非改了什么 ## 输出示例 feat(user-auth): 增加手机号验证码登录 原有登录方式仅支持密码移动端输入体验差。 新增验证码登录作为备选降低移动端登录门槛。 ## 注意 - 不要输出解释性文字直接给 commit message - 如果暂存区为空提示用户先 git add写完保存重启会话这个 skill 就能用了。4.3 实测效果和微调实测下来这个 skill 的触发准确率很高基本你说帮我写个 commit它就会调用。生成质量也稳定因为规范写死在文件里不受当天 prompt 措辞影响。但用了一周后我发现一个问题scope 判断有时不准。比如改动横跨 user 和 order 两个模块它会随机选一个。后来我在 SKILL.md 里补了一条规则如果改动涉及多个模块scope 用逗号分隔如user,order。改完之后就准了。这就是 skills 的好处——发现问题改文件永久生效。不用每次在 prompt 里重复交代。5. 写 skill 的几个反直觉经验5.1 description 不是越详细越好新手写 description 容易写成小作文把 skill 能做的所有事都列一遍。结果反而触发不准因为描述太长模型抓不住重点。正确做法是一句话说清做什么 一句话说清什么时候用。前者给模型判断能力边界后者给模型判断触发时机。超过三行的 description基本可以砍。5.2 步骤要写成可执行动作不是目标对比两种写法差的写法检查代码质量好的写法运行git diff --staged逐文件检查是否有未处理的 null前者是目标模型不知道具体怎么做只能自由发挥后者是动作模型照着执行就行。skills 的核心价值就是把自由发挥变成按部就班所以步骤必须具体到可执行。5.3 给 skill 加退出条件复杂 skill 容易陷入死循环或过度执行。比如一个修复所有 lint 错误的 skill如果代码里有个错误它修不好可能会反复尝试。解决办法是在 SKILL.md 里加退出条件如果同一个错误尝试两次仍未修复停止并报告不要继续。这句话能省掉很多麻烦。5.4 版本管理别偷懒skills 是代码资产就该像代码一样管理。全局 skills 目录建议也做成 git 仓库每次改动都有记录。我吃过亏——有次改了一个 skill 的触发条件结果另一个场景不触发了想回滚却发现没记录只能凭记忆重写。6. 那些热搜词背后的真实问题热搜词里混着不少报错信息比如cc switch local proxy failedqt.qpa.plugin: could not find the qt platform pluginyou are applying flutters main gradle plugin imperatively。这些看起来和 skills 无关但其实是同一批人在折腾 AI 编程工具时遇到的环境问题。我的观察是skills 用不起来八成不是 skill 本身的问题而是环境没配好。工具装不上、模型连不通、插件冲突这些基础问题不解决skills 写得再好也白搭。所以给新手的建议是先把 Claude Code 或 Codex 本身跑通能正常对话、能读写文件再折腾 skills。顺序反了会在环境问题上浪费大量时间还以为是 skill 写错了。另外热搜词里安卓脱壳 skillsagentpoison: red-teaming llm agents这类属于安全研究领域的 skills 应用和日常开发用的 skills 是两回事。前者是攻击/防御技术后者是效率工具。别被这些词带偏以为 skills 是什么高深黑科技——对绝大多数开发者来说它就是个把重复 prompt 固化下来的实用机制。7. 团队协作场景下 skills 的落地方式个人用 skills 是提效团队用 skills 是统一标准。这两件事的价值量级不一样。个人用你省的是自己敲 prompt 的时间团队用你省的是每个人理解规范不一致导致的返工。后者才是大头。落地方式我推荐这样在项目仓库里建.claude/skills/目录把团队规范类的 skill 放进去纳入 git。新成员拉下代码自动获得和老人一样的能力。代码审查 skill、commit 规范 skill、PR 模板 skill这几个是团队最该先做的。但要注意别搞成强制。skills 是辅助不是枷锁。如果某个 skill 在特定场景下不合适成员应该有权不用。我见过团队把 skill 做成硬性流程结果遇到边缘情况时大家只能绕开工具手动操作反而更乱。维护上建议指定一个人负责 skills 目录的 review就像 review 代码一样。skill 改动也要走 PR这样规范演进有迹可循。8. 我踩过的几个坑你可以直接避开第一个坑skill 名字用了中文。有些工具对文件夹名和 name 字段的字符集有限制中文名可能导致加载失败。统一用英文小写加连字符最稳。第二个坑在 SKILL.md 里写了太多背景知识。skills 是给模型看的操作手册不是给人看的技术文档。写一堆为什么要有这个规范的历史背景只会稀释关键指令。背景知识放 READMESKILL.md 只留可执行内容。第三个坑指望一个 skill 解决所有问题。skill 越聚焦越好用。我一开始想做一个万能代码助手skill结果什么都不精。后来拆成审查格式化生成测试三个独立 skill每个都好用多了。第四个坑忘了重启会话。skills 是会话启动时加载的改完文件不重启改动不生效。这个坑我踩过不止一次每次都要愣几秒才想起来。第五个坑description 里用了太多同义词。想让触发更宽泛就把审查、检查、review、看看全塞进去结果模型反而困惑。description 用最自然的表达就行模型的理解能力比你想的强。9. 关于 skills 未来的一点个人判断skills 这个机制现在还处在各自为政的阶段Claude Code 一套、Codex 一套没有统一标准。但从趋势看把可复用能力封装成文件这个方向是对的因为它解决了 AI 助手最大的痛点——每次对话都是白纸一张没有积累。我个人的做法是不管工具怎么变核心能力都沉淀成 Markdown。工具换了转换格式的成本很低但如果能力只存在于某次对话的 prompt 里工具一换就全丢了。所以别纠结哪个工具的 skills 机制更好先把你的重复性工作梳理出来写成结构化的文档这一步的价值是跨工具的。至于要不要现在就投入大量时间做 skills 库我的建议是从最高频的那一个任务开始。别一上来就规划几十个 skill先做一个用一周确认它真的省了时间再考虑第二个。skills 的价值在于精而不在于多十个半吊子 skill 不如一个天天用的。