1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题很多人会懵——这词太泛了。但结合热搜词里的Claude Code、Codex、plugin、agents方向就清楚了这里说的 skills指的是围绕 AI 编程助手尤其是 Claude Code、Codex 这类命令行/编辑器内的智能体构建的可复用能力单元。它不是传统意义上的插件市场里点一下安装的那种东西而是一套让 AI 助手在特定任务上表现更稳、更专、更可控的配置与脚本集合。我接触这套东西的起点很朴素用 Claude Code 写代码时发现它在通用任务上很强但一碰到项目特有的规范、特定的构建流程、某个内部工具的调用方式就开始自由发挥。每次都要在对话里重复交代背景效率极低。后来才意识到问题不在于模型不够聪明而在于我没把这个项目该怎么干活这件事固化成一个它能稳定读取的能力单元。skills 就是干这个的。所以这篇内容适合三类人看一是已经在用 Claude Code 或 Codex但总觉得差点意思的开发者二是想给团队统一 AI 助手行为规范的 tech lead三是纯粹好奇agent skills 到底是个啥的技术爱好者。我会从概念、结构、实操、踩坑几个层面把它讲透尽量让你看完就能动手搭一个自己的 skill。需要先说明一点skills 这个概念在不同工具里的实现细节有差异Claude Code 的 skill 机制、Codex 的配置方式、以及各类 agent 框架里的技能抽象名字一样但形态不完全相同。下面我会以最主流的 Claude Code skill 为主线穿插 Codex 和其他 agent 场景的对照因为热搜词里这几类都出现了读者大概率是混着用的。2. 拆开一个 skill 看内部它凭什么让 AI 变专业2.1 skill 的本质是一份给 AI 看的操作手册很多人把 skill 想得很玄其实它的核心非常朴素一段结构化的说明文本加上可选的辅助资源脚本、模板、参考文档放在 AI 助手能主动读取的特定位置。当你的请求和这个 skill 描述的场景匹配时AI 会把这个 skill 的内容加载进上下文然后按里面的指引干活。打个比方默认状态下的 AI 助手像一个刚入职的聪明新人什么都能聊但不懂你们公司的规矩。skill 就是你写给这个新人的《XX 任务操作 SOP》——里面写清楚遇到这类任务时第一步做什么、用什么工具、输出成什么格式、有哪些坑不能踩。新人AI在接到相关任务时会先翻这份 SOP再动手。这个类比能解释一个常见困惑为什么我写了 skillAI 有时候还是不按它来因为新人翻不翻 SOP取决于任务匹配度。如果你的 skill 描述写得含糊AI 判断这任务跟那份 SOP 关系不大就不会加载。所以 skill 的触发描述description写得准不准直接决定它有没有用。2.2 一个 skill 的典型目录结构以 Claude Code 的 skill 为例一个标准的 skill 通常长这样.claude/skills/ └── my-deploy-skill/ ├── SKILL.md # 核心技能说明与操作指引 ├── scripts/ # 可选辅助脚本 │ └── deploy.sh ├── templates/ # 可选输出模板 │ └── report.md └── reference/ # 可选参考资料 └── api-notes.md关键文件是SKILL.md它一般包含两大部分frontmatter元信息和正文操作指引。frontmatter 里最重要的是name和description前者是技能标识后者是触发条件。正文则是给 AI 看的详细步骤。这里有个容易被忽略的点description 不是写给人看的简介而是写给 AI 看的匹配依据。很多人把它写成这个技能用于部署太笼统。好的写法是描述清楚什么时候该用——比如当用户要求把当前项目部署到测试环境、或提到 deploy/staging/发布测试 时使用本技能。把触发关键词和场景都塞进去命中率会高很多。2.3 为什么是渐进式加载而不是全塞进去Claude Code 的 skill 机制有个很聪明的设计它不会一次性把所有 skill 的全文都塞进上下文。启动时只加载每个 skill 的 name 和 description很轻量只有当某个 skill 被判定为相关时才把它的完整正文读进来。这个设计解决了一个现实问题如果你有几十个 skill全量加载会瞬间吃光上下文窗口既费钱又降低模型注意力。渐进式加载相当于先看目录需要哪章再翻哪章。理解这一点很重要因为它意味着——你可以放心地积累很多 skill不用担心它们互相挤占空间前提是每个 skill 的 description 写得足够精准让 AI 能正确判断何时该翻它。2.4 skill 和 plugin、agent 的关系热搜词里plugin、agents和skills并列出现这三者容易混。我的理解是概念定位类比plugin扩展宿主程序功能的模块给编辑器装的扩展agent能自主规划、调用工具完成任务的智能体一个能独立干活的员工skillagent 可调用的具体能力单元员工掌握的一项专项技能简单说agent 是谁在干活skill 是它会哪门手艺plugin 更偏向传统软件层面的功能扩展。一个 agent 可以挂载多个 skill按任务需要调用。Claude Code 本身可以看作一个 agent你写的 skill 就是给它加的手艺。3. 动手写第一个 skill从零到能跑通3.1 环境准备先确认你的工具版本支持 skill不是所有版本的 Claude Code 都支持 skill 机制。动手前先确认版本命令行里跑一下版本检查确保是比较新的版本。如果你用的是 VS Code 里的 Claude Code 扩展也要留意扩展本身的更新。热搜里claude code windows、ubuntu配置claude code、vscode配置claude code这些词说明跨平台配置是高频需求这里给个通用思路Windows注意路径分隔符和脚本执行权限.sh脚本在纯 Windows 环境下可能跑不了建议用.ps1或.bat或者干脆用跨平台的 Node/Python 脚本。macOS / Linux相对省心注意给脚本加可执行权限chmod x。VS Code 扩展skill 目录一般放在项目根目录的.claude/skills/下扩展会读取项目级配置。提示skill 分项目级和用户级。项目级放在项目目录里只对这个项目生效用户级放在用户主目录下对所有项目生效。团队协作建议用项目级跟着代码仓库走大家行为一致。3.2 写一个生成规范提交信息的 skill我们拿一个真实场景练手让 AI 在帮你提交代码时自动生成符合团队规范的 commit message。这个需求足够具体又能体现 skill 的价值。第一步建目录mkdir -p .claude/skills/commit-helper第二步写SKILL.md--- name: commit-helper description: 当用户要求提交代码、生成 commit message、或提到 git commit / 提交信息 时使用。按照团队规范生成符合 Conventional Commits 格式的提交信息。 --- # 提交信息生成规范 ## 何时使用 用户要求提交代码、生成或优化 commit message 时。 ## 提交信息格式 必须遵循 Conventional Commits type(scope): subject body footer ## type 取值 - feat: 新功能 - fix: 修复 bug - docs: 文档变更 - refactor: 重构不改功能 - test: 测试相关 - chore: 构建/工具链变更 ## 规则 1. subject 用中文不超过 50 字结尾不加句号 2. body 说明为什么改不是改了什么 3. 破坏性变更必须在 footer 写 BREAKING CHANGE ## 操作步骤 1. 先运行 git diff --staged 查看暂存区改动 2. 分析改动性质确定 type 和 scope 3. 生成提交信息展示给用户确认 4. 用户确认后再执行 git commit第三步测试。在项目里改点代码git add之后对 Claude Code 说帮我提交观察它是否按规范生成。如果没触发多半是 description 写得不够贴场景把用户可能说的原话提交commit生成提交信息都补进去。3.3 让 skill 调用脚本把重复劳动固化skill 的正文里可以指示 AI 去运行某个脚本。比如上面这个 commit-helper如果团队有更复杂的校验逻辑检查 commit message 长度、禁止某些词可以写个脚本#!/usr/bin/env bash # scripts/validate-commit.sh MSG$1 if [ ${#MSG} -gt 72 ]; then echo 提交信息过长${#MSG} 字符请压缩到 72 字符以内 exit 1 fi echo 校验通过然后在SKILL.md里加一句生成提交信息后运行scripts/validate-commit.sh校验不通过则重新生成。 这样 AI 就有了一个确定性的检查环节而不是全靠它自觉。这里的心得是能用脚本保证的确定性就别交给模型判断。模型擅长理解和生成不擅长精确的格式校验。把校验逻辑写成脚本让 AI 调用既稳又省 token。3.4 验证 skill 是否真的被加载写完 skill 后怎么确认它生效了我的做法是直接问 AI你现在有哪些可用的 skill 或者commit-helper 这个 skill 的内容是什么 如果它能复述出你写的内容说明加载成功。如果它说不知道检查三件事目录位置对不对、SKILL.md的 frontmatter 格式对不对---包裹、description 是否匹配当前对话。4. 进阶玩法让 skill 组合出超能力4.1 多个 skill 协同一个任务链的拆解单个 skill 解决单点问题但真实任务往往是链条。比如给项目加一个新 API 接口这件事可以拆成读现有接口规范 → 生成代码 → 写测试 → 更新文档 → 提交。如果每个环节都有对应 skillAI 就能串起来干。热搜里superpower skills这个词挺有意思我理解它指的就是这种组合出超能力的效果。做法是写一个编排型 skill正文里明确指示本任务需要依次调用 skill A、B、C。不过要注意skill 之间的调用目前更多是靠 AI 自己判断不是硬编码的依赖所以每个 skill 的 description 边界要清晰避免互相抢触发。4.2 把项目知识沉淀进 skill团队里最值钱的往往不是代码而是为什么这么写的隐性知识。比如我们的数据库连接池为什么设成这个值这个模块为什么不能用某个库。这些知识散落在老员工脑子里新人踩坑才能学到。skill 是沉淀这类知识的好载体。写一个project-conventionsskill把项目的架构决策、命名规范、禁用清单都写进去。新人用 AI 助手时AI 会自动带上这些背景相当于给每个新人都配了个记得所有历史决策的老员工。我实测下来这类知识型 skill的投入产出比最高。因为它不需要写脚本纯文本但每次对话都在省去重复解释的成本。4.3 Codex 场景下的 skills 对照热搜里codex skills、codex安装、codex接入deepseek这些词说明不少人在用 Codex。Codex 的 skill 机制和 Claude Code 不完全一样但思路相通都是通过配置文件或特定目录给 AI 注入任务相关的上下文和指令。如果你在 Codex 里想实现类似效果核心是找到它的指令注入点——可能是项目根目录的某个配置文件也可能是启动参数。不同版本差异较大建议以你所用版本的官方文档为准。但底层逻辑不变用结构化的文本把这个项目该怎么干活告诉 AI。4.4 用 skill 统一团队 AI 行为这是 skill 最有价值的团队场景。想象一下团队里 10 个人用 AI 助手如果没有统一规范每个人得到的代码风格、提交格式、测试写法都不一样review 时一团乱。把团队规范写成 skill放进代码仓库的.claude/skills/所有人拉下来就自动生效。AI 生成的代码天然符合团队规范review 成本大幅下降。这比写一份没人看的《开发规范文档》有效得多——因为规范是强制执行在 AI 生成环节的而不是靠人自觉遵守。5. 踩坑实录那些让我折腾半天的坑5.1 skill 死活不触发description 是重灾区我遇到的第一个坑就是skill 写好了AI 就是不用。排查了半天问题出在 description。我最初写的是用于处理部署相关任务太抽象。AI 判断部署相关的边界很模糊经常不触发。改成当用户要求部署到测试/生产环境、提到 deploy、发布、上线、staging 等词时使用之后命中率立刻上来了。教训description 要写用户会怎么说而不是这个技能是干嘛的。把用户可能用的口语、关键词都列进去。5.2 路径问题Windows 下的脚本执行在 Windows 上写了个.sh脚本skill 里让 AI 调用结果一直报错。原因是 Windows 默认没有 bash 环境或者路径分隔符不对。后来改成用 Node 脚本node scripts/xxx.js跨平台就没问题了。如果你非要用 shell 脚本Windows 下建议用 Git Bash 提供的环境或者在 skill 里明确写用bash scripts/xxx.sh调用。但最省心的还是用 Node 或 Python 写辅助脚本跨平台一致性最好。5.3 上下文被 skill 撑爆有段时间我写了个超长的 skill把整个项目的 API 文档都塞进正文。结果每次触发这个 skill上下文就被占掉一大块AI 反而变笨了——注意力被稀释回答质量下降。后来学乖了skill 正文只放操作指引大块参考资料放到reference/目录正文里写需要时读取 reference/xxx.md。这样 AI 平时不加载大文件真需要时才读上下文利用率高很多。这其实就是渐进式加载思想在 skill 内部的延伸。5.4 skill 之间互相打架当你有多个 skill且它们的 description 有重叠时AI 可能触发错误的那个。比如我同时有commit-helper和git-workflow两个都涉及 git 操作AI 经常搞混。解决办法是明确划分边界commit-helper只管生成提交信息git-workflow只管分支管理、合并、rebase。在各自的 description 里写清楚不负责 XX把职责切干净。skill 设计跟微服务设计一个道理——边界清晰比功能强大更重要。5.5 版本更新导致 skill 失效工具更新后skill 的目录位置或 frontmatter 格式可能变化。我有次升级 Claude Code 后原来的 skill 全不生效了折腾半天才发现是目录结构变了。建议升级工具后先跑一个最小 skill 验证机制是否还正常别等干活时才发现。6. 关于 skills 的一些零散经验和判断聊到这儿把一些不成体系但我觉得有用的判断分享一下。skill 不是越多越好。我见过有人一口气写几十个 skill结果 AI 触发混乱维护成本也高。我的建议是先从最高频、最痛的场景开始写三五个用顺了再扩。质量比数量重要得多。skill 的维护要跟着项目走。项目规范变了skill 要同步更新否则 AI 会按过时规范干活。最好把 skill 纳入 code review 流程改规范时一起改 skill。别指望 skill 解决所有问题。skill 擅长的是把已知的、稳定的流程固化下来。对于探索性的、一次性的任务写 skill 反而累赘。判断标准很简单这个任务你会重复做很多次吗会就值得写 skill。测试 skill 要用真实任务。别自己造个假场景测直接在真实工作里用观察 AI 的实际表现。真实任务的复杂度往往超出你的预期能暴露很多设计问题。关注 skill 的可读性。skill 是给人维护的不是一次性的。写的时候想想三个月后的我或者接手的同事能不能看懂这个 skill 在干嘛结构清晰、注释到位比写得聪明更重要。最后说个我自己的体会skills 这套机制真正改变的不是 AI 的能力上限而是AI 输出的稳定性下限。它让 AI 从偶尔惊艳、经常跑偏变成稳定可靠、符合预期。对于要把 AI 助手真正用进生产流程的团队来说这个下限的提升比上限的偶尔爆发有价值得多。