★ FEATURED ARTICLE 1. 从skills这个模糊词说起它到底指什么第一次看到skills这个词作为项目标题说实话我是有点懵的。这个词太泛了泛到放在任何语境下都能说得通——招聘网站上的技能标签叫skills游戏里的技能树叫skills而最近技术圈里反复被提起的skills指的其实是Agent Skills也就是围绕Claude Code、Codex这类AI编程代理构建的一套可复用能力模块体系。我接触这套东西的契机很偶然。当时我在做一个前端项目需要反复让AI帮我处理组件拆分、样式规范检查、接口类型对齐这几件事。每次开新会话我都得把同样的规则重新讲一遍讲得我自己都烦了。后来有人跟我说你为什么不把这些规则写成一个skill我才开始认真研究这套机制。简单来说Agent Skills的核心逻辑是把你希望AI怎么干活这件事从每次对话里的口头交代变成一份结构化的、可被AI自动识别和加载的文件。这个文件通常叫SKILL.md放在特定的目录结构下AI在需要的时候会自己去读它然后按照里面写的流程和规范来执行任务。它解决的是什么问题解决的是重复交代、标准漂移、上下文浪费这三个痛点。你不需要每次都告诉AI我们团队用TypeScript严格模式组件必须拆到200行以内样式用CSS Modules不用styled-components这些写进skill里AI自己会看。你也不需要担心这次会话里AI记得规范、下次会话就忘了因为skill是持久化的文件不依赖对话上下文。适合谁来学我觉得三类人最该关注一是日常高频使用Claude Code或类似AI编程工具的开发者二是需要团队协作、希望统一AI输出标准的技术负责人三是做数学建模、内容创作等需要AI按固定套路输出的人。哪怕你只是偶尔用AI写写脚本学会写一个简单的skill也能省下大量重复沟通的时间。接下来我会从skill的文件结构、编写方法、安装配置、实战案例、常见坑这几个角度把这件事讲透。2. SKILL.md的文件结构为什么这样设计2.1 一个skill的最小组成单元先看一个最简的skill长什么样。假设我要做一个前端组件代码审查的skill目录结构大概是这样skills/ frontend-review/ SKILL.md references/ style-guide.md component-checklist.md核心就是那个SKILL.md。它的内容通常包含几个部分元信息name、description、触发条件、执行步骤、输出格式、参考文件索引。我拿一个真实在用的例子给你看--- name: frontend-review description: 审查前端组件代码检查命名规范、拆分粒度、类型完整性 --- ## 何时使用 当用户要求审查React/Vue组件代码或提到组件规范代码审查时使用。 ## 执行步骤 1. 读取 references/style-guide.md 中的命名规范 2. 检查组件是否超过200行超过则建议拆分 3. 检查props/emit是否有完整类型定义 4. 检查是否存在内联样式有则建议提取 ## 输出格式 按问题-位置-建议三段式输出每条问题标注严重程度。这个结构不是随便定的。name和description放在最前面是因为AI在判断要不要加载这个skill时最先看的就是这两项。description写得越具体AI匹配得越准。我见过有人把description写成一个有用的skill结果AI根本不知道什么时候该用它等于白写。2.2 为什么用Markdown而不是JSON或YAML这个问题我被问过好几次。用Markdown的好处是AI读起来自然。你想想skill的本质是给AI看的操作手册而AI对Markdown格式的理解能力是最强的——标题层级、列表、代码块这些结构AI都能准确解析。如果你用JSON写虽然机器解析没问题但AI在理解步骤之间的逻辑关系时反而容易出错。另一个原因是人也能读。skill不只是给AI看的团队成员也要能看懂、能改。Markdown的可读性远超JSON一个不懂技术的人打开SKILL.md也能大概明白这个skill在干什么。2.3 references目录的作用与取舍references目录放的是详细参考资料比如完整的代码规范文档、检查清单、示例代码。为什么不把这些直接写进SKILL.md因为上下文是有成本的。SKILL.md本身要尽量精简让AI快速理解要做什么references里的内容只在需要时才被读取避免一次性塞太多信息把上下文撑爆。我的经验是SKILL.md控制在100-200行以内references可以随便长。如果一个skill的SKILL.md超过300行基本可以考虑拆成两个skill或者把细节挪到references里。注意references目录不是必须的。简单的skill只有SKILL.md一个文件也完全能用。不要为了看起来完整而硬造references。3. 写一个能用的skill从需求到落地3.1 先想清楚触发场景再动笔很多人写skill的第一个错误是上来就开始写步骤结果写完发现AI根本不知道什么时候该用。正确的顺序是先定义触发场景。我一般会问自己三个问题这个skill在什么情况下该被激活用户会用什么词来描述这个需求如果不激活会有什么后果把这三个问题的答案写进description和何时使用部分AI的匹配准确率会高很多。举个例子我写过一个数学建模论文格式检查的skill。description我写的是检查数学建模竞赛论文的格式规范包括摘要结构、公式编号、图表标题、参考文献格式。当用户提到建模论文格式检查论文排版时使用。这样写之后我只要在对话里说帮我看看这篇建模论文的格式AI就能自动加载这个skill。3.2 步骤要写成可执行的动作而不是原则这是区分新手和老手的关键。新手写步骤喜欢写原则比如确保代码质量注意命名规范老手写的是可执行动作比如检查每个函数名是否以动词开头检查变量名是否超过30个字符。为什么因为AI执行原则时会产生歧义而执行具体动作时不会。你写注意命名规范AI可能觉得getUserInfo和fetch_user_info都算规范你写函数名必须用驼峰命名且以动词开头AI就能明确判断。我自己的做法是每写一条步骤就问自己如果换一个AI来执行它能不能100%确定该做什么。如果不能就继续细化。3.3 输出格式的约束力比你想的更重要很多人忽略输出格式这一节觉得AI自己会组织语言。但实际用下来输出格式是保证结果可用的关键。如果你不约束AI可能这次给你一段话下次给你一个列表再下次给你一个表格你根本没法做后续处理。我通常会在输出格式里规定三件事结构分几段、每段叫什么、粒度每条多长、标记方式用什么符号标注严重程度。比如## 输出格式 按以下结构输出 - 【严重】问题描述 | 位置 | 修复建议 - 【建议】问题描述 | 位置 | 优化方向 每条不超过两行位置精确到行号或函数名。这样约束之后输出结果可以直接贴进代码审查工具或者用脚本做二次处理。3.4 一个完整的skill编写流程我把自己的编写流程总结成五步记录痛点在日常使用中把我又要重复交代一遍的场景记下来提炼规则把这些交代整理成明确的规则和步骤写SKILL.md按元信息、触发条件、步骤、输出格式的结构写实测三轮用三个不同的真实任务测试看AI是否能正确触发、正确执行迭代description如果触发不准优先改description而不是改步骤实测三轮这一步不能省。我写过一个API接口文档生成的skill前两轮测试都正常第三轮遇到一个返回结构特别复杂的接口AI就懵了。后来我在步骤里加了一条如果返回结构超过三层嵌套先画结构树再生成文档问题才解决。4. 安装与配置不同环境下的落地方式4.1 Claude Code环境下的skill放置位置Claude Code读取skill的位置通常有两个项目级目录和用户级目录。项目级的放在项目根目录下的.claude/skills/或skills/里只对当前项目生效用户级的放在用户主目录下的配置文件夹里对所有项目生效。我的建议是团队协作的规范类skill放项目级个人习惯类skill放用户级。比如组件命名规范是团队约定放项目级跟着代码仓库走我个人的代码注释风格放用户级换项目也能用。配置的时候有个细节容易踩坑目录名必须和skill的name一致。我有一次把skill放在skills/review/目录下但SKILL.md里的name写的是frontend-review结果AI死活加载不了。后来改成目录名和name一致就好了。4.2 从GitHub获取现成skill的正确姿势网上有很多开源的skill集合比如一些superpower skills仓库。获取方式一般是clone或者下载压缩包然后放到对应的skills目录下。但这里有个常见问题下载下来的skill可能依赖特定的目录结构或额外的工具。我建议拿到一个skill后先打开SKILL.md看三件事它依赖哪些references文件它假设的运行环境是什么它的输出格式是否符合你的需求确认没问题再放进去。另外如果你用的是Windows环境注意路径分隔符的问题。有些skill里写死了/路径在Windows下可能读不到文件。遇到这种情况把路径改成相对路径或者用path.join的方式处理。4.3 验证skill是否生效的三种方法装完skill之后怎么确认它真的生效了我用三种方法第一种直接问AI。在对话里问你现在加载了哪些skillAI会列出它识别到的skill列表。如果列表里没有你刚装的说明路径或name有问题。第二种触发测试。用description里提到的关键词发起一个请求看AI是否按照skill里的步骤执行。比如skill里写了输出按三段式你就看输出是不是三段式。第三种看日志。Claude Code在加载skill时通常会有日志输出能看到它扫描了哪些目录、加载了哪些文件。如果日志里没有你的skill就是没被扫描到。提示如果skill没生效排查顺序是——目录名是否匹配name、SKILL.md的frontmatter格式是否正确、文件编码是否是UTF-8。这三个问题占了90%的加载失败原因。4.4 多skill共存时的优先级问题当你装了很多skill之后会遇到一个情况两个skill的触发条件有重叠AI不知道该用哪个。这时候description的精确度就决定了优先级。写得越具体的skill越容易被选中。我的处理方式是给每个skill的description加上排他性描述。比如当用户明确要求检查组件代码时使用不用于检查样式文件。这样AI在匹配时就能区分开。如果实在冲突严重可以在项目级目录里放一个skill索引文件明确告诉AI什么场景用什么skill。不过这属于进阶用法skill数量少于10个的时候一般用不上。5. 实战场景拆解skill在不同领域的用法5.1 前端开发中的skill组合前端是我用得最多的场景。我目前维护着四个前端相关的skill组件审查、样式规范检查、接口类型对齐、提交信息生成。它们各自独立但在实际工作流里会串联使用。比如我写完一个组件会先触发组件审查skill它会检查拆分粒度和命名然后触发样式规范检查确认没有内联样式和魔法数字最后提交前触发提交信息生成按约定格式生成commit message。整个过程我不需要重复交代任何规范AI自己会按skill里的流程走。这里有个经验skill之间不要互相调用。我试过让一个skill去触发另一个skill结果AI在理解调用关系时经常出错。正确做法是让它们保持独立由我在对话里按顺序触发。5.2 数学建模比赛中的skill应用数学建模是我另一个高频使用场景。比赛期间时间紧、任务重AI辅助的效率直接决定成败。我总结了一套建模skill组合论文格式检查、公式推导验证、图表规范生成、摘要结构优化。其中论文格式检查这个skill帮我省了最多时间。它内置了国赛和美赛两套格式规范我只要把论文丢给它它就会逐项检查摘要字数、公式编号连续性、图表标题位置、参考文献格式。以前这些检查要花我两个小时现在十分钟搞定。公式推导验证这个skill比较特殊它的步骤里包含如果推导结果与预期不符列出可能的假设错误。这一条是我踩坑之后加的——有一次AI推导出一个错误结果但它自己没发现直接输出给我了。加了这条之后它会主动做合理性检查。5.3 内容创作场景的skill设计除了技术场景我也用skill来辅助内容创作。比如AI漫剧脚本生成这个skill里面规定了角色对话的风格、分镜的描述格式、每集的时长控制。内容类skill和技术类skill的最大区别是技术类skill重规则内容类skill重风格。技术类skill的步骤要精确到可执行动作内容类skill的步骤要精确到风格特征。比如角色对话要口语化每句不超过20字避免书面语这种描述对AI来说就是可执行的风格约束。5.4 不同AI工具的skill兼容性目前skill这套机制在Claude Code上支持最好Codex、opencode等工具也在逐步跟进。但不同工具对SKILL.md的解析方式有差异。我实测下来frontmatter的格式兼容性最好正文部分的Markdown结构兼容性次之references的加载逻辑差异最大。如果你需要跨工具使用同一个skill建议把核心逻辑写在SKILL.md正文里references只放可选的补充材料。这样即使某个工具不支持references加载skill的核心功能也不受影响。6. 踩坑记录那些让我折腾半天的错误6.1 skill写了但AI不触发这是最高频的问题。我遇到过至少五次排查下来原因各不相同第一次是description太笼统写的是帮助处理代码AI根本不知道什么时候该用。改成审查React组件代码检查命名、拆分、类型之后就好了。第二次是frontmatter格式错误我在---后面多打了一个空格导致AI解析不了元信息。这种错误很隐蔽因为文件看起来是正常的。第三次是目录层级不对我把skill放在了skills/skills/frontend-review/下面多了一层目录AI扫描不到。第四次是文件编码问题我用某个编辑器保存成了GBK编码AI读出来是乱码。第五次最离谱skill的name和目录名不一致而且description里用了中文标点AI匹配时出了问题。6.2 触发太频繁不该用的时候也加载这个问题和上面正好相反。我写过一个代码优化的skilldescription写得太宽泛结果我每次让AI写新代码它都会触发这个skill然后开始优化我还没写完的代码。解决办法是在description里加否定条件。比如改成当用户明确要求优化已有代码时使用不用于生成新代码。加了这句之后误触发率大幅下降。6.3 skill之间的规则冲突我同时装了代码简洁优先和代码可读性优先两个skill结果AI在执行时经常左右为难。一个说能一行写完就一行写完另一个说每行不超过80字符逻辑要分段。这种冲突没有完美的技术解决方案只能在规则层面做取舍。我的做法是把冲突的规则合并到一个skill里明确优先级。比如默认简洁优先但当简洁影响可读性时可读性优先。6.4 更新skill后行为不一致我改了一个skill的步骤但AI的行为还是按旧版执行。排查后发现是缓存问题——Claude Code会缓存已加载的skill改了文件之后需要重启会话或者手动刷新。这个坑的教训是改完skill一定要开新会话测试不要在旧会话里验证。旧会话可能还在用缓存的版本。6.5 排查skill问题的通用链路踩了这么多坑之后我总结了一套排查链路按顺序走基本能定位问题步骤检查项常见问题1目录名与name是否一致不一致导致加载失败2frontmatter格式多空格、缺分隔符、编码错误3description精确度太笼统导致不触发太宽泛导致误触发4文件编码非UTF-8导致乱码5缓存状态改完未刷新导致行为不一致6skill间冲突规则重叠导致执行混乱按这个顺序排查90%的问题能在前三步解决。7. 让skill真正提升效率的几个心得7.1 从最小可用skill开始迭代我见过很多人想一次写一个完美的skill结果写了三天还没写完最后放弃了。我的建议是先写一个能用的最小版本哪怕只有五行先跑起来然后在实际使用中迭代。我的第一个skill只有三行name、description、一条步骤。但它确实解决了我的问题——不用每次重复交代命名规范。后来我根据使用中遇到的情况慢慢加到了现在的二十多行。7.2 把我经常说的话变成skill判断一个场景该不该做成skill有个很简单的标准这句话我是不是说过三次以上。如果是就值得做成skill。我现在的skill库里大部分都是从我又要说一遍的场景里提炼出来的。比如接口返回要判空日志要带traceId异常要分类处理这些都是我说过无数遍的话现在都固化在skill里了。7.3 定期清理不再用的skillskill装多了会有两个问题一是AI匹配时容易混淆二是维护成本上升。我每隔一个月会清理一次skill库把三个月没用过的删掉或者归档。清理的标准很简单如果这个skill的规则已经变成了我的肌肉记忆或者已经写进了项目的lint配置那它就可以删了。skill的价值在于弥补人的遗忘和AI的上下文限制当这个缺口被其他方式补上时skill就完成了使命。7.4 团队协作中的skill管理如果是团队使用skill的管理需要额外注意几点版本控制skill跟着代码仓库走改动要有记录、命名规范团队内统一前缀比如team-开头、评审机制新skill或重大改动要经过评审。我们团队现在的做法是skill放在项目仓库的.claude/skills/目录下和代码一起做code review。每个skill的description里必须写明负责人出问题能找到人。7.5 关于skill的未来演进从我自己的使用体验来看skill这套机制还在快速演进。目前比较明显的趋势是skill的组合使用多个skill协同完成复杂任务、skill的动态加载根据任务类型自动选择skill、skill的跨工具标准化同一份SKILL.md在不同AI工具间通用。我现在会刻意把skill写得工具无关——不依赖特定工具的API只用标准的Markdown结构。这样即使以后换工具skill也能直接迁移。最后分享一个我最近在用的技巧给skill加一个自检步骤。在SKILL.md的最后加一条执行完成后检查输出是否符合输出格式要求不符合则重新生成。这一条加上之后输出质量的稳定性明显提升。这个技巧不复杂但确实管用。
阅读完成 · 觉得有帮助？
