1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题很多人会一头雾水。它太泛了泛到像是一个占位符。但结合热搜词里高频出现的 Claude、Agent Skills、SKILL.md、Claude Code 这些词方向就清晰了——这里说的 skills指的是围绕 AI 编程助手尤其是 Claude Code 这类命令行 Agent 工具构建的技能包体系也就是用一份结构化的 SKILL.md 文件把某类任务的处理方法、工具调用、判断逻辑固化下来让 AI 在遇到对应场景时能自动加载并执行。说白了skills 就是给 AI 助手准备的操作手册 工具箱。你平时怎么教一个新同事干活先告诉他这类任务的目标是什么再告诉他有哪些工具可以用然后给出几个典型场景的处理流程最后提醒他哪些坑不能踩。skills 干的就是这件事只不过对象从人换成了 AI。为什么这个东西最近热度这么高因为大家发现光靠一个通用大模型它在具体领域里的表现经常差一口气。你让它写个数学建模的代码它可能给你一堆看起来对但跑不通的东西你让它处理前端工程化配置它可能忽略你项目里已有的约定。skills 的价值就在于把这些领域知识、项目约定、工具链细节提前喂给 AI让它从通用助手变成懂行的专家。这篇文章适合谁看如果你是刚接触 Claude Code 或者类似 AI 编程工具的新手想搞清楚 skills 是什么、怎么装、怎么写那这篇能给你一条完整的路径。如果你已经在用这类工具但觉得效果不稳定、想通过 skills 来提升输出质量那这篇里的实操细节和踩坑经验应该对你有用。如果你只是听说过这个词想了解个大概那看完前两节你就能建立基本认知。需要先说明一点skills 这个概念本身还在快速演进中不同工具、不同平台对它的实现方式有差异。下面讲的内容是基于当前主流实践以 Claude Code 的 Agent Skills 体系为主的梳理具体到你用的版本细节可能有出入但核心逻辑是通的。2. skills 的底层逻辑为什么一份 Markdown 文件能改变 AI 的表现2.1 SKILL.md 的本质是一份上下文注入协议很多人第一次看到 SKILL.md 会觉得奇怪就一个 Markdown 文件凭什么能让 AI 变聪明要理解这个得先明白大模型的工作方式。模型本身是一个无状态的推理引擎它每次回答问题时能依赖的只有当前上下文窗口里的内容。你给它什么信息它就在什么范围内思考。skills 的本质就是在合适的时机把合适的信息塞进这个上下文窗口。SKILL.md 里通常包含几类内容技能的名称和描述告诉 AI 这个技能是干什么的、触发条件什么情况下该用这个技能、具体步骤一步步怎么做、可用工具能调用哪些命令或 API、注意事项哪些情况要小心。当 AI 判断当前任务匹配某个技能的触发条件时它就会把这份文件的内容加载进来作为自己行动的指导。这就像你给一个外包工程师发需求文档。文档写得越清楚他交付的东西越接近你的预期。SKILL.md 就是给 AI 的需求文档只不过格式更结构化而且能被自动检索和加载。2.2 为什么是 Markdown 而不是代码这里有个设计选择值得说为什么 skills 用 Markdown 而不是 JSON、YAML 或者某种专门的 DSL因为 Markdown 对模型最友好。大模型在训练时见过海量的 Markdown 文本它对这种格式的理解能力最强。你用自然语言加简单的结构标记模型能准确抓住重点。而如果用严格的代码格式反而可能因为格式错误导致解析失败或者让模型把注意力放在语法上而不是内容上。另一个原因是可读性。skills 不只是给机器看的也是给人看的。你写了一个技能团队里其他人要能看懂、能改、能复用。Markdown 在这方面几乎没有门槛。一个前端工程师、一个数据分析师、一个产品经理都能直接读和写。2.3 技能加载的时机与优先级skills 不是一股脑全塞进上下文的那样会撑爆窗口。实际运行时AI 会先看当前任务然后从可用的技能库里检索匹配的技能。这个检索过程可能基于关键词匹配也可能基于语义相似度。匹配到之后再把对应 SKILL.md 的内容加载进来。这里有个关键点技能的描述写得准不准直接决定了它能不能被正确触发。如果你把描述写得太窄AI 遇到稍微变形的任务就匹配不上写得太宽又会在不相关的场景里被误触发浪费上下文还干扰判断。这个平衡需要在实际使用中反复调。3. 从零装起Claude Code 与 skills 的安装配置实操3.1 环境准备绕开那些让人抓狂的报错安装 Claude Code 本身不算复杂但新手最容易卡在环境问题上。热搜词里出现的那些报错——无法将 claude 项识别为 cmdlet、requires the virtual machine platform on windows——基本都是环境没配好导致的。先说 Windows 平台。如果你在 PowerShell 里敲claude提示无法识别为 cmdlet说明要么没装要么装了但没加到 PATH 里。Claude Code 是通过 npm 分发的所以第一步是确认 Node.js 装好了。打开终端敲node -v能输出版本号才行。如果没装去 Node.js 官网下 LTS 版本安装时记得勾选Add to PATH。装好 Node 之后用 npm 全局安装npm install -g anthropic-ai/claude-code装完再敲claude --version能出版本号就说明成功了。如果还是提示找不到命令检查一下 npm 的全局 bin 目录有没有在 PATH 里。Windows 上通常是%APPDATA%\npmMac/Linux 上是/usr/local/bin或~/.npm-global/bin。至于virtual machine platform那个报错通常出现在 Windows 上跑某些依赖 WSL2 的组件时。解决办法是在启用或关闭 Windows 功能里勾选虚拟机平台和适用于 Linux 的 Windows 子系统然后重启。这个不是 Claude Code 本身的要求而是它某些依赖项的需要。提示如果你所在的环境访问 npm 官方源不稳定可以配置国内镜像源比如npm config set registry https://registry.npmmirror.com。这个操作只影响包下载速度不涉及其他。3.2 安装 skills手动装 GitHub 上的技能包Claude Code 本身自带一些基础能力但 skills 生态里的很多技能包是社区贡献的托管在 GitHub 上。热搜里有人问claude code 怎么手动装 github 上的 skills这里给一个通用流程。大多数 skills 仓库的结构是这样的根目录下有一个skills文件夹里面每个子文件夹是一个独立技能每个技能文件夹里有一个SKILL.md。安装方式通常有两种第一种是直接把技能文件夹复制到 Claude Code 的技能目录下。这个目录一般在~/.claude/skills/Mac/Linux或%USERPROFILE%\.claude\skills\Windows。你把从 GitHub 克隆下来的技能文件夹整个拷进去就行。git clone https://github.com/某用户/某skills仓库.git cp -r 某skills仓库/skills/* ~/.claude/skills/第二种是有些技能包提供了安装脚本你按照它的 README 跑一下就行。但要注意跑别人的脚本前最好先看一眼脚本内容确认没有奇怪的操作。装完之后重启 Claude Code或者用它的技能列表命令确认一下技能有没有被识别到。不同版本的命令可能不一样常见的是/skills或者claude skills list。3.3 验证安装怎么确认技能真的生效了装完不代表生效。你得验证一下。最简单的办法是找一个该技能应该触发的场景看 AI 的行为有没有变化。比如你装了一个数学建模技能那就给它一个建模题目观察它是不是按照技能里定义的流程在走——有没有先做问题分析、有没有按步骤选模型、有没有给出可运行的代码。如果行为没变化排查顺序是先确认技能文件在不在正确目录、文件名是不是SKILL.md大小写敏感、文件内容格式对不对有没有正确的 frontmatter、然后看 Claude Code 的日志里有没有加载技能的记录。注意有些技能包依赖特定的工具或环境比如需要 Python 某个版本、需要某个命令行工具。装技能的时候顺手看一眼它的依赖说明能省掉很多装了没反应的困惑。4. 自己写一个 SKILL.md从需求到可复用技能4.1 先想清楚什么任务值得做成技能不是所有事情都值得写成 skill。判断标准很简单这个任务是不是会重复出现而且每次的处理逻辑基本一致。如果是那就值得固化。如果是一次性的、每次都要重新判断的那写成技能反而累赘。举个例子。把一段中文翻译成英文这种任务通用模型就能干得不错没必要专门写技能。但按照我们团队的代码规范审查一个 React 组件这种任务涉及具体的规范条目、具体的检查项、具体的输出格式就非常适合做成技能。因为每次审查的逻辑是一样的而且通用模型不知道你们团队的规范。再比如热搜里提到的数学建模 skills、AI 漫剧常用 skills、STM32 开发 skills这些都是典型的领域任务——有固定的方法论、有常用的工具链、有反复出现的坑。把这些沉淀成技能收益很明显。4.2 SKILL.md 的结构一份可抄的模板一个结构清晰的 SKILL.md 通常包含这几块--- name: 技能名称 description: 一句话说明这个技能做什么、什么时候用 --- # 技能标题 ## 适用场景 描述什么情况下应该使用这个技能。 ## 前置条件 使用这个技能需要什么环境、工具、依赖。 ## 操作步骤 1. 第一步做什么 2. 第二步做什么 3. ... ## 可用工具 - 工具A用来做什么 - 工具B用来做什么 ## 注意事项 - 哪些情况要小心 - 哪些做法是错的frontmatter 里的name和description最关键因为 AI 主要靠这两个字段来判断要不要加载这个技能。description 要写得具体包含触发关键词但不要堆砌。4.3 描述字段的写法决定技能能否被正确触发description 是技能的广告语它要在几十个字里说清楚三件事这个技能解决什么问题、适用于什么场景、有什么特别之处。差的写法这是一个处理数据的技能。——太泛AI 不知道什么时候该用。好的写法当需要对 CSV 或 Excel 格式的表格数据进行清洗、去重、格式转换时使用。适用于数据预处理阶段支持缺失值处理和类型推断。——具体包含了触发场景CSV/Excel 数据清洗、适用阶段数据预处理、能力边界缺失值、类型推断。写 description 的时候可以想象你在跟一个同事口头介绍这个技能。你会怎么说哦这个啊就是当你拿到一堆乱七八糟的表格数据想快速清理一下的时候用的它能处理空值、重复行、还有格式不统一的问题。把这段话精炼一下就是不错的 description。4.4 步骤设计让 AI 能一步步跟着走步骤部分要避免两个极端太粗和太细。太粗了 AI 不知道怎么执行太细了又限制了它的灵活性。一个好的做法是按决策点来组织步骤而不是按操作来组织。比如写一个代码审查技能不要写第一步打开文件第二步看第 10 行第三步...而是写第一步确认审查范围是整个模块还是单个文件第二步按规范检查命名和结构第三步检查边界条件处理第四步检查错误处理是否完整。每个步骤里可以包含判断逻辑如果发现使用了 any 类型标记为需要修复如果是第三方库的类型定义问题标记为可忽略。这种条件分支能让 AI 在具体场景下做出合理判断。5. 技能库的日常维护清理、更新与冲突处理5.1 技能不是越多越好装了一堆技能之后你可能会发现 AI 的表现反而下降了。原因很简单技能太多检索时容易匹配到不相关的技能把上下文搞乱。而且有些技能之间可能有重叠或冲突AI 不知道该听谁的。热搜里有人问tibo 关于清理 skills 的方法推荐说明这个问题很普遍。清理的原则是只保留当前项目或当前工作流真正需要的技能。你可以按项目建不同的技能目录切换项目时切换技能集。或者定期审查把三个月没用过的技能归档。5.2 识别技能冲突当两个技能给出矛盾指令技能冲突的典型表现是AI 在同一个任务上反复横跳一会儿按 A 技能的方式做一会儿按 B 技能的方式做。这通常是因为两个技能的触发条件有重叠而且给出的指令不一致。解决办法是给技能加更明确的边界。比如两个技能都涉及代码生成那就把其中一个的 description 改得更具体限定在特定语言或特定框架。或者在技能内容里加一句如果同时匹配到其他代码生成技能优先使用本技能。排查冲突的时候可以临时禁用一半技能看问题是否消失逐步缩小范围。这个过程跟排查软件冲突是一个思路。5.3 版本更新技能也会过时技能包跟软件一样会随着工具链更新而过时。一个半年前写的技能里面引用的命令可能已经改了依赖的库可能已经升级了。定期更新技能包是必要的。如果你是从 GitHub 克隆的技能用git pull拉最新版就行。如果是自己写的建议也放到版本控制里每次工具链有变动时检查一下相关技能是否需要调整。提示更新技能前先备份当前能用的版本。有时候新版本反而引入了问题能快速回滚很重要。6. 不同场景下的 skills 实战从数学建模到前端开发6.1 数学建模场景把方法论固化成技能数学建模是个典型的有固定套路但细节繁多的领域。从问题分析、模型选择、算法实现到论文写作每个环节都有成熟的方法。热搜里数学建模 skills 推荐、华为杯建模比赛好用的 codex skills这些词说明很多人希望把这套流程固化下来。一个数学建模技能可以这样设计description 写当需要解决数学建模竞赛题目或实际优化问题时使用涵盖问题分析、模型选型、求解实现、结果验证四个阶段。步骤部分按这四个阶段展开每个阶段给出常用的模型和工具。比如问题分析阶段提示 AI 先判断是优化问题、预测问题还是评价问题模型选型阶段根据问题类型推荐线性规划、回归分析、层次分析法等求解实现阶段指定用 Python 的 scipy、sklearn 等库结果验证阶段要求做灵敏度分析。注意事项里可以写不要一上来就套复杂模型先尝试简单方法所有假设要明确写出代码要能直接运行不要留占位符。这些都是建模老手才知道的坑。6.2 前端开发场景项目约定比通用知识更重要前端开发的 skills 重点不在教 AI 怎么写 React 或 Vue——这些它本来就会——而在于告诉它你们项目的具体约定。比如目录结构怎么组织、组件命名用什么风格、状态管理用哪个库、样式方案是 CSS Modules 还是 Tailwind、API 请求封装在哪个文件。一个前端项目技能可以包含项目结构说明哪个目录放什么、代码规范命名、注释、导入顺序、常用命令启动、构建、测试、组件模板新建组件时应该长什么样。把这些写清楚AI 生成的代码就能直接融入项目而不是需要你手动改半天。热搜里前端开发 skills、typesafe ai skills github这些词反映的就是这种需求。大家想要的不是通用前端知识而是能直接对接自己项目的技能。6.3 嵌入式与硬件场景STM32 技能的特殊性嵌入式开发跟纯软件不一样它涉及硬件寄存器、时序、中断这些底层概念。热搜里出现claude code stm32说明有人在做这方面的尝试。STM32 技能的设计要点是把常用的外设初始化流程、中断处理模板、通信协议实现I2C、SPI、UART固化下来。description 可以写当需要为 STM32 系列 MCU 编写外设驱动或通信代码时使用涵盖 GPIO、定时器、中断、I2C、SPI、UART。步骤里给出标准初始化流程注意事项里强调时钟配置、引脚复用、中断优先级这些容易出错的地方。这类技能的价值在于它能把老工程师的经验传递给 AI让 AI 生成的代码更接近实际可用的水平而不是停留在看起来对但跑不起来的阶段。7. 技能生态的现状与个人实践建议7.1 社区技能的质量参差不齐目前 skills 生态还处于早期社区贡献的技能质量差异很大。有些技能写得很扎实步骤清晰、边界明确、注意事项到位有些就是随便写了几句话实际用起来效果很差。挑选技能的时候可以看几个指标description 是否具体、步骤是否有决策逻辑、有没有注意事项、最近有没有更新。如果一个技能连 description 都写得很含糊那基本不用指望它的内容质量。7.2 从改别人的技能开始比从零写更容易如果你刚开始接触 skills不建议一上来就自己写。更好的路径是先装几个社区技能用起来然后挑一个跟你需求最接近的在它的基础上改。改的过程中你会逐渐理解 SKILL.md 的结构逻辑知道哪些地方该详细、哪些地方可以简略。改的时候注意保留原技能的框架只调整具体内容。这样即使改坏了也能对照原版找问题。7.3 技能要跟着工作流走而不是反过来最后一个建议不要让技能定义你的工作流而是让你的工作流决定需要什么技能。先观察自己日常工作中哪些任务重复度高、哪些环节容易出错、哪些知识需要反复解释然后针对这些点去建技能。这样建出来的技能才是真正有用的而不是为了建而建。我自己在实际操作中的体会是一个技能从写出来到真正好用通常要经过三四次迭代。第一版往往太理想化实际跑起来会发现 AI 的理解跟你的预期有偏差第二版补充了边界条件第三版调整了描述让触发更准第四版才基本稳定。所以别指望一次写好把它当成一个持续打磨的过程。另外技能文件里适当加一些反例很有用。比如在注意事项里写不要这样做XXX因为 YYY。AI 对负面示例的敏感度有时候比正面指令还高一个明确的反例能避免很多重复犯错。这个技巧是我踩了几次坑之后才总结出来的比单纯写要这样做效果好得多。