Agent Skills 实战指南：从 SKILL.md 编写到 Claude Code 安装配置

1. 从skills这个热词说起它到底在解决什么问题最近一段时间不管是在技术社区还是各种开发者群里skills这个词出现的频率高得离谱。很多人第一次看到它会以为是某个新出的编程语言特性或者某个框架的功能模块。但如果你真的去翻一翻相关的讨论会发现大家聊的其实是另一回事——Agent Skills也就是给 AI 智能体尤其是 Claude 这类工具配置的一套可复用的能力包。我最早接触这个概念的时候也是一头雾水。当时看到有人在群里问claude code怎么手动装github上的skills底下回复五花八门有人说直接丢到某个目录就行有人说要改配置文件还有人说要先装什么依赖。我照着试了一圈踩了不少坑最后才慢慢摸清楚这套东西的运作逻辑。简单来说Skill 就是一个用 Markdown 写的说明文件通常叫 SKILL.md配合一些辅助脚本或资源告诉 AI 在特定场景下应该怎么做事情。它不是什么高深的技术本质上就是把你平时反复跟 AI 解释的那套流程固化下来变成一个可以随时调用的模块。比如你经常让 AI 帮你写数学建模的论文摘要那你可以写一个数学建模摘要的 Skill把格式要求、常见套路、注意事项全写进去以后直接调用就行不用每次都重新解释一遍。这个东西解决的核心痛点是AI 本身很聪明但它不知道你的具体规矩。每个团队、每个人做事都有自己的习惯和标准Skill 就是把这些隐性知识显性化、可复用化的载体。对于经常用 Claude Code、Codex 这类工具干活的人来说掌握 Skill 的写法和用法能省下大量重复沟通的时间。这篇文章我会从实际使用的角度出发把 Skill 是什么、怎么写、怎么装、怎么避坑这几个问题讲透。不管你是刚听说这个词的新手还是已经用过几个现成 Skill 但想自己动手写的人应该都能找到有用的东西。2. Skill 的本质一份写给 AI 看的操作手册2.1 为什么是 Markdown而不是代码很多人第一次接触 Skill 会有一个疑问为什么这东西是用 Markdown 写的而不是用某种编程语言我一开始也觉得奇怪后来想明白了——因为 Skill 的核心是描述不是执行。你想想你平时怎么教一个新同事做事的你不会给他写一段代码而是会跟他说这个报表你先从系统里导出然后按部门分类注意把上个月的数据排除掉最后用这个模板生成。Skill 就是把这套口头说明变成了文字而 Markdown 恰好是最适合写这种说明的格式——它结构清晰、可读性强、不需要任何编译就能看懂。AI 读 Markdown 的方式和人读的方式很像它能理解标题层级、列表、加粗这些格式背后的语义。所以当你写## 步骤的时候AI 知道下面是具体操作当你写 注意的时候AI 知道这是需要特别留意的点。这种自然语言 轻量结构的组合比写代码灵活得多也比纯文本清晰得多。2.2 SKILL.md 里到底该放什么一个标准的 SKILL.md通常包含这几个部分名称和描述告诉 AI 这个 Skill 是干什么的什么时候该用它适用场景明确在什么情况下调用这个 Skill避免误触发具体步骤一步步的操作说明越具体越好注意事项容易出错的地方、需要特别处理的边界情况示例给一两个输入输出的例子让 AI 有参照我见过很多人写 Skill 的时候喜欢写得很高级用一堆抽象的描述。比如请以专业的方式处理用户请求——这种话等于没说AI 根本不知道什么叫专业的方式。好的 Skill 应该是具体的、可执行的、有明确判断标准的。与其说注意格式不如说标题用二级标题每段不超过五行代码块必须标注语言类型。2.3 Skill 和 Prompt 的区别在哪有人会问这不就是 Prompt 吗我直接跟 AI 说不行吗区别在于复用性和结构化程度。Prompt 是你临时说的话说完就没了Skill 是存下来的文件可以反复调用、可以分享给别人、可以版本管理。而且 Skill 通常比 Prompt 长得多、详细得多因为它要覆盖一个完整场景的各种情况而不是解决一个具体问题。打个比方Prompt 像是你临时问路Skill 像是你手里的一本导航手册。问路只能解决一次手册可以一直用。3. 动手写第一个 Skill从场景拆解到文件落地3.1 先想清楚这个 Skill 要解决什么重复劳动写 Skill 之前最重要的一步不是打开编辑器而是回顾你最近反复跟 AI 解释的那些事。我自己有个习惯会记录一周内跟 AI 重复沟通超过三次的内容这些就是最值得做成 Skill 的候选。举个例子我之前做数学建模比赛的时候每次让 AI 帮忙写模型假设部分都要重新说明一遍格式要求、语言风格、需要包含哪些要素。后来我干脆写了一个建模假设生成的 Skill把这些要求全写进去之后每次只要说用建模假设 Skill 处理这段材料出来的东西基本就能直接用。判断一个场景值不值得做成 Skill有三个标准第一这个任务你会反复做第二这个任务有明确的流程或标准第三这个任务的细节比较多每次解释起来很麻烦。三个都满足那就值得写。3.2 一个可用的 SKILL.md 骨架下面是我自己常用的一个骨架你可以直接拿去改# Skill 名称 ## 描述 一句话说明这个 Skill 是干什么的。 ## 何时使用 - 场景一... - 场景二... ## 执行步骤 1. 第一步... 2. 第二步... 3. 第三步... ## 输出格式 - 格式要求一... - 格式要求二... ## 注意事项 - 注意点一... - 注意点二... ## 示例 输入... 输出...这个骨架看起来简单但每一部分都有讲究。何时使用这一节特别重要因为它决定了 AI 会不会在正确的时机调用这个 Skill。如果你写得太宽泛AI 可能在不该用的时候也用写得太窄又可能该用的时候想不起来。3.3 把隐性经验翻译成显性步骤写 Skill 最难的地方是把你自己觉得理所当然的东西写出来。比如你让 AI 帮你改代码你心里知道改完之后要跑一遍测试但你不说AI 就不会做。写 Skill 的时候你要假设 AI 完全不懂你的行业、不懂你的习惯把所有你觉得这还用说的东西都写进去。我自己的做法是先写一版然后故意让一个完全不懂这个领域的朋友看一遍问他你看完知道该怎么做吗。如果他有疑问说明你写漏了。这个方法虽然笨但特别有效。还有一个技巧是用如果……那么……的句式。比如如果输入是空值那么返回错误提示而不是继续处理。这种条件判断在 Skill 里非常有用因为 AI 需要知道各种边界情况该怎么处理。4. 安装与配置那些文档里不会写的细节4.1 手动安装 GitHub 上的 Skill 到底放哪这是被问得最多的问题之一。网上答案五花八门我实测下来关键是要找到你所用工具的 Skill 目录。不同工具、不同版本这个目录位置可能不一样。以 Claude Code 为例常见的 Skill 存放位置有几种位置类型典型路径适用场景用户级目录~/.claude/skills/个人常用所有项目共享项目级目录项目根目录下的.claude/skills/项目专用随项目走自定义配置配置文件中指定的路径特殊需求灵活调整我建议先用用户级目录因为这样不管你切换到哪个项目Skill 都能用。等项目稳定了再把项目专用的 Skill 挪到项目目录里。安装步骤其实很简单从 GitHub 上把 Skill 仓库下载下来直接下载 ZIP 或者用 git clone 都行找到里面的 SKILL.md 文件所在的文件夹把整个文件夹复制到你的 Skill 目录下重启工具或者执行重新加载命令注意复制的时候要连整个文件夹一起复制不能只复制 SKILL.md。因为很多 Skill 还包含辅助脚本、模板文件、参考文档只复制一个文件会导致 Skill 不完整。4.2 装完之后不生效先查这三个地方我遇到过好几次装完了但 AI 好像没反应的情况排查下来基本都是这几个原因第一目录层级不对。有些 Skill 的仓库结构是仓库名/skills/技能名/SKILL.md你需要复制的是技能名这一层而不是整个仓库。如果你把整个仓库丢进去AI 可能找不到 SKILL.md。第二文件名大小写问题。有些系统对文件名大小写敏感SKILL.md和skill.md可能被当成两个不同的文件。建议统一用大写。第三缓存没刷新。很多工具会缓存 Skill 列表装完之后需要重启或者手动触发刷新。如果你不确定怎么刷新直接重启最省事。4.3 多个 Skill 冲突了怎么办当你装了很多 Skill 之后可能会遇到AI 用错了 Skill的情况。这通常是因为两个 Skill 的何时使用描述有重叠。解决办法是把触发条件写得更精确。比如你有一个写周报的 Skill 和一个写日报的 Skill如果两个都只写用于写报告AI 就分不清。你应该写成当用户提到周报本周总结时使用和当用户提到日报今日总结时使用。如果实在分不清可以在 Skill 里加一句如果同时匹配多个 Skill优先使用本 Skill或者本 Skill 不适用于……场景。5. 从能用到好用Skill 设计的进阶思路5.1 让 Skill 具备判断力而不是死执行初级 Skill 是第一步做什么、第二步做什么高级 Skill 是根据情况选择不同的处理方式。好的 Skill 应该像一个有经验的员工而不是一个只会照章办事的机器人。举个例子一个代码审查的 Skill不应该只写检查语法错误而应该写如果发现的是语法错误直接指出并给出修正建议如果发现的是逻辑问题先描述问题现象再分析可能的原因如果发现的是风格问题标注出来但不强制修改让用户决定这种分情况处理的写法能让 Skill 的适用范围大大扩展。5.2 用示例代替解释AI 学习的方式和人很像给它看例子比给它讲道理更有效。与其写一大段输出应该简洁明了不如直接给一个输入输出的例子输入帮我总结这段会议记录 输出 - 决议事项3 项 - 待办任务5 项负责人已标注 - 下次会议时间待定一个具体的例子胜过十句抽象的描述。我写 Skill 的时候如果某个要求不好用文字说清楚就会直接给例子。5.3 版本管理和迭代Skill 不是写完就完事了它需要像代码一样迭代。我建议在 Skill 文件夹里放一个CHANGELOG.md记录每次修改的内容和原因。这样当你发现某个 Skill 效果变差了可以回溯是哪次修改导致的。另外如果你是从 GitHub 上 fork 了别人的 Skill 来改记得保留原作者的署名和许可证信息。这是基本的尊重也能避免法律问题。6. 常见问题与踩坑记录6.1 无法将 claude 项识别为 cmdlet这类报错这个报错通常出现在 Windows 环境下原因是命令行工具没有加到系统 PATH 里。解决办法是找到工具的安装目录把那个目录添加到环境变量 PATH 中。具体操作是系统设置 → 环境变量 → 编辑 Path → 新增一行把工具所在目录填进去。如果加了 PATH 还是不行可能是安装本身有问题。建议重新安装一遍安装时注意勾选添加到 PATH选项。6.2 Skill 写得太长AI 反而不执行我一开始写 Skill 的时候恨不得把所有细节都写进去结果写了两三千字AI 反而抓不住重点。后来我发现Skill 的长度要控制在一个合理范围内核心步骤最好不超过 20 条。如果内容确实很多可以拆成多个 Skill或者把详细内容放到单独的参考文件里在 SKILL.md 里用详见 xxx.md来引用。这样主文件保持简洁需要细节的时候 AI 再去读参考文件。6.3 不同工具之间的 Skill 能不能通用理论上Skill 的核心是 Markdown 文件格式是通用的。但不同工具对 Skill 的支持程度不一样有些工具支持自动加载有些需要手动指定有些对文件结构有特定要求。我的建议是先在你主要使用的工具上把 Skill 跑通再考虑迁移到其他工具。迁移的时候重点检查何时使用这一节因为不同工具的触发机制可能不同。6.4 关于 Skill 的安全问题装别人写的 Skill 之前一定要看一眼里面的内容。因为 Skill 本质上是一段会被 AI 执行的指令如果里面藏了恶意内容可能会导致意想不到的后果。特别是那些包含脚本的 Skill更要仔细检查脚本在做什么。我自己的习惯是只装来源可靠的 Skill装之前把 SKILL.md 完整读一遍有脚本的话也大致扫一眼。如果看不懂宁可不装。7. 我个人的一些使用体会用了这段时间的 Skill 之后我最大的感受是它改变了我跟 AI 协作的方式。以前我是想到什么问什么现在我会先想这件事有没有现成的 Skill 可以用如果没有就考虑要不要写一个。有几个小技巧是我自己摸索出来的分享给你第一从最小的 Skill 开始。不要一上来就写一个覆盖整个工作流的复杂 Skill先写一个只解决一个小问题的跑通了再慢慢扩展。第二定期清理不用的 Skill。装得太多会让 AI 的选择变困难也会拖慢加载速度。我一般每个月会清理一次把最近没用过的删掉或者归档。第三把 Skill 当成团队资产来管理。如果你在团队里用可以把大家写的 Skill 集中到一个仓库里互相 review、互相改进。这样积累下来整个团队的效率都会提升。第四不要指望 Skill 能解决所有问题。有些任务就是需要人来判断Skill 只能处理那些有明确流程的部分。分清楚哪些该交给 Skill哪些该自己动手这本身就是一种能力。最后说一句Skill 这个东西写比读重要用比写重要。你看再多教程不如自己动手写一个。哪怕写得很粗糙跑一遍之后你就知道该怎么改了。