1. 从“skills”这个热词说起它到底是什么为什么突然火了最近几个月不管是在技术社区还是各种开发者群里“skills”这个词出现的频率高得离谱。很多人第一次看到“Claude Skills”或者“SKILL.md”的时候第一反应是这不就是个提示词模板吗跟以前那种复制粘贴的 prompt 有什么区别我一开始也这么想直到自己动手拆了几个开源 skills 仓库、写了两三个能跑通的技能包之后才意识到这东西的设计思路跟传统提示词完全不在一个层面上。简单来说Agent Skills智能体技能是一套让 AI 助手具备“可复用专业能力”的机制。你可以把它理解成给 AI 装插件——每个 skill 是一个独立的功能单元里面封装了特定领域的知识、操作流程、工具调用逻辑和输出规范。当用户提出某个需求时AI 会自动匹配对应的 skill按照里面定义的步骤和规则来完成任务而不是每次都要你从头解释一遍“你是谁、你要干什么、你要怎么干”。这套机制最早由 Claude 体系推广开来核心载体是一个叫SKILL.md的 Markdown 文件。这个文件里写清楚了技能的触发条件、执行步骤、注意事项和输出格式。配合 Claude Code、Claude Desktop 这类工具skills 可以被自动加载和调用。后来开源社区跟进出现了 opencode skills、codex skills 等变体玩法越来越丰富。那它到底解决了什么问题我总结下来主要是三个痛点。第一重复劳动。以前你让 AI 帮你做数学建模每次都要重新描述题目背景、建模要求、论文格式现在把这些写进一个 skill 里下次直接调用就行。第二质量不稳定。同一个 prompt 在不同时间、不同上下文下AI 的输出质量波动很大。skill 通过固定流程和检查清单把输出质量拉到一个相对稳定的水平线上。第三知识沉淀难。团队里某个老手总结了一套特别好用的分析方法以前只能靠文档或者口头传授现在可以封装成 skill变成团队共享的能力资产。适合谁来学我的判断是只要你在日常工作中频繁使用 AI 工具并且有某个垂直领域的重复性任务就值得花时间了解 skills。前端开发者可以用它来规范代码审查流程数学建模选手可以用它来固化建模套路内容创作者可以用它来统一文章风格。门槛没有想象中那么高但想写好一个真正好用的 skill确实需要一些方法论。2. 核心机制拆解SKILL.md 里到底写了什么2.1 一个 skill 的基本结构长什么样很多人第一次打开一个 skill 仓库看到的就是一个文件夹加一个 SKILL.md 文件心里会犯嘀咕就这么简单实际上这个 Markdown 文件承担了“技能说明书 执行脚本 质量检查表”三重角色。我拆过十几个不同领域的 skill结构上大同小异但写得好的和写得差的效果差距非常明显。一个完整的 SKILL.md 通常包含以下几个部分。元信息区放在文件最前面用 YAML front matter 的格式声明技能名称、描述、触发关键词、适用场景。这部分决定了 AI 什么时候会想起调用这个技能。角色定义区告诉 AI 在这个技能里应该扮演什么角色比如“你是一名资深数学建模教练”或者“你是一名前端代码审查专家”。执行流程区是核心把任务拆成有序的步骤每一步写清楚输入、操作、输出。约束与禁忌区列出不能做的事情比如“不要使用超过三阶的微分方程”“不要生成超过 200 行的代码块”。输出规范区定义最终结果的格式包括标题层级、表格样式、代码块语言标注等。我见过一个写得特别讲究的数学建模 skill它在执行流程里把“审题→选模型→定参数→写代码→验证→写论文”六个阶段全部展开每个阶段下面又列了 3 到 5 个检查点。比如选模型阶段它会要求 AI 先列出至少三种候选模型然后从数据需求、计算复杂度、结果可解释性三个维度做对比最后给出推荐理由。这种颗粒度才是 skill 真正有价值的地方。2.2 触发机制AI 怎么知道该用哪个 skill这是很多人容易忽略的一个设计点。skill 不是你想让它触发就能触发的它依赖一套匹配逻辑。目前主流的做法有两种关键词匹配和语义匹配。关键词匹配比较简单粗暴就是在元信息里列出触发词比如“数学建模”“建模比赛”“论文格式”用户输入里包含这些词的时候AI 就考虑加载对应的 skill。这种方式的好处是可控性强坏处是容易漏触发或者误触发。语义匹配则依赖 AI 自己的理解能力根据用户意图来判断该不该调用某个技能。这种方式更灵活但对 skill 的描述质量要求很高。我的经验是两者结合最稳。在元信息里既写关键词也写一段自然语言的场景描述。比如“当用户需要完成数学建模竞赛题目包括审题、建模、求解、论文撰写等环节时使用本技能。”这样 AI 在判断的时候有更多依据触发准确率会明显提升。还有一个细节值得注意skill 的优先级和互斥关系。如果你同时装了好几个功能相近的 skillAI 可能会犯迷糊。我建议在元信息里加一个priority字段或者在描述里写清楚“本技能优先于通用对话模式”。有些团队还会在 skill 里加一条规则“如果用户明确要求不使用技能则直接以普通模式回答。”这种兜底逻辑能避免很多尴尬。2.3 为什么是 Markdown 而不是代码这个问题我被问过好几次。用 Markdown 写 skill本质上是因为AI 对自然语言的理解能力已经足够强不需要用严格的代码结构来约束它。Markdown 的好处是写起来快、改起来方便、非技术人员也能看懂。你不需要会写 Python 或者 JavaScript只要能把一件事的流程说清楚就能写出一个可用的 skill。但这不意味着 Markdown 就是随便写。恰恰相反写得好的 SKILL.md 需要极高的逻辑严密性。因为 AI 会严格按照你写的步骤来执行如果步骤之间有歧义、有遗漏、有矛盾输出结果就会出问题。我踩过的一个坑是在某个 skill 里写了“根据数据特点选择合适的模型”但没有定义“数据特点”具体指哪些维度。结果 AI 每次选模型的标准都不一样有时候看样本量有时候看特征数有时候看分布形态导致同一个任务跑三次出来三个不同的模型。后来我改成“根据以下三个维度选择模型样本量是否大于 1000、特征是否线性可分、目标变量是否连续。每个维度给出判断依据和对应的模型推荐。”这样一改输出就稳定多了。所以我的体会是写 skill 的过程其实就是把你脑子里那套“默认知道但说不清楚”的经验逼着自己显性化、结构化的过程。3. 从零手写一个 skill完整实操流程3.1 准备工作环境与工具选型在动手写之前你需要先确定自己的使用环境。目前支持 skills 的主流工具包括 Claude Code、Claude Desktop、以及一些开源社区维护的 CLI 工具。不同工具的安装方式和 skill 加载路径不太一样我分别说一下。Claude Code是目前最常用的选择它是一个命令行工具安装方式根据操作系统有所不同。Windows 用户需要注意某些版本可能需要启用虚拟机平台相关的系统功能才能正常运行。安装完成后你可以通过claude --version来验证是否成功。如果提示“无法将 claude 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”说明环境变量没有配置好需要手动把安装路径加到 PATH 里。Claude Desktop是桌面版应用适合不习惯命令行的用户。它的 skill 管理界面更直观可以直接在设置里看到已加载的技能列表。不过桌面版的 skill 加载路径和 CLI 版不一样通常放在用户目录下的.claude/skills文件夹里。VS Code 集成是另一个常见场景。你可以在 VS Code 里安装 Claude Code 扩展然后在项目根目录下创建.claude/skills文件夹把 SKILL.md 放进去。这样在编辑器里就能直接调用技能不用切换到终端。提示不管你用哪种工具skill 文件的存放路径一定要确认清楚。我见过有人把 SKILL.md 放在桌面然后纳闷为什么 AI 不加载。正确的做法是放在工具指定的 skills 目录下或者通过配置项显式指定路径。3.2 确定技能边界一个 skill 只做一件事这是我在写了几个 skill 之后最大的感悟。新手最容易犯的错误就是试图用一个 skill 解决所有问题。比如有人写一个“全能写作助手”skill里面既包含技术文档写作又包含营销文案生成还包含学术论文润色。结果 AI 每次加载这个 skill 都要处理一大堆互相冲突的规则输出质量反而下降。正确的做法是按任务类型拆分。如果你既需要写技术文档又需要写营销文案那就写两个 skill分别叫tech-doc-writer和marketing-copywriter。每个 skill 只关注一类任务规则可以写得更细、更精准。AI 在匹配的时候也更容易判断该用哪个。那怎么判断一个 skill 的边界是否合理我的标准是如果你能用一句话说清楚这个 skill 的输入和输出那它的边界就是清晰的。比如“输入是一道数学建模题目输出是一篇符合竞赛格式的论文”这就是一个清晰的边界。如果一句话说不清楚说明这个 skill 太宽泛了需要继续拆。3.3 编写 SKILL.md逐段拆解与示例下面我以一个“数学建模竞赛论文写作”skill 为例逐段说明怎么写。这个 skill 的目标是用户给出一道建模题目AI 按照标准流程完成审题、建模、求解、论文撰写。元信息区这样写--- name: math-modeling-paper description: 数学建模竞赛论文写作技能适用于全国大学生数学建模竞赛、美国大学生数学建模竞赛等场景 trigger_keywords: - 数学建模 - 建模比赛 - 建模论文 - 竞赛论文 priority: high ---这里的关键是description要写清楚适用场景trigger_keywords要覆盖用户可能用的各种说法。priority设为 high 是因为建模论文写作是一个高度专业化的任务不应该被通用对话模式覆盖。角色定义区## 角色 你是一名拥有十年以上数学建模竞赛指导经验的教练熟悉各类建模方法优化、统计、微分方程、图论、机器学习等擅长将复杂实际问题转化为数学模型并能按照竞赛论文规范输出完整解答。角色定义的作用是给 AI 一个明确的身份锚点。有了这个锚点AI 在后续生成内容时会自动调整语气、深度和专业度。我试过不写角色定义直接写流程结果 AI 的输出风格飘忽不定有时候像教科书有时候像博客。加上角色定义之后风格就稳定多了。执行流程区是重头戏我把它拆成六个阶段## 执行流程 ### 阶段一审题与背景分析 1. 通读题目提取关键信息问题背景、已知条件、待求目标、约束条件 2. 判断问题类型优化类、预测类、评价类、分类类、机理分析类 3. 输出审题报告包含问题重述、关键假设、符号说明 ### 阶段二模型选型与对比 1. 针对问题类型列出至少三种候选模型 2. 从数据需求、计算复杂度、结果可解释性三个维度对比 3. 给出推荐模型及理由 ### 阶段三模型建立与求解 1. 写出模型的数学表达式包括目标函数和约束条件 2. 说明求解方法解析法、数值法、启发式算法等 3. 给出求解步骤和关键参数设置 ### 阶段四结果验证与灵敏度分析 1. 对求解结果进行合理性检验 2. 对关键参数做灵敏度分析 3. 讨论模型的优缺点和适用范围 ### 阶段五论文撰写 1. 按照摘要、问题重述、模型假设、符号说明、模型建立、模型求解、结果分析、模型评价、参考文献的结构撰写 2. 摘要控制在 300 字以内包含方法、结果、结论三要素 3. 公式使用 LaTeX 格式图表编号规范 ### 阶段六质量检查 1. 检查论文是否回答了题目所有问题 2. 检查公式符号是否前后一致 3. 检查图表是否有标题和单位这个流程的颗粒度是我反复调整后的结果。太粗了 AI 会偷懒太细了 AI 会机械执行。每个阶段 3 到 5 个步骤每个步骤有明确的输出物这个粒度比较合适。约束与禁忌区## 约束 - 不要使用超过三阶的微分方程除非题目明确要求 - 不要生成超过 200 行的代码块长代码拆分成多个片段 - 不要编造数据所有数据必须来自题目或公开可查的来源 - 不要使用“显然”“易得”等跳过推导的表述 - 论文中不要出现第一人称“我”统一使用“本文”这些约束看起来琐碎但每一条都是我踩坑之后加上的。比如“不要编造数据”这条是因为有一次 AI 在求解过程中自己造了一组“合理”的数据来演示结果用户以为那是真实结果。加上这条约束之后AI 会明确标注哪些是题目数据、哪些是假设数据。输出规范区## 输出规范 - 论文标题使用二级标题章节使用三级标题 - 公式使用 $$...$$ 包裹行内公式使用 $...$ - 表格使用 Markdown 表格必须有表头和单位 - 代码块标注语言类型 - 参考文献使用 GB/T 7714 格式输出规范的作用是让结果直接可用。没有这个规范AI 输出的格式每次都不一样你还要手动调整。加上之后基本可以复制粘贴直接交。3.4 测试与迭代怎么判断一个 skill 写得好不好写完 SKILL.md 只是第一步真正的功夫在测试和迭代。我的做法是准备三到五个测试用例覆盖典型场景和边界场景然后观察 AI 的输出是否符合预期。测试用例的设计有讲究。以数学建模 skill 为例我会准备一道优化类题目、一道预测类题目、一道评价类题目、一道数据不完整的题目、一道有多个小问的题目。每次修改 skill 之后把这五个用例跑一遍记录输出质量的变化。判断标准我通常看四个维度完整性是否覆盖了所有要求、一致性同一类任务的输出结构是否稳定、准确性专业内容是否有明显错误、可读性格式是否规范、表达是否清晰。四个维度里一致性是最难做到的也是最考验 skill 设计功力的。迭代的时候我建议每次只改一个地方。比如这次只调整模型选型阶段的对比维度下次只修改论文结构的章节顺序。这样你能清楚地知道哪个改动带来了什么效果。如果一次改好几个地方输出变好了你也不知道是哪个改动起了作用变差了更找不到原因。4. 进阶玩法让 skills 真正融入工作流4.1 多 skill 协作串联与并联单个 skill 能解决的问题有限真正强大的玩法是多个 skill 协作。我目前的做法分两种模式串联和并联。串联模式适合有先后依赖的任务。比如“数据清洗 skill → 特征工程 skill → 模型训练 skill → 结果可视化 skill”前一个的输出是后一个的输入。这种模式下每个 skill 的输出规范要严格对齐否则下游 skill 会拿到格式混乱的数据。我的经验是在每个 skill 的输出规范里明确写清楚“输出格式必须为 JSON/CSV/Markdown 表格”并且给出示例。并联模式适合可以同时进行的任务。比如写一篇技术文章可以同时调用“资料搜集 skill”“大纲生成 skill”“案例整理 skill”三个 skill 各自输出一部分内容最后再合并。这种模式的关键是避免内容冲突我通常会在合并阶段加一个“一致性检查 skill”专门用来发现和解决矛盾之处。注意多 skill 协作时加载顺序会影响结果。我建议在配置里显式指定 skill 的加载优先级或者在每个 skill 的元信息里写明“本技能应在 XX 技能之后加载”。4.2 团队共享把个人经验变成组织资产Skills 最大的价值之一就是把个人经验沉淀成团队可复用的资产。我们团队现在的做法是每个人把自己擅长的领域写成 skill放到共享仓库里其他人可以直接拉取使用。但这里有个管理问题skill 多了之后怎么保证质量我们的做法是建立一套 review 机制。每个新 skill 提交后至少两个人用标准测试用例跑一遍确认输出质量达标才能合并。同时每个 skill 都要写一个CHANGELOG.md记录每次修改的内容和原因。这样当某个 skill 出问题的时候可以快速定位是哪次改动引入的。还有一个细节skill 的命名规范。我们统一使用“领域-任务-版本”的格式比如math-modeling-paper-v2、frontend-code-review-v1。这样一眼就能看出这个 skill 是干什么的也方便管理版本。4.3 常见误区与避坑指南在推广 skills 的过程中我见过不少典型的误区这里集中说一下。误区一把 skill 当成 prompt 模板。这是最常见的误解。Prompt 模板是一段静态文本你复制粘贴给 AI 就行。Skill 是一个动态的执行框架它包含流程控制、条件判断、质量检查。两者的设计思路完全不同。如果你只是把以前的 prompt 改个名字叫 skill效果不会有什么提升。误区二追求大而全。前面说过一个 skill 只做一件事。但很多人还是忍不住往里面塞东西结果 skill 越来越臃肿AI 加载之后反而不知道该听哪条规则。我的建议是如果一个 skill 的 SKILL.md 超过 500 行就该考虑拆分了。误区三写完就不管了。Skill 不是一劳永逸的东西。AI 模型在更新你的业务需求在变化skill 也需要持续迭代。我建议至少每个月 review 一次常用 skill看看有没有需要调整的地方。误区四忽略测试。很多人写完 skill 直接就用出了问题再改。这种“边用边改”的方式效率很低因为你在真实任务中发现问题的时候往往已经浪费了不少时间。花半个小时准备测试用例能省下后面好几个小时的调试时间。5. 常见问题排查与实战技巧实录5.1 安装与加载类问题问题Claude Code 安装后提示命令不存在。这个问题的原因通常是环境变量没有配置好。Windows 用户可以在“系统属性 → 高级 → 环境变量”里把 Claude Code 的安装路径加到 Path 变量中。macOS 和 Linux 用户可以在.bashrc或.zshrc里加一行export PATH$PATH:/path/to/claude然后执行source ~/.bashrc生效。如果还是不行检查一下安装路径里有没有空格或特殊字符这些有时候会导致路径解析失败。问题SKILL.md 放对了位置但 AI 不加载。先确认文件命名是否正确必须是SKILL.md大小写敏感。然后检查元信息区的 YAML 格式有没有语法错误比如冒号后面少了空格、缩进不一致等。YAML 对格式要求很严格一个小错误就可能导致整个文件解析失败。我建议用在线 YAML 校验工具先验证一遍。问题多个 skill 冲突AI 不知道用哪个。在元信息里加priority字段数值越高优先级越高。或者在 skill 描述里写清楚适用场景的边界比如“本技能仅适用于数学建模竞赛不适用于日常数据分析”。如果冲突实在严重可以考虑在配置里手动指定当前会话使用哪个 skill。5.2 输出质量类问题问题AI 不按照 SKILL.md 里的流程执行。这种情况通常是因为流程写得太抽象AI 理解不了。比如“根据数据特点选择合适的模型”这种表述AI 每次的理解都不一样。改成“根据以下三个维度选择模型样本量、特征维度、目标变量类型每个维度给出判断依据和对应推荐”执行就稳定多了。流程步骤要具体到“做什么、怎么做、输出什么”不能有模糊空间。问题输出格式每次都不一样。检查输出规范区是否写清楚了格式要求。如果写了但还是不稳定可以在流程的最后加一个“格式检查”步骤让 AI 自己检查一遍输出是否符合规范。另外给出一个完整的输出示例也很有效AI 会参照示例的格式来生成。问题AI 在 skill 执行过程中“偷懒”跳过某些步骤。这是很常见的问题。解决方法是在约束区加一条“必须完成所有阶段不得跳过任何步骤。如果某个步骤因信息不足无法完成明确说明原因并请求补充信息。”另外把每个步骤的输出物定义清楚AI 为了生成输出物就不太容易跳过了。5.3 性能与效率类问题问题skill 加载太慢影响使用体验。SKILL.md 文件太大的话加载确实会慢。我的建议是控制在 300 行以内超过就拆分。另外把不常用的参考内容放到单独的文件里在 SKILL.md 里用链接引用而不是全部写进去。问题同一个 skill 在不同任务上表现差异很大。这说明 skill 的适用范围定义得太宽了。检查一下元信息里的description和trigger_keywords是不是覆盖了太多不同类型的任务。如果是考虑拆分成多个更专精的 skill。5.4 实战技巧速查表问题类型典型表现排查方向解决手段安装失败命令找不到环境变量、安装路径配置 PATH检查路径字符加载失败AI 不调用 skill文件命名、YAML 格式校验 YAML确认路径流程跳步输出不完整步骤描述太抽象细化步骤加约束格式混乱每次输出不一样输出规范不明确加格式检查给示例触发错误该用的没用不该用的用了关键词和描述不准确调整触发词加优先级性能下降加载慢、响应慢文件太大拆分 skill外链参考内容最后分享一个我个人的小技巧给每个 skill 建一个“测试用例”文件夹里面放三到五个典型输入和对应的期望输出。每次修改 skill 之后跑一遍测试用例对比输出变化。这个习惯帮我省了大量调试时间也让我对每个 skill 的能力边界有更清晰的认识。6. 不同场景下的 skills 应用思路6.1 前端开发场景前端开发是 skills 应用比较成熟的领域。我见过几个写得不错的前端 skill覆盖了代码审查、组件生成、性能优化、样式规范等环节。以代码审查为例一个好的 skill 会定义清楚检查项命名规范、类型安全、边界条件处理、性能隐患、可访问性等。每个检查项下面列出具体的判断标准和修改建议。前端 skill 的一个特殊之处是需要处理多种文件类型。一个组件可能涉及.tsx、.css、.test.ts等多个文件。我的做法是在 skill 里定义一个“文件关联规则”告诉 AI 当修改某个组件时需要同时检查哪些关联文件。这样可以避免只改了一个文件、漏掉其他文件的问题。6.2 数学建模场景数学建模是 skills 的另一个热门应用场景。前面已经详细讲过论文写作 skill 的写法这里补充一下建模求解 skill的设计思路。这类 skill 的核心是把“从问题到模型”的转化过程标准化。我通常会在 skill 里内置一个“模型库”列出常见问题类型和对应的推荐模型比如优化问题对应线性规划、整数规划、动态规划预测问题对应回归分析、时间序列、灰色预测等。建模 skill 还有一个特殊需求代码生成与验证。AI 生成的求解代码需要能实际运行并且结果要合理。我会在 skill 里加一个“代码验证”步骤要求 AI 生成代码后自己检查语法错误、边界条件、数值稳定性并给出预期结果的量级范围。6.3 内容创作场景内容创作类的 skill 更注重风格一致性和结构规范。我写过一个技术文章写作 skill核心是定义清楚文章的结构模板、语言风格、术语使用规范。比如“每段不超过 5 行”“专业术语首次出现时给出解释”“代码示例必须可运行”等。这类 skill 的一个难点是如何平衡规范性和灵活性。规范太死文章会显得僵硬规范太松风格又会飘。我的经验是结构层面严格规范表达层面给一定自由度。比如规定“必须包含问题背景、解决方案、实操步骤、注意事项四个部分”但每个部分怎么写、用什么语气让 AI 根据内容自行判断。7. 我个人的一些实践体会写了这么多 skill踩了这么多坑如果让我总结几条最重要的经验大概是下面这几条。第一从最小可用版本开始。不要一上来就写一个覆盖全流程的大 skill先写一个只解决单一环节的小 skill跑通了再逐步扩展。我最早写的一个 skill 只有 50 行只做一件事把用户输入的需求拆解成任务清单。就这么简单的功能跑通之后给了我很大信心也让我理解了 skill 的基本运作方式。第二把测试当成写 skill 的一部分。我现在写 skill 的时间分配大概是写 SKILL.md 占 40%准备测试用例占 20%跑测试和迭代占 40%。测试不是写完之后的附加步骤而是写作过程的一部分。很多时候正是在设计测试用例的时候我才发现自己对某个步骤的定义不够清晰。第三关注 AI 的“理解偏差”。AI 不是人它对你的指令的理解方式和人不一样。你觉得说得很清楚的地方它可能理解成另一个意思。所以写完 skill 之后一定要实际跑几遍观察 AI 的执行过程看看它在哪些地方出现了偏差。这些偏差点就是你下一步优化的方向。第四保持 skill 的“可读性”。Skill 不仅是给 AI 看的也是给人看的。团队协作的时候其他人需要能看懂你的 skill 在做什么、怎么改。所以我在写 SKILL.md 的时候会尽量用清晰的结构、明确的标题、适当的注释。一个让人看不懂的 skill很难被有效维护和迭代。第五不要追求完美。我见过有人花了好几天打磨一个 skill试图覆盖所有可能的边界情况。结果 skill 变得极其复杂AI 反而执行不好。我的建议是先覆盖 80% 的常见场景剩下的 20% 在遇到的时候再补充。Skill 是活的可以持续迭代不需要一次做到完美。最后说一个我最近在尝试的方向把 skill 和知识库结合起来。Skill 负责定义流程和规范知识库负责提供领域知识和参考案例。两者配合可以让 AI 在专业领域的表现再上一个台阶。这个玩法我还在摸索阶段等跑通了再单独写一篇分享。