1. 从“skills”这个热词说起它到底是什么为什么突然火了如果你最近在技术社区、AI 工具群或者前端圈子里频繁看到“skills”这个词不用怀疑它说的不是传统意义上的“技能”泛称而是特指Agent Skills——一种让 AI 编程助手尤其是 Claude Code、Codex 这类 CLI/桌面端工具具备可复用、可组合、可版本管理的“能力模块”的机制。简单说以前你用 AI 写代码每次都要把背景、规范、流程重新讲一遍现在你可以把一套固定的工作流、领域知识、代码模板封装成一个SKILL.md文件AI 在需要的时候自动加载、按你的规矩干活。我第一次接触这个概念是在一个前端重构项目里。当时团队用 Claude Code 做组件迁移每个人都要反复提醒 AI“我们用的是 Vue 3 组合式 API”“样式必须走 design token”“不要用 any”。后来有人丢了一个SKILL.md到仓库根目录里面写清楚了技术栈约束、目录结构、命名规范、甚至常见错误的修复方式。从那以后AI 生成的代码一次通过率肉眼可见地上升。这就是 skills 的核心价值把“人脑里的隐性规范”变成“AI 可读取的显性资产”。它解决的问题非常具体。第一上下文重复注入。没有 skills 的时候你每次开新会话都要重新贴一遍项目说明浪费 token 也浪费注意力。第二团队协作不一致。张三让 AI 用 axios李四让 AI 用 fetch代码风格就散了。skills 相当于一份“AI 行为契约”谁用都一样。第三领域知识难以沉淀。比如数学建模、STM32 嵌入式开发、AI 漫剧脚本生成这些场景有大量非通用规则skills 可以把这些规则固化下来变成可分享、可安装的模块。适合谁来参考如果你是刚接触 Claude Code 或类似工具的新手skills 能让你少走很多弯路如果你是小团队的技术负责人skills 是统一 AI 辅助开发流程的低成本抓手如果你做数学建模、嵌入式、前端、甚至内容创作只要你的工作流里有重复性的“告诉 AI 怎么做”的环节skills 都值得花时间研究。下面我会从设计思路、核心细节、实操过程、常见问题四个层面把 skills 这件事拆透。2. 内容整体设计与思路拆解为什么是 SKILL.md而不是插件或提示词库2.1 从“提示词工程”到“技能封装”的演进逻辑早期大家用 AI 编程主流做法是写一长串 system prompt或者维护一个prompts/文件夹。但这种方式有几个硬伤提示词和代码仓库分离更新不同步提示词之间没有优先级和触发条件AI 不知道什么时候该用哪条提示词无法携带可执行脚本或模板文件。Agent Skills 的设计思路完全不同它把“技能”当成一个有边界、有入口、有依赖的模块来对待。SKILL.md是这个模块的入口文件。它通常包含元信息技能名称、描述、触发条件、指令正文AI 应该遵循的规则、以及可选的资源引用脚本、模板、示例。AI 在运行过程中会根据当前任务上下文判断是否需要加载某个 skill。这个判断过程不是关键词匹配那么简单而是基于语义理解——这也是为什么 skills 比传统提示词库更“聪明”。我自己的体会是skills 的设计哲学很像微服务。每个 skill 只负责一件事比如“生成符合 ESLint 规则的 React 组件”或“按国赛格式写数学建模论文摘要”。skill 之间可以组合也可以覆盖。这种设计让 AI 的行为变得可预测、可测试、可迭代。2.2 为什么选择 Markdown 作为载体你可能会问为什么不是 JSON、YAML 或者 Python 脚本Markdown 的优势在于对人类友好对 AI 也友好。人类可以直接阅读、编辑、review不需要额外工具AI 在解析时Markdown 的标题层级、列表、代码块天然就是结构化的。而且SKILL.md可以塞进 Git 仓库走正常的代码审查流程这对团队协作至关重要。另一个原因是低门槛。你不需要会写插件、不需要懂 AST只要会写清楚步骤和规则就能做出一个可用的 skill。我见过一个运营同学完全不懂编程但她写了一个“小红书文案生成 skill”里面规定了语气、emoji 使用频率、标签策略效果比很多工程师写的还好。这就是 Markdown 载体的普惠性。2.3 技能库的生态位和 MCP、插件、自定义指令的区别现在 Claude Code 生态里有好几个容易混淆的概念。MCP 是 Model Context Protocol解决的是 AI 如何连接外部工具和数据源的问题插件通常是 IDE 层面的扩展自定义指令是全局的、粗粒度的行为约束。Agent Skills 的生态位在它们之间比自定义指令更细粒度、更场景化比 MCP 更轻量、更偏向“知识”而非“连接”。举个例子你要让 AI 帮你操作数据库。MCP 负责让 AI 能连上数据库skill 负责告诉 AI“我们这个项目的数据库命名规范是什么、查询要加什么索引提示、哪些表不能直接删”。两者配合使用效果最好。理解这个区别你就能明白为什么 skills 不是昙花一现的热词而是 AI 辅助工作流里的一块必要拼图。3. 核心细节解析与实操要点一个高质量 SKILL.md 应该长什么样3.1 技能元信息的写法与触发条件设计一个SKILL.md的开头通常有一段元信息用来告诉 AI 这个技能是干什么的、什么时候该用。我见过很多新手写的元信息过于模糊比如“帮助写代码”这种 skill 基本不会被正确触发。好的元信息应该包含领域限定、任务类型、触发关键词。比如一个前端组件生成 skill 的元信息可以这样写--- name: react-component-generator description: 当用户需要创建新的 React 函数组件、修改现有组件结构、或询问组件文件放置位置时使用。适用于使用 TypeScript Tailwind CSS 的项目。 trigger: 创建组件、新建组件、生成 React 组件、component scaffold ---这里的关键是description要写清楚“什么时候用”而不是“这是什么”。AI 在判断是否加载 skill 时主要看的是使用场景匹配度。我实测下来把触发场景写得越具体误触发和漏触发的概率越低。3.2 指令正文的结构化写法规则、步骤、示例三件套元信息之后就是指令正文。我建议采用“规则 步骤 示例”的三段式结构。规则部分用列表写清楚硬性约束比如“必须使用函数式组件”“禁止使用 default export”“样式必须通过 className 传入”。步骤部分写清楚操作顺序比如“先创建文件再写类型定义再写组件主体最后写测试”。示例部分给出一段正确的代码和一段错误的代码让 AI 有参照。这里有个细节很多人忽略规则要写“为什么”。比如你写“禁止使用 index 作为 key”最好补一句“因为列表重排时会导致状态错乱”。AI 在理解原因后遇到边界情况时能做出更合理的判断而不是死板执行。我在数学建模 skill 里写过“摘要必须包含模型假设”并解释了“评委第一眼就看假设是否合理”之后 AI 生成的摘要质量明显更稳定。3.3 资源引用与脚本集成让 skill 不止是文字高级一点的 skill 会引用外部资源。比如一个“生成 API 文档”的 skill可以引用一个templates/api-doc.md模板文件或者一个scripts/validate-schema.py校验脚本。AI 在加载 skill 时会把这些资源一并纳入上下文。这样做的好处是skill 本身保持简洁复杂逻辑放在脚本里维护起来更方便。需要注意的是脚本集成要控制好权限和副作用。我一般只允许 skill 调用只读脚本或生成类脚本涉及删除、部署、修改线上配置的操作一定要加人工确认环节。踩过的坑是有一次写了个自动格式化脚本skill 触发后直接把整个目录的文件都改了幸好有 Git 兜底。从那以后我在 skill 里明确写“执行任何写操作前先输出将要修改的文件列表等待用户确认”。3.4 技能之间的依赖与冲突处理当项目里 skill 多了以后依赖和冲突是必然的。比如一个“代码风格” skill 说用双引号另一个“遗留代码兼容” skill 说用单引号。AI 遇到这种情况会困惑。我的做法是建立优先级标记在元信息里加一个priority字段数字越小优先级越高。同时在 skill 正文里写明“本 skill 优先级高于通用风格 skill”。另一个技巧是用命名空间隔离。比如frontend/react-component、frontend/vue-component、backend/api-design这样 AI 在加载时能根据当前文件路径和任务类型快速定位。我见过一个团队把所有 skill 平铺在一个目录里结果 AI 经常加载错误的 skill后来改成命名空间目录结构问题就解决了。4. 实操过程与核心环节实现从零搭建一个可用的 skills 工作流4.1 环境准备与工具选型Claude Code 安装与配置要点要玩 skills首先得有支持它的工具。目前最主流的是 Claude Code它有 CLI 版本和桌面版。安装方式根据操作系统不同有所差异。Windows 用户如果遇到“claude 无法识别为 cmdlet”这类报错通常是环境变量没配好或者安装路径没加入 PATH。我的建议是优先用官方推荐的安装方式安装完成后在终端执行claude --version确认。配置方面核心是找到 skills 的存放目录。Claude Code 一般会从项目根目录的.claude/skills/或者用户主目录的.claude/skills/加载 skill。项目级的 skill 适合团队共享用户级的适合个人通用。我通常把通用规范放用户级把项目特定规则放项目级这样换项目时不用重复配置。如果你用的是 VS Code可以安装 Claude Code 扩展在编辑器内直接调用。配置过程中如果遇到网络或区域相关的提示按官方文档的指引处理即可这里不展开。重点是把基础环境跑通后面的事情才顺。4.2 第一个 skill 的完整创建流程假设我们要做一个“数学建模论文摘要生成” skill。第一步在.claude/skills/下新建目录math-modeling-abstract/。第二步创建SKILL.md写入元信息和指令。第三步可选地创建templates/abstract-template.md和examples/good-abstract.md。第四步在 Claude Code 里触发测试。元信息可以这样写--- name: math-modeling-abstract description: 当用户需要撰写数学建模竞赛论文摘要、修改摘要、或询问摘要结构时使用。适用于国赛、美赛等常见格式。 trigger: 摘要、abstract、论文开头、建模摘要 priority: 10 ---指令正文我一般分四块结构要求、语言风格、常见错误、示例。结构要求写清楚“第一段写问题背景第二段写模型方法第三段写求解结果第四段写创新点”。语言风格写“避免口语化用被动语态控制在一页以内”。常见错误写“不要出现‘我们’‘我觉得’这类主观表述”。示例给出一篇获奖论文的摘要作为参考。创建完成后在 Claude Code 里输入“帮我写一个数学建模摘要题目是XXX”观察 AI 是否自动加载了这个 skill。如果没有检查元信息的触发词是否匹配或者手动用/skill math-modeling-abstract强制加载。4.3 从 GitHub 安装第三方 skills 的实操方法社区里已经有不少开源的 skills 仓库比如 typesafe-ai/skills、superpower-skills 等。安装方式通常有两种手动复制和命令行安装。手动复制就是把仓库里的 skill 目录拷贝到你的.claude/skills/下。命令行安装则看具体工具的支持情况有些提供了claude skill install repo之类的命令。我一般推荐手动复制因为可以顺便 review 一下 skill 内容避免引入不安全的指令。复制完成后重启 Claude Code 或者执行重新加载命令。测试时先用一个简单任务触发确认 skill 正常工作。如果 skill 依赖外部脚本还要检查脚本的执行权限和依赖是否齐全。这里有个坑有些 skill 是为特定版本的 Claude Code 写的元信息格式可能不兼容。遇到加载失败时先看日志输出再对照官方文档检查SKILL.md的字段名是否正确。我遇到过trigger字段写成triggers导致 skill 完全不触发的情况排查了半天。4.4 技能开发中的调试与迭代节奏写 skill 不是一蹴而就的。我的节奏是先写一个最小可用版本只包含最核心的规则然后在实际任务中测试记录 AI 哪些地方没按预期执行接着针对性地补充规则或示例最后再考虑优化元信息和资源引用。调试时有个技巧让 AI 自己解释为什么没加载某个 skill。你可以问“你为什么没有使用 math-modeling-abstract 这个 skill”AI 通常会给出它的判断依据比如“当前任务没有匹配到触发词”或“优先级被其他 skill 覆盖”。根据这个反馈调整比盲目改文件高效得多。迭代过程中要注意版本管理。我习惯给每个 skill 加一个version字段每次修改后递增。这样出问题时可以快速回滚到上一个稳定版本。团队协作时skill 的修改也要走代码审查避免有人不小心改坏了公共规范。5. 常见问题与排查技巧实录踩过的坑和对应的解法5.1 技能不触发或误触发的排查思路这是最高频的问题。表现是你明明写了 skillAI 却不用或者不该用的时候它用了。排查顺序我总结成一张表现象可能原因排查方法解决方式完全不触发元信息字段名错误检查name、description、trigger拼写对照官方文档修正完全不触发存放路径不对确认.claude/skills/层级移动到正确目录偶尔触发触发词太泛或太窄查看 AI 的判断日志调整description和trigger误触发多个 skill 描述重叠列出所有 skill 的 description增加优先级或合并 skill加载报错依赖文件缺失检查资源引用路径补全文件或移除引用我自己的经验是触发词要写“用户会说的话”而不是“技术术语”。比如用户说“帮我写个摘要”你写trigger: abstract generation就不如写trigger: 摘要、写摘要、论文摘要来得准。5.2 技能冲突与优先级混乱的处理当两个 skill 给出矛盾指令时AI 的行为会变得不稳定。比如一个 skill 说“用分号结尾”另一个说“不要用分号”。我的处理原则是能合并就合并不能合并就分层。分层的意思是通用 skill 优先级低项目特定 skill 优先级高。在元信息里用priority字段控制数字小的先加载、后覆盖。另外我建议定期清理不再使用的 skill。社区里有人分享过用tibo相关方法清理 skills 的思路核心就是定期 review 每个 skill 的触发频率和实际效果把三个月没触发过的删掉或归档。skill 不是越多越好维护成本会随数量上升。5.3 跨平台与跨工具的兼容性问题Claude Code 有 CLI、桌面版、VS Code 扩展等多种形态skills 的加载行为可能略有差异。比如桌面版可能对文件路径更敏感CLI 版对权限控制更严格。我的做法是在 skill 里避免使用绝对路径和平台特定命令尽量用相对路径和跨平台工具。如果你同时在用 Codex、OpenCode 等其他工具要注意它们的 skill 格式可能不完全一样。有些工具支持SKILL.md有些不支持。跨工具使用时最好把核心规则抽成纯文本再针对不同工具做适配层。我试过把同一个数学建模 skill 同时用在 Claude Code 和 Codex 上发现 Codex 对 Markdown 表格的解析更严格后来统一改成列表格式就兼容了。5.4 安全与权限skill 能做什么不能做什么skills 本质上是一段会被 AI 执行的指令所以安全边界必须划清楚。我的原则是skill 可以读、可以生成、可以建议但不能未经确认就删改关键文件或执行危险命令。在 skill 正文里我会明确写“执行任何写操作前必须输出变更预览”“禁止执行 rm -rf、drop table 等破坏性命令”。另外从 GitHub 安装第三方 skill 时一定要先读一遍内容。我见过有人写了个 skill里面藏了把环境变量上传到外部地址的指令。虽然大多数社区 skill 是善意的但保持警惕是必要的。团队内部可以建立一个 skill 审查清单新 skill 入库前由至少一人 review。6. 技能库的扩展玩法从个人效率到团队资产6.1 把重复工作流封装成 skill 的判断标准不是所有事情都值得做成 skill。我的判断标准有三条重复频率高、规则明确、错误成本高。比如“每次新建 API 都要写一遍参数校验”频率高、规则明确、写错了要返工就值得做 skill。反过来“偶尔写个一次性脚本”就不值得。另一个标准是是否涉及多人协作。如果只有你自己用记在脑子里也行如果团队五个人都要做同样的事skill 就是最低成本的统一方式。我见过一个团队把“代码提交信息格式”做成了 skillAI 在生成 commit message 时自动遵循规范省去了大量 review 时的格式争论。6.2 团队共享 skill 库的组织方式团队规模大了以后skill 库需要版本管理和分发机制。我们的做法是建一个独立的 Git 仓库目录结构按领域划分frontend/、backend/、data/、devops/。每个 skill 一个子目录包含SKILL.md和可选资源。仓库的 README 里写清楚每个 skill 的用途、维护人、最近更新时间。分发方式有两种一种是让成员手动 clone 到本地.claude/skills/另一种是写个同步脚本定期拉取最新版本。我们用的是后者配合 CI 检查 skill 格式是否合法。这样新人入职时一条命令就能拿到全套团队规范上手速度明显加快。6.3 技能效果评估与持续优化skill 写完不是终点。我会定期看两个指标触发次数和任务一次通过率。触发次数低说明触发词或场景描述有问题一次通过率低说明规则不够清晰或示例不够好。根据这两个指标做针对性优化。还有一个软性指标是用户反馈。我经常问团队成员“你觉得哪个 skill 最有用哪个最鸡肋”。有时候工程师觉得没用的 skill产品经理用得很顺手因为使用场景不同。收集多方反馈才能让 skill 库真正服务于整个团队而不是某个人的偏好。7. 我个人的一些实操体会写了几十个 skill 之后我最大的体会是skill 的质量取决于你对工作流的理解深度而不是你对 AI 的调教技巧。如果你自己都没想清楚一个任务的步骤和标准写出来的 skill 一定是模糊的。反过来如果你能把一个任务拆到“新人照着做也不会错”的程度skill 自然就好用。另一个体会是从小处着手。不要一上来就想做一个“全能开发助手” skill那样大概率会失败。先做一个“生成 React 组件”的小 skill跑通了、用顺了再逐步扩展。skill 库是长出来的不是设计出来的。最后分享一个实用技巧让 AI 帮你写 skill。你可以把一段工作流描述给 AI让它生成SKILL.md初稿然后你再修改。我试过用这种方式生成数学建模 skill 的初稿虽然细节需要调整但结构框架省了不少时间。AI 写 skill人 review skill这个循环本身就很 skill。