1. 从“skills”这个热词说起它到底是什么为什么突然火了最近几个月不管是在技术社区还是各种开发者群里“skills”这个词出现的频率高得离谱。很多人第一次看到它脑子里冒出来的问号是这不就是“技能”的英文吗有什么好聊的但如果你最近在折腾 Claude、Claude Code、Codex 这类 AI 编程工具就会发现大家嘴里的 skills 已经变成了一个非常具体的东西——它是一套写给 AI 看的“操作手册”用来告诉 AI 在特定场景下应该怎么做、按什么流程做、注意哪些坑。说白了skills 就是把你脑子里那些“老司机才知道”的经验写成 AI 能读懂的结构化文档。以前你用 AI 写代码得在对话里反复交代背景、反复纠正它的错误现在你把规则提前写进一个叫 SKILL.md 的文件里AI 每次执行相关任务时就会自动加载这套规则相当于给它装了一个“专业模式”。这个思路其实不新鲜早些年做自动化脚本、做 CI 配置的时候大家就在用类似的方式固化流程只不过现在对象从机器换成了 AI。那为什么偏偏是现在火起来了我自己的观察是三个原因叠加。第一Claude Code 这类工具把 AI 编程从“聊天窗口”搬到了“终端和编辑器”里AI 能直接读写文件、执行命令能力边界一下子打开了但随之而来的问题是它太自由了容易乱来所以需要 skills 来约束。第二Agent Skills 这个概念被明确提出之后大家发现原来可以像搭积木一样给 AI 组合能力一个 skill 负责查数据库一个 skill 负责写测试一个 skill 负责代码审查组合起来就是一个完整的开发助手。第三社区里开始出现大量现成的 skills 分享从数学建模到前端开发从 STM32 嵌入式到 AI 漫剧脚本几乎每个垂直领域都有人在写自己的 skill这种“抄作业”的便利性让传播速度极快。这篇文章我想聊的不是某个单一工具的安装教程而是把 skills 这件事从头到尾拆开讲清楚它的核心设计逻辑是什么一个高质量的 SKILL.md 应该怎么写怎么把 GitHub 上的 skills 手动装到本地遇到常见报错怎么排查以及我自己在实际使用中踩过的那些坑。不管你是刚听说 Claude Code 想入门的新手还是已经在用但觉得效果不稳定的老用户应该都能从里面找到能直接用的东西。2. skills 的核心设计逻辑为什么是 Markdown为什么是 SKILL.md2.1 用自然语言约束 AI而不是用代码很多人第一次接触 skills 会有一个误解觉得它应该像插件一样是一段可执行的代码。但实际上绝大多数 skills 的核心就是一个 Markdown 文件里面写的是自然语言。这个选择乍看很“偷懒”但仔细想想非常合理。AI 模型本身就是靠自然语言训练的你用自然语言给它下指令它理解起来最顺畅。如果你非要把规则写成 JSON schema 或者某种 DSL反而增加了翻译成本模型可能理解偏。Markdown 的好处是结构清晰、人类可读、AI 也好解析标题层级天然对应任务的优先级和分类列表对应步骤代码块对应示例。我试过用纯文本写规则和用 Markdown 写规则同样的内容Markdown 版本 AI 执行准确率明显更高因为它能通过##、###这些标记判断哪些是主流程、哪些是补充说明。另一个原因是可维护性。skills 不是写完就扔的你需要根据实际使用效果不断调整。Markdown 改起来没有心理负担打开编辑器就能改改完保存立刻生效不需要编译、不需要重启服务。这种低摩擦的迭代体验是 skills 能快速在社区传播的重要前提。2.2 SKILL.md 的命名约定与目录结构社区里约定俗成的做法是每个 skill 放在一个独立目录下目录名就是 skill 的名字里面必须有一个SKILL.md作为入口文件。为什么强调这个命名因为 Claude Code 这类工具在加载 skills 时会按约定去扫描特定目录找到SKILL.md就认为这是一个可用的 skill。如果你把文件名写成skill.md小写或者写成README.md工具可能就识别不到。一个典型的 skill 目录长这样my-skill/ ├── SKILL.md # 必需入口文件 ├── examples/ # 可选示例代码或输入输出 │ ├── input.md │ └── output.md ├── scripts/ # 可选辅助脚本 │ └── helper.py └── resources/ # 可选参考资料 └── reference.mdSKILL.md里面通常包含几个固定区块skill 的名称和一句话描述、适用场景、前置条件、执行步骤、注意事项、示例。这个结构不是强制标准但社区里高质量的 skill 基本都遵循类似套路因为这样 AI 解析起来最稳定。2.3 skills 与 prompt、agent、tool 的区别这里有必要厘清几个容易混淆的概念。prompt 是你每次对话时临时输入的内容用完就没了skills 是持久化的规则文件只要在目录里就一直生效。agent 是一个能自主决策、调用工具的执行体skills 更像是 agent 的“知识库”和“行为准则”agent 在决策时会参考 skills 里的内容。tool 通常指具体的函数或 APIAI 调用它来执行动作skills 不直接执行动作它告诉 AI 什么时候该调用哪个 tool、怎么调用、调用前后要做什么检查。打个比方如果把 AI 比作一个新来的员工prompt 是你当面交代的任务tool 是公司里的各种设备agent 是员工本人那 skills 就是员工桌上的那本《岗位操作手册》。手册不会替员工干活但员工干活时会翻手册按手册里的流程走出错概率就低很多。3. 手把手写一个能用的 SKILL.md从零到可运行3.1 先想清楚这个 skill 要解决什么问题写 skill 最容易犯的错误是一上来就写内容结果写出来的东西又长又散AI 抓不住重点。我的习惯是先花五分钟想清楚三件事这个 skill 在什么场景下被触发触发后要完成什么具体任务完成任务的判断标准是什么举个例子假设我要写一个“代码审查”的 skill。触发场景是用户提交了一段代码或者一个 PR具体任务是检查代码里的常见问题比如空指针、边界条件、命名规范、重复代码判断标准是输出一份结构化的审查报告每个问题标注严重程度和修改建议。这三件事想清楚了SKILL.md 的骨架自然就出来了。3.2 SKILL.md 的标准结构模板下面是我自己常用的一个模板你可以直接拿去改# Skill 名称 一句话描述这个 skill 是做什么的。 ## 适用场景 - 场景一... - 场景二... ## 前置条件 - 需要什么环境、什么文件、什么权限 ## 执行步骤 1. 第一步... 2. 第二步... 3. 第三步... ## 注意事项 - 注意点一... - 注意点二... ## 示例 输入 ... 输出 ...这个模板看起来简单但每个区块都有讲究。适用场景决定了 AI 什么时候加载这个 skill写得太宽泛会导致误触发写得太窄又会在需要时用不上。前置条件是为了让 AI 在执行前先检查环境避免跑到一半发现缺东西。执行步骤要按顺序写每一步尽量是原子操作不要一步里塞太多事情。注意事项是精华把你踩过的坑写进去AI 就不会再踩。3.3 描述语言的选择中文还是英文社区里英文 skill 居多但中文 skill 完全没问题Claude 系列模型对中文的理解能力足够强。我的建议是看你的使用场景如果 skill 主要处理中文内容比如中文写作、中文数据分析那就用中文写AI 理解起来更自然如果 skill 涉及大量英文技术术语、要调用英文 API那用英文写可能更精确。实际测试下来中英混写也是可以的关键术语用英文解释说明用中文AI 一样能处理。但要注意一点同一个 skill 里不要中英文随意切换保持一致性否则 AI 可能会在输出时也跟着乱切语言。3.4 一个完整的实战示例数学建模辅助 skill数学建模比赛是 skills 应用的一个典型场景因为建模流程固定、步骤多、容易漏环节。下面这个 skill 是我帮朋友写的一个简化版# 数学建模辅助 辅助完成数学建模竞赛的完整流程从问题分析到论文撰写。 ## 适用场景 - 用户提出数学建模问题需要完整解题流程 - 用户需要检查建模方案的完整性 ## 前置条件 - 已明确题目要求和数据文件位置 - 确认使用的编程语言默认 Python ## 执行步骤 1. 问题重述用自己的话复述题目确认理解无误 2. 假设提出列出所有合理假设每条假设说明理由 3. 符号说明建立符号表避免后续混用 4. 模型建立先选基础模型再根据题目特点改进 5. 模型求解写出求解算法给出代码实现 6. 结果分析对结果做敏感性分析说明稳定性 7. 模型评价列出优缺点给出改进方向 8. 论文撰写按摘要、问题重述、假设、模型、求解、分析、评价的顺序组织 ## 注意事项 - 假设不能太多一般 5 到 8 条为宜每条都要能站住脚 - 符号说明要在建模前完成中途加符号容易乱 - 敏感性分析是加分项不要省略 - 论文摘要最后写但要放在最前面 ## 示例 输入某城市共享单车投放量优化问题给出各区域需求数据 输出完整的建模论文框架 核心代码 结果图表说明这个 skill 写完之后AI 在接到建模任务时会自动按这八步走不会跳步也不会漏掉敏感性分析这种容易被忽略的环节。我朋友反馈说用了这个 skill 之后他们队伍的建模流程规范了很多至少不会出现“模型建完了才发现假设没写”这种低级失误。4. 安装与配置把 GitHub 上的 skills 装到本地4.1 手动安装的通用流程GitHub 上的 skills 仓库通常是一个大目录里面按功能分成多个子目录每个子目录是一个独立 skill。手动安装的核心就是把这些子目录复制到你本地工具能识别的 skills 目录下。以 Claude Code 为例默认的 skills 目录一般在用户主目录下的.claude/skills或者项目根目录的.claude/skills。具体位置取决于你的配置可以在工具的设置里确认。安装步骤大致是从 GitHub 克隆或下载 skills 仓库到本地找到你需要的 skill 子目录把整个子目录复制到.claude/skills/下确认子目录里有SKILL.md文件重启工具或重新加载配置这里有个细节很多人会忽略复制的时候要复制整个目录不能只复制SKILL.md。因为有些 skill 依赖同目录下的脚本或资源文件只复制入口文件会导致运行时报错。4.2 目录结构检查清单安装完成后建议按下面的清单检查一遍检查项正确示例常见错误目录层级.claude/skills/my-skill/SKILL.md.claude/skills/SKILL.md少了中间层文件名SKILL.mdskill.md、Skill.md、README.md文件编码UTF-8GBK 导致中文乱码目录权限可读写只读导致无法更新依赖文件同目录下齐全脚本缺失导致执行失败我遇到过最常见的问题就是目录层级搞错把SKILL.md直接放在 skills 根目录下工具扫描时把它当成一个没有名字的 skill加载失败。还有就是从 Windows 复制到 Linux 环境时文件名大小写变了SKILL.md变成skill.md工具识别不到。4.3 在 VS Code 里配置 Claude Code 的注意事项如果你是在 VS Code 里用 Claude Code配置路径可能和纯终端环境不一样。VS Code 的工作区设置里可以指定 skills 目录建议用绝对路径避免相对路径在不同工作区下解析不一致。另外VS Code 的 Claude Code 插件有时候会有缓存你更新了 skill 文件但插件还在用旧版本。这时候需要执行一次“重新加载窗口”或者重启插件。我自己的习惯是每次改完 skill 都手动重载一次虽然麻烦但能避免“改了没生效”的困惑。提示如果你在 Windows 上遇到“requires the virtual machine platform”这类提示通常是系统组件没启用和 skills 本身无关按系统提示启用对应组件即可。5. 常见问题与排查技巧实录5.1 命令找不到claude 不是可识别的命令这是新手最高频的问题报错信息通常是“无法将‘claude’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”。原因基本就一个Claude Code 的可执行文件没有加到系统的 PATH 环境变量里。解决办法分平台。Windows 上找到 Claude Code 的安装目录把那个目录路径加到系统环境变量的 Path 里然后重开终端。macOS 和 Linux 上在~/.bashrc或~/.zshrc里加一行export PATH$PATH:/path/to/claude然后source一下。加完之后用claude --version验证能输出版本号就说明成功了。如果加了 PATH 还是不行检查一下可执行文件本身有没有执行权限。Linux 和 macOS 上用chmod x给一下权限Windows 上检查文件是不是被安全软件拦截了。5.2 skill 加载了但不生效有时候你确认目录结构没问题文件也在但 AI 执行任务时就是不按 skill 里的规则走。这种情况我总结了几种可能第一种是 skill 的描述太模糊AI 判断当前任务和这个 skill 不匹配所以没加载。解决办法是把“适用场景”写得更具体最好带上关键词比如“当用户提到数学建模、建模比赛、论文框架时触发”。第二种是 skill 内容太长超出了工具的加载上限。有些工具对单个 skill 的 token 数有限制太长的 skill 会被截断。解决办法是精简内容把不必要的大段示例移到单独的参考文件里SKILL.md 里只留核心流程。第三种是多个 skill 冲突。如果你装了两个功能重叠的 skillAI 可能不知道该听谁的。解决办法是合并或者明确优先级在 skill 里写清楚“当与其他 skill 冲突时以本 skill 为准”。5.3 中文乱码与编码问题从 GitHub 下载的 skill 如果包含中文偶尔会出现乱码。这通常是文件编码不是 UTF-8 导致的。用编辑器打开SKILL.md另存为 UTF-8 编码即可。VS Code 右下角可以看当前编码点一下就能切换。还有一种情况是终端本身的编码设置不对导致显示乱码但文件内容其实是好的。这种不影响 AI 读取只是看着难受调整终端编码就行。5.4 常见问题速查表问题现象可能原因解决方法命令找不到PATH 未配置添加安装目录到 PATHskill 不生效描述模糊或内容过长精简内容明确触发词中文乱码文件编码非 UTF-8另存为 UTF-8加载报错目录层级错误确保 skill 在独立子目录更新不生效工具缓存重启工具或重载窗口执行中断依赖文件缺失检查同目录下脚本和资源6. 进阶玩法组合 skills 与垂直领域实践6.1 用 superpower skills 做能力叠加社区里有个叫 superpower skills 的概念思路是把多个基础 skill 组合成一个“超级 skill”让 AI 一次性获得多种能力。比如你把“代码生成”“代码审查”“测试编写”三个 skill 放在同一个目录下用一个总的SKILL.md引用它们AI 在处理一个完整开发任务时就能自动切换。这种做法的好处是减少手动切换成本坏处是调试变复杂。我的建议是先用单个 skill 跑通确认每个都稳定了再组合。组合的时候在总 skill 里写清楚每个子 skill 的职责边界避免 AI 混淆。6.2 前端开发场景的 skills 设计前端开发是 skills 应用很成熟的领域因为前端流程标准化程度高。一个典型的前端 skill 会覆盖组件结构规范、样式命名约定、状态管理方式、接口调用封装、错误处理、性能检查点。我见过一个写得不错的前端 skill它在“注意事项”里列了十几条团队踩过的坑比如“不要在 useEffect 里直接改 state 导致死循环”“图片必须加 alt 属性”“接口错误必须统一走错误边界”。这些规则如果靠口头交代新人根本记不住写进 skill 里 AI 每次生成代码都会自动遵守相当于把团队规范固化下来了。6.3 嵌入式与 STM32 场景的特殊考量嵌入式场景和纯软件不一样它涉及硬件寄存器、时序、中断AI 如果不懂这些很容易写出跑不起来的代码。给 STM32 写 skill 时前置条件里要明确芯片型号、时钟配置、使用的 HAL 库版本。执行步骤里要包含“检查引脚冲突”“确认中断优先级”“验证时钟树”这些硬件相关环节。另外嵌入式调试成本高烧录一次要等半天所以 skill 里最好加上“生成代码后先做静态检查”的步骤把能提前发现的问题提前发现减少实际烧录次数。6.4 AI 漫剧与内容创作场景AI 漫剧是最近比较新的应用方向skills 在这里的作用是规范剧本结构、角色设定、分镜描述。一个漫剧 skill 通常会定义剧本格式场景标题、角色、对白、动作描述、角色一致性规则外貌、性格、说话风格、分镜描述模板镜头类型、画面内容、情绪基调。这个场景的难点是“一致性”AI 写着写着容易把角色性格写崩。解决办法是在 skill 里放一个角色卡区块每次生成前先让 AI 读一遍角色卡生成后再对照检查。我试过在 skill 里加一条“每生成三幕就回顾一次角色设定”效果比不加好很多。7. 我踩过的坑与实操心得7.1 不要试图一次写完美我刚开始写 skill 的时候总想一次把所有情况都覆盖到结果写出来的文件又长又乱AI 反而抓不住重点。后来我改成“先写最小可用版本用起来再补”效果好很多。第一版只写核心流程和三条最重要的注意事项跑几次之后看哪里出问题再针对性补充。这样迭代出来的 skill 更精炼也更贴合实际使用场景。7.2 注意事项比执行步骤更值钱执行步骤网上到处能搜到但注意事项是只有真正做过的人才知道的。比如“这个 API 在并发超过 10 的时候会限流”“这个库在 Windows 上路径要用反斜杠”“这个参数单位是毫秒不是秒”这些细节写进 skill 里能帮 AI 避开大量低级错误。我现在写 skill花在注意事项上的时间比花在步骤上的还多。7.3 定期清理不再用的 skillsskills 装多了会有两个问题一是加载变慢二是 AI 可能被不相关的 skill 干扰。我现在的习惯是每个月清理一次把最近一个月没用过的 skill 移到备份目录只留常用的。清理的时候顺便看看有没有可以合并的把功能相近的 skill 整合成一个减少数量。7.4 版本管理很重要skill 也是代码也需要版本管理。我建议把 skills 目录纳入 Git 管理每次修改都提交写清楚改了什么、为什么改。这样万一改坏了可以回滚也能看到 skill 的演进过程。团队协作时更是必须否则你改了我改最后谁也不知道哪个版本是对的。7.5 从别人的 skill 里学写法GitHub 上有很多高质量的 skill 仓库我经常去翻别人的SKILL.md是怎么写的。看多了会发现一些共性技巧比如用表格代替长段落、用代码块标注示例、用引用块突出警告。这些写法上的细节直接影响 AI 的理解效果。我自己的模板就是从好几个开源 skill 里拼出来的取各家之长。8. 关于 skills 学习路径的一点个人建议如果你刚开始接触 skills我的建议是不要一上来就写复杂的。先找一个现成的、简单的 skill把它读懂然后照着改一个自己的版本。改的过程中你会遇到各种问题带着问题去查资料、去看别人的写法学得最快。第二步是把你日常工作中重复性最高的一个流程写成 skill。不用追求完美能跑就行。跑起来之后你会发现哪些地方写得不清楚再改。这个过程重复几次你就摸到门道了。第三步是尝试组合多个 skill解决一个稍微复杂的任务。这时候你会遇到 skill 之间的协调问题解决这些问题的经验比单个 skill 的写法更有价值。最后说一个我自己的体会skills 的价值不在于写得多而在于写得准。一个精准的、经过实战检验的 skill比十个泛泛而谈的 skill 有用得多。与其追求数量不如把手上常用的那几个打磨到极致。