最近我花了一整个周末把 Claude Agent Skills 从头到尾折腾了一遍从官方市场里下载了一堆现成的 Skills又自己手写了几个专用技能模块还顺手把 Codex Skills 的目录结构和触发机制也翻了个底朝天。整个过程用打开新世界来形容一点都不过分因为我发现很多人至今还在把 Agent 当聊天框用每次对话都把上下文喂得满满当当却不知道真正高效的用法是把会做的事沉淀成可复用的 Skills让 Agent 在需要的时候自己调用。这篇文章不是我拍脑袋整理的概念科普而是基于实际安装、开发、调试经验的完整记录包含踩过的坑和能直接照抄的方案如果你是做前端开发、内容生产、论文写作或者日常办公自动化的这篇应该能帮你省下大量重复沟通的时间。1. 先搞清楚 Skills 到底是什么能解决什么问题1.1 从提示词膨胀说起为什么单靠 prompt 扛不住了过去一年多大家用 Claude 这类大模型 Agent 的方式基本还是一个巨大的提示词 一轮又一轮对话。这种做法最直接的问题就是提示词膨胀今天要加一个输出格式明天要补一个行业术语表后天又要塞一套公司内部的编码规范最后 prompt 动辄几千上万字每次发起新对话都得重新粘贴一遍既浪费 token又容易互相冲突。我在实际项目里感受最深的是前端开发场景。写一个页面时我希望 Agent 严格遵循项目的组件命名规范、CSS 变量体系、API 错误处理约定这些规则如果全部写进 prompt不仅晦涩还常常因为优先级不明确导致 Agent 在局部任务上新旧规则打架。后来我换了个思路把不同的能力拆成独立的 Skills每个 Skill 只负责一件事Agent 接到任务时按需加载规则之间天然隔离冲突概率大大降低。这才是 Skills 设计的第一性原理——把复杂系统中的稳定知识从对话上下文里剥离出来变成可复用、可版本化、可分享的独立模块。1.2 Skills 的本质把会做的事情变成可复用的模块第一次看到 Claude Agent Skills 目录时我有点恍惚因为它太像我们做工程时的函数库了一个 Skill 就是一个文件夹里面有一个核心说明文件、若干参考文档可能还带几个示例文件。关键在于这个文件夹不是给人看的而是给 Agent 看的。Agent 在执行任务时会根据用户的意图判断是否需要某个 Skill一旦匹配成功就把 Skill 文件夹里的说明和参考内容读进上下文然后按照里面的步骤去执行。用生活化的类比来说Skills 就像给 Agent 配了一整套工作手册工具箱你不用每次都给 Agent 重新讲一遍怎么处理图片、怎么走代码审查流程它自己会去手册里查查完就照着做。这跟那些把某个功能写死在模型权重里的方式有本质区别——Skills 是纯文本、纯规则、纯状态的集合你可以随意改、随意增删改完立刻生效不需要重新训练模型。1.3 Claude Skills 和 Codex Skills 的差异在哪市面上主流的 Agent Skills 体系最典型的是 Claude 官方实现的 Skills 机制和 Codex Skills。Claude Skills 目前主要依托 Anthropic 推出的 Agent Skills 规范核心文件叫 SKILL.md支持引用同目录下的辅助文件也支持在 SKILL.md 里声明所需的依赖或元数据。整个体系结构化得很干净官方市场里也已经出现了大量由团队维护的高质量技能包。Codex Skills 则更像是一个约定驱动的技能库它更强调技能描述在触发阶段的作用在命令行场景和写代码、写论文这类任务上表现非常突出。我在本地同时装了这两套平时的做法是日常写作和代码重构任务交给 Claude Skills 体系一些轻量的脚本生成、markdown 文档整理就丢给 Codex Skills。两者并不冲突核心目录结构都是一个技能文件夹 一个说明文件 辅助资源学会了其中一个另一个基本能无缝迁移。2. 本地环境准备与 Skills 安装的详细过程2.1 先把运行环境理清楚想要跑起来 Claude Agent Skills第一步不是急着下载技能包而是确定你用的 Agent 运行环境。目前主流的方式有三种官方桌面客户端、CLI 命令行工具、以及集成在 IDE 插件里的环境。我实测下来桌面客户端和 CLI 的 Skills 读取逻辑几乎没有差别它们都是扫描指定的 skills 目录然后在对话时进行匹配。如果你跟我一样同时使用多套环境建议先固定一个主环境避免后面排查问题时不知道技能包到底是被哪个进程加载的。安装前还要确认一件事你的账号和网络可以正常访问官方市场。这一点很重要因为 Skills 的自动安装本质上还是从官方仓库拉取文件如果你的网络环境访问不了整个流程就会卡住。别去想什么特殊手段正常的企业网络或家庭网络基本都能搞定少数情况只需要把 DNS 设置成公共解析就能解决。我这里就遇到过 DNS 解析失败导致市场列表刷不出来的问题换成公共 DNS 后立刻恢复。2.2 从官方市场安装 Skills 的完整步骤如果你用的是 Claude 桌面客户端安装流程非常简单在设置或者技能管理页面里找到Skills入口打开市场面板搜索你需要的技能包点击安装等它下载完成即可。安装完成后技能会默认放在用户目录下的某个固定路径不同版本可能路径略有差异但通常形如~/.claude/skills/或客户端数据目录下的skills/文件夹。考虑到命令行用户的需求我特意在 CLI 环境里也做了一遍手动安装步骤更直接打开终端先查看当前 CLI 版本确认支持 Skills 功能。创建一个skills目录如果客户端没自动创建就手动建一个。从官方市场或可信的 GitHub 仓库把技能包 clone 或者下载解压到skills目录下每个技能包保持一个独立子目录。在 CLI 里发起一个和技能领域相关的测试对话看 Agent 是否自动加载该技能。这里有个很多人忽略的细节技能包目录名最好保持小写加连字符比如blog-image-processor不要用空格和中文。我一开始给技能包起了中文名结果 Agent 匹配时频繁失败改成英文小写后一切正常。原因不难理解Agent 处理技能 ID 时通常会把目录名当作关键标识特殊字符很容易在语义解析阶段被忽略或截断。2.3 手动安装第三方 Skills 的目录规范如果你从 GitHub 或者 skills 下载平台找到第三方技能包手动安装时最关键的一步是检查目录结构是否合规。一个标准的 Claude Skill 目录需要满足根目录下有一个SKILL.md文件这是技能的大脑Agent 主要靠它理解该技能的所有能力。可以包含assets、scripts、references等子目录用来存放图片、脚本、参考文档。如果技能需要 Python 依赖通常会在SKILL.md里写明依赖列表或提供requirements.txt。很多第三方技能包在 README 里写得天花乱坠但 SKILL.md 写得一塌糊涂。判断一个技能包值不值得装别看广告文案直接打开 SKILL.md 看它的明确步骤是否清晰、示例是否完整、边界条件有没有说明。如果一个技能包描述含糊到连 Agent 都要靠猜那它大概率也会让你在关键时刻失望。我安装过二十多个技能包踩了不少次坑之后现在养成的习惯是每次装完第三方技能先用一个小型测试任务验证再正式投入使用。提示千万不要把手动下载的安装包直接拖进市场安装目录而不检查内容。第三方技能包可能会包含可执行脚本安装前至少肉眼扫一遍 SKILL.md 和 scripts 目录确认没有做可疑的外发请求操作。尤其涉及自动挖洞、信息收集这类高权限技能风险更高谨慎使用或者干脆别用。3. 从零手写一个自己的 Skill博客图片处理实战3.1 先设计技能的应用场景光会用别人写好的 Skills 还不够真正能提升效率的是把自己的重复性工作封装成技能。我选了一个最常见的场景来练手博客配图处理。以前我写一篇技术博客配图要手动压缩、转格式、补白边、加阴影一套流程下来十分钟起步而且每次操作细节还不一样非常浪费精力。于是我想让 Agent 能够根据一张原图自动完成调整尺寸——压缩——转为 WebP——加圆角阴影——输出到指定目录这条流水线。最开始我把这些步骤写进了系统提示词但每次换项目都要重新调整路径参数后来我干脆把整套处理流程做成一个 Skill把常见的参数、命名规则、输出目录全部固化下来效果立刻不一样了。Agent 只需要拿到图片路径就会自己去 Skills 里找处理逻辑根据我的要求只处理需要的步骤。3.2 SKILL.md 的内容编排与触发条件设计创建 Skill 的第一步是新建一个目录并在目录里创建SKILL.md文件。这个文件的头部是 YAML 格式的元数据后面是 Markdown 格式的处理逻辑。我通常这样组织--- name: blog-image-processor description: 用于博客配图的自动化处理可将输入图片按博客要求调整尺寸、 压缩质量、转换为 WebP 格式并添加圆角阴影效果。当用户提供图片路径、 要求处理图片或提到博客配图时使用。 ---注意description非常关键因为 Agent 判断该不该加载这个技能时主要就是靠这段描述与用户消息的语义匹配。描述写得越具体、触发词越明确Agent 误判的概率越低。我一开始写得很泛——图片处理工具结果 Agent 有时候在处理头像、截图时也加载了这个技能白白浪费 token。后来我在描述里明确加上博客配图、尺寸、压缩、WebP、圆角这些限定词触发准确度大幅提升。接下来是正文部分我一般会写清楚这几个板块技能目标、使用前置条件、处理步骤、输出格式、常见边界情况。不过要注意SKILL.md 不是给开发者看的 API 文档而是给 Agent 看的操作指引所以语句要尽量指令化步骤之间不要留有歧义空间。下面是我的技能正文的简化版# 博客配图处理流程 ## 前置条件 - 输入图片必须存在且为常见格式jpg、png、webp、gif。 - 输出目录默认为 assets/images/如果不存在则自动创建。 ## 执行步骤 1. 使用 Python 脚本 scripts/process_image.py 处理图片。 2. 调整图片宽度为目标宽度默认 800px保持宽高比。 3. 将图片质量压缩到 82%优先输出为 WebP 格式。 4. 为图片添加 16px 圆角与 8px 阴影效果。 5. 保存到输出目录文件名格式为 slug-{yyyyMMdd}.webp。 6. 如果输入图片是动画 GIF跳过圆角阴影处理直接压缩后输出。 ## 注意事项 - 当用户没有指定宽度时使用默认值 800px。 - 当原图本身就是 WebP 且质量低于 82% 时不做二次压缩。这种结构的好处在于Agent 在运行时会把整个文件读完形成一个稳定的任务清单一步一步执行。我也试过把处理脚本单独放在scripts/子目录SKILL.md 只写运行脚本并传入参数实践证明这种方式更稳妥因为处理逻辑复杂时全写在 markdown 里容易让 Agent 出现理解偏差而脚本本身的确定性远高于自然语言。3.3 添加辅助脚本并验证调用为了省事我把核心处理逻辑封装成了 Python 脚本放在技能目录的scripts/process_image.py里。脚本读取命令行参数接收输入路径、输出路径、宽度、质量等参数再用 Pillow 库完成整个处理流程。这里面有个经验给脚本加参数时要尽量用位置参数 默认可省略的方式不要设计十几二十个开关因为 Agent 在调用脚本时如果参数过多大概率会漏传或者传错。我写的一个简化版脚本如下供参考import argparse from PIL import Image, ImageOps, ImageDraw, ImageFilter def process(input_path, output_path, width800, quality82): img Image.open(input_path) ratio width / img.width img img.resize((width, int(img.height * ratio))) if img.format GIF: img.save(output_path, WEBP, qualityquality) else: # 圆角与阴影处理 mask Image.new(L, img.size, 0) draw ImageDraw.Draw(mask) draw.rounded_rectangle((0, 0) img.size, radius16, fill255) img.putalpha(mask) shadow Image.new(RGBA, (img.width 32, img.height 32), (0, 0, 0, 0)) shadow_draw ImageDraw.Draw(shadow) shadow_draw.rounded_rectangle((16, 24) (16 img.width, 24 img.height), radius16, fill(0, 0, 0, 80)) shadow shadow.filter(ImageFilter.GaussianBlur(8)) shadow.paste(img, (16, 16), img) shadow.save(output_path, WEBP, qualityquality) if __name__ __main__: parser argparse.ArgumentParser() parser.add_argument(input) parser.add_argument(output) parser.add_argument(--width, typeint, default800) parser.add_argument(--quality, typeint, default82) args parser.parse_args() process(args.input, args.output, args.width, args.quality)脚本写好后先不要急着扔给 Agent 用自己在终端直接跑一遍确认脚本本身没问题再回到 Agent 对话里测试。我在这个阶段踩过一个典型的坑脚本里依赖了某个第三方库但 Agent 在执行技能时用的是系统默认的 Python 环境并没有这个库于是技能直接报错。后来我在 SKILL.md 里增加了依赖声明并且在环境里提前装好依赖才把问题解决。全部配置完成后我在对话里输入帮我把这张配图处理成博客格式几秒钟后 Agent 自动加载了blog-image-processor技能图片被正确输出到assets/images/目录整体体验非常顺滑。这个技能我现在每天都在用再也没手动碰过那些重复的命令行。4. 我踩过的坑Skills 调用失败的典型问题与排查思路4.1 为什么 Agent 死活不调用我写好的 Skill这是我在实践过程中遇到最多的问题也是最让人崩溃的一类。明明技能已经装好了目录结构也没问题但 Agent 就是视而不见继续用通用能力硬答。排查思路第一步检查description是否足够具体。Agent 判断是否调用 Skill本质上是一个意图分类问题它拿你的历史消息和技能描述做语义匹配。如果描述里没有出现和用户请求强相关的高频词它就不会触发。我见过有人把 description 写成帮助用户解决问题这种描述就等于没有描述Agent 怎么可能判断出该在哪个场景调用呢排查思路第二步看看当前对话是否已经加载了其他技能。Agent 在一次会话中通常会限制同时加载的技能数量如果上下文里已经被别的高优先级技能塞满你的技能就可能被挤出局。解决办法是把技能数量控制在一个合理的范围别贪多装几十个真正高频用到的其实也就三五个。排查思路第三步检查触发条件是否与用户话术相差太远。比如你的技能是处理前端代码规范的但用户说的是帮我修一下这个样式如果技能描述里没有样式CSS样式修复等词汇Agent 很可能不会联想到这个技能。我一般会给每个技能准备三到五个同义触发词让匹配更稳。4.2 技能包运行时的路径和依赖问题就算 Agent 成功调用了技能实际运行过程中也常常出幺蛾子。最常见的是路径问题技能包里的脚本如果用了相对路径而 Agent 当前工作目录不在技能包文件夹下就会出现文件找不到的情况。我的解决办法是让脚本始终基于SKILL.md所在目录推导路径而不是依赖当前工作目录。具体到代码层面就是os.path.dirname(os.path.abspath(__file__))这一套。依赖问题也非常折磨人。有些第三方技能写着需要 Python 3.10、需要 xx 库但你的环境里装的是旧版本或者 pip 安装时把依赖装到了错误的 Python 环境。我试过好几个从网上下载的技能包运行时不是缺requests就是缺beautifulsoup4。现在我的做法是给技能包单独建一个虚拟环境在 SKILL.md 里写明激活该虚拟环境后运行这样能极大减少依赖冲突。4.3 如何看 Agent 到底看了什么日志和调试技巧当技能行为不符合预期时最有效的排查手段是打开对话日志看 Agent 实际读取了哪个技能文件、读了多少内容、从哪一步开始偏离预期。桌面客户端一般有日志目录CLI 工具可以用--log参数输出调试信息。我每次调技能时都会开日志因为只有看到 Agent 的推理轨迹你才能判断问题出在技能没被加载还是技能内容写得有歧义。实际调试中我总结了一个三分钟定位法先复现问题看 Agent 的输出格式是否正确。打开日志找到技能加载记录确认 SKILL.md 被读入了。如果技能被加载但结果不对多半是 SKILL.md 里的步骤描述不够精确或者参考文档与当前场景打架。如果技能压根没加载回过去改 description加触发词再测一遍。只要严格走这套流程绝大多数 Skills 问题都能在十几分钟内定位。注意调试时别频繁在对话里试错浪费 token 不说还容易干扰 Agent 的上下文状态。最好是改完 SKILL.md 之后新开一个会话验证保证每次测试都在干净环境里进行。5. 我在 GitHub、Reasonix 等平台找过的 Skills 资源与选型方法5.1 值得关注的技能获取渠道除了 Claude 官方市场GitHub 上也有大量高质量的 Skills 仓库比如github skills相关的项目、各种awesome-claude-skills集合页以及一些开发者把自己写的技能包开源出来供社区使用。我收藏了二十多个仓库里面既有一行代码都不用写的纯文档型技能也有带完整脚本和测试的工程型技能。Reasonix 是一个在热词里出现频次很高的名字本质上是专门聚合 Skills 下载和评测的社区平台。我在上面翻到过代码审查论文润色前端分镜开发等技能包多到让人眼花缭乱。从这里找技能包的最大好处是社区自带评分和评论区能直接看到真实用户的使用反馈比自己盲装瞎试高效得多。还有一类容易被忽略的资源是官方示例仓库Anthropic 曾公开过一批官方技能的源码级示例。这些例子虽然看起来简单但对理解什么样的 SKILL.md 才算合格非常有帮助。我建议新手别急着装一堆花里胡哨的技能先把官方示例翻一遍逐行理解它们的结构比什么都管用。5.2 如何辨别一个 Skill 是神器还是垃圾这年头skills 大全和skills 推荐的文章满天飞但真正常用的技能包其实很有限。我个人的筛选标准有三个描述明确边界清晰。好的 SKILL.md 会在开头就写清楚什么时候用和什么时候不用这个技能。垃圾技能往往啥都想干结果啥都干不好。有可执行的验证路径。技能包是否自带测试用例、示例输入输出如果没有至少要有作者给出的复现步骤否则无法确认它是否真的可用。维护频率健康。看仓库最近 commit 时间、issue 回复情况。一个半年没更新的技能包即使能用也可能因为依赖升级而随时挂掉用起来不安心。5.3 安装多个 Skills 后的性能与冲突问题装得多了之后你会遇到另一个烦恼技能之间开始互相干扰。比如我装了前端分镜开发和代码规范检查两个技能在生成页面结构时 Agent 经常会同时加载它们导致输出内容出现重复或矛盾。解决方式是在 SKILL.md 里明确声明该技能不负责 XX 任务给 Agent 一个负向排除信号。性能方面技能包不是越大越好。有一次我下载了一个自称全能助手的技能SKILL.md 内容超过一万字结果每次对话光加载它就要消耗大量上下文响应速度肉眼可见地下降。后来我坚决放到 3000 字以内的技能包保留最核心的内容把详细资料挪到 references 子目录让 Agent 按需读取响应速度和准确性都恢复回来了。这里也可以给各位提个醒技能包内容重在精准而不是大而全。6. 把 Skills 玩出花来的更多实操经验6.1 用 Skills 处理前端开发与写作的复合任务掌握了基础安装和写作技能后就可以尝试复合任务了。比如我最近在做一个项目需要把一篇技术方案文档自动转化为前端分镜脚本。这个任务如果靠纯提示词驱动光描述分镜规范就得写八百字而且改一次需求就要改一遍提示词。我把这件事做成了两个 Skill 的接力第一个 Skill 负责解析文档提取核心叙事线索并生成分镜表第二个 Skill 负责把分镜表渲染成页面骨架代码。Agent 在执行时自动先加载第一个技能完成后再调用第二个技能配合起来天衣无缝。如果你也做前端开发强烈建议试试把那些重复的交接文档转代码组件命名规范检查浏览器兼容性提醒这类任务全部技能化做一个你自己的前端开发 skills 工具箱。这里有个小技巧在技能的 description 里不写前端开发这种宏观词而是写生成 HTML 骨架根据设计稿输出 Tailwind 类名这类具体操作触发率会高得多。6.2 让技能包像产品一样持续迭代技能的封装不是一劳永逸的事。随着你用的场景越来越复杂原有的 SKILL.md 很可能需要持续调整。我的做法是给每个技能包都初始化一个 git 仓库每次修改 SKILL.md 都提交一次方便在出问题时回滚。同时我会在技能包目录里放一个CHANGELOG.md记录每次变更的原因这样隔几个月再回来看也能快速回忆起当时的设计意图。还有一点经验是关于版本管理的不要试图做一个万能技能而应该做多个小技能然后通过触发词控制它们的使用边界。比如我把图片压缩和图片添加水印拆成了两个独立技能虽然有一小部分逻辑重叠但维护起来非常清晰Agent 也不会在处理水印时莫名其妙地把图片压缩了一遍。6.3 一个值得注意的安全与隐私习惯技能包虽然只是文本和脚本但它可以包含任意指令这些指令会被 Agent 忠实执行。如果技能要求 Agent 读取本地敏感文件、向某个远程地址发送数据、甚至执行带有危险操作的命令后果可能非常严重。我每次安装第三方技能前都会完整浏览一遍 SKILL.md同时检查 scripts 目录里的代码确认没有恶意行为。对于自动挖洞这类听起来很猛的技能我更建议少碰这类技能往往依赖大量外部工具不仅环境配置复杂而且容易带来合规风险。挑技能时记住一句话技能能力越大责任越大来路不明的技能包再强大也慎用。安装官方市场或者大型团队维护的技能包时通常可以放心一些但也要保持基本的警惕。如果你的技能包里出现了明显不属于该功能的脚本比如一个图片处理技能里却有一个读取浏览器密码的 Python 文件那直接删掉整个包别犹豫。写在最后Skills 这个功能真正厉害的地方不在于它能帮你省几百个 token而在于它改变了我使用 AI 的方式。以前我总是想方设法把每一件事的上下文塞给模型现在我会先问自己这件事有哪些部分是稳定的、可复用的然后把它们沉淀成技能包。所谓打开新世界就是当你把常用的五十个动作都变成了技能再跟 Agent 协作时你会产生一种它真的懂我的工作方式的感觉。我的建议是别贪多先把你一周里重复做过三次以上的任务选一个写进 Skills写完赶紧用起来等你跑顺了第一套流程自然会知道下一步该封装什么。踩过几次坑后你也会有自己的技能设计方法论。