1. 从skills这个热词说起它到底在解决什么问题最近一段时间不管是在技术社区还是各种开发者群聊里skills这个词出现的频率高得离谱。很多人第一次看到它会以为是某种新的编程语言特性或者某个框架的插件系统。但如果你真的去翻一翻相关的讨论会发现大家聊的其实是另一回事——Agent Skills也就是给 AI 智能体尤其是 Claude 这类工具配置的一套技能包机制。我最初接触这个概念的时候也走了弯路。当时我以为 skills 就是一堆提示词模板复制粘贴到对话框里就完事了。结果折腾了半天发现真正让 skills 有价值的东西是它背后那套结构化的技能描述文件也就是大家常说的SKILL.md。这个文件不是随便写写的说明文档它更像是给 AI 的一份岗位说明书——告诉它在这个特定场景下应该扮演什么角色、遵循什么流程、调用什么工具、输出什么格式。为什么这件事值得单独拿出来讲因为大多数人用 AI 工具的方式还停留在问一句答一句的阶段。你问它帮我写个排序算法它给你一段代码你问它帮我分析这份数据它给你一段文字。但当你需要它稳定地、可复现地完成一类任务时这种对话式的交互就很容易翻车——每次输出的格式不一样每次理解的侧重点不一样甚至同一个问题问两遍答案都不同。skills 要解决的就是这个不稳定的问题。从热搜词里能看出来大家关心的方向非常分散有人问claude code 怎么手动装 github 上的 skills有人问数学建模 skills 推荐还有人问ai 漫剧常用 skills。这说明 skills 的适用场景已经远远超出了单纯的编程辅助它正在变成一种通用的能力封装方式。不管你是做前端开发、数学建模、内容创作还是数据分析只要你有重复性的、有固定套路的任务就可以把它封装成一个 skill。这篇文章我会从实际使用的角度出发把 skills 的核心机制、编写方法、安装配置、常见坑点以及不同场景下的实战经验都讲清楚。不管你是刚听说这个词的新手还是已经用过一段时间但总觉得没发挥出全部威力的老用户应该都能从里面找到对自己有用的东西。2. SKILL.md 到底该怎么写从能跑到好用的差距2.1 一个 skill 的最小可用结构很多人第一次写SKILL.md的时候最容易犯的错误就是把它写成了使用说明书。比如写成这样这个 skill 用于帮助用户处理 Excel 数据。 用户可以把 Excel 文件发给我我会帮他们做数据清洗。这种写法不能说错但它几乎没有给 AI 提供任何可执行的约束。AI 看到这段话只能靠自己的理解去猜数据清洗具体指什么——是去重是填充缺失值是格式转换还是全都做结果就是每次输出的质量参差不齐。一个真正能用的 skill至少应该包含以下几个部分角色定义这个 skill 让 AI 扮演什么角色具备什么专业背景触发条件什么情况下应该启用这个 skill什么情况下不应该输入规范用户需要提供什么格式的输入有哪些必填项和可选项处理流程分步骤描述 AI 应该按照什么顺序做什么事输出格式最终结果应该以什么形式呈现有没有固定的模板边界与异常遇到不符合预期的情况时应该怎么处理我拿一个实际例子来说明。假设你要做一个数学建模论文摘要生成的 skill不要只写帮用户写摘要而是应该写成类似这样的结构# 数学建模论文摘要生成 Skill ## 角色 你是一位有十年数学建模竞赛指导经验的教练熟悉国赛和美赛的评审标准。 ## 触发条件 当用户提供了建模问题的背景、采用的模型方法和主要结论时启用。 ## 输入要求 - 问题背景必填一段 100-300 字的描述 - 模型方法必填列出使用的主要模型和算法 - 求解结果必填关键数值结果和结论 - 论文类型可选国赛/美赛/其他默认国赛 ## 处理流程 1. 先判断问题类型优化类/预测类/评价类/分类类 2. 根据问题类型选择对应的摘要结构模板 3. 按照背景-方法-结果-结论四段式组织内容 4. 检查是否包含所有必填信息缺失则主动询问 ## 输出格式 - 总字数控制在 300-500 字 - 第一段交代问题背景和研究意义 - 第二段说明采用的模型和方法 - 第三段给出关键结果 - 第四段总结创新点和推广价值 ## 异常处理 - 如果用户只给了问题没有给方法先追问方法再生成 - 如果结果数据不完整在摘要中标注待补充而不是编造你看这样的 skill 文件给到 AI 之后它的输出就会稳定得多。因为它不是在猜你要什么而是在执行一套明确的流程。2.2 为什么流程描述比结果描述更重要这里有一个很多人没意识到的关键点AI 在执行任务时过程约束比结果约束更有效。举个例子你说帮我写一段高质量的代码这是结果约束。AI 不知道你说的高质量是指性能好、可读性强、还是注释全它只能按自己的理解来。但如果你说先分析需求再列出边界条件然后写代码最后补充单元测试这就是过程约束。AI 每一步都有明确的动作最终结果自然就更接近你的预期。我在写 skills 的时候会刻意把流程拆得细一点。比如一个代码审查的 skill我不会只写审查用户提供的代码而是会写成先通读代码理解整体功能检查命名规范变量、函数、类名是否清晰检查边界条件处理空值、越界、异常检查性能隐患循环嵌套、重复计算、内存泄漏检查安全隐患注入、越权、敏感信息泄露按严重程度分级列出问题对每个问题给出修改建议和示例代码这样拆下来AI 的审查就会非常系统不会漏掉重要维度。而且因为流程是固定的你每次用这个 skill 得到的结果结构都是一致的方便对比和复用。2.3 常见写法对比差 skill 和好 skill 的差距维度差 skill 的写法好 skill 的写法角色不定义或一句话带过明确专业背景和经验年限触发没有触发条件明确何时启用、何时不启用输入不说明需要什么列出必填项、可选项和格式流程只描述目标分步骤描述执行顺序输出不规定格式给出模板或结构要求异常不考虑定义缺失信息和错误处理这个表格里的每一条都是我在实际使用中踩过坑之后总结出来的。最开始我写的 skills 基本都集中在差的那一列结果就是每次用都要重新解释一遍需求完全失去了封装的意义。后来把流程和格式补上之后同一个 skill 的复用率至少提升了三倍。3. 安装与配置不同环境下的 skills 落地方式3.1 命令行环境下的安装逻辑热搜词里有很多关于安装的问题比如claude code 怎么手动装 github 上的 skills、安装 claude code、vscode 安装 claude code等等。这说明很多人在第一步就卡住了。我先说清楚一个基本逻辑skills 本质上就是一组文件通常是一个文件夹里面放一个SKILL.md可能还会附带一些辅助文件比如模板、示例、脚本。所谓安装其实就是把这些文件放到 AI 工具能够读取到的目录里。不同工具的目录约定不太一样但大体上遵循一个规律有一个全局的 skills 目录也有一个项目级的 skills 目录。全局目录里的 skills 对所有项目生效项目级目录里的只对当前项目生效。我一般建议把通用的、跨项目使用的 skills 放在全局目录把跟特定项目强相关的放在项目目录里。手动安装 GitHub 上的 skills基本步骤是这样的找到你想用的 skill 仓库确认里面有SKILL.md文件把整个文件夹下载下来可以直接下载 zip 解压也可以用 git clone找到你的 AI 工具对应的 skills 目录把文件夹复制进去重启工具或者重新加载配置验证 skill 是否被正确识别这里有几个容易出问题的地方。第一文件夹结构不能乱。有些 skill 仓库里SKILL.md是放在子目录里的你需要把包含SKILL.md的那一层目录整体复制过去而不是只复制文件。第二文件名大小写要一致。有些系统对大小写敏感SKILL.md和skill.md会被当成两个不同的文件。第三复制完之后要确认权限特别是在 Linux 或 macOS 环境下如果文件权限不对工具可能读不到。3.2 桌面版和编辑器插件的配置差异桌面版工具和编辑器插件在 skills 的加载方式上通常有一些差异。桌面版一般会有自己的配置目录你可以在设置里找到 skills 相关的路径。编辑器插件则通常会跟随编辑器的工作区配置也就是说你打开不同的项目文件夹它加载的 skills 可能是不一样的。我在用编辑器插件的时候遇到过一个典型问题明明把 skill 文件夹放到了正确的位置但插件就是不识别。排查了半天发现是因为插件的配置文件里有一个 skills 路径的白名单只有白名单里的目录才会被扫描。这种情况你就需要去翻一下插件的配置文档把自定义路径加进去。还有一个常见问题是版本兼容。有些 skills 是针对特定版本的工具写的用了新版本或者旧版本都可能出问题。如果你发现某个 skill 之前能用突然不能用了先检查一下工具是不是自动更新了。3.3 验证 skill 是否生效的实用方法装完之后怎么确认 skill 真的生效了我一般用这几个方法直接问问 AI你现在有哪些可用的 skills看它能不能列出来触发测试构造一个应该触发该 skill 的场景看输出是否符合 skill 里定义的格式边界测试给一个不应该触发该 skill 的场景看它会不会误触发对比测试同一个问题启用 skill 和不启用 skill 各问一遍看输出差异如果发现 skill 没生效排查顺序建议是先确认文件路径对不对再确认文件内容格式对不对特别是开头的元信息部分最后确认工具版本是否支持。提示不同工具对SKILL.md的格式要求可能有细微差别建议先拿一个最简单的 skill 做测试跑通之后再写复杂的。4. 场景化实战skills 在不同领域的落地思路4.1 编程开发场景从代码生成到项目脚手架编程是 skills 应用最成熟的场景之一。热搜词里提到的前端开发 skills、claude code stm32、typesafe ai skills都属于这个范畴。我在前端开发中常用的一个 skill 是组件生成器。它的核心逻辑是给定组件名称、props 定义和基本功能描述自动生成符合项目规范的组件文件包括组件本体、样式文件、类型定义和单元测试。这个 skill 的价值在于统一规范——团队里每个人生成的组件结构都是一样的不会出现有人用export default有人用命名导出、有人写 PropTypes 有人写 TypeScript 的情况。写这类 skill 的关键是把项目的约定写清楚。比如文件命名用 PascalCase 还是 kebab-case样式用 CSS Modules 还是 styled-components状态管理用 Redux 还是 Zustand测试框架用 Jest 还是 Vitest这些约定不写清楚AI 就会按自己的习惯来生成出来的代码虽然能跑但跟项目风格不搭后续维护很麻烦。对于嵌入式开发场景比如热搜里提到的 STM32skills 的作用更多体现在寄存器配置和外设初始化上。你可以把常用的外设配置流程封装成 skill比如GPIO 初始化、UART 配置、定时器设置等。这样每次新建工程的时候不需要从头翻手册直接调用 skill 就能生成基础代码。4.2 数学建模场景把竞赛套路固化下来数学建模 skills 推荐和华为杯建模比赛好用的 codex skills这两个热搜词说明建模圈对 skills 的需求很旺盛。这其实很好理解——数学建模有很强的套路性常见的题型就那么几类每类题型的解题流程也相对固定。我帮几个参加建模比赛的朋友整理过一套 skills主要包括问题分析 skill输入题目描述输出问题类型判断、可能的建模方向、需要的数据和假设模型选择 skill根据问题类型推荐合适的模型优化类用线性规划/遗传算法预测类用时间序列/神经网络评价类用层次分析/熵权法论文写作 skill按照竞赛论文的标准结构生成摘要、问题重述、模型假设、符号说明等部分代码实现 skill针对选定的模型生成 Python 或 MATLAB 代码框架这套 skills 最大的好处是节省时间。比赛时间紧张很多队伍把大量时间花在想思路和调格式上真正用来建模和求解的时间反而不够。有了 skills 之后格式化和套路化的部分可以快速完成团队就能把精力集中在核心创新点上。不过这里要提醒一句skills 是辅助工具不是替代思考的。模型的选择、假设的合理性、结果的解释这些还是需要人来判断。我见过有队伍完全依赖 AI 生成的模型结果假设条件跟题目实际情况不符最后论文被评委一眼看穿。4.3 内容创作场景AI 漫剧和文案生成ai 漫剧常用 skills这个热搜词反映了一个新趋势——skills 正在进入内容创作领域。漫剧制作涉及剧本、分镜、角色设定、对话等多个环节每个环节都有相对固定的格式要求。我了解到的做法是把漫剧制作的流程拆成几个 skill剧本结构 skill按照起承转合或者三幕式结构生成剧本框架角色设定 skill根据故事背景生成角色的外貌、性格、背景故事分镜描述 skill把剧本转换成适合 AI 绘图工具理解的分镜描述对话生成 skill根据角色性格生成符合人设的对话这类 skill 的难点在于风格一致性。漫剧最怕的就是角色前后性格不一致、画风突变。所以在写 skill 的时候要把角色的核心特征、说话方式、行为逻辑都写进去让 AI 每次生成内容时都参考这些设定。4.4 不同场景下 skill 设计的侧重点对比场景类型核心诉求skill 设计重点常见坑编程开发规范统一、可维护项目约定、代码风格、测试要求约定不明确导致风格混乱数学建模快速套路化、结构完整题型分类、模型推荐、论文模板过度依赖导致假设不合理内容创作风格一致、产出高效角色设定、风格约束、格式模板前后设定冲突数据分析流程可复现、结果可解释数据清洗步骤、分析方法、可视化规范数据格式假设错误这个表格是我在实际使用中慢慢总结出来的。不同场景下skill 的设计思路差别很大。编程类重约束建模类重流程创作类重设定分析类重复现。搞清楚你的场景属于哪一类写 skill 的时候就能抓住重点。5. 踩坑实录那些让我折腾半天的典型问题5.1 skill 不生效的排查链路这个问题我遇到过至少五次每次原因都不一样。我把完整的排查链路整理出来你可以按顺序检查第一步确认文件是否在正确的位置。不同工具的 skills 目录不一样有的在用户主目录下的隐藏文件夹里有的在工具的安装目录里有的在项目根目录。先查清楚你的工具用的是哪个路径。第二步确认文件结构是否正确。一个 skill 应该是一个文件夹文件夹里至少有一个SKILL.md。如果你直接把SKILL.md放在 skills 根目录下很多工具是识别不了的。第三步确认文件内容格式是否正确。有些工具要求SKILL.md开头有特定的元信息比如 name、description 等字段格式不对就不会被加载。建议先复制一个官方示例或者别人验证过的 skill确认能跑通之后再改。第四步确认工具是否需要重启。很多工具只在启动时扫描 skills 目录你新加了文件不重启是不会生效的。第五步确认版本是否兼容。如果以上都没问题那可能是工具版本和 skill 要求的版本不匹配。看看 skill 的说明文档里有没有版本要求。我印象最深的一次是折腾了两个小时最后发现是文件夹名字里有个空格工具解析路径的时候出错了。所以现在我的习惯是skill 文件夹名字只用小写字母和连字符绝对不用空格和特殊字符。5.2 触发条件写得太宽或太窄skill 的触发条件是个很微妙的东西。写得太宽它会在不该触发的时候触发干扰正常对话写得太窄该用的时候又用不上。我早期写过一个代码优化的 skill触发条件写的是当用户提到代码相关问题时启用。结果就是不管我问什么代码问题它都会跳出来给我做一遍全面优化哪怕我只是想问一个简单的语法问题。后来我把触发条件改成了当用户明确要求优化代码性能或可读性时启用就精准多了。反过来我也写过一个触发条件过窄的 skill。那个 skill 是用于生成 API 文档的触发条件写的是当用户说生成API文档时启用。结果用户说帮我写一下接口说明的时候它就不触发。后来我改成当用户要求生成或编写 API/接口相关文档时启用覆盖面就合理了。我的经验是触发条件里最好包含同义词和常见变体。比如优化可以包含改进、提升、重构文档可以包含说明、注释、README。这样用户不管怎么表达都能被正确识别。5.3 输出格式不稳定的根因分析输出格式不稳定是另一个高频问题。明明 skill 里写了输出 JSON 格式结果 AI 有时候输出 JSON有时候输出 Markdown 表格有时候又变成纯文本。这个问题的根因通常有三个一是格式描述不够具体。你只说输出 JSON但没说 JSON 的字段名、字段类型、嵌套结构。AI 每次都会自己发挥结果自然不一样。正确的做法是给出一个完整的示例{ problem_type: 优化类, recommended_models: [线性规划, 遗传算法], difficulty: 中等, estimated_time: 4-6小时 }二是流程中没有强调格式检查。如果 skill 的流程里没有最后检查输出格式是否符合要求这一步AI 很容易在生成过程中跑偏。我一般会在流程的最后加一步生成完成后对照输出格式要求逐项检查不符合则重新生成。三是上下文干扰。如果对话历史里有其他格式的内容AI 可能会被带偏。这种情况可以在 skill 里加一句忽略对话历史中的格式严格按本 skill 定义的格式输出。5.4 多 skill 冲突时的处理策略当你装了很多 skills 之后可能会遇到两个 skill 同时想处理一个请求的情况。比如你有一个代码审查 skill 和一个代码优化 skill用户说帮我看看这段代码两个 skill 都可能被触发。处理这种冲突我有几个建议在 skill 里写明优先级比如当同时满足代码审查和代码优化条件时优先执行代码审查审查完成后再询问是否需要优化合并相关 skill如果两个 skill 经常一起使用可以考虑合并成一个用流程步骤来区分不同阶段用明确的触发词区分让每个 skill 有独特的触发词减少重叠我现在的做法是把功能相近的 skill 做成一个技能组用一个主 skill 来调度。比如代码质量技能组下面包含审查、优化、重构三个子流程用户触发主 skill 后根据具体需求走不同的分支。6. 进阶思路让 skills 真正成为你的能力放大器6.1 从单点 skill 到技能库的演进刚开始用 skills 的时候大家都是零散地写几个解决眼前的问题。但用久了你会发现真正有价值的不是单个 skill而是一套相互配合的技能库。我现在维护的技能库大概有二十多个 skill按领域分成几组开发组、写作组、分析组、效率组。每组里面有一个入口 skill负责判断用户意图并路由到具体的子 skill。这样我用的时候只需要记住几个入口不用记二十多个 skill 的名字。技能库的另一个好处是可以组合。比如我要做一个数据分析报告可以先调用数据清洗 skill 处理原始数据再调用统计分析 skill 做计算最后调用报告生成 skill 输出文档。三个 skill 串起来就是一个完整的工作流。6.2 版本管理与迭代维护skills 是需要迭代的。你第一次写的版本肯定不完美用着用着就会发现各种问题。所以版本管理很重要。我的做法是给每个 skill 文件夹里加一个CHANGELOG.md记录每次修改的内容和原因。比如## v1.2 (2024-01-15) - 修复了触发条件过宽的问题增加了仅当用户明确要求时启用的限制 - 输出格式增加了字段类型说明 ## v1.1 (2024-01-10) - 补充了异常处理流程 - 优化了角色描述 ## v1.0 (2024-01-05) - 初始版本这样当某个 skill 出问题的时候我可以快速回滚到上一个版本也可以对比不同版本的表现找出是哪个改动导致了问题。另外我建议定期清理不再使用的 skill。有些 skill 可能只是当时为了解决一个临时问题写的后来再也没用过。这些 skill 留在库里不仅占地方还可能在扫描时拖慢工具启动速度。热搜词里有个tibo关于清理skills的方法推荐说明清理这件事确实是大家的共同需求。6.3 团队协作中的 skills 共享如果是团队使用skills 的共享就很重要。我们的做法是建一个内部的 git 仓库专门放团队共用的 skills。每个人都可以提交新的 skill 或者改进现有的 skill通过 pull request 来审核。这样做有几个好处一是保证一致性团队所有人用的都是同一套 skill输出格式统一二是知识沉淀老员工的经验可以通过 skill 传递给新员工三是持续改进一个人发现的问题改进后所有人都受益。不过团队共享也要注意权限管理。不是所有人都应该能修改核心 skill特别是那些被多个流程依赖的 skill。我们一般会设一个核心 skill 维护者的角色只有这个人能合并核心 skill 的修改。6.4 判断一个 skill 是否值得写的标准不是所有任务都值得封装成 skill。我判断的标准有三个第一这个任务是否重复出现如果只是偶尔做一次写 skill 的时间可能比直接做还长。只有高频重复的任务才值得封装。第二这个任务是否有固定套路如果每次的做法都不一样很难写成固定的流程。skill 适合那些步骤相对固定但执行起来繁琐的任务。第三这个任务的输出是否有明确的验收标准如果输出好坏很主观skill 很难定义清楚什么是好的输出。有明确标准的任务比如生成符合 ESLint 规范的代码、输出包含四个部分的摘要更适合做成 skill。按照这三个标准我筛掉了大概一半想写的 skill。剩下的那些才是真正能提升效率的。6.5 关于 skills 学习路径的一点个人体会最后说一点关于如何学习 skills的看法。热搜词里有如何学习skills(技能)和skills开发这两个方向说明大家既想用别人写好的也想自己写。我的建议是先用后写。先找几个成熟的 skill 用起来感受一下它跟普通对话的区别理解 skill 是怎么约束 AI 行为的。用了一段时间之后你自然会知道什么样的 skill 好用、什么样的不好用。这个时候再动手写自己的 skill成功率会高很多。写的时候也不要追求一步到位。先写一个最小可用的版本跑通之后再逐步补充流程、格式、异常处理。我现在的很多 skill 都是迭代了五六个版本才稳定下来的。一开始就想着写一个完美的 skill大概率会卡在某个细节上最后不了了之。另外多看别人的 skill 也很有帮助。GitHub 上有很多开源的 skill 仓库看看别人是怎么组织内容、怎么定义流程的能学到不少技巧。特别是那些被很多人 star 的 skill通常在结构设计上都有值得借鉴的地方。注意使用别人分享的 skill 时建议先通读一遍内容确认没有不适合自己场景的设定再使用。有些 skill 可能包含特定的假设或偏好直接拿来用可能会跟你的实际需求冲突。我在实际使用中最大的体会是skills 的价值不在于让 AI 更聪明而在于让 AI 更可控。它把那些模糊的、依赖临场发挥的交互变成了明确的、可复现的流程。对于需要稳定输出的工作场景来说这种可控性比单纯的智能程度更重要。