1. 从skills这个模糊词说起它到底指什么第一次看到skills这个词作为项目标题说实话我是有点懵的。这个词太泛了泛到放在任何语境下都能说得通——招聘网站上的技能标签、游戏里的技能树、健身App里的训练动作都能叫skills。但结合关键词里的Claude、Agent Skills、SKILL.md、Claude Code这几个词方向就清晰了这里说的skills是围绕Claude生态构建的一套能力扩展机制核心载体是SKILL.md文件运行环境主要是Claude Code这类命令行或桌面端工具。我接触这套东西的契机很偶然。当时在做一个前端项目的自动化重构需要让AI按照团队既定的代码规范去批量处理组件文件。一开始我的做法很笨——每次对话都把规范文档粘贴一遍或者写一个超长的系统提示词。问题是提示词越写越长模型反而越容易忘记中间部分的约束而且每次新开一个会话就得重新贴一遍效率极低。后来有人跟我提了一句你试试用skills的方式组织我才开始认真研究这套机制。所谓skill本质上是一个结构化的指令包。它把在什么场景下触发需要遵循什么规则可以调用哪些工具输出应该长什么样这些信息用一种模型容易解析的格式固化下来。你可以把它理解成给AI写的一份岗位说明书——不是泛泛地说你要做好前端开发而是具体到当你看到.vue文件时按以下五条规则检查发现问题按这个格式输出。这种颗粒度的指令比笼统的提示词有效得多。SKILL.md是这套机制的核心文件。它的命名本身就说明了定位Markdown格式文件名固定放在约定的目录下模型在需要时会自动读取。这个设计思路很聪明——Markdown天然适合写结构化文档人读起来舒服模型解析起来也顺畅不需要额外的解析器或配置文件。适合谁来了解这套东西我的判断是三类人一是日常用Claude Code做开发的工程师想让AI更贴合自己的项目规范二是做AI应用的产品或运营需要把领域知识封装成可复用的能力模块三是纯粹对AI工具链好奇的技术爱好者想搞清楚skills这个词在AI语境下到底意味着什么。不管你是哪一类接下来的内容都会从实际使用的角度展开不讲虚的。2. SKILL.md的文件结构一份能被模型读懂的岗位说明书2.1 为什么是Markdown而不是JSON或YAML很多人第一反应会问既然是给机器读的配置为什么不用JSON或YAML这种结构化格式我一开始也有这个疑问直到自己写了几份SKILL.md之后才理解其中的考量。JSON和YAML确实结构化程度高但它们有个致命问题不适合写自然语言指令。skill的核心内容是告诉模型怎么做一件事这里面大量的描述是自然语言——什么情况下触发、遇到边界情况怎么处理、输出的语气和格式要求。把这些塞进JSON的字符串字段里写起来痛苦读起来更痛苦而且一旦指令变长转义字符和换行处理能把人逼疯。Markdown的优势在于它同时兼顾了结构化和可读性。你可以用标题划分章节用列表罗列规则用代码块嵌入示例用引用块标注注意事项而所有这些在纯文本层面都是人类可读的。模型在解析时Markdown的层级结构几级标题、列表嵌套本身就提供了语义信息不需要额外的schema定义。提示如果你的skill逻辑特别复杂需要精确的字段校验可以在SKILL.md里嵌入一段YAML frontmatter来承载元数据正文部分仍然用Markdown写指令。这是目前比较常见的折中做法。2.2 一份SKILL.md通常包含哪些部分根据我自己的实践和看过的一些开源skill一份完整的SKILL.md大致包含以下几个部分。注意这不是强制规范而是一个经过验证的实用结构。元信息区放在文件开头说明这个skill叫什么、适用于什么场景、作者是谁、版本号多少。这部分可以用YAML frontmatter写也可以用简单的键值对列表。元信息的作用是让使用者在加载之前就能判断这个skill是不是我要的。触发条件明确写出什么情况下应该激活这个skill。比如当用户提到代码审查当处理.py文件时当需要生成SQL查询时。触发条件写得越具体模型误触发的概率越低。我见过一些skill把触发条件写成当用户需要帮助时这等于没写因为几乎所有对话都符合这个条件。核心指令这是skill的主体详细描述模型应该怎么做。好的核心指令有几个特征步骤清晰、边界明确、有正例和反例。比如不要只写检查代码风格而要写检查以下五项命名是否用驼峰、缩进是否为两个空格、是否有未使用的import、函数是否超过50行、是否有硬编码的密钥。工具与依赖说明这个skill需要调用哪些外部工具或读取哪些文件。比如需要读取项目根目录的.eslintrc文件需要调用git diff命令获取变更。这部分帮助使用者提前准备好环境。输出格式规定模型输出应该长什么样。是纯文本、Markdown表格、JSON还是代码块有没有固定的字段这部分直接决定了skill的输出能不能被下游流程消费。示例给出至少一个完整的输入输出示例。示例的价值在于消除歧义——文字描述再详细也不如一个具体例子来得直观。2.3 一个真实可用的SKILL.md骨架下面这个骨架是我在自己项目里用的做了脱敏处理你可以直接拿去改。--- name: frontend-component-review version: 1.2 author: your-name description: 审查Vue/React组件的代码质量 --- ## 触发条件 当用户要求审查前端组件代码或对话中出现了.vue/.jsx/.tsx文件内容时激活。 ## 核心指令 1. 检查组件是否遵循单一职责原则若一个组件超过300行标记为需要拆分。 2. 检查props定义是否完整是否有类型标注或PropTypes。 3. 检查是否存在内联样式若有建议提取到样式文件或使用CSS-in-JS方案。 4. 检查事件处理函数是否使用了防抖或节流针对高频事件如scroll、resize。 5. 检查是否有未处理的Promise rejection。 ## 输出格式 以Markdown表格输出列为问题类型 | 位置 | 严重程度 | 修改建议。 ## 示例 输入一个包含内联样式的Vue组件 输出 | 问题类型 | 位置 | 严重程度 | 修改建议 | |---------|------|---------|---------| | 内联样式 | template第12行 | 中 | 提取到scoped style块 |这个骨架看起来简单但每一部分都有存在的理由。元信息让skill可管理触发条件控制激活范围核心指令是实际逻辑输出格式保证结果可用示例消除歧义。缺了任何一块skill的可靠性都会打折扣。3. 在Claude Code里加载和使用skills的完整流程3.1 环境准备绕不开的几个前置条件在讲具体操作之前得先把环境问题说清楚。Claude Code的运行依赖Node.js环境这是最基础的前提。我建议用nvm或fnm这类版本管理工具来装Node而不是直接下安装包因为后续切换版本会方便很多。安装完Node之后通过npm全局安装Claude Code的命令行工具。这里有个细节如果你在公司网络环境下npm的默认源可能访问不畅需要配置镜像源。这个配置是一次性的配好之后就不用管了。Windows用户需要额外注意一点Claude Code的某些功能依赖虚拟化平台。如果你在Windows上遇到提示说需要启用虚拟机平台去控制面板-程序-启用或关闭Windows功能里勾选对应选项然后重启。这个步骤容易被忽略导致后面命令跑不起来还找不到原因。安装完成后在终端输入命令验证是否成功。如果提示无法将claude项识别为cmdlet、函数、脚本文件或可运行程序的名称说明环境变量没配好或者安装根本没成功。这时候先检查npm的全局bin目录是否在PATH里这是最常见的原因。3.2 skill文件的存放位置与加载机制Claude Code加载skill的方式有两种项目级和用户级。项目级skill放在项目根目录下的特定文件夹里只对当前项目生效。这种方式适合团队协作——把skill文件提交到代码仓库所有成员拉下来就能用保证了规范的一致性。用户级skill放在用户主目录下的配置文件夹里对所有项目生效适合个人通用的能力封装。加载机制上Claude Code不会一次性把所有skill都读进上下文而是根据当前对话内容判断是否需要激活某个skill。这个判断依据就是SKILL.md里的触发条件。所以触发条件写得准不准直接决定了skill会不会在该用的时候用上、不该用的时候乱入。我踩过的一个坑是把触发条件写得太宽泛结果在一个纯后端项目里前端组件审查的skill被反复激活每次都要手动忽略。后来我把触发条件改成当对话中出现.vue/.jsx/.tsx文件内容且用户明确要求审查时误触发就基本消失了。3.3 手动安装第三方skill的步骤网上有不少开源的skill仓库比如一些做数学建模的、做特定框架开发的。手动安装的流程大致如下。第一步找到skill仓库通常是一个GitHub仓库里面有一个或多个SKILL.md文件。先读一遍README确认这个skill的适用场景和依赖要求。第二步把SKILL.md文件下载到本地。可以直接复制文件内容新建也可以用git clone把整个仓库拉下来。如果仓库里有多个skill按需选取。第三步把文件放到正确的目录下。项目级就放到项目的skill目录用户级就放到用户配置目录。目录不存在的话手动创建。第四步重启Claude Code或重新加载配置。有些版本支持热加载但为了保险起见重启一次最稳妥。第五步验证。开一个新对话输入一个应该触发该skill的场景看模型的行为是否符合预期。如果没触发检查触发条件是否匹配如果触发了但行为不对检查核心指令是否有歧义。注意第三方skill的质量参差不齐安装前务必通读一遍SKILL.md的内容。我见过一些skill里嵌入了不合理的指令比如要求模型忽略某些安全约束这种直接删掉不要用。3.4 一个完整的实操案例假设我要为一个Python数据分析项目配置一个skill功能是自动检查pandas代码的性能问题。首先创建目录结构在项目根目录下建好skill文件夹。然后新建SKILL.md写入以下内容--- name: pandas-performance-check version: 1.0 description: 检查pandas代码中的常见性能陷阱 --- ## 触发条件 当对话中出现pandas的DataFrame操作代码且用户要求性能优化或代码审查时激活。 ## 核心指令 1. 检查是否在循环中逐行操作DataFrame若有建议改用向量化操作。 2. 检查是否频繁使用apply且未指定rawTrue若有建议评估是否可用内置方法替代。 3. 检查是否在循环中反复concat若有建议先收集到列表再一次性concat。 4. 检查是否对大型DataFrame使用了iterrows若有建议改用itertuples或向量化。 5. 检查merge操作前是否对连接键建立了索引。 ## 输出格式 按严重程度排序的列表每条包含问题描述、代码位置、优化建议、预期收益。保存后重启Claude Code开一个新对话粘贴一段包含循环操作的pandas代码观察模型是否按预期输出检查结果。如果一切正常这个skill就可以在日常开发中用了。4. 写一个高质量skill的实战心得4.1 触发条件宁窄勿宽这是我最想强调的一点。新手写skill最容易犯的错就是把触发条件写得太宽。比如写当用户需要代码帮助时这几乎覆盖了所有编程对话结果就是skill在不该出现的时候频繁出现干扰正常对话。正确的做法是把触发条件收窄到具体的文件类型、具体的操作动词、具体的场景关键词。比如当用户粘贴了.sql文件内容并要求优化查询时这就精确多了。窄触发条件的代价是可能漏触发但漏触发用户可以手动指定误触发却会打断思路两害相权取其轻。4.2 指令要可执行不要写口号写出高质量的代码——这是口号不是指令。模型看到这句话不知道具体该做什么。好的指令是函数不超过50行变量名用驼峰每个public方法必须有docstring。这些是可以逐条检查的模型执行起来有明确的依据。我习惯把核心指令写成编号列表每条以动词开头包含明确的判断标准。如果某条指令涉及阈值比如行数、复杂度把具体数字写出来不要用过长过高这种模糊词。4.3 输出格式决定可用性skill的输出如果是一大段自然语言那它的价值就大打折扣——你还得自己从里面提取信息。好的输出格式应该是结构化的能直接被下游消费。Markdown表格、JSON、带固定前缀的列表都是不错的选择。我在做代码审查类skill时统一用表格输出列为问题类型、位置、严重程度、建议。这样我一眼就能扫到严重程度高的条目也可以直接把表格复制到issue跟踪系统里。4.4 版本管理不能省skill是会迭代的。今天写的触发条件用了一周发现太宽要改核心指令跑了一个月发现漏了某个边界情况要补。如果没有版本管理改着改着就乱了甚至改出问题想回滚都回不去。我的做法是在SKILL.md的元信息里维护版本号每次修改都递增同时在文件末尾加一个简短的变更记录。如果项目用git管理skill文件跟着一起提交历史记录天然就有了。4.5 测试用例要覆盖边界写完一个skill不能只测正常情况。要专门构造一些边界输入空输入、超长输入、格式错误的输入、触发条件边缘的输入。看模型在这些情况下的表现是否符合预期。我一般会准备三组测试一组是标准场景验证基本功能一组是边界场景验证鲁棒性一组是干扰场景验证不会误触发。三组都过了这个skill才算基本可用。5. 常见问题排查从不生效到乱触发5.1 skill完全不生效的排查链路遇到skill不生效按以下顺序排查基本能定位到问题。先确认文件位置对不对。项目级skill和用户级skill的目录不同放错了就不会被加载。检查目录名是否拼写正确大小写是否匹配。再确认文件名是不是SKILL.md。有些系统对文件名大小写敏感写成skill.md或Skill.md可能就识别不了。然后确认触发条件是否匹配当前对话。可以临时把触发条件改得非常宽泛测试skill本身是否能工作。如果能工作说明是触发条件的问题如果还不能工作说明是加载机制的问题。最后确认Claude Code的版本是否支持skill功能。早期版本可能没有这个能力升级到最新版再试。5.2 skill乱触发的处理办法乱触发通常有两个原因触发条件太宽或者多个skill的触发条件重叠。先检查触发条件把宽泛的词替换成具体的词。比如代码换成Python代码优化换成性能优化。如果是多个skill重叠考虑给它们加上优先级标记或者在触发条件里加入互斥判断。比如skill A的触发条件加上且skill B不适用。5.3 输出格式不符合预期的调整模型没有严格按输出格式来通常是因为格式要求写得不够明确或者示例不够具体。把格式要求从用表格输出改成用Markdown表格输出表头为列1|列2|列3每行一个条目。再给一个完整的示例把输入和输出都写出来。示例越具体模型遵循格式的概率越高。如果还是不行可以在核心指令的最后加一句严格按照上述格式输出不要添加额外的解释文字。这句话能压住模型自由发挥的倾向。5.4 性能问题的优化思路skill太多会导致上下文膨胀影响响应速度。优化思路有几个一是合并功能相近的skill减少数量二是把不常用的skill设为手动激活不自动加载三是精简SKILL.md的内容去掉冗余描述。我自己的项目里常驻的skill控制在五个以内其他的按需手动调用。这样既保证了常用能力的即时可用又不会让上下文过于臃肿。6. 从数学建模到AI漫剧skills的跨领域应用思路6.1 数学建模场景下的skill设计数学建模比赛里skills能发挥的作用比想象中大。比赛时间紧、任务重很多重复性的工作可以封装成skill。比如数据预处理环节可以写一个skill规定当拿到CSV数据时先检查缺失值比例超过30%的列建议删除10%-30%的列建议插值低于10%的直接删除行。再比如论文写作环节可以写一个skill规定摘要必须包含问题重述、方法概述、主要结论三部分每部分不超过三句话。这类skill的价值在于把赛前的经验固化下来比赛时不用再翻笔记模型会自动按既定规则执行。我见过一些队伍在比赛前专门花半天时间整理skill比赛时效率明显高于临时抱佛脚的队伍。6.2 内容创作场景下的skill设计做AI漫剧或短视频的团队可以把分镜脚本的写作规范封装成skill。比如规定每个分镜必须包含镜号、景别、画面描述、台词、时长五个字段景别只能从远、全、中、近、特五个里选单镜头时长不超过8秒。这类skill的好处是保证了产出的一致性。多人协作时每个人写出来的分镜格式都一样后期合成时不用再花时间对齐格式。6.3 跨领域复用的关键抽象出通用模式不同领域的skill底层逻辑是相通的定义触发场景、规定执行步骤、约束输出格式。掌握了这个模式换一个领域只需要替换具体内容结构不用变。我的建议是先把一个领域的skill写透写到用起来顺手、改起来清晰的程度然后再往其他领域迁移。迁移的时候重点调整触发条件和核心指令输出格式和元信息结构可以直接复用。7. 我踩过的坑和总结出的几条硬规矩7.1 不要试图用一个skill解决所有问题我最初写skill的时候总想写一个万能skill把代码审查、文档生成、测试编写全塞进去。结果就是触发条件没法写——写窄了覆盖不全写宽了到处乱触发。后来拆成三个独立的skill每个只管一件事反而都好用了。这条经验放到任何领域都成立skill的粒度要小职责要单一。一个skill只做一件事做好一件事。7.2 指令里的不要比要更重要模型有很强的补全倾向你告诉它要做什么它往往会额外做很多你没要求的事。所以在skill里明确写出不要做什么和写出要做什么同样重要。比如代码审查skill里我会写只输出问题列表不要输出修改后的完整代码不要对没有问题的部分做评价。这些否定指令能有效约束模型的输出范围。7.3 定期清理不再使用的skillskill用久了会积累有些是过时的有些是当时试了一下就再没碰过的。这些僵尸skill不仅占位置还可能在某个时刻意外触发造成干扰。我现在的习惯是每个月过一遍skill列表三个月没用过的直接归档。保持skill库的精简比不断往里加新skill更重要。7.4 把skill当成代码来管理skill文件应该和代码一样纳入版本控制有清晰的提交记录有review流程。团队协作时修改skill要经过讨论不能谁想改就改。我见过因为一个人随手改了skill的触发条件导致整个团队的自动化流程出问题的案例。如果团队规模大可以考虑给skill建一个独立的仓库配上README说明每个skill的用途和维护人。这样新人进来能快速了解有哪些能力可用也能找到对应的人问问题。7.5 别忘了skill是给人用的最后一条也是最重要的一条skill的最终目的是提升人的效率不是炫技。如果一个skill写得很复杂但用起来还不如手动操作快那它就没有存在的价值。我评判一个skill好不好标准很简单用它比不用它省了多少时间如果省的时间不明显或者用它的学习成本高于收益那就果断放弃。工具是为人服务的不要本末倒置。这套东西我用了大半年从最开始的一头雾水到现在基本形成自己的工作流中间踩了不少坑也积累了一些确实好用的模式。如果你刚开始接触建议从一个小场景入手写一个最简单的skill跑通整个流程再逐步扩展。不要一上来就追求大而全那样大概率会卡在某个环节然后放弃。先把一个点打透后面的路自然就清晰了。