1. 从“skills”这个热词说起它到底是什么为什么突然火了最近半年不管是在开发者社区还是各种技术群里“skills”这个词出现的频率高得离谱。你随便翻翻热搜词列表就能看到skills、codex skills、claude agent skills、skills推荐、skills开发、find skills、agent skills测试……一大串。很多人第一次看到会懵这不就是“技能”的英文吗怎么就成了一个技术圈的热门话题了我一开始也以为是某个新出的技能培训课程或者认证体系后来实际用了一圈才明白这里的skills指的是一套面向 AI 编程助手比如 Claude Code、Codex 这类工具的可插拔能力扩展机制。你可以把它理解成给 AI 助手装的“技能包”——原本它只会聊天、写代码装上 skills 之后它能按照你预设的流程去执行特定任务比如自动生成项目脚手架、按团队规范做代码审查、调用本地模型、处理特定格式的文件等等。说白了skills 解决的是一个很实际的问题通用 AI 助手很强但它不懂你的项目、不懂你的规范、不懂你的工作流。你每次都要重复告诉它“我们这个项目用 FlutterGradle 插件要这样配”“代码提交前必须跑这三个检查”“日志格式必须是这个样子的”。说一次两次还行天天说谁都受不了。skills 就是把这些重复性的上下文和操作固化下来让 AI 助手一上来就知道该干什么、怎么干。这篇文章适合谁看如果你是刚接触 Claude Code 或 Codex 的新手想搞清楚 skills 到底能帮你做什么那这篇就是写给你的。如果你已经在用这些工具但每次都要手动重复一堆操作想找个办法把流程自动化那这篇也能给你一套可落地的方案。如果你只是想了解这个领域在发生什么那至少看完你能明白大家在聊的到底是什么不至于一头雾水。我下面会从整体设计思路、核心机制、实操步骤、常见坑几个角度把 skills 这件事讲透。内容基于我自己和身边几个朋友的实际使用经验加上对公开资料的整理尽量做到你照着做就能跑起来。2. skills 的整体设计与核心思路拆解2.1 为什么需要 skills通用助手的“最后一公里”问题先想一个问题为什么 Claude Code、Codex 这些工具已经这么强了还需要 skills答案其实很简单——通用能力和项目落地之间隔着一条很宽的沟。一个通用 AI 助手可以帮你写一个排序算法、解释一段报错、生成一个正则表达式这些都没问题。但当你让它“帮我把这个项目的 CI 流程跑一遍”或者“按照我们团队的规范审查这个 PR”时它就开始犯迷糊了。因为它不知道你的 CI 流程是什么不知道你们团队的规范长什么样。这就好比你请了一个很厉害的通才律师他什么法律都懂但你让他处理你公司的具体合同他还是得先花时间了解你公司的业务、你们的合同模板、你们的风控要求。skills 的作用就是提前把这些“公司特定知识”准备好让通才律师一上来就能干活。从技术角度看skills 本质上是一种结构化的上下文注入机制。它把原本散落在对话历史、系统提示、外部文档里的信息整理成一个个独立的、可复用的模块。每个模块包含这个技能是干什么的、什么时候触发、执行时需要哪些步骤、依赖哪些工具或文件。AI 助手在运行时根据当前任务匹配对应的 skill然后按照 skill 里定义的流程去执行。2.2 skills 和 plugin、agents 的关系别搞混了热搜词里同时出现了skills、plugin、agents很多人分不清这三者的关系。我刚开始也绕了一阵后来画了个简单的对应关系才理清楚。plugin插件是更底层的概念指的是对宿主程序的功能扩展。比如你在 IDE 里装一个插件它可能给你加了一个新的侧边栏、一个新的命令。plugin 关注的是“给程序加功能”。agents智能体是更上层的概念指的是一个能自主感知环境、做出决策、执行动作的 AI 实体。一个 agent 可能包含多个 skills也可能调用多个 plugin。agent 关注的是“自主完成任务”。skills则介于两者之间它更像是 agent 的“操作手册”。一个 agent 决定要做什么之后具体怎么做往往就是靠 skills 来指导的。skills 关注的是“把一件事做对”。举个具体的例子你有一个负责代码审查的 agent它需要检查代码风格、跑测试、看覆盖率、生成报告。这四件事每一件都可以写成一个 skill。agent 负责决定“现在该审查了”然后依次调用这四个 skill 来完成整个流程。所以你在配置的时候思路应该是先想清楚要解决什么任务然后把这个任务拆成几个可复用的步骤每个步骤写成一个 skill最后用一个 agent 把这些 skill 串起来。2.3 方案选型为什么是“文件约定”而不是“代码API”我研究过几种不同的 skills 实现方式有的走的是纯代码路线你得写一堆 Python 或 JavaScript 来定义技能有的走的是配置文件路线用 YAML 或 JSON 来描述。但 Claude Code 和 Codex 这类工具主推的 skills 方案走的是**“Markdown 文件 目录约定”**的路线。为什么这么设计我琢磨了一下大概有这么几个原因。第一降低门槛。写代码定义技能你得会编程、会调试、会处理依赖。写 Markdown 文件只要你会写字就行。这直接把能参与 skills 开发的人群从“程序员”扩大到了“所有会用电脑的人”。第二便于版本管理。Markdown 文件是纯文本扔进 Git 里 diff 一目了然。你改了哪句话、加了哪个步骤review 的时候看得清清楚楚。如果用代码定义一个逻辑改动可能涉及好几处review 起来就费劲了。第三天然适合 AI 理解。AI 模型本身就是用大量文本训练的它对自然语言的理解能力远强于对代码结构的理解。你用 Markdown 写一段“第一步做什么、第二步做什么”AI 读起来毫无障碍。你如果用代码写AI 还得先解析代码逻辑反而多了一层转换。第四灵活可扩展。Markdown 里可以嵌代码块、可以嵌表格、可以嵌链接。需要精确控制的时候你可以在代码块里写具体的命令需要解释说明的时候你可以用自然语言描述。这种混合表达能力是纯配置文件做不到的。当然这个方案也有代价。最大的问题是执行的一致性没法保证。你用代码定义技能输入输出都是确定的你用自然语言描述AI 每次执行可能都有细微差别。所以写 skill 的时候关键步骤一定要写得足够具体能写命令就别写描述能写参数就别写范围。3. 核心细节解析与实操要点3.1 skill 文件的基本结构一个 skill 应该包含什么一个标准的 skill 文件通常包含以下几个部分。我拿一个“生成项目脚手架”的 skill 来举例说明。元信息部分放在文件开头用 YAML front matter 的格式写。包含 skill 的名称、描述、触发条件、依赖项等。这部分是给 AI 助手读的让它知道这个 skill 是干什么的、什么时候该用。--- name: project-scaffold description: 根据项目类型生成标准化的项目脚手架 trigger: 当用户要求创建新项目或初始化项目结构时 dependencies: - node - git ---概述部分用一两段话说明这个 skill 的目标和使用场景。这部分是给人读的方便其他人理解这个 skill 的用途。前置条件列出执行这个 skill 之前需要满足的条件。比如需要安装哪些工具、需要哪些文件已经存在、需要用户提供哪些信息。执行步骤这是核心部分按顺序列出每一步要做什么。每一步尽量写清楚执行什么命令、期望什么输出、如果失败怎么办。验证方法说明怎么确认 skill 执行成功了。比如检查某个文件是否存在、运行某个命令看输出是否符合预期。注意事项列出容易出错的地方和对应的处理方式。这部分往往是经验积累的结果新手写 skill 时最容易忽略。3.2 触发机制AI 怎么知道该用哪个 skill这是很多人关心的问题我写了一堆 skillAI 怎么知道什么时候该用哪个目前主流的做法是基于描述的语义匹配。每个 skill 在元信息里都有一个description和trigger字段AI 助手在处理用户请求时会把这些描述和用户请求做语义比对找出最匹配的 skill。这里有个关键点描述写得越具体匹配越准确。如果你写“用于处理文件”那几乎所有涉及文件的操作都可能触发这个 skill容易误触发。如果你写“用于将 CSV 文件转换为 JSON 格式并校验字段类型”那匹配就精准多了。我自己的经验是写 trigger 的时候要遵循“具体动作 具体对象 具体条件”的公式。比如“当用户要求将 CSV 转换为 JSON 且需要字段校验时”就比“当用户处理数据时”好得多。另外有些工具支持显式调用就是你在对话里直接说“用 xxx skill 来做这件事”。这种方式适合你已经知道该用哪个 skill 的情况可以避免 AI 匹配错误。还有一个技巧是给 skill 起个好名字。名字本身也是匹配的依据之一。csv-to-json-validator就比># macOS 用 Homebrew brew install node20 # Ubuntu/Debian curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs # 验证 node --version npm --version第二步安装 Claude Code 本体。官方提供了 npm 包直接全局安装即可。npm install -g anthropic-ai/claude-code安装完成后运行claude --version确认安装成功。第一次运行会引导你完成登录和初始配置。第三步配置工作目录。Claude Code 默认会在当前目录下寻找 skill 文件。我建议专门建一个目录来管理 skills比如~/.claude/skills/。这样所有项目都能共享同一套 skill不用每个项目都复制一遍。mkdir -p ~/.claude/skills cd ~/.claude/skills注意不同版本的 Claude Code 对 skill 目录的约定可能不同。装完之后先跑一下claude --help看看有没有关于 skill 路径的说明。如果没有就查官方文档确认。4.2 写第一个 skill从“生成 README”开始理论说再多不如动手写一个。我们从一个最简单的 skill 开始根据项目信息自动生成 README 文件。在~/.claude/skills/下新建一个目录readme-generator然后在里面创建SKILL.md文件。--- name: readme-generator description: 根据项目结构和依赖信息生成标准化的 README 文件 trigger: 当用户要求生成或更新 README 时 dependencies: - git --- # README 生成器 ## 目标 读取当前项目的结构、依赖和 Git 信息生成一份包含项目简介、安装步骤、使用说明的 README.md 文件。 ## 前置条件 - 当前目录是一个 Git 仓库 - 存在 package.json 或 requirements.txt 等依赖描述文件 ## 执行步骤 1. 读取项目根目录下的依赖描述文件提取项目名称、版本、依赖列表。 2. 运行 git log --oneline -10 获取最近的提交记录用于生成更新日志。 3. 扫描项目目录结构识别主要源码目录和入口文件。 4. 按照标准模板生成 README.md包含以下章节 - 项目名称和一句话简介 - 安装步骤根据依赖文件类型生成对应命令 - 快速开始根据入口文件生成示例 - 目录结构说明 - 最近更新基于 Git 提交记录 5. 如果 README.md 已存在先备份为 README.md.bak 再覆盖。 ## 验证方法 - 检查 README.md 文件是否生成 - 检查文件内容是否包含所有必需章节 - 检查安装命令是否与依赖文件匹配 ## 注意事项 - 如果项目没有依赖描述文件跳过依赖相关章节并在 README 中注明 - 如果 Git 仓库没有提交记录更新日志章节写“暂无提交记录” - 生成的内容要保留原有 README 中的自定义章节如果存在写完之后在 Claude Code 里输入“帮我生成这个项目的 README”看看它能不能正确匹配到这个 skill 并执行。我第一次写的时候踩了个坑trigger 写得太宽泛写的是“当用户处理文档时”结果我让它改个注释它也去生成 README。后来改成“当用户明确要求生成或更新 README 时”就正常了。4.3 进阶写一个带参数和条件分支的 skill上面那个 skill 比较简单没有参数也没有分支。实际工作中我们经常需要根据不同的输入走不同的流程。下面这个“项目初始化”skill 就复杂一些。--- name: project-init description: 根据项目类型初始化项目结构支持 Web、CLI、Library 三种类型 trigger: 当用户要求创建新项目或初始化项目时 dependencies: - git - node --- # 项目初始化 ## 目标 根据用户指定的项目类型生成对应的目录结构和基础配置文件。 ## 参数 - project_type: 项目类型可选值为 web、cli、library - project_name: 项目名称 ## 执行步骤 1. 确认 project_type 和 project_name。如果用户没有提供主动询问。 2. 创建项目根目录 {{project_name}}进入该目录。 3. 运行 git init 初始化 Git 仓库。 4. 根据 project_type 执行不同的初始化流程 如果 project_type 是 web - 创建 src/、public/、tests/ 目录 - 生成 index.html、src/main.js、src/style.css - 生成 package.json包含 dev、build、test 三个脚本 如果 project_type 是 cli - 创建 src/、bin/、tests/ 目录 - 生成 bin/cli.js添加可执行权限 - 生成 package.jsonbin 字段指向 bin/cli.js 如果 project_type 是 library - 创建 src/、tests/、examples/ 目录 - 生成 src/index.js 作为入口 - 生成 package.jsonmain 字段指向 src/index.js 5. 生成 .gitignore 文件根据项目类型忽略对应的文件。 6. 生成 README.md包含项目名称和基本使用说明。 7. 运行 git add . git commit -m Initial commit 提交初始代码。 ## 验证方法 - 检查项目目录结构是否符合对应类型的约定 - 检查 package.json 是否存在且格式正确 - 检查 Git 仓库是否初始化成功且有初始提交 ## 注意事项 - 如果目标目录已存在且非空停止执行并提示用户 - 如果 project_type 不是三个可选值之一提示用户重新选择 - 所有生成的文件使用 UTF-8 编码这个 skill 展示了几个关键技巧参数定义、条件分支、循环处理虽然这里没体现但你可以加。写这种 skill 的时候条件分支一定要写清楚每种情况的处理方式不要让 AI 去猜。4.4 把 skill 串起来用 agent 编排多个 skill单个 skill 能做的事有限真正强大的是把多个 skill 组合起来。比如一个“代码提交前检查”的 agent可以依次调用“代码风格检查”“单元测试”“生成变更日志”三个 skill。在 Claude Code 里你可以通过一个主 skill 来编排其他 skill。主 skill 的步骤里直接写“调用 xxx skill”即可。--- name: pre-commit-check description: 提交代码前的完整检查流程 trigger: 当用户要求提交代码或运行提交前检查时 --- # 提交前检查 ## 执行步骤 1. 调用 code-style-check skill检查代码风格。 2. 如果风格检查通过调用 run-tests skill运行单元测试。 3. 如果测试通过调用 generate-changelog skill生成变更日志。 4. 汇总所有检查结果输出报告。 5. 如果所有检查都通过提示用户可以提交否则列出失败项。 ## 注意事项 - 任何一步失败都停止后续步骤直接输出失败原因 - 报告要包含每一步的执行时间和结果这种编排方式的好处是每个 skill 可以独立开发和测试组合起来又能完成复杂任务。我一般会把常用的检查项都写成独立 skill然后根据不同的场景组合成不同的 agent。5. 常见问题与排查技巧实录5.1 skill 不触发或者触发错了怎么办这是最高频的问题。你写了一个 skill结果 AI 要么不用要么用错了。排查思路如下。先检查文件位置。skill 文件必须放在工具约定的目录下而且目录结构要符合要求。Claude Code 一般要求skills/skill-name/SKILL.md这种结构。如果你直接放了一个my-skill.md在 skills 目录下它可能识别不了。再检查元信息格式。YAML front matter 的格式很严格冒号后面要有空格缩进要用空格不能用 Tab。我见过好几次因为缩进问题导致元信息解析失败的情况。然后检查描述和触发词。如果描述太宽泛会误触发如果太狭窄会不触发。建议先用一个明确的触发词测试确认能触发之后再逐步放宽。最后看日志。大多数工具都提供了调试模式可以看到 skill 匹配的过程。Claude Code 可以用claude --debug启动会输出详细的匹配日志。下面这个表格总结了几种典型情况和对应的处理方式。现象可能原因处理方式完全不触发文件位置不对检查目录结构是否符合约定完全不触发元信息格式错误用 YAML 校验工具检查 front matter偶尔触发描述太宽泛收窄 description 和 trigger触发但执行错步骤描述有歧义把关键步骤改成具体命令触发但中途停止缺少依赖或权限检查 dependencies 和文件权限5.2 执行过程中卡住或者报错skill 执行到一半卡住通常是因为某一步的命令在等待输入或者网络请求超时。排查的时候先看它卡在哪一步然后手动执行那一步的命令看是什么反应。如果是命令等待输入比如npm init会交互式询问那就在 skill 里改成npm init -y跳过询问。如果是网络超时就在 skill 里加上重试逻辑和超时设置。还有一种情况是权限不足。比如 skill 要写某个系统目录但当前用户没有权限。这种要在前置条件里写清楚让用户提前处理。我自己的经验是skill 里涉及文件操作和网络操作的步骤一定要加错误处理。文件操作要检查文件是否存在、是否有读写权限网络操作要设置超时和重试次数。这些细节写进去skill 的稳定性会高很多。5.3 多个 skill 冲突怎么办当你装了很多 skill 之后可能会出现两个 skill 都想处理同一个请求的情况。比如你有一个“生成文档”的 skill 和一个“生成 README”的 skill用户说“生成项目文档”两个都可能被触发。解决思路有这么几个。一是明确优先级在元信息里加一个priority字段数值高的优先。二是细化触发条件让每个 skill 的触发场景互不重叠。三是合并 skill如果两个 skill 经常冲突说明它们可能应该是一个 skill 的两个分支。我一般倾向于第二种和第三种。优先级机制虽然简单但容易导致“高优先级的 skill 总是抢活”的问题。细化触发条件虽然麻烦一点但长期来看更清晰。5.4 怎么调试一个复杂的 skill复杂 skill 的调试是个体力活。我的做法是分段调试先把 skill 拆成几个独立的步骤每一步单独测试确认没问题之后再串起来。具体操作是在 skill 里加一个debug参数当这个参数为真时每执行完一步就暂停输出当前状态等用户确认后再继续。这样能精确定位到是哪一步出了问题。## 调试模式 如果 debug 参数为 true - 每执行完一步输出该步骤的执行结果 - 等待用户输入 continue 后再执行下一步 - 如果某一步失败输出完整的错误信息后停止这个技巧在开发新 skill 的时候特别有用。等 skill 稳定了把 debug 参数去掉或者默认设为 false 就行。5.5 常见问题速查表问题排查方向快速解决skill 不触发文件位置、元信息格式检查目录结构和 YAML 格式触发错误 skill描述重叠细化 trigger 字段执行卡住命令等待输入加 -y 或 --yes 参数执行报错依赖缺失检查 dependencies 列表结果不符合预期步骤描述模糊改成具体命令和参数多个 skill 冲突触发条件重叠合并或细化触发条件执行速度慢步骤太多或网络慢合并步骤、加缓存修改了不该改的文件缺少前置检查加文件存在性和权限检查6. 我踩过的坑和几条实用建议写 skill 这件事说难不难说简单也不简单。我前后写了二十多个 skill踩过的坑总结下来有这么几条。第一条别一上来就写复杂的 skill。我刚开始的时候雄心勃勃想写一个“全自动项目开发”的 skill结果写了三百多行调试了两天都没跑通。后来拆成十几个小 skill每个只做一件事反而很快就跑起来了。skill 的设计哲学应该是“小而专”一个 skill 只解决一个问题组合起来解决大问题。第二条能写命令就别写描述。比如“安装项目依赖”这句话AI 可能执行npm install也可能执行yarn install还可能执行pnpm install。你如果写“运行npm install安装依赖”那就没有歧义了。skill 里涉及具体操作的步骤尽量写成可以直接复制粘贴的命令。第三条给每个 skill 写测试用例。就像写代码要写单元测试一样写 skill 也要有测试。我的做法是给每个 skill 配一个test.md文件里面列出几个典型的输入和期望的输出。每次修改 skill 之后跑一遍测试用例确认没有回归。第四条版本管理很重要。skill 文件一定要放进 Git 管理。我吃过亏有一次改了一个 skill 之后发现效果变差了想回滚却找不到之前的版本。从那以后所有 skill 都进 Git每次修改都写清楚改了什么、为什么改。第五条别忽略文档。每个 skill 除了 SKILL.md 之外我还会写一个简短的 README说明这个 skill 的用途、依赖、使用示例。这样别人包括几个月后的自己拿到这个 skill 时能快速理解它是干什么的。第六条定期清理。用了一段时间之后你会发现有些 skill 从来没用过有些 skill 已经被更好的方案替代了。定期清理这些僵尸 skill能让整个 skill 库保持清爽也能减少触发冲突的概率。最后分享一个我最近在用的技巧给 skill 加“使用统计”。在 skill 执行时往一个日志文件里追加一条记录包含时间、skill 名称、执行结果。过一段时间看看哪些 skill 用得多、哪些从来不用、哪些经常失败。这个数据对优化 skill 库特别有帮助。这个方向后续还可以继续扩展比如把 skill 和 CI/CD 流程打通让 skill 在代码提交时自动触发或者把 skill 做成可分享的包团队内部互相复用。我现在正在尝试把常用的 skill 打包成一个集合新项目直接引入就能用省去了重复配置的麻烦。