最近这阵子AI 圈子里最热的关键词就是 Skills。不管你是刷 GitHub、逛技术社区还是翻 Claude、Codex 这些 Agent 的官方文档都会看到 claude agent skills、codex skills、skills 推荐这类话题连带着 skills 开发、skills 下载的实操帖也越来越多。我自己前前后后把主流 Agent 的 Skills 机制都摸了一遍装过社区里几百星的现成包也自己写过、改过、跑崩过不少 Skill今天就把这些经验整理成一篇能直接照做的实战笔记。这篇东西不聊虚的从原理讲到安装、开发、测试再到前端开发、论文写作、分镜这类具体场景怎么用最后附上我踩过的坑。先说清楚它适合谁如果你正在用 Claude Code、Codex 或者类似的 Agent 工具想让它从会聊天变成会干活这篇就是给你写的如果你完全没接触过 Skills从零开始跟着走也没问题。这篇内容不依赖特定平台思路和套路在各家工具里都是通的。1. Skills到底是个什么东西1.1 一句话理解给Agent装上的能力插件Skills 本质上是把一组指令 脚本 示例资源打包成一个文件夹放到 Agent 能识别的位置让模型在特定任务上能调用这套能力。有人把它比作手机里的 App有人说是游戏里的 DLC也有人直接叫它 Agent 的 super power——这几个说法都对但我更愿意用一个工匠的比喻大模型本身是那双手Skills 是工具箱里的专用工具。手再巧没有滑丝刀也拆不了精密螺丝模型再强没有一套结构化的行业知识包遇到复杂任务也容易手忙脚乱。我之前第一次看到这个概念的直观感受是原来不用每次都在对话里反复描述请你按某某格式输出、请你调用某某函数而是可以把这些规则固化成一个 Skill需要时让 Agent 自己加载。这解决了几个长期痛点提示词太长导致上下文被浪费、每次会话都要重新教一遍、复杂工作流没法复用。Skills 把怎么做事沉淀成了文件这才是它最有价值的地方。1.2 运行机制SKILL.md、脚本和资源文件一个标准的 Skill 目录结构长这样核心是SKILL.md这个入口文件它决定了 Agent 会不会用、怎么用这个 Skill。这个文件通常包含 YAML 格式的 frontmatter名称、描述、适用场景正文里则是给模型看的详细操作指引包括步骤、约束条件、输入输出格式甚至是一些 few-shot 示例。除了SKILL.md旁边一般还有scripts/、assets/这些目录。scripts 里放 Python、Shell、Node 脚本负责真正执行动作比如抓取网页、处理 JSON、调用某个 APIassets 里放模板、参考图片、数据字典这些被动资源。Agent 在运行时会先读SKILL.md判断这个 Skill 适不适合当前任务然后决定是直接按文档里的步骤推理还是调用脚本去执行最后把脚本输出拿回来继续处理。这里有一个关键点Skills 和 MCPModel Context Protocol经常被混为一谈但它们是两个层次的东西。MCP 解决的是Agent 如何连接到外部工具和数据源的协议问题你可以把它理解成 USB 接口Skills 解决的是某个具体任务怎么做才专业的知识封装问题更像是预装好的专用软件。一个 Skill 内部完全可以调用 MCP server 的接口两者是配合关系不是替代关系。我见过不少新手在这里绕晕后面开发时会走很多弯路。2. 去哪里找现成的Skills平台、仓库与检索技巧2.1 官方市场与第三方平台很多人第一步就卡在到底去哪下载。目前 Skills 的分发渠道还很分散不像当年 App Store 一家独大但已经有了几个相对集中的入口。首先是各家 Agent 的官方渠道。Claude 这边在 GitHub 上有专门存放 Skills 的官方仓库收录了不少经过验证的高质量 SkillCodex 也有自己的插件系统和官方示例。官方仓库的好处是质量有人把关、更新及时适合新手直接上手。其次是社区聚合平台比如一些专门收录 AI Agent Skills 的导航站和论坛上面按前端开发、数据处理、写作等分类整理了大量 Skill 包下载前能看到别人的评价和踩坑记录。第三类就是最原始的 GitHub 搜索。说实话我装过的大部分好玩又实用的 Skill 都来自 GitHub而不是官方市场。因为技能这种东西更新太快官方收录永远滞后于社区创造。搜索时别只会输 skills要学会计较关键词找前端类就搜 frontend skill agent找安全检测类就搜 security testing skill再配合awesome-claude-skills、awesome-agent-skills这类合集仓库效率会高很多。2.2 如何在GitHub上快速筛选靠谱的SkillsGitHub 上的 Skills 质量参差不齐有的仓库就一个几十行的SKILL.md有的连测试用例和文档都写得很完整。我的筛选习惯是四看看 star 数和更新时间、看 README 的完整度、看 SKILL.md 本身写得清不清楚、看有没有人提过 issue。star 数是最直观的参考但不能只看总量还要看趋势。一个三个月前火的仓库可能已经跟现在的模型版本脱节了我建议用 GitHub 的搜索排序功能按 Recently updated 排序优先看最近一个月还有维护的仓库。README 里如果写了适用的 Agent 版本、依赖要求和已知限制说明作者真的在用而不是随手扔了个半成品。SKILL.md 的写法也能看出水平。好的描述不是含糊的help with coding而是Generates React components following the projects design system, handles TypeScript types, and outputs test cases。描述越具体Agent 越能在正确的时候自动触发它误召回的几率也越小。另外别忘了看 license有些 Skill 集成了第三方内容商用会有版权风险这一点容易被忽视。2.3 几个值得关注的高质量方向社区里沉淀下来的 Skills 虽然五花八门但有几类是真的经过检验、装上就能提效的方向。前端开发类是重灾区各类生成组件、重构代码、检查无障碍性的 Skill 都很成熟配合 Claude 这类代码能力强的模型基本能覆盖从搭页面到写测试的完整链路。学术写作类的 Skill 也值得关注尤其是帮人找文献、组织论文结构、统一引用格式这些能标准化的工作流。我见过一些写得好的论文 Skills能把写摘要这种模糊任务拆成背景-方法-结果-结论四段式每一段还有明确的字数建议和写作风格提示比空手让模型写要稳定得多。此外图像分镜、数据处理、自动化测试这几类也都不错。3. 手把手安装一个Skill通用流程与踩坑记录3.1 安装前的环境准备装 Skill 之前先把 Agent 工具本身装好、跑通。无论你用的是 Claude Code 还是 Codex都需要先确认两件事命令行工具能正常运行Python 和 Node 环境可用。大部分 Skill 的脚本都是用 Python 或 Node 写的缺了运行环境装完也用不了。然后要搞清楚目标 Agent 的 Skills 目录约定。不同工具的默认路径不一样Claude 系一般是用户目录下的.claude/skills/Codex 系是.codex/skills/或者项目目录里单独建.skills/。这些信息在官方文档里都能查到我建议第一次装之前先花十分钟把目录约定读明白不然后面排查路径问题会很痛苦。这里多说一句项目级和用户级的 Skills 目录是有区别的。用户级目录对所有项目生效适合放通用技能项目级目录只对当前项目生效适合放业务特定的技能。我现在的习惯是通用的自己写、放用户级项目相关的绑定到项目仓库里这样团队协作时每个人 clone 下来就能直接用。3.2 标准安装五步法整个安装流程并不复杂我把它拆成五步照着走就行第一步下载 Skill 源码。可以用git clone拉仓库也可以直接在 GitHub 页面上下载 ZIP 包。我推荐只拉单个目录而不是整个仓库用git sparse-checkout或者 degit 这类工具都能做到避免把一堆没用的文件拖进项目里。第二步把 Skill 文件夹放到正确的目录。注意文件夹名就是 Skill 的名字会被 Agent 用来识别建议保留原始名称不要随便改。放好后检查一下目录结构确认SKILL.md在文件夹的根目录而不是嵌套在下一层。第三步安装依赖。打开SKILL.md或者requirements.txt、package.json看有没有需要安装的第三方库然后在该 Skill 的运行环境里装好。有些 Skill 还依赖外部 API key需要配置环境变量这一步漏掉的概率比想象中高。第四步重启 Agent让它重新扫描目录。这一步看起来简单但特别容易被忽略——我见过不少同学装完发现技能没生效其实就是没重启Agent 还停留在旧的文件列表上。第五步做一个最小验证。直接给 Agent 一个和该 Skill 能力完全匹配的任务看它是否能自动触发并给出合理输出。如果没触发先检查描述是否清晰、目录是否正确再看是否有依赖缺失。3.3 安装后的权限与安全检查装完不代表完事。第三方 Skills 本质上是别人写好的代码运行时等于让你的 Agent 在本地执行这些脚本。所以在正式使用前我会养成熟读一遍源码的习惯尤其是 scripts 目录里涉及网络请求、文件写入、命令执行的代码。重点关注三件事脚本会访问哪些域名、会不会读取敏感文件、有没有把数据外传的代码。不是说要像做安全审计一样逐行读但至少做到心里有数。除此之外检查一下文件权限也很重要Linux 和 macOS 上有些脚本需要chmod x才能执行Windows 上则要注意路径里不能有空格导致脚本找不到解释器。另外如果 Skill 自带 AI provider 的配置比如要求你填 API key务必确认这个 key 只存在于本地环境变量里不要写进 Skill 的脚本文件中更不要提交到 Git 仓库。这个坑我踩过一次虽然只是个人项目但上线前做安全自查时看到硬编码的 key 还是吓出一身冷汗。4. 动手开发自己的Skills从需求到落地4.1 设计原则一个Skill只做一件事用了别人的 Skill 之后你一定会遇到这个功能不够贴合我需求的时刻这时候就该自己动手写了。开发自己的 Skills 并不需要多高深的技术核心是设计能力。第一条设计原则是单一职责。一个 Skill 只解决一个问题宁可多建几个 Skill也不要做一个什么都能干但什么都干不好的大杂烩。举例来说前端开发这个需求拆成生成组件、重构代码、“写测试”三个 Skill比装一个 giant 前端全家桶要实用得多。原因很简单Agent 按描述触发技能描述越聚焦触发越精准技能内部逻辑越简单越不容易出错。第二条原则是明确输入输出。在SKILL.md里把期望的输入格式、输出格式写清楚最好附一个示例。真实世界的任务往往是模糊的Agent 接收到帮我查一下这个数据这种请求时如果 Skill 不告诉它查什么、怎么查、结果怎么表达它就很容易跑偏。写清楚边界反而是在帮 Agent 省时间。4.2 SKILL.md的结构模板与写法要点下面是一个我常用的SKILL.md模板你可以直接抄--- name: csv_analyzer description: 分析 CSV 数据文件输出统计摘要和可视化建议。适用于数据清洗、报表生成等任务。 --- # CSV Analyzer ## 适用场景 - 用户提供 CSV 文件路径 - 需要快速了解数据规模、字段类型、缺失值情况 ## 执行步骤 1. 使用 scripts/analyze.py 扫描文件输出字段统计信息 2. 根据统计结果生成摘要报告 3. 若用户要求可视化使用 scripts/plot.py 生成图表 ## 注意事项 - 输入文件必须先校验存在性和编码格式 - 超过 100MB 的文件提示用户分段处理 - 所有输出使用 Markdown 表格格式 ## 示例 用户: 分析 data.csv 执行: python scripts/analyze.py data.csv 输出: | 字段 | 类型 | 缺失率 | |------|------|--------| | id | int | 0% |模板里的第一部分 frontmatter 最重要description决定了 Agent 在什么时候会调用这个 Skill。我建议描述里同时包含触发条件和禁止条件比如仅在用户明确要求分析 CSV 时使用非数据处理任务不要触发。这个细节能让误触发问题大幅减少。执行步骤要控制粒度写清楚关键判断和工作流就够不用把每一步的代码逻辑都描述出来模型会根据脚本实现自行推理。4.3 配套脚本的编写要点与迭代思路脚本是 Skill 的手脚写法上我总结了几条经验。首先要保证脚本可以独立运行传入参数、得到输出不依赖 Agent 的特殊环境。这样你调试的时候可以直接在终端里跑脚本而不必每次都启动 Agent 走一遍对话流程。其次脚本对输入要做防御性处理异常要给出清晰的中文错误信息而不是抛一堆 Python traceback 给 Agent 去猜。脚本和 Agent 之间的数据交换格式也很关键。我习惯统一用 JSON 输出因为 Agent 解析 JSON 最稳妥。凡是涉及文件路径、时间、金额这类信息都要在脚本里做标准化比如统一时间格式、统一币种这样 Agent 拿到结果后不会因为格式混乱做出错误判断。开发完成后一定不要急着宣布完工要多轮实测。我自己通常会在真实任务上至少跑三轮正常场景、边界场景、异常场景。正常场景看效果是否达标边界场景看数据量大了会不会出问题异常场景看输入明显不对时脚本是否能优雅报错。三轮下来改的问题往往比写脚本本身花的时间还多但每一步都是值得的。5. 基于Skills的典型场景实战5.1 前端开发Skills从生成组件到整体重构前端是 Skills 应用最成熟的领域之一。我常用的一个做法是先把项目的设计规范沉淀成一个 Skill里面包含颜色变量、间距规则、组件风格示例然后让 Agent 在这个 Skill 的约束下生成新组件。这样输出的代码天然符合团队规范不用每次都在 prompt 里复述一遍设计 token也不用担心模型自由发挥出风格不一致的代码。重构场景更适合用专门的 Skill 来干。比如把类组件改成函数组件、把 Redux 迁移到 Zustand、把 CSS 换成 Tailwind这类任务规则明确、重复性强特别适合封装成 Skill 自动化处理。我试过一个代码重构的 Skill它会把改动拆成先梳理依赖、再做小步迁移、最后统一测试每个阶段都给我输出进度报告整个过程的可靠性比我手动一步一步问要高得多。还有一类被低估的前端 Skill 是代码审查。把团队的代码规范、常见反模式、性能检查点写进 Skill 里Agent 就能对每一段新增代码做自动化 review。这等于你的团队里多了一个永远在线的 senior reviewer虽然不能完全替代人但能挡住大部分低级问题。5.2 学术写作Skills查证、结构与格式的一体化用 AI 写论文最大的风险是什么编造文献。所以我见过的好用学术写作 Skill第一步往往不是写内容而是查证和引用——接一个文献检索 API或者严格约束用户提供真实文献列表然后基于这些文献组织内容。这类 Skill 的另一个价值在于结构化管理。写论文时最怕的不是没思路而是思路太散。一个设计良好的论文 Skills 会把任务拆成先写 outline再逐节填充每节控制字数比例最后统一润色语言。整个过程会持续提醒模型这一节的目标是论证 X不要跑题到 Y相当于给你的写作用上了轨道。格式处理也值得交给 Skill。不同期刊、不同课程的引用格式要求各异把 APA、MLA、GB/T 7714 这些格式规则写进 SKILL.md让 Agent 在输出参考文献时自动套用能省掉大量手工调整的功夫。我自己在写技术博客时也会用一个简单的博客排版 Skill自动统一标题层级、代码块标注、词汇风格省心很多。5.3 分镜Skills创意内容生产的提效之路分镜 Skills 最近在视频和内容创作圈很火它的核心思路是把脑海中想象的画面转化成可执行的镜头描述。好的分镜 Skill 会包含景别词表远景、中景、特写、运镜方式、时长预估、音画对应规则等内容让 Agent 能把一段文字脚本自动拆成分镜表。我在实际项目里的用法是先让模型基于文案生成分镜框架再逐镜头补充画面细节和提示词。因为分镜 Skills 里通常内置了画面描述模板比如主体 动作 环境 光影 氛围五件套它生成的镜头描述拿去喂给绘图工具出图的可控性明显比随口描述要高。这里有个经验分镜 Skills 最怕提示词抽象。新手写描述喜欢用美丽神秘这类虚词而好的 SKILL.md 会要求用具体可渲染的词比如黄昏时分的街道冷色调逆光剪影浅景深。这类约束不写进去模型就永远学不会具体化。5.4 自动化安全检测Skills在授权框架内发挥价值在网络安全圈自动挖洞类 Skills 最近讨论度也很高。需要提醒的是这类工具必须严格限定在授权的安全测试、CTF 比赛、漏洞赏金项目和自己的实验环境里使用任何未经授权的扫描和探测都是违规行为。按合规边界使用这类 Skills 确实能提升效率。一个靠谱的自动化安全检测 Skill内部通常包含资产信息收集、常见漏洞指纹识别、日志分析、报告生成这几个模块。它的价值不在于一键破解而在于把测试过程中重复性高的信息收集和分析工作自动化让安全工程师把精力集中在需要人工判断的部分。我见过做得好的这类 Skill最终输出不是一堆扫描结果而是一份带严重级别和修复建议的报告这才是真正可用的东西。6. 测试与调试怎么判断一个Skill是真好用还是花架子6.1 建立最小测试集与评价维度从社区下载一个 Skill 或者在写自己的 Skill 时很多人犯的错误是装完演示一下觉得挺厉害就直接用了。正确的做法是建立一套最小测试集用小成本验证真实效果。我的做法是给每个 Skill 准备 3 到 5 个代表性任务覆盖典型场景和一个边界场景。比如一个写摘要的 Skill我会用一篇长文、一篇带术语的技术文、一个只有两句话的极短文来测试。跑完之后按三个维度打分完成度输出是否满足需求、稳定性同一任务跑三次结果差异大不大、效率相对于手写 prompt 是否真的省时间。稳定性是最容易被忽略的指标。AI 本身有随机性但一个设计良好的 Skill 应该能把随机性约束在合理范围内。如果同一个 Skill 跑三次出了三种完全不同的结果说明 SKILL.md 里的指令不够具体或者脚本处理的中间结果没有被有效回传。碰到这种情况不要急着怪模型回去优化 Skill 本身。6.2 常见失败模式与调试方法我调试过的 Skill 里最高频的失败模式有几种。第一种是根本没触发Agent 全程无视这个 Skill。这通常是描述写得太模糊比如helps with data模型觉得普通对话也能干就没必要加载它。解决方法很直接把描述写窄、写具体加上明确的触发场景关键词。第二种是触发但执行到一半断掉。我遇到过的一个 CSV 分析 Skill 就是这样脚本在读取文件时一直报编码错误。排查发现是脚本里写死了 UTF-8但用户给的是 GBK 编码的 Excel 导出文件。这一类问题靠修改脚本、增加编码自动检测逻辑解决教训是脚本一定要对现实世界的脏数据有防御。第三种是输出了但完全不对。这种往往出在上下文的中间结果传递上——脚本输出的 JSON 字段名和 SKILL.md 里描述的字段名不一致导致 Agent 理解偏差。所以我在调试时会把 Agent 的实际对话流程完整打开看它每一步读到了什么、卡在了哪里。很多问题不看过程根本猜不到原因。7. 避坑指南与常见问题速查7.1 高频踩坑现场根据我的实际经验整理一个速查表帮你快速定位问题现象常见原因解决思路Skill 完全不触发目录位置不对或 SKILL.md 描述太模糊检查目录约定重写 description加入触发关键词触发后脚本报找不到文件相对路径错误改用脚本所在目录推导绝对路径不要用当前工作目录中文字符乱码编码声明缺失或依赖库默认编码不对在脚本头部统一声明 UTF-8读取文件时自动检测编码输出格式不符合预期SKILL.md 与脚本输出字段不一致统一 JSON 的 key 命名在 SKILL.md 里写明输出映射关系装了新 Skill 但系统还走老逻辑没有重启 Agent重启后再测试依赖的 API key 未生效环境变量未加载确认.env文件路径正确重启终端使变量生效这些坑看着都不起眼但每一个我都是实打实花时间踩过的。最典型的还是路径问题脚本里千万不要用相对当前工作目录的写法因为 Agent 发起调用的位置极有可能和你想象的不一样代码里应该基于__file__或者os.path.dirname这类方式推导资源路径。7.2 四条独家经验写到最后分享几条我个人折腾 Skills 以来最值钱的体会。第一条经验优先自己写核心 Skill用社区的 Skill 来探索方向。直接拿别人的 Skill 改永远不如自己从零写一遍理解得深。我自己第一个 Skill 是前端的代码规范检查写得稀烂但正是那个烂版本让我彻底搞懂了SKILL.md和脚本之间怎么配合。后来自写自用的熟练度是光靠下载别人的包无法获得的。第二条经验保持 Skill 小而精。每当我忍不住往一个 Skill 里塞新功能时都会想起吃过的亏。功能越多触发越不准维护越痛苦。一个 Skill 超过两个脚本、超过一百行说明我就会认真考虑是不是该拆了。第三条经验版本管理要用上。Skills 目录放在 Git 仓库里管理每次改动写清楚 commit message。因为模型在不同版本下的表现会有微妙差异有了版本记录哪天发现效果变差还能回溯到上一个可用版本做对比。第四条经验测试集要留好。我为自己的每个 Skill 都留了一份测试输入和期望输出每次改代码后先跑一遍测试集。Skill 开发和普通软件开发本质上是同一件事——没有回归测试你永远无法确信改动没有破坏已有功能。这是我被现实教育过后才养成的习惯希望你能少走这一步。