1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题很多人会懵——这词太泛了。但结合热搜词里的 Claude Code、Codex、plugin、agents 这些关键词方向就很清楚了这里说的 skills指的是 AI 编程助手尤其是 Claude Code 和 Codex 这类终端 Agent 工具的技能扩展机制。简单说就是给 AI 助手装插件包让它从能聊天变成能干活。我最早接触这个概念是在折腾 Claude Code 的时候。当时默认的 Claude Code 已经能读写文件、跑命令但遇到特定任务——比如按团队规范生成代码、调用某个内部 API、执行一套固定的部署流程——它每次都要我重新解释一遍。后来发现 skills 机制就是解决这个问题的把一套可复用的指令、脚本、资源打包成一个 skillAI 在需要时自动加载。这跟传统 IDE 的插件思路类似但载体是自然语言加脚本而不是编译好的二进制。为什么 skills 值得单独拿出来讲因为它改变了 AI 助手的使用范式。没有 skills 的时候你面对的是一个通用助手能力上限取决于模型本身有了 skills你可以把领域知识、团队规范、私有工具链注入进去让它变成你的专属助手。这个差别在实际项目里非常明显——我做过一个对比同一个重构任务裸用 Claude Code 花了 20 分钟反复沟通配好 skill 之后 3 分钟一次过。这篇文章面向三类人一是刚装上 Claude Code 或 Codex、还在摸索怎么让它更好用的新手二是想给团队搭建统一 AI 工作流的技术负责人三是好奇 skills 底层机制、想自己开发 skill 的进阶用户。我会从概念、安装、配置、开发、排错几个层面展开尽量把踩过的坑都写出来。需要先说明一点skills 这个概念在不同工具里叫法不完全一样。Claude Code 里叫 skillsCodex 里也有类似的扩展机制社区里还有 agents、plugins 等相近说法。本文以 Claude Code 的 skills 为主线因为它的机制最成熟、文档最全其他工具的对应功能我会在相关章节做对比说明。2. Claude Code 的 skills 机制拆解2.1 skill 的本质一个带元数据的文件夹很多人以为 skill 是什么高深的东西其实拆开看非常简单。一个 skill 就是一个文件夹里面至少有一个SKILL.md文件这个文件用 YAML frontmatter 声明元数据用 Markdown 正文写指令。结构大概长这样my-skill/ ├── SKILL.md # 必需技能定义 ├── scripts/ # 可选辅助脚本 │ └── deploy.sh ├── references/ # 可选参考文档 │ └── api-spec.md └── assets/ # 可选模板资源 └── template.pySKILL.md的头部大概是这样--- name: api-codegen description: 根据 OpenAPI 规范生成 TypeScript 客户端代码遵循团队命名约定 --- # API 代码生成技能 当用户要求生成 API 客户端时按以下步骤操作 1. 读取项目根目录的 openapi.yaml 2. 运行 scripts/gen.sh 生成代码 3. 按 references/naming.md 的约定重命名 ...关键点在于description字段。Claude Code 启动时会扫描所有已安装 skill 的 description把它们拼进系统提示词。当你的请求和某个 description 语义匹配时模型会主动加载那个 skill 的完整内容。这就是所谓的渐进式披露——平时只加载摘要用到时才读全文避免上下文爆炸。2.2 为什么是 Markdown 而不是代码这是 skills 设计里最聪明的地方。传统插件要用特定语言写、要编译、要处理版本兼容。skills 用 Markdown 写指令本质上是给 AI 看的文档。这意味着零编译改完直接生效不用重启零语言门槛会写文档就能写 skill可组合skill 之间可以互相引用可读性强出问题直接看文件不用调试我一开始觉得这太软了不够工程化。但用久了发现AI 助手的核心能力本来就是理解自然语言用自然语言给它下指令是最自然的。硬要用代码去描述当用户说 X 时做 Y反而绕远了。2.3 skill 和 plugin、agent 的区别热搜词里 plugin、agents 和 skills 经常一起出现容易混。我按自己的理解理一下概念载体作用范围典型场景skillMarkdown 文件夹单次任务的能力扩展生成代码、执行流程plugin代码包工具级功能扩展接入新工具、新命令agent独立进程/配置自主完成多步任务长任务、并行任务简单类比skill 是技能手册plugin 是新工具agent 是实习生。skill 告诉 AI 怎么做某件事plugin 给 AI 一把新工具agent 是让 AI 自己规划着做一整套事。三者可以叠加使用——一个 agent 可以调用多个 skillskill 里可以调用 plugin 提供的工具。2.4 官方市场和本地安装的取舍Claude Code 有官方 skill 市场社区也有一堆第三方 skill 仓库。我的建议是核心流程用官方或自己写的尝鲜用社区的。原因很简单skill 本质上是给 AI 下指令第三方 skill 的指令质量参差不齐有的会覆盖你的项目规范有的会引入不必要的步骤。我踩过一次坑装了个社区很火的全栈开发skill结果它默认用 Jest 做测试而我项目用的是 Vitest每次生成测试都要手动改。后来我把那个 skill 的SKILL.md打开删掉测试相关段落改成引用项目自己的测试规范问题就解决了。所以第三方 skill 不是不能用而是要审一遍再装。3. 安装与配置从零跑通第一个 skill3.1 环境准备里最容易忽略的两件事安装 Claude Code 本身不复杂官方文档写得很清楚。但有两个细节新手经常卡住第一Node 版本。Claude Code 对 Node 版本有要求太老的版本会报奇怪的错。我建议直接用 nvm 装最新的 LTSnvm install --lts nvm use --lts node -v # 确认版本第二终端编码。在 Windows 上如果终端不是 UTF-8skill 里的中文描述会乱码导致匹配失败。PowerShell 里执行[Console]::OutputEncoding [System.Text.Encoding]::UTF8或者在 Windows Terminal 的设置里把默认编码改成 UTF-8。这个坑我调了半天才定位到因为报错信息完全不提编码。3.2 skill 的存放位置与加载顺序Claude Code 会从几个位置扫描 skill优先级从高到低项目根目录的.claude/skills/—— 项目级只对当前项目生效用户目录的~/.claude/skills/—— 用户级对所有项目生效官方市场安装的 —— 全局但优先级最低这个顺序很重要。如果你在项目里放了一个和用户级同名的 skill项目级的会覆盖用户级的。我利用这个特性做了一件事把通用的代码规范放在用户级把项目特有的规范放在项目级同名覆盖切换项目时自动切换规范。安装一个 skill 最直接的方式就是手动放文件夹# 项目级 mkdir -p .claude/skills/my-skill vim .claude/skills/my-skill/SKILL.md # 用户级 mkdir -p ~/.claude/skills/my-skill放好之后不用重启Claude Code 下次启动时会自动扫描。如果没生效检查一下文件夹名和name字段是否一致——不一致会导致加载失败而且不报错只是静默忽略。3.3 验证 skill 是否被正确加载装完 skill 第一件事是验证。Claude Code 里有个命令可以列出当前加载的所有 skill/skills如果列表里没有你的 skill按这个顺序排查文件夹路径对不对.claude/skills/不是.claude/skill/SKILL.md文件名大小写对不对必须全大写frontmatter 格式对不对---开头结尾YAML 语法正确description字段有没有写没写 description 的 skill 不会被匹配我遇到过一次 skill 死活不加载最后发现是SKILL.md里 frontmatter 的---后面多了一个空格YAML 解析失败。这种问题没有报错只能靠肉眼检查。3.4 让 skill 真正被触发的技巧skill 加载了不等于会被触发。触发靠的是 description 和用户请求的语义匹配。这里有几个实操技巧description 要写什么时候用不是这是什么。对比一下差description: 一个代码生成工具好description: 当用户要求根据 API 规范生成客户端代码、或提到 openapi/swagger 时使用后者明确写了触发场景匹配率高很多。description 里放关键词。模型匹配时对关键词敏感。如果你的 skill 和部署相关description 里就要出现部署deploy发布这些词。避免 description 太泛。我见过一个 skill 的 description 是帮助处理各种编程任务结果它几乎每次都被触发把其他 skill 都挤掉了。description 越具体触发越精准。4. 自己写一个 skill从需求到落地4.1 先想清楚什么任务值得做成 skill不是所有事都值得做成 skill。我的判断标准是三条重复性高一周至少用一次步骤固定每次流程基本一样有领域知识需要项目特有的规范或私有工具举个例子生成 React 组件值得做成 skill因为团队有固定的目录结构、命名规范、样式方案。解释这段代码不值得因为每次情况都不一样直接问就行。我给自己项目做的第一个 skill 是新增 API 端点。流程固定在routes/下建文件、在index.ts注册、写对应的测试、更新 API 文档。以前每次都要跟 AI 解释一遍做成 skill 后一句话搞定。4.2 SKILL.md 的结构设计一个高质量的SKILL.md通常包含这几块--- name: add-api-endpoint description: 当用户要求新增 API 端点、添加路由、或提到 routes 目录时使用 --- # 新增 API 端点 ## 前置检查 - 确认项目使用 Express TypeScript - 确认 routes 目录存在 ## 执行步骤 1. 在 src/routes/ 下创建 name.route.ts 2. 按 references/route-template.md 的模板填充 3. 在 src/routes/index.ts 注册路由 4. 在 tests/routes/name.test.ts 创建测试 5. 更新 docs/api.md ## 命名约定 - 文件名用 kebab-case - 路由路径用复数形式 - 测试文件与被测文件同名 ## 常见错误 - 忘记在 index.ts 注册导致 404 - 测试没 mock 数据库导致 CI 失败注意常见错误这一节。这是 skill 里最有价值的部分因为它把踩过的坑固化下来了。AI 读到这节就会主动避开这些错误。4.3 用脚本增强 skill 的能力纯 Markdown 的 skill 只能指导AI不能执行具体操作。要执行操作得配合脚本。比如上面那个 skill我可以加一个scripts/scaffold.sh#!/bin/bash # 用法: ./scaffold.sh endpoint-name NAME$1 mkdir -p src/routes tests/routes cat src/routes/${NAME}.route.ts EOF import { Router } from express; const router Router(); // TODO: 实现 ${NAME} 路由 export default router; EOF echo 已创建 src/routes/${NAME}.route.ts然后在SKILL.md里写运行scripts/scaffold.sh name创建骨架。这样 AI 就不用一步步手动建文件直接调脚本又快又不容易出错。脚本要注意两点一是加执行权限chmod x二是路径用相对路径因为 skill 被调用时工作目录可能变。4.4 测试 skill 是否按预期工作写完 skill 一定要测。测试方法是构造几个典型请求看 AI 是否触发正确的 skill、是否按步骤执行。我一般测三类正向测试明确提到 skill 相关关键词应该触发边界测试语义相近但不该触发的请求不应该触发异常测试前置条件不满足时比如文件不存在skill 是否优雅处理我测过一个 skill正向测试全过但边界测试发现它对删除 API 端点也会触发因为 description 里写了API 端点这个宽泛词。后来改成新增 API 端点才解决。5. 踩坑实录那些文档不会告诉你的问题5.1 skill 冲突两个 skill 抢同一个任务最常见的问题是两个 skill 的 description 语义重叠导致 AI 随机选一个行为不稳定。我遇到过代码审查和代码质量检查两个 skill功能高度重合每次触发哪个全看运气。解决办法有两个一是合并成一个 skill二是把 description 写得更精确划清边界。我选了后者把代码审查限定为审查 PR 变更把代码质量检查限定为检查整个文件的规范问题冲突就消失了。5.2 上下文爆炸skill 太多导致响应变慢每个 skill 的 description 都会进系统提示词。装了几十个 skill 之后光 description 就占了几千 token导致每次对话的上下文被挤占响应变慢甚至触发模型的上下文限制。我的做法是按项目精简。用户级只放 3-5 个真正通用的 skill项目级放项目特有的。不用的 skill 及时删掉或移到备份目录。实测下来把 skill 从 30 个减到 8 个响应速度明显提升。5.3 路径问题skill 里的相对路径失效skill 里的脚本如果用相对路径在不同工作目录下调用会失败。我踩过一次脚本里写./scripts/gen.sh在项目根目录调用没问题但在子目录调用就找不到文件。解决办法是用$CLAUDE_SKILL_DIR环境变量Claude Code 会注入或者用绝对路径。更稳妥的做法是在SKILL.md里明确写在项目根目录执行让 AI 先cd再执行。5.4 权限问题脚本没有执行权限从 Git 拉下来的 skill脚本的执行权限可能丢失。表现是 AI 调用脚本时报Permission denied。修复很简单chmod x .claude/skills/*/scripts/*.sh但要在团队里避免这个问题最好在仓库里加个postinstall钩子自动加权限或者在SKILL.md里写如果脚本无执行权限先 chmod。5.5 中文乱码description 匹配失败前面提过编码问题这里再强调一次。如果SKILL.md是 GBK 编码中文 description 会乱码导致匹配失败。统一用 UTF-8并且在编辑器里确认保存编码。VS Code 右下角可以看到当前编码点一下就能改。6. 进阶玩法把 skills 用出花来6.1 用 skill 固化团队规范这是 skills 最有价值的用法。团队里每个人对规范的理解不一样新人尤其容易跑偏。把规范写成 skillAI 生成代码时自动遵守比写文档有效得多。我帮一个团队做过这件事把他们的代码规范、目录结构、命名约定、测试要求全部写成 skill放在项目仓库的.claude/skills/里。新人 clone 下来Claude Code 自动加载生成的代码直接符合规范。他们的 code review 时间缩短了大概 40%。6.2 skill 链让多个 skill 协同工作skill 之间可以互相引用。比如一个发布新版本的 skill可以依次调用更新 changelog打 tag构建产物推送几个子 skill。这样复杂流程被拆成小块每块独立维护组合起来完成大任务。实现方式是在SKILL.md里写依次执行 skill A、skill B、skill C。AI 会按顺序加载和执行。注意子 skill 的 description 要写清楚否则 AI 可能找不到。6.3 跨工具复用Claude Code 和 Codex 的 skill 互通Claude Code 和 Codex 的 skill 格式不完全一样但核心思路相同。我做过一次迁移把 Claude Code 的 skill 稍作调整放到 Codex 的对应目录大部分能直接用。主要差异在 frontmatter 字段名和触发机制上。如果你同时用两个工具建议把 skill 内容Markdown 正文和元数据frontmatter分开维护用脚本生成两个工具各自的格式。这样改一次内容两边都更新。6.4 用 skill 做本地模型适配热搜词里有claude code 调用 lmstudio 的本地模型这其实和 skill 关系不大但可以结合。本地模型的能力通常弱于云端模型对指令的理解没那么精准。这时候 skill 要写得更啰嗦——把每一步都拆细把可能的歧义都排除。我试过用本地模型跑同一个 skill把步骤从 5 步拆到 12 步之后成功率从 60% 提到了 90%。7. 排查 skill 不生效的完整链路skill 不生效是最让人抓狂的问题因为往往没有报错。我整理了一套排查流程按顺序走基本能定位第一步确认 skill 被加载。运行/skills看列表里有没有。没有的话检查路径、文件名、frontmatter 格式。第二步确认 description 被读取。如果列表里有但触发不了多半是 description 的问题。把 description 临时改成一个非常具体的关键词测试能否触发。第三步确认触发条件。构造一个明确包含 description 关键词的请求看是否触发。如果明确请求都不触发说明 description 写得太泛或太窄。第四步确认执行过程。触发了但没按步骤走说明SKILL.md正文的指令不够清晰。检查步骤是否有歧义、是否有前置条件没写。第五步确认脚本执行。步骤走了但脚本报错检查路径、权限、依赖。在终端手动跑一遍脚本看是否正常。第六步确认上下文。如果 skill 之前能用突然不能用了可能是上下文被其他 skill 挤占。临时禁用其他 skill 测试。这套流程我用了很多次基本能在 10 分钟内定位问题。关键是要一步步排除不要跳步。8. 一些零散但有用的经验关于 skill 的命名我建议用动词开头比如add-api-endpoint、generate-client、deploy-staging。这样 description 和 name 语义一致匹配更准。关于 skill 的粒度我的经验是一个 skill 做一件事。我见过一个全栈开发skill包含建表、写 API、写前端、写测试、部署结果每次触发都执行一大堆不相关的步骤。拆成 5 个独立 skill 之后按需触发效率高多了。关于 skill 的版本管理建议和项目代码一起进 Git。这样团队共享改动能追溯。用户级的 skill 可以单独建个仓库管理用软链接连到~/.claude/skills/。关于 skill 的调试可以在SKILL.md里临时加一行echo skill triggered之类的标记确认是否真的被加载。调试完删掉。关于 skill 的安全性第三方 skill 要审。skill 里的脚本会以你的权限执行恶意脚本能干任何事。装之前至少把scripts/目录看一遍。关于 skill 的性能脚本尽量轻量。我见过一个 skill 每次触发都跑npm install慢得要命。能缓存的就缓存能跳过的就跳过。最后说一个我自己的习惯每做完一个重复性任务就问自己这个值不值得做成 skill。如果答案是肯定的当场就写。拖久了就忘了下次又要重新解释一遍。skills 的价值在于积累用得越久你的 AI 助手就越懂你。