1. 从“skills”这个热词说起它到底是什么为什么突然火了最近几个月不管是在技术社区还是各种开发者群里“skills”这个词出现的频率高得离谱。如果你只是偶尔刷到可能会以为它说的是某种通用技能培训但只要你稍微往深了看一眼就会发现大家讨论的其实是Agent Skills——一套让 AI 编程助手从“能聊天”变成“能干活”的能力扩展机制。尤其是跟 Claude Code 这个终端里的 AI 编程工具绑在一起之后skills 几乎成了今年开发者圈子里最值得花时间研究的东西之一。我最早接触这个概念的时候也花了不少时间才把思路理清楚。简单来说skills 就是一组用 Markdown 写的指令文件放在特定目录下AI 助手在执行任务时会自动读取并按照里面的流程去操作。你可以把它理解成给 AI 写的一份“操作手册”以前你每次都要在对话里反复交代“先做 A 再做 B注意 C”现在你把这些写进一个SKILL.md文件里AI 在需要的时候就会自己去翻这份手册按你预设的步骤执行。这个变化听起来不大但实际用起来效率差距非常明显。那为什么偏偏是现在火起来了我的判断是三个因素叠加的结果。第一Claude Code 这类终端 AI 编程工具在过去半年里成熟度提升很快已经能稳定处理多步骤的工程任务这就给 skills 提供了落地的土壤。第二SKILL.md这种纯文本、纯 Markdown 的格式门槛极低不需要写代码、不需要编译、不需要配置复杂的运行环境任何人打开编辑器就能写。第三社区里已经有人把常用的 skills 整理成了可复用的技能库从数学建模到前端开发从代码审查到文档生成覆盖面越来越广新手可以直接拿来用不用从零开始。这篇文章适合谁看如果你是刚听说 Claude Code 和 skills、想搞清楚它们之间是什么关系的新手我会从最基础的概念和安装配置讲起如果你已经在用 Claude Code但还没认真研究过 skills 怎么写、怎么组织、怎么排查问题我会把实操流程和踩坑经验完整展开如果你关注的是数学建模、前端开发这类具体场景下的 skills 应用我也会给出对应的思路和参考方案。整篇内容基于我自己的实际使用和社区里的常见实践整理尽量做到看完就能上手。2. 核心概念拆解Agent Skills、SKILL.md 和 Claude Code 的关系2.1 Agent Skills 的本质给 AI 装上一套“可插拔的操作流程”要理解 Agent Skills先要理解一个前提AI 编程助手的能力上限很大程度上取决于你给它的上下文质量。你描述得越清楚、越结构化它执行得越准确。但问题是很多任务的操作流程是固定的、重复的比如“每次提交代码前先跑一遍 lint、再跑单元测试、然后检查是否有未处理的 TODO”你不可能每次都手动打一遍这些要求。Agent Skills 解决的就是这个问题。它把这些固定流程写成文件放在 AI 助手能读取的目录里当 AI 判断当前任务需要用到某个 skill 时它会自动加载对应的SKILL.md然后按照里面的步骤执行。这个过程不需要你手动触发也不需要你每次重复交代。从使用体验上来说就像你给 AI 配了一套“技能包”它在需要的时候自己会去调用。这里有一个关键点需要说清楚skills 不是代码插件也不是 API 接口它本质上就是自然语言写的指令文档。这意味着两件事。第一写 skills 不需要编程基础你只要能把自己的操作流程用清晰的文字描述出来就行。第二skills 的灵活度非常高你可以为任何重复性的任务写一个 skill不管是技术类的还是非技术类的。我见过有人给“每周周报生成”写 skill也有人给“数学建模论文格式检查”写 skill思路都是一样的。2.2 SKILL.md 的文件结构为什么 Markdown 是最合适的选择SKILL.md是 skills 的核心载体它的格式就是标准的 Markdown。你可能会问为什么不用 JSON、YAML 或者某种专门的配置格式我的理解是Markdown 在“人类可读”和“机器可解析”之间找到了最好的平衡点。AI 模型对 Markdown 的理解能力非常强标题层级、列表、代码块这些结构它都能准确识别同时你作为作者写起来也不需要关心缩进、转义、语法校验这些烦人的细节。一个典型的SKILL.md通常包含这几个部分。开头是一段简短的描述说明这个 skill 是做什么的、什么时候应该使用。然后是具体的操作步骤用有序列表或者分节的方式写清楚每一步要做什么。如果涉及命令或代码用代码块标注出来。最后可以附上注意事项和常见问题的处理方式。整个文件不需要很长我见过很多高效的 skill 只有几十行关键是把流程写清楚、把边界条件说明白。注意SKILL.md的文件名是固定的不能改成其他名字。AI 助手在扫描目录时就是按这个文件名去查找的。如果你写了一个 skill 但发现 AI 没有调用第一件事就是检查文件名是否正确。2.3 Claude Code 在其中的角色skills 的运行载体Claude Code 是 Anthropic 推出的终端 AI 编程工具它可以在命令行里直接运行读取你的项目文件、执行命令、修改代码。Skills 机制就是 Claude Code 的一个重要能力扩展点。当你在项目目录或者用户目录下放置了 skills 文件夹Claude Code 在启动时会扫描这些目录把可用的 skills 加载进来。当你在对话中提出的任务匹配到某个 skill 的描述时它就会自动读取并执行。这里有一个实际使用中很容易忽略的细节skills 的存放位置会影响它的作用范围。放在项目根目录下的.claude/skills/里这个 skill 只对当前项目生效放在用户主目录下的.claude/skills/里则对所有项目都生效。这个设计很合理因为有些 skill 是项目特定的比如这个项目的部署流程有些是通用的比如代码审查规范。我自己的做法是通用的 skill 放在用户目录项目特有的放在项目目录这样既方便复用又不会互相干扰。另外Claude Code 本身是一个需要在终端里运行的工具安装和配置有一些前置条件。在 Windows 上它需要虚拟化平台的支持在 macOS 和 Linux 上相对直接一些。安装方式通常是通过包管理器或者官方提供的安装脚本。具体的安装步骤我会在下一节详细展开这里先建立一个整体认知Claude Code 是载体skills 是内容两者配合才能发挥完整的效果。3. 从零开始Claude Code 安装与 skills 目录配置实操3.1 安装 Claude Code 的前置条件与平台差异在开始安装之前有几个前置条件需要确认。首先Claude Code 目前主要通过命令行使用所以你需要一个可用的终端环境。macOS 和 Linux 系统自带终端Windows 用户建议使用 WSL 或者 PowerShell 7 以上的版本。其次你需要一个 Anthropic 的账号并且确保你所在的地区支持该服务。如果启动时看到“Claude Code might not be available in your country”这类提示说明当前网络环境不在支持范围内这种情况没有绕过的方法只能等待官方扩展支持区域。安装方式根据平台有所不同。macOS 上可以通过 Homebrew 安装命令是brew install claude-code。Linux 上可以用 npm 全局安装命令是npm install -g anthropic-ai/claude-code。Windows 上如果使用 WSL步骤和 Linux 一样如果直接在 PowerShell 里安装需要先确保 Node.js 版本在 18 以上然后用同样的 npm 命令安装。安装完成后在终端输入claude命令如果能看到欢迎信息说明安装成功。提示如果你在 Windows 上看到“claude 无法将‘claude’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”这个报错通常是因为 npm 全局安装的路径没有加到系统环境变量里。解决办法是找到 npm 的全局安装目录可以用npm config get prefix查看把这个路径添加到 PATH 环境变量中然后重启终端。3.2 初始化配置与首次运行安装完成后第一次运行claude命令会进入初始化流程。它会引导你完成几个步骤登录账号、选择默认模型、确认工作目录。登录环节会打开浏览器进行授权授权完成后终端里会显示登录成功的提示。如果你是在远程服务器或者没有图形界面的环境里使用可以选择用 API Key 的方式认证在配置文件中填入你的 API Key 即可。初始化完成后Claude Code 会在你的用户主目录下创建一个.claude文件夹里面包含配置文件和 skills 目录。你可以用ls ~/.claude查看这个目录的结构。默认情况下skills 目录可能是空的或者只包含一些内置的示例。你可以把自己写的或者从社区下载的 skills 放进去每个 skill 一个子文件夹子文件夹里放SKILL.md文件。这里有一个实操中总结出来的经验建议在项目目录下也创建一个.claude/skills/文件夹用来存放项目专用的 skills。这样做的好处是当你切换项目时Claude Code 会自动加载对应项目的 skills不会把不同项目的流程搞混。我自己的习惯是用户目录下放通用的代码审查、提交规范、文档生成这几个 skill项目目录下放部署流程、数据库迁移、特定框架的代码生成这些跟项目强相关的 skill。3.3 手动安装 GitHub 上的 skills步骤与注意事项社区里已经有很多人把自己写的 skills 开源到了 GitHub 上你可以直接下载使用。手动安装的步骤并不复杂但有几个细节容易出错。基本流程是这样的先从 GitHub 上找到你需要的 skill 仓库把仓库克隆到本地或者直接下载 ZIP 包解压然后把包含SKILL.md的文件夹放到.claude/skills/目录下。放好之后重启 Claude Code 或者重新加载配置新的 skill 就会被识别。这里有几个容易踩的坑。第一文件夹结构要对。有些仓库的目录层级比较深SKILL.md可能藏在好几层子目录里你需要把包含SKILL.md的那一层文件夹直接放到 skills 目录下而不是把整个仓库文件夹放进去。第二文件名要准确。SKILL.md的大小写必须完全匹配有些系统对大小写不敏感但 Claude Code 的扫描逻辑是区分大小写的。第三依赖要确认。有些 skill 可能依赖特定的命令行工具或者环境变量使用前先看一下仓库的 README 说明把依赖装好。如果你在 Windows 上操作解压和复制文件夹的时候注意不要多套一层目录。我见过有人把 ZIP 解压后得到一个skill-name-main文件夹里面还有一层skill-name-main结果SKILL.md的路径就变成了.claude/skills/skill-name-main/skill-name-main/SKILL.md这样 Claude Code 是扫描不到的。正确的做法是确保SKILL.md直接位于.claude/skills/下的某个子文件夹的第一层。4. 自己动手写一个 SKILL.md从需求到可运行文件4.1 确定 skill 的边界什么任务适合写成 skill不是所有任务都适合写成 skill。根据我的经验适合写成 skill 的任务通常有这几个特征流程固定、重复频率高、步骤之间有明确的先后顺序、每次执行时变化的部分很少。比如“每次新建 React 组件时按照固定模板生成文件”“每次提交前跑一遍检查清单”“每次写数学建模论文时按照固定格式整理摘要”这些都是典型的 skill 场景。反过来那些每次都需要大量创造性判断、步骤不固定、依赖大量外部信息的任务就不太适合写成 skill。比如“帮我设计一个系统架构”这种任务虽然也可以写一个 skill 来引导 AI 的思考方向但效果远不如针对具体操作流程的 skill 来得明显。我的建议是先从你每天重复做的小事开始把那些“每次都要跟 AI 说一遍”的流程抽出来写成 skill积累几个之后你自然就有感觉了。4.2 SKILL.md 的写作模板与关键要素写SKILL.md不需要复杂的格式但有几个要素是必须包含的。下面是我常用的一个模板结构你可以直接参考# Skill 名称 ## 描述 用一两句话说明这个 skill 是做什么的什么情况下应该使用。 ## 触发条件 列出哪些任务或关键词会触发这个 skill。 ## 操作步骤 1. 第一步具体做什么 2. 第二步具体做什么 3. 第三步具体做什么 ## 注意事项 - 需要特别注意的点 - 容易出错的地方 ## 示例 给出一个具体的输入和期望输出示例。这个模板看起来简单但每个部分都有它的作用。“描述”和“触发条件”帮助 AI 判断什么时候该加载这个 skill“操作步骤”是核心要写得足够具体让 AI 能一步步执行“注意事项”用来处理边界情况“示例”则给 AI 一个参照减少理解偏差。写操作步骤的时候有一个技巧很实用用动词开头每一步只做一件事。比如不要写“检查代码质量并修复问题”而要拆成“运行 lint 命令检查代码风格”和“根据 lint 输出修复格式问题”两步。步骤越细AI 执行起来越准确。另外如果某一步涉及具体的命令一定要用代码块标注出来这样 AI 能准确识别命令内容不会把命令和说明文字混在一起。4.3 调试与验证怎么确认 skill 真的生效了写完SKILL.md之后怎么确认它真的被 Claude Code 加载并生效了最直接的方法是启动 Claude Code然后输入一个应该触发这个 skill 的任务描述观察它的执行过程。如果它按照你写的步骤一步步操作说明 skill 生效了。如果它没有按照预期执行可能是几个原因skill 文件位置不对、文件名不对、描述和触发条件写得不够清晰、或者任务描述跟 skill 的匹配度不高。我自己的调试习惯是先写一个最简单的 skill只包含两三个步骤确认整个链路能跑通之后再逐步增加复杂度。这样出问题的时候容易定位。另外Claude Code 在加载 skills 时通常会有日志输出你可以留意终端里的提示信息看看它扫描到了哪些 skill、加载了哪些文件。如果日志里没有出现你的 skill 名称那基本可以确定是文件位置或命名的问题。注意修改SKILL.md之后通常需要重启 Claude Code 或者重新加载配置才能生效。有些版本支持热加载但为了保险起见改完文件后重启一下是最稳妥的做法。5. 常见问题与排查技巧实录5.1 skill 不生效的排查清单skill 不生效是新手遇到最多的问题。我整理了一个排查清单按照这个顺序检查基本能覆盖大部分情况。排查项检查方法常见问题文件位置确认SKILL.md在.claude/skills/下的子文件夹第一层多套了一层目录文件名确认文件名是SKILL.md大小写完全匹配写成了skill.md或Skill.md文件编码确认文件是 UTF-8 编码中文内容出现乱码导致解析失败描述清晰度检查描述和触发条件是否明确描述太模糊AI 无法判断何时使用配置加载重启 Claude Code 后观察日志修改后未重启配置未刷新权限问题确认文件有读取权限Linux/macOS 下权限不足这个表格里的每一项我都实际遇到过。最常见的是文件位置和文件名问题尤其是从 GitHub 下载的 skill目录结构往往跟预期不一样。其次是描述太模糊比如只写了“代码检查”没有说明检查什么、什么时候检查AI 就很难判断该不该加载这个 skill。5.2 跨平台使用的注意事项不同操作系统下使用 Claude Code 和 skills有一些差异需要注意。Windows 用户如果直接在 PowerShell 里使用路径分隔符是反斜杠而SKILL.md里写的命令如果是给 bash 用的可能会执行失败。这种情况下要么在 WSL 里使用 Claude Code要么在 skill 里注明命令需要在什么环境下执行。macOS 和 Linux 用户相对省心一些但也要注意文件权限和换行符的问题。还有一个跨平台的坑是换行符。Windows 上默认的换行符是 CRLF而 macOS 和 Linux 是 LF。虽然大多数情况下 AI 能正确处理但在某些对换行符敏感的场景下可能会出问题。如果你在 Windows 上写 skill然后拿到 Linux 服务器上用建议把换行符统一成 LF。VS Code 右下角可以切换换行符格式或者用dos2unix命令转换。5.3 性能与上下文占用的平衡skills 虽然好用但也不是越多越好。每个被加载的 skill 都会占用一定的上下文空间如果 skills 太多可能会挤占 AI 处理实际任务的空间。我的经验是用户目录下的通用 skill 控制在 5 到 8 个以内项目目录下的专用 skill 控制在 3 到 5 个以内。超过这个数量就要考虑合并或者删减了。另外SKILL.md的内容也要控制长度。我见过有人写了一个几百行的 skill把各种边界情况都列进去了结果 AI 加载之后反而抓不住重点。比较好的做法是主流程写清楚边界情况用简短的列表带过详细的示例可以放在单独的文件里在SKILL.md里引用。这样既保证了信息的完整性又不会让单个文件过于臃肿。6. 典型场景下的 skills 应用思路6.1 数学建模场景从数据预处理到论文格式检查数学建模比赛里时间紧、任务重很多操作是重复性的。比如数据清洗、特征工程、模型训练、结果可视化、论文格式排版这些流程每次比赛都要走一遍。把这些流程写成 skills可以省下大量重复沟通的时间。我见过有人专门为数学建模写了一套 skills包括“数据探索性分析”“模型对比实验”“论文摘要生成”等比赛的时候直接调用效率提升很明显。具体来说一个“数据预处理”的 skill 可以包含这些步骤读取数据文件、检查缺失值和异常值、根据数据类型选择填充或删除策略、输出处理后的数据摘要。一个“论文格式检查”的 skill 可以包含检查标题层级是否符合要求、检查图表编号是否连续、检查参考文献格式是否统一、检查摘要字数是否在限制范围内。这些步骤写清楚之后AI 就能按照你的规范去执行不需要你每次手动检查。6.2 前端开发场景组件生成与代码审查前端开发里组件的创建和代码审查是两个高频重复的任务。一个“React 组件生成”的 skill 可以定义好组件的文件结构、命名规范、样式方案、测试文件模板AI 在需要新建组件时自动按照这个规范生成。一个“代码审查”的 skill 可以列出审查清单检查是否有未使用的变量、检查是否有硬编码的样式值、检查事件处理函数是否绑定正确、检查是否有性能隐患。这类 skill 的价值在于把团队规范固化下来。以前你可能需要写一份文档然后指望每个人都记住并执行现在你把规范写成 skillAI 在执行任务时会自动按照规范操作减少人为遗漏。而且 skill 是可以版本管理的规范更新了改一下SKILL.md就行所有使用这个 skill 的人都会同步到最新版本。6.3 通用效率场景文档生成与提交规范除了技术场景skills 也可以用在日常的效率提升上。比如“周报生成”的 skill可以定义好周报的格式、需要包含的内容模块、数据来源AI 在每周固定时间帮你整理好草稿。“提交信息规范”的 skill可以定义好提交信息的格式要求AI 在每次提交前帮你检查并格式化提交信息。这类 skill 的写法跟技术类 skill 没有本质区别关键是把你的个人习惯或者团队规范用清晰的文字描述出来。我自己的做法是先观察自己一周内重复做了哪些事情然后挑出最耗时的两三个写成 skill。积累下来之后日常工作中很多琐碎的操作都自动化了省下来的时间可以用在更需要创造力的地方。7. 我个人的一些实操体会写了这么多最后分享几个我自己在实际使用中总结出来的体会。第一个是不要追求一次写出完美的 skill。我最早写的几个 skill 都很粗糙但用起来之后发现粗糙的 skill 也比没有强。先写一个能用的版本然后在实际使用中不断调整比一开始就追求完美要高效得多。第二个是skill 的命名和描述要站在“AI 能不能理解”的角度去写而不是站在“我自己能不能看懂”的角度。有时候你觉得描述很清楚了但 AI 就是匹配不上这时候换一种更直白的说法往往就解决了。我习惯在写完之后自己模拟一下 AI 的视角看看这个描述能不能让我判断出“什么时候该用这个 skill”。第三个是定期清理不再使用的 skill。跟代码一样skill 也会积累技术债。有些 skill 可能只适用于某个已经结束的项目有些 skill 的流程已经过时了这些都应该及时删掉或者归档。保持 skills 目录的整洁不仅能让 AI 加载更高效也能让你自己更清楚当前有哪些能力可用。如果你刚开始接触 skills我的建议是从一个最简单的场景开始比如“每次新建文件时按照固定模板生成头部注释”写一个只有三五行的SKILL.md跑通整个流程。有了这个成功经验之后再逐步扩展到更复杂的场景。这个过程不需要什么高深的技术背景关键是理解“把重复流程写成文档让 AI 按文档执行”这个核心思路。一旦你体会到了它带来的效率提升自然就知道该怎么继续往下做了。