1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术社区还是开发者群聊里“skills”这个词出现的频率高得离谱。你如果只看字面意思可能会以为大家在聊职场技能或者某种培训课程但实际上一旦你打开任何一个跟 AI 编程助手相关的讨论串就会发现这个词指向的是一个非常具体的东西给 AI 编程助手比如 Claude Code、Codex 这类工具安装可复用的能力模块。我最早接触这个概念是在去年底当时用 Claude Code 写一个 Flutter 项目每次都要手动告诉它“帮我检查一下 Gradle 插件配置”“帮我把这个 Widget 拆成独立组件”重复到第三遍的时候我就想能不能把这些指令固化下来让它自动识别场景并执行。后来发现社区里已经有人在做类似的事情而且给它起了个名字叫 skills。简单来说skills 就是一套预定义好的指令集、脚本和资源文件的组合你把它放到 AI 编程助手能读取的目录里助手在遇到特定任务时就会自动调用对应的 skill 来完成任务。它解决的核心问题是把重复性的、有固定套路的开发操作从“每次手动描述”变成“一次定义、反复调用”。这个东西适合谁呢我觉得三类人最需要关注。第一类是每天用 AI 助手写代码的开发者尤其是前端和全栈方向因为这类工作里重复模式特别多。第二类是团队的技术负责人如果你想让团队里所有人用 AI 助手时都遵循同一套规范skills 是最直接的落地手段。第三类是对 AI 工具链感兴趣的产品经理或独立开发者理解 skills 的机制能帮你判断哪些工作流值得自动化。注意skills 这个概念在不同工具里的叫法和实现方式不完全一样。Claude Code 里叫 Agent SkillsCodex 里可能叫 plugin 或者自定义指令集但核心逻辑是相通的——都是通过结构化文件来扩展 AI 助手的能力边界。2. 核心机制拆解skills 到底是怎么工作的2.1 一个 skill 的解剖结构我拆过好几个社区里流传的 skill 包也自己写过几个发现它们的结构其实非常统一。一个标准的 skill 通常包含三个部分元数据文件一般是一个 Markdown 或者 YAML 文件里面写清楚这个 skill 叫什么名字、什么场景下触发、需要哪些前置条件。这个文件的作用是让 AI 助手知道“什么时候该用我”。指令正文这是核心部分用自然语言描述具体要执行的操作步骤。写得好的指令会包含判断分支、参数说明和异常处理逻辑。辅助资源可能是一些脚本文件、模板文件或者参考文档。比如一个用来生成 React 组件的 skill可能会附带一个组件模板文件。我拿一个实际例子来说明。假设你要写一个“自动检查并修复 ESLint 错误”的 skill元数据部分大概长这样name: fix-eslint-errors description: 当项目中出现 ESLint 报错时自动触发分析错误并尝试修复 trigger: 检测到 eslint 错误输出或用户提到 lint 问题指令正文则会写清楚先运行npx eslint --format json获取结构化错误列表然后按错误类型分类对于no-unused-vars这类简单问题直接删除或注释变量对于react-hooks/exhaustive-deps这类需要判断的问题则给出修改建议而不是直接改。2.2 触发机制AI 怎么知道该用哪个 skill这是很多人第一次接触 skills 时最困惑的地方。我一开始也以为需要手动指定“用某某 skill”但实际上主流工具都是基于语义匹配自动触发的。具体来说当你向 AI 助手发送一条消息时工具会先把你的消息和所有已安装 skill 的元数据描述做一次语义相似度计算。如果某个 skill 的描述和你的意图匹配度超过阈值助手就会自动加载那个 skill 的完整指令正文然后按照里面的步骤来执行。这个机制的好处是使用起来很自然你不需要记住每个 skill 的名字。但坏处也很明显如果两个 skill 的描述写得太像或者你的表述比较模糊就可能触发错误的 skill。我遇到过最离谱的一次是我让助手“帮我整理一下项目结构”结果它触发了一个“整理代码格式”的 skill把整个项目的缩进全改了。实操心得写 skill 描述的时候一定要把“不适用场景”也写清楚。比如在描述末尾加一句“本 skill 仅适用于 XXX不适用于 YYY”能大幅降低误触发概率。2.3 与 plugin、agents 的关系和区别热词里同时出现了 skills、plugin、agents 这几个词很多人搞不清楚它们之间的关系。我用自己的理解打个比方Agent像是一个完整的员工有自己的人设、记忆和决策能力。Plugin像是给这个员工配的工具箱里面装的是外部工具和 API 连接能力。Skill像是员工脑子里的操作手册告诉他遇到什么情况该按什么步骤做。在实际使用中这三者是配合工作的。一个 Agent 可以加载多个 Plugin 来获得外部能力同时调用多个 Skill 来执行具体任务。比如一个“前端开发 Agent”可能加载了“浏览器预览 Plugin”和“组件生成 Skill”“样式检查 Skill”“路由配置 Skill”。理解这个分层很重要因为很多人在配置的时候会把该写成 Skill 的东西写成了 Plugin结果发现根本没法用。判断标准很简单如果这个能力不需要调用外部服务只是一套操作流程那就写成 Skill如果需要连接数据库、调用 API、操作文件系统之外的东西那才需要 Plugin。3. 实操从零开始写一个能用的 skill3.1 环境准备与目录结构不同工具对 skill 的存放位置要求不一样。Claude Code 默认会读取项目根目录下的.claude/skills/文件夹Codex 则可能读取.codex/skills/或者用户主目录下的配置文件夹。我建议你先确认自己用的工具版本和文档然后按以下结构组织项目根目录/ .claude/ skills/ my-first-skill/ skill.md # 元数据 指令正文 templates/ # 可选模板文件 scripts/ # 可选辅助脚本如果你想让 skill 在所有项目里都能用可以放到用户主目录下比如~/.claude/skills/。但要注意全局 skill 的触发优先级通常低于项目级 skill这是为了避免全局配置覆盖项目特定需求。3.2 写一个“自动生成 API 请求函数”的 skill我拿一个真实场景来演示前端项目里经常需要根据后端接口文档生成对应的请求函数。这个工作重复性高、格式固定非常适合做成 skill。第一步创建目录和元数据文件mkdir -p .claude/skills/gen-api-fn然后创建skill.md先写元数据部分--- name: gen-api-fn description: 根据接口描述生成 TypeScript API 请求函数适用于 RESTful 接口。不适用于 GraphQL 或 WebSocket 场景。 trigger: 用户提供接口路径、方法、参数和返回类型时触发 ---第二步写指令正文。这部分要用清晰的步骤描述并且考虑到各种边界情况## 执行步骤 1. 从用户消息中提取以下信息 - 接口路径如 /api/user/list - HTTP 方法GET/POST/PUT/DELETE - 请求参数类型query/body/path - 返回数据类型 2. 如果信息不完整先向用户询问缺失部分不要猜测。 3. 在 src/api/ 目录下创建或追加到对应的模块文件。 4. 生成的函数必须包含 - 完整的 TypeScript 类型标注 - 错误处理try-catch 包裹 - 请求取消支持AbortController - JSDoc 注释 5. 生成后运行 tsc --noEmit 检查类型错误。第三步实际测试。我在一个真实项目里试了这个 skill输入“帮我生成一个获取用户列表的接口函数GET /api/users返回 User[]支持分页参数 page 和 pageSize”助手自动生成了以下代码/** * 获取用户列表 * param params 分页参数 * returns 用户数组 */ export async function fetchUserList( params: { page: number; pageSize: number }, signal?: AbortSignal ): PromiseUser[] { try { const query new URLSearchParams({ page: String(params.page), pageSize: String(params.pageSize), }); const response await fetch(/api/users?${query}, { signal }); if (!response.ok) { throw new Error(请求失败: ${response.status}); } return await response.json(); } catch (error) { console.error(fetchUserList error:, error); throw error; } }生成结果基本符合预期唯一的问题是它没有自动处理User类型的导入这需要我在指令里补充一句“如果返回类型是自定义类型自动添加 import 语句”。3.3 参数计算与阈值设定写 skill 的时候经常需要设定一些数值阈值比如“文件超过多少行就拆分”“函数超过多少个参数就建议重构”。这些数值不能拍脑袋定我一般参考社区共识和实际项目经验场景建议阈值依据单个函数行数50 行超过后可读性明显下降函数参数个数4 个超过后建议用对象传参单个文件行数300 行超过后建议拆分模块嵌套层级3 层超过后建议提取函数这些数值写进 skill 的指令里助手在执行时就会按照这个标准来判断。当然你可以根据自己的项目规范调整关键是阈值要明确写出来不能含糊地说“太长了就拆分”。4. 常见问题与排查技巧实录4.1 skill 不触发或者触发错误这是最高频的问题。我整理了一个排查清单按顺序检查基本都能定位到原因现象可能原因解决方法完全不触发skill 目录位置不对确认工具文档要求的路径检查大小写偶尔触发描述太模糊在 description 里加入更具体的关键词触发错误的 skill多个 skill 描述重叠给每个 skill 加上“不适用”说明触发后不执行指令正文格式错误检查 YAML 头部是否正确闭合执行到一半停止指令步骤有歧义把每一步拆得更细避免“然后处理一下”这种表述我踩过最坑的一次是 skill 文件编码问题。当时用 Windows 记事本编辑了一个 skill 文件保存后 AI 助手死活读不出来后来发现是 BOM 头导致的。建议统一用 UTF-8 无 BOM 格式保存编辑器用 VS Code 或者 Cursor 这类对编码处理比较规范的工具。4.2 多个 skill 之间的冲突处理当项目里 skill 数量超过十个之后冲突几乎不可避免。我遇到过两个 skill 都声称自己处理“代码格式化”结果每次保存文件时两个都触发一个要求用 2 空格缩进一个要求用 4 空格最后代码被改得乱七八糟。解决思路有三个层次。最粗暴的是直接删掉不常用的那个。稍微好一点的是在元数据里加优先级字段让工具按优先级选择。最彻底的是重新设计 skill 的职责边界确保每个 skill 只负责一个明确的、不重叠的场景。我现在写 skill 之前会先画一张职责矩阵表横轴是操作类型生成/修改/检查/删除纵轴是对象类型组件/函数/样式/配置每个格子最多放一个 skill。这样从设计层面就避免了冲突。4.3 性能与上下文长度问题skill 的指令正文会占用 AI 助手的上下文窗口。如果你装了二十个 skill每个平均 500 字那就是一万字的额外上下文会明显影响助手的响应速度和回答质量。我的做法是分层管理核心 skill每天用十次以上的保持精简控制在 300 字以内边缘 skill偶尔用的可以写详细一些但用完就临时禁用。另外很多工具支持“按需加载”也就是只在触发时才加载完整指令这个特性一定要开启。提示定期清理不再使用的 skill。我每个月会 review 一次 skill 列表把过去一个月没触发过的直接归档保持活跃 skill 数量在 8 个以内。5. 进阶玩法把 skills 组合成工作流5.1 串联多个 skill 完成复杂任务单个 skill 能做的事情有限但把多个 skill 串联起来就能完成相当复杂的工作流。我举一个实际例子从接口文档到前端页面完整生成。这个工作流包含四个 skill第一个负责解析接口文档并提取数据结构第二个根据数据结构生成 TypeScript 类型定义第三个生成 API 请求函数第四个根据类型和接口生成基础的列表页面组件。每个 skill 的输出是下一个 skill 的输入形成一条流水线。实现方式是在每个 skill 的指令末尾加上“完成后自动触发下一个 skill”的说明或者在项目里配置一个 orchestrator skill 来统一调度。我试过两种方式对于固定流程用 orchestrator 更稳定对于需要人工判断的分支用链式触发更灵活。5.2 团队协作中的 skill 管理如果你在团队里推广 skills最大的挑战不是技术问题而是版本管理和规范统一。我建议把 skill 目录纳入 Git 管理并且制定几条简单规则每个 skill 必须有明确的 owner负责审核和更新skill 的修改必须走 Pull Request至少一人 review每月第一个周五做一次 skill 清理和优化新 skill 上线前必须在至少两个真实项目里验证过我们团队按这个规则跑了三个月skill 数量从最初的 3 个增长到 15 个但活跃使用的始终保持在 10 个左右没有出现失控的情况。5.3 从社区获取现成 skill 的注意事项现在社区里流传的 skill 包越来越多直接拿来用确实能省不少时间但有几个坑我必须提醒。第一安全审查。skill 的指令正文本质上是一段会被 AI 执行的代码如果里面包含恶意指令比如“删除所有 node_modules 以外的文件”后果可能很严重。拿到任何第三方 skill先通读一遍指令正文确认没有危险操作。第二版本兼容。不同工具版本对 skill 格式的支持程度不一样有些 skill 在 Claude Code 里能用换到 Codex 就可能报错。用之前先看 skill 的兼容性说明。第三过度依赖。我见过一些开发者装了上百个 skill结果 AI 助手每次响应都要花好几秒来匹配体验反而变差了。skill 的价值在于精准不在于数量。6. 我个人的一些实践体会写了这么多 skill也用了大半年我最大的感受是skill 的质量取决于你对任务本身的理解深度而不是你对 AI 工具的熟悉程度。一个连你自己都说不清楚的操作流程写成 skill 之后 AI 也执行不好。反过来如果你能把一个任务拆解到每一步都清晰无歧义那 skill 的效果会好得出乎意料。另外我建议刚开始不要贪多。选一个你每天都要重复做三次以上的操作把它写成 skill用一周时间观察效果根据实际触发情况调整描述和指令。等这一个跑顺了再写第二个。我见过太多人一次性写了十几个 skill结果没有一个真正用起来的。最后分享一个小技巧在 skill 的指令正文最后加一句“执行完成后用一句话总结你做了什么”这样每次触发你都能快速确认它有没有按预期工作排查问题的时候特别有用。