★ FEATURED ARTICLE 1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术社区还是开发者群聊里“skills”这个词出现的频率高得离谱。你随便翻翻热搜词列表就能看到claude code skills、codex skills、agent skills测试、skills开发、skills推荐、前端开发skills、superpower skills……一大串。很多人第一次看到会懵这跟“技能”有什么关系是某种新框架还是某个插件市场我一开始也以为是营销概念直到自己在几个项目里真正用起来才发现它背后是一套非常务实的东西。简单说skills 是一组可复用、可组合、可被 AI 编码助手直接调用的能力单元。你可以把它理解成给 AI 助手准备的“工具包”或者“操作手册”——每个 skill 封装了一类具体任务比如“生成一个 React 组件”“跑一次数据库迁移”“检查代码里的安全漏洞”“把一段自然语言需求转成单元测试”。当你在 Claude Code、Codex 或者别的 agent 环境里工作时这些 skills 就是 AI 真正能“动手”的抓手。那它解决了什么问题核心就一个把 AI 从“只会聊天”变成“能干活”。以前你用 AI 写代码得反复贴上下文、手动纠正格式、复制粘贴到编辑器。现在有了 skillsAI 可以直接调用你定义好的能力按你项目的规范去执行。比如你定义一个create-api-endpoint的 skill里面写清楚路由怎么写、参数怎么校验、错误怎么返回之后每次让 AI 加接口它都会按这个模板来不用你一遍遍重复。适合谁看三类人最该关注一是日常用 Claude Code 或 Codex 写代码的开发者想提升效率、减少重复沟通二是团队里的技术负责人想统一 AI 辅助编码的规范三是对 agent 开发感兴趣的人想搞清楚 skills 的底层机制和扩展方式。哪怕你只是刚装好 Claude Code 的新手理解 skills 也能让你少走很多弯路。接下来我会从设计思路、核心细节、实操过程、常见问题四个层面把 skills 这件事讲透。内容基于我自己在多个项目里的实际使用也参考了社区里高频出现的踩坑记录。不堆概念直接说怎么用、为什么这么用、哪里容易出错。2. 内容整体设计与思路拆解2.1 为什么是“skills”而不是“插件”或“工具”你可能会问这不就是插件吗Claude Code 有 pluginCodex 也有自己的扩展机制为什么还要搞一套 skills我一开始也有这个疑问后来对比用下来发现两者的定位完全不同。插件plugin通常是平台级的扩展比如你给 VS Code 装一个插件它改变的是编辑器本身的行为。而skills 是任务级的封装它不依赖特定编辑器更像是一份“可执行的说明书”。举个例子idea设置plugin中插件仓库地址这种是插件配置问题属于环境层面而codex好用的skills讨论的是“怎么让 AI 更好地完成某类编码任务”属于工作流层面。另一个关键区别是可移植性。skills 的设计初衷就是跨 agent 复用。你今天在 Claude Code 里写了一个refactor-component的 skill明天换到 Codex 或者别的 agent 环境只要接口约定一致这个 skill 还能用。插件往往绑死在一个平台上迁移成本高。这也是为什么热词里同时出现claude code skills和codex skills——大家希望一套能力两边都能跑。还有一点skills 更强调“意图”而非“实现”。一个插件可能告诉你“我提供了 20 个 API”但 skills 会告诉你“我能帮你完成代码审查输入是 diff输出是问题列表”。对 AI 来说后者更容易理解和调用。这也是claude agent skills: a first principles deep dive这类内容受欢迎的原因——大家想知道第一性原理而不是表面功能。2.2 核心架构skill 由哪几部分组成我拆过不少社区里分享的 skill也自己写过几十个总结下来一个完整的 skill 通常包含四个部分元信息metadata名称、描述、版本、适用场景。这部分决定了 AI 什么时候会想到调用它。描述写得越具体触发越准确。比如“生成 React 函数组件”就比“写代码”好得多。输入定义input schema需要哪些参数每个参数的类型、是否必填、默认值。这跟函数签名一个道理AI 靠这个知道该传什么。执行逻辑execution具体怎么做。可以是一段提示词模板也可以是一段脚本甚至是对外部工具的调用。复杂 skill 会在这里做分支判断。输出约定output contract返回什么格式成功和失败分别怎么表示。这一步很多人忽略导致 AI 拿到结果后不知道怎么处理。我见过最常见的错误就是只写执行逻辑不写输入输出约定。结果 AI 调用时要么传错参数要么拿到结果一脸懵。你可以把 skill 想象成一个函数没有签名和返回类型的函数没人敢调。2.3 方案选型自己写还是用现成的热词里skills推荐、find skills、claude 国内安装skills 官方市场这些搜索量很高说明大家最纠结的就是到底该自己写还是去市场找现成的我的建议是先找再用用不顺再改改不动再写。原因很简单skills 的质量参差不齐很多现成的 skill 描述模糊、边界不清直接拿来用反而添乱。但完全从零写又太慢容易打击积极性。具体操作上我会先看官方市场或社区推荐的 skill重点看三样东西描述是否具体、输入输出是否清晰、有没有人反馈过问题。如果这三样都过关直接拿来改参数就能用。如果描述含糊比如只写“帮助处理代码”那我宁愿自己写一个。自己写的时候也不用追求大而全一个 skill 只做一件事做精比做多重要。另外superpower skills这类词最近很火指的是一些能力特别强、能显著提升效率的 skill 组合。我的经验是不要一上来就追求“超级能力”先把三五个高频小任务封装好比如“格式化提交信息”“生成变更日志”“检查命名规范”这些用起来立竿见影信心就来了。3. 核心细节解析与实操要点3.1 skill 描述怎么写才能被准确触发这是我最想强调的一点skill 的触发准确率90% 取决于描述。你写得越模糊AI 越容易在错误的时候调用它或者该调用的时候想不起来。我踩过的坑早期写了一个 skill 叫fix-code描述是“修复代码问题”。结果 AI 几乎不用它因为“代码问题”太宽泛了AI 不知道什么时候该用。后来改成fix-typescript-type-error描述写成“当 TypeScript 编译报类型错误时根据错误信息定位并修复类型定义”触发率立刻上来了。具体怎么写我总结了一个模板当【具体场景】时使用本 skill 来【具体动作】输入是【输入内容】输出是【输出格式】。比如当用户要求为现有函数补充单元测试时使用本 skill 生成测试用例。输入是函数源码和测试框架类型输出是可直接运行的测试文件内容。这种写法有三个好处场景明确、动作具体、输入输出清晰。AI 一看就知道什么时候该调用调用后也知道怎么处理结果。还有一个技巧在描述里加入否定条件。比如“不要用于生成新函数只用于补充测试”。这能避免 AI 在边界情况下误判。很多人不写否定条件结果 skill 被滥用到不该用的地方。3.2 输入参数设计少即是多新手写 skill 容易犯的另一个错误是参数太多。我见过一个 skill 定义了十几个参数结果 AI 每次调用都要猜哪些该填、哪些留空效率反而低。我的原则是能推断的参数不要暴露能合并的参数合并必填参数不超过三个。比如一个“生成 API 接口”的 skill我只需要两个参数接口路径和请求方法。至于返回格式、错误码规范这些应该写在 skill 内部作为默认约定而不是让 AI 每次传。如果确实需要灵活配置可以用可选参数加默认值的方式。比如style参数默认是standardAI 不传就用标准风格传了minimal就用精简风格。这样既保留了灵活性又不增加日常调用的负担。还有一个细节参数命名要自解释。path比p好componentName比name好。AI 理解参数含义越容易调用越准确。别为了省几个字符用缩写得不偿失。3.3 执行逻辑的三种实现方式skill 的执行逻辑怎么实现取决于任务复杂度。我把它分成三类第一类纯提示词模板。适合格式化、转换、生成类任务。比如“把这段代码转成 TypeScript”“生成符合 Conventional Commits 的提交信息”。这类 skill 不需要外部工具就是一段精心写的提示词加上输入变量的占位符。写的时候注意把规则说清楚比如“提交信息格式为 type(scope): descriptiontype 只能是 feat/fix/docs/style/refactor/test/chore”。第二类脚本调用。适合需要执行命令、读写文件、调用 API 的任务。比如“运行测试并解析结果”“检查依赖版本”。这类 skill 要定义好脚本的入口、参数传递方式、超时处理。我一般用 shell 或 Python 写脚本然后在 skill 里声明怎么调用。注意错误处理要写清楚脚本失败时返回什么AI 该怎么应对。第三类组合调用。适合复杂流程一个 skill 内部调用多个子 skill。比如“发布新版本”可能包含“更新版本号”“生成变更日志”“打标签”“推送”四个步骤。这类 skill 的关键是定义好步骤间的依赖和失败回滚。我通常会在执行逻辑里写明如果第二步失败第一步要不要撤销。三种方式没有优劣看任务。我的经验是能用提示词解决的不要写脚本能用单个脚本解决的不要组合。每增加一层复杂度调试成本就翻倍。3.4 输出约定让 AI 知道“接下来干什么”输出约定是最容易被忽略的部分但它直接决定了 skill 能不能被顺畅地串联起来。你想想如果一个 skill 返回一堆乱七八糟的文本AI 拿到后不知道怎么解析那这个 skill 基本就废了。我的做法是强制结构化输出。简单任务用 JSON复杂任务用带标记的文本。比如一个代码审查 skill输出格式定为{ issues: [ { severity: high, line: 42, message: 未处理的空指针, suggestion: 添加空值检查 } ], summary: 发现 3 个问题其中 1 个高危 }这样 AI 拿到后可以直接提取issues数组逐条处理。如果输出是“我检查了一下发现有几个问题比如第 42 行……”这种自然语言AI 还得再做一次理解效率低且容易出错。还有一个技巧在输出里带上“下一步建议”。比如审查完代码后输出里加一个nextAction字段值是“修复高危问题”或“可以合并”。这样 AI 能自动决定后续动作形成工作流闭环。4. 实操过程与核心环节实现4.1 环境准备Claude Code 和 Codex 的安装要点在写 skill 之前得先把运行环境搭好。热词里claude code安装、codex安装、codex安装教程、claude code windows、ubuntu配置claude code这些搜索量很高说明安装环节卡住了不少人。我把自己在 Windows 和 Ubuntu 上的安装过程整理一下。Claude Code 安装官方推荐用 npm 全局安装。先确认 Node.js 版本在 18 以上然后执行npm install -g anthropic-ai/claude-code装完后运行claude命令按提示完成登录。Windows 用户如果遇到路径问题检查一下 npm 全局目录有没有加到 PATH 里。Ubuntu 上如果权限报错不要用 sudo 装改用 nvm 管理 Node 版本能避免很多麻烦。Codex 安装Codex 的安装方式取决于你用的版本。社区里codex安装包、codex下载、codex官网下载这些词很热但我要提醒一句优先从官方渠道获取第三方打包的安装包容易夹带旧版本或配置问题。安装完成后codex登录环节如果卡住先检查网络和账号权限codex无法加载组织设置这类报错通常跟账号配置有关不是安装本身的问题。VS Code 集成vscode配置claude code、claude code for vs code也是高频需求。我的建议是先在终端里把 Claude Code 跑通再装 VS Code 扩展。顺序反了容易出问题因为扩展依赖终端环境。装完扩展后在设置里把 Claude Code 的可执行文件路径配好不然扩展找不到命令。注意安装过程中如果遇到cc switch local proxy failed while handling codex endpoint /responses这类报错先别急着改配置。多数情况下是本地端口冲突或环境变量没生效重启终端再试一次往往就好了。4.2 写第一个 skill从“生成提交信息”开始我建议第一个 skill 选生成提交信息因为它足够简单又能立刻感受到效率提升。下面是完整过程。第一步确定 skill 的存放位置。Claude Code 和 Codex 通常有约定的 skills 目录一般在用户配置目录下的skills文件夹。具体路径可以查官方文档不同版本可能不一样。找不到就用find skills命令搜一下或者看skills推荐里别人分享的目录结构。第二步创建 skill 文件。我习惯用 Markdown 格式因为可读性好AI 也容易解析。文件名用generate-commit-message.md内容如下--- name: generate-commit-message description: 当用户要求生成 Git 提交信息时使用。输入是暂存区的变更内容输出是符合 Conventional Commits 规范的提交信息。 version: 1.0.0 --- ## 输入 - diff: 暂存区的代码变更内容 ## 执行逻辑 分析 diff判断变更类型feat/fix/docs/style/refactor/test/chore提取影响范围scope用一句话概括变更内容。 ## 输出格式 type(scope): description 其中 description 不超过 50 个字符使用祈使句首字母小写结尾不加句号。 ## 示例 输入新增了用户登录接口 输出feat(auth): add user login endpoint第三步测试触发。在 Claude Code 里输入“帮我生成提交信息”看它会不会调用这个 skill。如果没触发检查描述里的关键词是否匹配。我一开始写的是“生成 commit”结果 AI 没反应改成“生成 Git 提交信息”就触发了。用词要贴近日常表达别用太专业的缩写。第四步迭代优化。用几次后你会发现有些情况没覆盖比如合并提交、回滚提交。这时候在 skill 里补充规则就行。我现在的版本已经迭代到能处理revert和merge类型了。4.3 进阶组合多个 skill 完成复杂任务单个 skill 用顺了就可以尝试组合。我拿“发布新版本”这个场景举例它涉及四个步骤我拆成四个 skillbump-version读取当前版本号按语义化版本规则递增。generate-changelog根据提交记录生成变更日志。create-tag创建 Git 标签。push-release推送标签和变更日志。然后写一个releaseskill 把它们串起来--- name: release description: 当用户要求发布新版本时使用。依次执行版本递增、变更日志生成、打标签、推送。 --- ## 执行逻辑 1. 调用 bump-version获取新版本号 2. 调用 generate-changelog传入新版本号 3. 调用 create-tag传入新版本号 4. 调用 push-release 5. 如果任一步骤失败停止后续步骤并报告 ## 输出 发布结果摘要包含新版本号、变更日志链接、标签名称这里的关键是失败处理。我一开始没写失败停止结果版本号递增了但标签没打上状态不一致排查了半天。后来加上“任一步骤失败即停止”问题就没了。实操心得组合 skill 时尽量让每个子 skill 保持无状态。也就是说子 skill 不依赖上一次调用的结果所有需要的数据都通过参数传入。这样调试单个 skill 时不用管上下文效率高很多。4.4 在 Codex 里复用 Claude Code 的 skill热词里codex skills、codex接入deepseek、claude code 调用lmstudio的本地模型这些说明大家希望跨平台复用。我的经验是只要 skill 的输入输出约定一致迁移成本很低。具体做法把 skill 文件放在两个平台都能访问的目录比如项目根目录下的.skills文件夹。然后在 Claude Code 和 Codex 的配置里都指向这个目录。这样改一次两边都生效。需要注意的是不同平台对 skill 元信息的解析可能有差异。比如 Claude Code 支持 YAML front matterCodex 可能要求 JSON。我一般写两份元信息或者用脚本在同步时转换。虽然麻烦一点但比维护两套 skill 内容强。另外codex无法加载组织设置这类问题有时会影响 skill 加载。如果 skill 突然不生效了先检查账号权限和组织配置再排查 skill 本身。5. 常见问题与排查技巧实录5.1 skill 不触发怎么办这是最高频的问题。我整理了一个排查顺序按这个走基本能定位排查项检查方法常见原因描述关键词看描述里有没有用户会说的词用了太专业的术语文件位置确认在 skills 目录下放错文件夹文件格式检查 front matter 是否合法YAML 缩进错误平台缓存重启 Claude Code 或 Codex缓存没刷新权限问题看日志有没有权限报错文件不可读我遇到最多的是描述关键词不匹配。比如用户说“帮我写个提交说明”但 skill 描述里写的是“生成 commit message”AI 就匹配不上。解决办法是在描述里把常见说法都列上用“或”连接。还有一个隐蔽问题skill 名称冲突。如果你装了两个功能相似的 skillAI 可能随机选一个。这时候要么删掉一个要么在描述里写清楚区别。我一般会加一句“本 skill 专用于 X不用于 Y”。5.2 参数传递错误的典型场景参数错误通常表现为 AI 调用 skill 时传了空值、类型不对、或者少传必填项。原因主要有三个一是输入定义太模糊。比如只写input: 代码AI 不知道是传文件路径还是代码内容。改成input: 代码内容字符串就清楚了。二是默认值没设好。可选参数如果没默认值AI 可能传空。我一般给所有可选参数设默认值并在描述里写明“不传时使用默认值 X”。三是参数名有歧义。name这种词太泛AI 可能理解成文件名、函数名、变量名。改成componentName或fileName就明确了。排查时我会在 skill 里加一段日志输出把实际收到的参数打印出来。这样一眼就能看出是 AI 传错了还是 skill 解析错了。5.3 输出格式不符合预期的处理AI 拿到 skill 输出后解析失败通常是因为输出里混入了额外内容。比如你要求输出 JSON但 AI 在前面加了一句“好的结果如下”解析就挂了。解决办法有两个一是在输出约定里强调“只输出 JSON不要任何额外文字”二是在解析前做一次清洗用正则提取 JSON 部分。我一般两个都用双保险。还有一个情况是输出字段缺失。比如约定返回issues数组但 AI 返回了空对象。这时候要在 skill 里写明“如果没有问题返回空数组而不是省略字段”。AI 对“空”的理解跟人不一样得明确说。5.4 性能与稳定性注意事项skill 用多了之后我总结了几条稳定性经验单个 skill 执行时间不要超过 30 秒。太长的任务拆成多个 skill否则容易超时。避免在 skill 里做网络请求。网络不稳定会导致整个流程卡住需要网络的操作单独封装加超时和重试。skill 之间不要有隐式依赖。A skill 依赖 B skill 的输出但没在参数里体现这种设计迟早出问题。定期清理不用的 skill。装太多 skill 会拖慢 AI 的决策速度我一般保持活跃 skill 在 20 个以内。踩坑记录我曾经写了一个 skill 去调用外部 API 获取数据结果那个 API 偶尔超时导致整个编码流程中断。后来改成先检查缓存缓存没有再请求并且加了 5 秒超时和两次重试稳定性好了很多。5.5 社区高频报错速查热词里有些报错信息很具体我挑几个常见的说说your organization has disabled claude subscription access for claude code这是账号权限问题不是 skill 问题。需要联系组织管理员开通权限或者换个人账号。qt.qpa.plugin: could not find the qt platform plugin windows这跟 skill 无关是 Qt 环境变量没配好。如果你在用带 GUI 的工具检查QT_PLUGIN_PATH环境变量。you are applying flutters main gradle plugin imperativelyFlutter 项目配置问题检查settings.gradle里的插件声明方式。in order to access this application, you must install the j2se plugin versionJava 环境缺插件跟 skill 体系没关系装对应版本的 J2SE 就行。agentpoison: red-teaming llm agents via poisoning memory or knowledge ba这是安全研究话题提醒我们 skill 的输入输出要做校验防止被恶意内容污染。我一般会在 skill 里加一层输入清洗过滤掉明显的注入尝试。这些报错看起来吓人但大部分跟 skill 本身无关是环境或账号问题。排查时先确认环境正常再怀疑 skill。6. 我个人的几条实操体会写了几十个 skill、踩了无数坑之后有几个体会特别深。第一skill 的价值在于“约定”而不是“功能”。一个 skill 功能再强如果输入输出约定不清晰用起来就是灾难。反过来一个简单的 skill只要约定明确就能被稳定调用、组合、复用。我现在写 skill花在定义输入输出上的时间比写执行逻辑还多。第二不要追求大而全的 skill。我早期写过一个“全能代码助手”skill想让它处理所有编码任务结果描述怎么写都不对触发率极低。后来拆成十几个小 skill每个只做一件事反而好用。这跟微服务的思路一样小、专、可组合。第三skill 需要维护。项目规范变了、工具升级了、AI 模型更新了skill 都可能失效。我一般每个月检查一次活跃 skill跑一遍测试用例确保还能正常工作。不维护的 skill 比没有 skill 更危险因为它会给出过时的建议。第四从自己的痛点出发。别看着别人推荐什么就装什么。先观察自己日常编码中哪些操作最重复、最烦人从那里开始封装 skill。这样写出来的 skill 你才会真正用也才知道怎么改进。最后分享一个小技巧给每个 skill 加一个lastVerified字段记录最后一次验证通过的日期。这样一眼就能看出哪些 skill 可能过时了优先检查它们。这个习惯帮我避免了好几次因为 skill 过时导致的错误。
阅读完成 · 觉得有帮助？
