这两年 agent 赛道最热闹的关键词除了 MCP 就是 Skills。如果你经常刷 GitHub、Reddit 或者 X一定见过一堆人晒自己写的 frontend skills、superpower skills还有人在讨论怎么给 Claude 装 skills、给 Codex 配 skills。很多朋友第一次看到SKILL.md这个文件名时都懵了这到底是个什么格式跟普通 prompt 有什么区别为什么装进自己的项目里却不生效这篇文章我不打算从头念文档而是站在实际使用和开发的角度把自己踩过的坑、验证过的方案、以及社区里真正好用的 skills 一并讲清楚。无论你是刚听说 skills 想试水的新手还是已经在维护自己 skill 仓库的老手应该都能从里面找到些能直接拿来用的东西。1. Skills 到底是什么为什么这么设计1.1 从隐式指令到显式技能先说一个最直观的类比。以前你让 agent 干活通常是在 system prompt 里写一大堆话比如“你是资深前端写代码时注意组件拆分、样式隔离、响应式适配”。这种做法的本质是把所有指令压在一段文本里让模型自己去理解、去记忆、去调用。问题在于提示词越长模型越容易抓不住重点而且每次对话都要重新“复习”这些内容既浪费 token又容易在长上下文里忽略细节。Skills 换了一种思路把“能力”本身做成一个独立单元放到专门目录里。这个单元有固定的结构、有说明文档、有配套脚本agent 在真正需要某类任务时才会去读取和加载。也就是说你不必在每轮对话里都提醒它“你是前端专家”而是给它一个可以随时翻开的工具箱需要时拿起来不需要时就放在那里。我第一次用 Claude 的 agent skills 时最大的感受是它更像“按需调用”而非“全量塞入”。系统提示词里只保留最基础的交互规则而真正专业的知识、模板、检查清单全部放在 skill 内部。这样既把主提示词保持精简又能让模型在关键时刻拿到足够细的操作指南。1.2 渐进式加载的核心思想Claude 官方那篇著名的《agent skills: a first principles deep dive》里反复强调了一个词progressive disclosure也就是渐进式披露。这个概念如果用大白话翻译就是“先看目录再翻正文”。具体来说agent 一开始只知道有哪些 skills 存在但不会把每个 skill 的全文都读一遍。只有当你提出的任务和某个 skill 的描述匹配上它才会去读取该 skill 的完整内容。就好比一个仓库管理员不会把所有货架的物品清单都背下来但他知道东西放哪、什么时候该去哪个货架取。这个设计带来的好处非常实际。第一上下文窗口被高效利用模型不会因为加载过多技能文档而丢失重点第二多个 skills 并存时不会互相干扰每个技能都能保持独立性第三生产成本更低你想新增一个技能时不需要改动全局提示词只需要新加一个目录。理解了这一点你就能明白为什么社区里会出现 tansu 这类被反复推荐的工具。它本质上是把多个单一技能的目录组合在一起让 agent 按需取用。很多“superpower skills”合集被大家追捧不是因为它们内容有多玄而是它们充分遵循了渐进式加载原则每份 skill 内部结构清楚、职责单一agent 一眼就能判断何时调用。1.3 与 MCP、插件、传统 prompt 的区别很多朋友会把这些概念混在一起实际上一开始我也在群里问过“有 MCP 了为什么还要 skills”。这里需要简单区分MCPModel Context Protocol解决的是“agent 如何连接外部工具和数据源”的问题它定义的是一套标准协议让模型能读写文件、调用 API、执行数据库查询而 Skills 解决的是“agent 如何在特定任务上表现出专业技能”的问题它提供的是一套知识、流程和模板。换个说法MCP 像是给了 agent 一双手让它能操作键盘鼠标Skills 则像是给 agent 一套完整的操作手册告诉它遇到某类问题应该按什么步骤处理、使用什么参数、规避什么坑。两者是可以配合的你的 skill 可以建议 agent 去调用某个 MCP 工具也可以完全依赖本地脚本完成工作。至于插件插件通常依赖特定宿主应用的运行时和接口规范而 skills 本身只是标准化的文件结构不绑定特定框架。这也是它跨平台、跨产品流行起来的原因。Claude 在用Codex 也在用大家基于同一套约定来组织和分发“技能包”让 agent 的能力边界可以像 npm 包一样被共享和安装。2. Skill 的目录结构与核心细节2.1 标准目录布局先说最简单的结构。一个 skill 本质上就是一个文件夹里面通常包含一个SKILL.md文件作为入口以及若干辅助目录和资源文件。典型的布局如下my-skill/ ├── SKILL.md ├── reference/ │ ├── 术语表.md │ └── 最佳实践.md ├── scripts/ │ ├── generate_names.py │ └── check_format.py └── assets/ ├── template.html └── logo.pngSKILL.md是核心它负责告诉模型“这个技能是干嘛的、什么时候使用、怎么用”。reference目录放辅助参考资料scripts目录放可执行脚本assets目录放模板、图片等非代码资源。对于更简单的技能一个SKILL.md单独就能撑起来对于复杂技能额外文件会让主文档更清爽。这里要提醒一点有些人在 GitHub 看到别人仓库里直接放SKILL.md就以为是普通 Markdown 文档复制到自己的目录下却用不了往往就是目录层级没放对。Skill 文件夹必须作为一个独立目录存在agent 按照文件夹名去索引而不是在项目根目录胡乱放一个同名文件。2.2 如何写一份高质量的 SKILL.md写SKILL.md不是写说明书而是写“给模型看的操作手册”。文本要结构清晰、指令明确、有可执行步骤。我一般会按照下面的骨架来写Frontmatter 元信息包括name、description其中description特别关键它会告诉 agent 何时该调用这个技能。描述里要包含触发条件、适用场景和典型任务类型写得越具体模型越容易在合适时机“想起”它。技能目标用两三句话说明这个技能要达成什么结果。比如“为一篇技术文章生成清晰的 Markdown 大纲包含引言、核心章节、FAQ 和结尾建议”。使用步骤按操作顺序列出模型应该执行的流程尽量细化到每个环节的输入、处理和输出。关键约束写明哪些事情不能做。比如“不要修改用户指定之外的文件”“不要删除已有目录结构”“生成的代码必须通过 ESLint 检查”。示例给出一到两个具体例子展示理想输出长什么样。很多人写 skill 写不好最常见的毛病是 description 写得过于宽泛。比如把 description 写成“帮助用户完成各种前端任务”这样的描述等于没写agent 无法判断什么时候该加载它。好的描述应该像这样“当用户需要创建或重构 React 组件、检查组件性能问题、生成可复用组件模板时使用此技能。”2.3 参数、依赖与执行策略复杂 skill 往往需要让 agent 执行脚本或读取外部文件。这里就涉及几个容易踩坑的细节。第一参数传递。如果你在SKILL.md里让模型运行python scripts/generate.py一定要写明参数怎么传、参数含义是什么最好附带一个示例命令。模型并不知道你的脚本内部逻辑你写得越明白它执行越准确。第二依赖环境。如果脚本用到了第三方库请在SKILL.md里注明安装方式和所需版本。比如“执行前请确保已安装 pandas 2.0可使用 pip install pandas 安装”。没有这一步模型可能在缺依赖时反复报错你还要花时间排查。第三执行策略。有些 skill 需要先读取参考文档再执行任务建议在步骤里明确“第一步读取 reference/xxx.md第二步基于文档内容执行……”。这样模型不会跳步结果更可控。我还习惯在每个 skill 里加一段“自检清单”让模型在输出之前逐项检查。比如写论文润色 skill 时会要求模型检查引用格式、段落衔接、术语统一写前端组件时会要求检查 accessibility、边界情况和错误处理。这个习惯帮我在实际使用中减少了很多返工。3. 安装、创建、调试的完整实操流程3.1 以 Claude Skills 为例目录放置与引入先说 Claude 这边的安装方式流程并不复杂但很多人第一次都卡在路径上。Claude 的 Skills 通常放在用户级目录下的.claude/skills/文件夹里每个 skill 占用一个子目录。以我的环境为例我的前端 skill 路径就是~/.claude/skills/frontend-dev/ ├── SKILL.md ├── reference/ 组件规范.md └── scripts/ scaffold.sh放在用户级目录的好处是全局可用不管你在哪个项目里工作Claude 都能识别到这些 skills。如果你只想让某个项目使用特定 skills也可以放到项目根目录下的.claude/skills/作用范围就限制在当前项目里。装好之后怎么确认生效最简单的办法是开启一个新的对话直接问一句“你现在有哪些可用的 skills”。正常情况下 agent 会列举出它扫描到的技能清单。如果回答里没有你刚放的 skill先检查目录结构是否正确、SKILL.md是否存在。我最初犯过的错误是把 SKILL.md 直接放在了.claude/skills/根目录下没有单独建立子文件夹结果始终无法识别。后来才意识到SKILL.md必须存在于某技能目录内部例如.claude/skills/frontend-dev/SKILL.md而不是.claude/skills/SKILL.md。3.2 以 Codex Skills 为例位置与配置CodexOpenAI 的命令行工具也支持类似机制路径上略有差异。我的默认配置放在~/.codex/skills/目录同样每个技能一个文件夹。第一次配置时我踩过一个坑Codex 在较新版本里要求 skill 目录下必须有SKILL.md并且该文件的格式要符合特定 frontmatter 规范否则工具会直接跳过这个 skill且不会给出明显警告。OpenAI 的 Codex 对 skill 的使用方式与 Claude 略有不同它更强调让模型在需要时通过内置的 skills 工具去加载。你可以把技能描述看作“服务目录”模型根据用户请求决定检索哪些技能。这意味着 skill 的description字段写得是否精准直接决定了被调用的概率。我的建议是写好一个 skill 后先做一个最简单的验证在 Codex 交互界面里输入一个明显匹配该技能的任务观察它是否会主动查阅该 skill。如果连续两次都没有触发大概率是 description 描述不够精准或者任务与描述之间匹配度不足。可以尝试把任务描述换成和 skill 描述相近的措辞再测试一次。3.3 调试会话让模型真正调用 skill装了却不调用是大家反馈最多的问题比安装失败还要普遍。这里有很多因素叠加但最核心的就是“匹配信号不强”。我们拿一个具体场景说明假设我写了一个paper-polish论文润色skill描述为“当用户要求对学术论文进行语言润色、逻辑优化、引用格式检查时使用”。如果用户在对话里只是简单说“帮我改改这段文字”模型很可能不会触发该 skill因为“改改文字”的意图很泛没有明确指向学术场景。但当你把 task 换成“请使用 paper-polish 技能帮我润色这段学术论文”模型基本都能正确调用。所以调试时不要总怪模型“笨”先从自身描述找原因。你把触发条件写得越窄、越具体、越贴合用户真实说法触发率就越高。另一个技巧是在SKILL.md里加入一段“如何检测是否适用本技能”让模型在不确定时自行核对条件列表。这相当于给模型一个判断题比单纯描述泛化场景有效得多。为了确认是否真的调用了 skill我会在SKILL.md里故意加入一些可观测的标记例如“请在完成任务后输出一行以 [paper-polish] 开头的处理记录”。如果最后输出里出现了这行标记就说明 skill 真的被读进去了。这个方法看起来笨但排查问题非常高效。3.4 版本管理与团队协作当你攒了十几个 skills 以后版本管理就变得重要了。我见过很多个人开发者直接把 skills 放进.gitignore理由是“这是本机的配置文件”。但对于团队协作或长期维护来说我更建议把 skills 当作独立仓库来管理最好建一个团队公共仓库每个人通过 git 同步到各自的.claude/skills/或~/.codex/skills/目录。这样做的好处有三个一是技能变更可追溯因为 skill 本质上是一份文档加脚本迭代过程中很容易出现“上一版能用、这版改了反而失效”的情况git 可以帮你对比差异二是有 Code Review 空间写 skill 其实是写产品团队成员评审能及时发现描述偏差或步骤缺漏三是新成员上手快克隆仓库后按说明放置目录即可不用口口相传。我在团队里推行过一个简单约定每个 skill 的SKILL.md必须包含change log区块记录最近三次修改。这个约定成本很低却让我们后续排查问题时少走了很多弯路。4. 常见问题与排查技巧实录4.1 模型不调用 skill这是出现频率最高的问题前面已经提过一些原因这里再系统梳理。模型不调用 skill可能的原因按优先级排序如下描述不精准触发条件和用户请求匹配度低。解决办法改写 description加入更多同义触发词和示例任务。skill 目录结构不对模型根本没扫描到。解决办法确认目录层级和SKILL.md位置。会话上下文太长模型忽略了技能索引。解决办法新开会话或者主动点名要求使用。模型版本或工具版本较旧不支持 skills 特性。解决办法升级客户端或工具版本。多个 skill 描述相互干扰模型不知道该选哪个。解决办法让每个 skill 职责边界更清晰减少重叠。我最常遇到的是第一种和第五种。之前写了一个frontend-devskill 和一个code-reviewskill两个描述里都提到了“检查代码质量”结果有时模型不知道该调哪个。后来我把code-review的描述改成“当用户明确要求进行代码审查、检查代码规范或提交代码评审意见时使用”问题就解决了。4.2 路径与跨平台问题路径问题在本地开发时往往不明显但换一台电脑或换一个用户目录就会爆发。我遇到过几种典型情况使用 Windows 时路径分隔符与SKILL.md里写的脚本路径不一致导致脚本无法执行。解决办法在 skill 文档里明确注明“如果遇到路径分隔符问题请使用操作系统默认形式或转换为绝对路径”。项目级 skill 路径和用户级 skill 路径同时存在agent 加载了项目级版本但用户以为是用户级版本在生效。解决办法在调试时先确认当前有效路径到底在哪里。相对路径解析错误。SKILL.md里写scripts/check.py时agent 可能把当前工作目录而非 skill 目录作为基准。解决办法在文档中写清楚“脚本路径相对于本 skill 文件夹”或者让模型在运行前先用pwd确认工作目录。这类问题虽然琐碎但一旦踩到就是半小时起步。我的经验是写 skill 时尽量使用“相对于 SKILL.md 所在目录”的路径描述并在关键步骤里让模型先打印当前工作目录做二次确认。4.3 依赖、权限与其他环境问题如果你在 skill 里放了脚本那依赖和权限问题基本躲不掉。先说权限在 macOS 和 Linux 上如果脚本要执行一定要有可执行权限。我遇到过多次模型反馈“permission denied”最后发现是我从 Windows 拷贝过来的文件没有继承执行权限。解决办法很简单在 skill 的文档里写明“如果脚本无法执行请先运行 chmod x 脚本名”。依赖问题更常见尤其是在不同机器上共享 skills 时。Python 脚本依赖版本不一致、Node 脚本缺少全局包等等。能想到的最好办法仍然是在文档里写明依赖安装命令并提供一个自动化的初始化脚本。我在很多社区分享的 skill 里看到setup.sh或install.sh目的就是降低环境差异带来的挫败感。还有一种情况容易被忽略skill 里的脚本会修改用户目录下其他文件。比如某个代码生成 skill 会自动修改.eslintrc或package.json这可能会破坏用户原本的工程配置。解决方式是给 skill 增加“是否修改用户文件”的约束说明并默认不修改任何用户已有文件除非用户明确授权。4.4 问题排查速查表我把高频问题整理成一张速查表方便你遇到同样情况时直接对照。现象可能原因排查步骤模型完全不提 skillpath 错误或格式错误检查 SKILL.md 是否在独立子目录下frontmatter 是否完整模型不主动调用description 泛化精简描述并加入触发示例、同义词脚本执行权限失败缺少可执行权限执行 chmod x 或手动设置权限脚本找不到文件相对路径基准不明确在 SKILL.md 中写明基于 skill 目录的路径多个 skill 互相干扰职责重叠重新界定每个 skill 的适用边界skill 未被当前项目识别放错作用域确认是用户级目录还是项目级目录必要时重新放置这张表不是标准答案我自己也是在不断踩坑中补全的。如果你的问题不在表里不妨先从目录路径、描述匹配、依赖环境三个层面入手基本能覆盖九成以上的故障。5. 典型场景与优质 skills 实践5.1 前端开发 skills前端是 skills 社区里最活跃的领域之一。原因很简单前端任务高度重复化和规范化从初始化项目、组件拆分、样式修复到性能优化每一步都有“最佳实践”可言。我自己的frontend-devskill 就包含了组件规范、可访问性检查清单和常用代码模板每次让 agent 创建 React 组件或者调整页面时它都会先读取规范再动手输出质量明显比裸用通用能力更稳定。社区里被广泛讨论的“frontend skills”往往还会细分比如tailwind-skills、react-component-skills、vue-migration-skills。这类细分的好处是触发更精准一个任务进来就只会加载对应的知识不会把无关的前端内容也塞进上下文。建议你在下载类似技能时先看一眼它的SKILL.md结构确认 reference 文档是否齐全、模板是否有实际价值而不是只看 README 里的吹嘘。5.2 学术写作与论文 skills写论文、写技术报告的场景是 skills 另一个大热门。社区里流行着“写论文的 skills”通常包含学术写作规范、引用格式模板、逻辑论证结构、以及行文风格示例。这类 skill 对内容创作者来说简直是救星因为学术写作的格式细节太多靠人肉提醒模型很容易遗漏。我测试过一个学术写作 skill体验比较深刻的一点是它会把任务拆成几个阶段分别是选题结构分析、段落润色、引用检查、定稿摘要。模型在每一阶段都会读取对应的 reference 文档比如reference/APA 格式.md从而保证输出符合具体规范。这比你在 prompt 里塞一整段“请按照 APA 格式改写”要可靠得多因为当参考文档被单独读取时模型对细节的注意力明显更强。如果你打算自己写一个论文写作 skill请务必把目标期刊或格式规范写得很具体比如“IEEE 格式”和“APA 格式”的引用差异非常大混用会让文章直接被退稿。5.3 分镜与内容创作 skills自媒体和短视频领域也出现了不少“分镜 skills”。这类技能的应用场景是你告诉 agent 视频主题、目标时长、受众人群它根据分镜脚本书写规范生成表格包含镜头序号、景别、画面内容、台词、音效和字幕建议。相比直接用 prompts 生成分镜skill 的按需加载优势在这里特别明显平时你看视频脚本时它不会打扰一旦你说“帮我写一个 3 分钟城市探索 vlog 的分镜脚本”它马上就知道要加载哪套模板。这类 skill 往往依赖 assets 目录里的模板文件。写模板时建议给出真实案例例如一个 30 秒广告分镜示例让模型有样可循。我见过一些内容创作 skill 只给出结构没有案例模型生成的表格会非常生硬而加了案例之后效果直接上了一个台阶。5.4 安全测试与自动化审计 skills这个方向在技术社区里讨论得也比较多所谓的“自动挖洞 skills”本质上就是把 Web 安全测试中的信息收集、漏洞扫描、结果分析等步骤标准化让 agent 在授权测试中按照规范执行。我在这里必须强调一句话所有安全测试相关的自动化操作都只能用于你有明确授权的目标。没授权的扫描无论出于什么目的都是越界行为这也是我使用此类 skill 的铁律。实践层面一个好的安全审计 skill 不会教 agent“直接掏工具乱扫”而是引导它先做信息收集、确认资产归属、再根据配置选择合理的检查项。换句话说它更像一份标准作业流程手册用来降低误操作和违规风险。我自己在测试自己的站时用过这类技能最大的启发是它把“检查输入输出边界”和“查看漏洞披露库”这类动作做成了清单不容易漏项比临时从脑子里蹦出来几个想法专业得多。如果你也考虑使用自动化审计 skill我给出三个原则第一只在自己或授权的资产上执行第二每次执行前确认目标范围和边界第三发现问题后重点关注修复建议和复测验证而不是停留在“能扫出漏洞”这一步。安全测试的最终目的是加固系统不是折腾旁人的业务。5.5 从哪找 skills如何甄别质量现在 skills 的获取渠道很多。除了各个产品自带的官方 skill 目录GitHub 上也有大量开源仓库还有一些社区站点专门做 skills 的分类和推荐。国内开发者经常问的“skills 下载平台有哪些”其实不需要迷信某个特定平台因为 skills 的本质就是文件夹和文件只要找到压缩包或者仓库放到对应目录就能用。不过下载和安装 skill 之前务必要看三点。第一看维护状态。如果仓库半年没更新里面的参考文档可能已经过时尤其前端和工具链变化非常快。第二看SKILL.md是否清晰。一个连主文档都写得含糊的 skill很难想象它实际运行起来会靠谱。第三看脚本的安全性。因为 skill 里的脚本会在你的机器上执行所以下载别人的 skill 前最好逐行看一下脚本内容确认没有可疑操作。这一点非常重要不要因为对方仓库 star 多就无条件信任。GitHub 上有个容易混淆的概念叫 “GitHub Skills”它是官方推出的交互式学习课程平台和 agent 运行时的 skills 是两回事。我最初也闹过乌龙在 GitHub Skills 的页面里找 agent 技能包找了一圈才发现自己搞混了。如果你也是冲着 agent 技能去的记得要在代码仓库或技能分享社区里搜索而不是去 GitHub 的官方学习页面。每个人用 skills 的方式都不太一样但我觉得核心就一句话把专业知识从对话里搬到文件里让模型在需要时按需取用。我自己现在维护着一个约二十个 skills 的仓库里面既有前端、写作、分镜这类内容型技能也有一些自动化脚本类技能。每次新增技能时我都会先花半小时把场景边界想清楚再动手写而不是想起什么就往里塞。用多了之后我最大的体会是 skills 的价值不在“多”而在“准”。一个描述精准、结构清晰、模板完善的 skill比十个泛泛而谈的合集管用得多。而且写 skill 这件事本身也是对自己工作流的一次梳理你会发现那些你反复让模型做的事情其实都可以沉淀成一份规范文档变成一个真正属于你的“superpower”。 
长河君 · 2026/10/7 14:09:44 · 阅读 1.2k 从SKILL.md到Agent Skills：构建高质量AI技能包的实战指南
这两年 agent 赛道最热闹的关键词除了 MCP 就是 Skills。如果你经常刷 GitHub、Reddit 或者 X一定见过一堆人晒自己写的 frontend skills、superpower skills还有人在讨论怎么给 Claude 装 skills、给 Codex 配 skills。很多朋友第一次看到SKILL.md这个文件名时都懵了这到底是个什么格式跟普通 prompt 有什么区别为什么装进自己的项目里却不生效这篇文章我不打算从头念文档而是站在实际使用和开发的角度把自己踩过的坑、验证过的方案、以及社区里真正好用的 skills 一并讲清楚。无论你是刚听说 skills 想试水的新手还是已经在维护自己 skill 仓库的老手应该都能从里面找到些能直接拿来用的东西。1. Skills 到底是什么为什么这么设计1.1 从隐式指令到显式技能先说一个最直观的类比。以前你让 agent 干活通常是在 system prompt 里写一大堆话比如“你是资深前端写代码时注意组件拆分、样式隔离、响应式适配”。这种做法的本质是把所有指令压在一段文本里让模型自己去理解、去记忆、去调用。问题在于提示词越长模型越容易抓不住重点而且每次对话都要重新“复习”这些内容既浪费 token又容易在长上下文里忽略细节。Skills 换了一种思路把“能力”本身做成一个独立单元放到专门目录里。这个单元有固定的结构、有说明文档、有配套脚本agent 在真正需要某类任务时才会去读取和加载。也就是说你不必在每轮对话里都提醒它“你是前端专家”而是给它一个可以随时翻开的工具箱需要时拿起来不需要时就放在那里。我第一次用 Claude 的 agent skills 时最大的感受是它更像“按需调用”而非“全量塞入”。系统提示词里只保留最基础的交互规则而真正专业的知识、模板、检查清单全部放在 skill 内部。这样既把主提示词保持精简又能让模型在关键时刻拿到足够细的操作指南。1.2 渐进式加载的核心思想Claude 官方那篇著名的《agent skills: a first principles deep dive》里反复强调了一个词progressive disclosure也就是渐进式披露。这个概念如果用大白话翻译就是“先看目录再翻正文”。具体来说agent 一开始只知道有哪些 skills 存在但不会把每个 skill 的全文都读一遍。只有当你提出的任务和某个 skill 的描述匹配上它才会去读取该 skill 的完整内容。就好比一个仓库管理员不会把所有货架的物品清单都背下来但他知道东西放哪、什么时候该去哪个货架取。这个设计带来的好处非常实际。第一上下文窗口被高效利用模型不会因为加载过多技能文档而丢失重点第二多个 skills 并存时不会互相干扰每个技能都能保持独立性第三生产成本更低你想新增一个技能时不需要改动全局提示词只需要新加一个目录。理解了这一点你就能明白为什么社区里会出现 tansu 这类被反复推荐的工具。它本质上是把多个单一技能的目录组合在一起让 agent 按需取用。很多“superpower skills”合集被大家追捧不是因为它们内容有多玄而是它们充分遵循了渐进式加载原则每份 skill 内部结构清楚、职责单一agent 一眼就能判断何时调用。1.3 与 MCP、插件、传统 prompt 的区别很多朋友会把这些概念混在一起实际上一开始我也在群里问过“有 MCP 了为什么还要 skills”。这里需要简单区分MCPModel Context Protocol解决的是“agent 如何连接外部工具和数据源”的问题它定义的是一套标准协议让模型能读写文件、调用 API、执行数据库查询而 Skills 解决的是“agent 如何在特定任务上表现出专业技能”的问题它提供的是一套知识、流程和模板。换个说法MCP 像是给了 agent 一双手让它能操作键盘鼠标Skills 则像是给 agent 一套完整的操作手册告诉它遇到某类问题应该按什么步骤处理、使用什么参数、规避什么坑。两者是可以配合的你的 skill 可以建议 agent 去调用某个 MCP 工具也可以完全依赖本地脚本完成工作。至于插件插件通常依赖特定宿主应用的运行时和接口规范而 skills 本身只是标准化的文件结构不绑定特定框架。这也是它跨平台、跨产品流行起来的原因。Claude 在用Codex 也在用大家基于同一套约定来组织和分发“技能包”让 agent 的能力边界可以像 npm 包一样被共享和安装。2. Skill 的目录结构与核心细节2.1 标准目录布局先说最简单的结构。一个 skill 本质上就是一个文件夹里面通常包含一个SKILL.md文件作为入口以及若干辅助目录和资源文件。典型的布局如下my-skill/ ├── SKILL.md ├── reference/ │ ├── 术语表.md │ └── 最佳实践.md ├── scripts/ │ ├── generate_names.py │ └── check_format.py └── assets/ ├── template.html └── logo.pngSKILL.md是核心它负责告诉模型“这个技能是干嘛的、什么时候使用、怎么用”。reference目录放辅助参考资料scripts目录放可执行脚本assets目录放模板、图片等非代码资源。对于更简单的技能一个SKILL.md单独就能撑起来对于复杂技能额外文件会让主文档更清爽。这里要提醒一点有些人在 GitHub 看到别人仓库里直接放SKILL.md就以为是普通 Markdown 文档复制到自己的目录下却用不了往往就是目录层级没放对。Skill 文件夹必须作为一个独立目录存在agent 按照文件夹名去索引而不是在项目根目录胡乱放一个同名文件。2.2 如何写一份高质量的 SKILL.md写SKILL.md不是写说明书而是写“给模型看的操作手册”。文本要结构清晰、指令明确、有可执行步骤。我一般会按照下面的骨架来写Frontmatter 元信息包括name、description其中description特别关键它会告诉 agent 何时该调用这个技能。描述里要包含触发条件、适用场景和典型任务类型写得越具体模型越容易在合适时机“想起”它。技能目标用两三句话说明这个技能要达成什么结果。比如“为一篇技术文章生成清晰的 Markdown 大纲包含引言、核心章节、FAQ 和结尾建议”。使用步骤按操作顺序列出模型应该执行的流程尽量细化到每个环节的输入、处理和输出。关键约束写明哪些事情不能做。比如“不要修改用户指定之外的文件”“不要删除已有目录结构”“生成的代码必须通过 ESLint 检查”。示例给出一到两个具体例子展示理想输出长什么样。很多人写 skill 写不好最常见的毛病是 description 写得过于宽泛。比如把 description 写成“帮助用户完成各种前端任务”这样的描述等于没写agent 无法判断什么时候该加载它。好的描述应该像这样“当用户需要创建或重构 React 组件、检查组件性能问题、生成可复用组件模板时使用此技能。”2.3 参数、依赖与执行策略复杂 skill 往往需要让 agent 执行脚本或读取外部文件。这里就涉及几个容易踩坑的细节。第一参数传递。如果你在SKILL.md里让模型运行python scripts/generate.py一定要写明参数怎么传、参数含义是什么最好附带一个示例命令。模型并不知道你的脚本内部逻辑你写得越明白它执行越准确。第二依赖环境。如果脚本用到了第三方库请在SKILL.md里注明安装方式和所需版本。比如“执行前请确保已安装 pandas 2.0可使用 pip install pandas 安装”。没有这一步模型可能在缺依赖时反复报错你还要花时间排查。第三执行策略。有些 skill 需要先读取参考文档再执行任务建议在步骤里明确“第一步读取 reference/xxx.md第二步基于文档内容执行……”。这样模型不会跳步结果更可控。我还习惯在每个 skill 里加一段“自检清单”让模型在输出之前逐项检查。比如写论文润色 skill 时会要求模型检查引用格式、段落衔接、术语统一写前端组件时会要求检查 accessibility、边界情况和错误处理。这个习惯帮我在实际使用中减少了很多返工。3. 安装、创建、调试的完整实操流程3.1 以 Claude Skills 为例目录放置与引入先说 Claude 这边的安装方式流程并不复杂但很多人第一次都卡在路径上。Claude 的 Skills 通常放在用户级目录下的.claude/skills/文件夹里每个 skill 占用一个子目录。以我的环境为例我的前端 skill 路径就是~/.claude/skills/frontend-dev/ ├── SKILL.md ├── reference/ 组件规范.md └── scripts/ scaffold.sh放在用户级目录的好处是全局可用不管你在哪个项目里工作Claude 都能识别到这些 skills。如果你只想让某个项目使用特定 skills也可以放到项目根目录下的.claude/skills/作用范围就限制在当前项目里。装好之后怎么确认生效最简单的办法是开启一个新的对话直接问一句“你现在有哪些可用的 skills”。正常情况下 agent 会列举出它扫描到的技能清单。如果回答里没有你刚放的 skill先检查目录结构是否正确、SKILL.md是否存在。我最初犯过的错误是把 SKILL.md 直接放在了.claude/skills/根目录下没有单独建立子文件夹结果始终无法识别。后来才意识到SKILL.md必须存在于某技能目录内部例如.claude/skills/frontend-dev/SKILL.md而不是.claude/skills/SKILL.md。3.2 以 Codex Skills 为例位置与配置CodexOpenAI 的命令行工具也支持类似机制路径上略有差异。我的默认配置放在~/.codex/skills/目录同样每个技能一个文件夹。第一次配置时我踩过一个坑Codex 在较新版本里要求 skill 目录下必须有SKILL.md并且该文件的格式要符合特定 frontmatter 规范否则工具会直接跳过这个 skill且不会给出明显警告。OpenAI 的 Codex 对 skill 的使用方式与 Claude 略有不同它更强调让模型在需要时通过内置的 skills 工具去加载。你可以把技能描述看作“服务目录”模型根据用户请求决定检索哪些技能。这意味着 skill 的description字段写得是否精准直接决定了被调用的概率。我的建议是写好一个 skill 后先做一个最简单的验证在 Codex 交互界面里输入一个明显匹配该技能的任务观察它是否会主动查阅该 skill。如果连续两次都没有触发大概率是 description 描述不够精准或者任务与描述之间匹配度不足。可以尝试把任务描述换成和 skill 描述相近的措辞再测试一次。3.3 调试会话让模型真正调用 skill装了却不调用是大家反馈最多的问题比安装失败还要普遍。这里有很多因素叠加但最核心的就是“匹配信号不强”。我们拿一个具体场景说明假设我写了一个paper-polish论文润色skill描述为“当用户要求对学术论文进行语言润色、逻辑优化、引用格式检查时使用”。如果用户在对话里只是简单说“帮我改改这段文字”模型很可能不会触发该 skill因为“改改文字”的意图很泛没有明确指向学术场景。但当你把 task 换成“请使用 paper-polish 技能帮我润色这段学术论文”模型基本都能正确调用。所以调试时不要总怪模型“笨”先从自身描述找原因。你把触发条件写得越窄、越具体、越贴合用户真实说法触发率就越高。另一个技巧是在SKILL.md里加入一段“如何检测是否适用本技能”让模型在不确定时自行核对条件列表。这相当于给模型一个判断题比单纯描述泛化场景有效得多。为了确认是否真的调用了 skill我会在SKILL.md里故意加入一些可观测的标记例如“请在完成任务后输出一行以 [paper-polish] 开头的处理记录”。如果最后输出里出现了这行标记就说明 skill 真的被读进去了。这个方法看起来笨但排查问题非常高效。3.4 版本管理与团队协作当你攒了十几个 skills 以后版本管理就变得重要了。我见过很多个人开发者直接把 skills 放进.gitignore理由是“这是本机的配置文件”。但对于团队协作或长期维护来说我更建议把 skills 当作独立仓库来管理最好建一个团队公共仓库每个人通过 git 同步到各自的.claude/skills/或~/.codex/skills/目录。这样做的好处有三个一是技能变更可追溯因为 skill 本质上是一份文档加脚本迭代过程中很容易出现“上一版能用、这版改了反而失效”的情况git 可以帮你对比差异二是有 Code Review 空间写 skill 其实是写产品团队成员评审能及时发现描述偏差或步骤缺漏三是新成员上手快克隆仓库后按说明放置目录即可不用口口相传。我在团队里推行过一个简单约定每个 skill 的SKILL.md必须包含change log区块记录最近三次修改。这个约定成本很低却让我们后续排查问题时少走了很多弯路。4. 常见问题与排查技巧实录4.1 模型不调用 skill这是出现频率最高的问题前面已经提过一些原因这里再系统梳理。模型不调用 skill可能的原因按优先级排序如下描述不精准触发条件和用户请求匹配度低。解决办法改写 description加入更多同义触发词和示例任务。skill 目录结构不对模型根本没扫描到。解决办法确认目录层级和SKILL.md位置。会话上下文太长模型忽略了技能索引。解决办法新开会话或者主动点名要求使用。模型版本或工具版本较旧不支持 skills 特性。解决办法升级客户端或工具版本。多个 skill 描述相互干扰模型不知道该选哪个。解决办法让每个 skill 职责边界更清晰减少重叠。我最常遇到的是第一种和第五种。之前写了一个frontend-devskill 和一个code-reviewskill两个描述里都提到了“检查代码质量”结果有时模型不知道该调哪个。后来我把code-review的描述改成“当用户明确要求进行代码审查、检查代码规范或提交代码评审意见时使用”问题就解决了。4.2 路径与跨平台问题路径问题在本地开发时往往不明显但换一台电脑或换一个用户目录就会爆发。我遇到过几种典型情况使用 Windows 时路径分隔符与SKILL.md里写的脚本路径不一致导致脚本无法执行。解决办法在 skill 文档里明确注明“如果遇到路径分隔符问题请使用操作系统默认形式或转换为绝对路径”。项目级 skill 路径和用户级 skill 路径同时存在agent 加载了项目级版本但用户以为是用户级版本在生效。解决办法在调试时先确认当前有效路径到底在哪里。相对路径解析错误。SKILL.md里写scripts/check.py时agent 可能把当前工作目录而非 skill 目录作为基准。解决办法在文档中写清楚“脚本路径相对于本 skill 文件夹”或者让模型在运行前先用pwd确认工作目录。这类问题虽然琐碎但一旦踩到就是半小时起步。我的经验是写 skill 时尽量使用“相对于 SKILL.md 所在目录”的路径描述并在关键步骤里让模型先打印当前工作目录做二次确认。4.3 依赖、权限与其他环境问题如果你在 skill 里放了脚本那依赖和权限问题基本躲不掉。先说权限在 macOS 和 Linux 上如果脚本要执行一定要有可执行权限。我遇到过多次模型反馈“permission denied”最后发现是我从 Windows 拷贝过来的文件没有继承执行权限。解决办法很简单在 skill 的文档里写明“如果脚本无法执行请先运行 chmod x 脚本名”。依赖问题更常见尤其是在不同机器上共享 skills 时。Python 脚本依赖版本不一致、Node 脚本缺少全局包等等。能想到的最好办法仍然是在文档里写明依赖安装命令并提供一个自动化的初始化脚本。我在很多社区分享的 skill 里看到setup.sh或install.sh目的就是降低环境差异带来的挫败感。还有一种情况容易被忽略skill 里的脚本会修改用户目录下其他文件。比如某个代码生成 skill 会自动修改.eslintrc或package.json这可能会破坏用户原本的工程配置。解决方式是给 skill 增加“是否修改用户文件”的约束说明并默认不修改任何用户已有文件除非用户明确授权。4.4 问题排查速查表我把高频问题整理成一张速查表方便你遇到同样情况时直接对照。现象可能原因排查步骤模型完全不提 skillpath 错误或格式错误检查 SKILL.md 是否在独立子目录下frontmatter 是否完整模型不主动调用description 泛化精简描述并加入触发示例、同义词脚本执行权限失败缺少可执行权限执行 chmod x 或手动设置权限脚本找不到文件相对路径基准不明确在 SKILL.md 中写明基于 skill 目录的路径多个 skill 互相干扰职责重叠重新界定每个 skill 的适用边界skill 未被当前项目识别放错作用域确认是用户级目录还是项目级目录必要时重新放置这张表不是标准答案我自己也是在不断踩坑中补全的。如果你的问题不在表里不妨先从目录路径、描述匹配、依赖环境三个层面入手基本能覆盖九成以上的故障。5. 典型场景与优质 skills 实践5.1 前端开发 skills前端是 skills 社区里最活跃的领域之一。原因很简单前端任务高度重复化和规范化从初始化项目、组件拆分、样式修复到性能优化每一步都有“最佳实践”可言。我自己的frontend-devskill 就包含了组件规范、可访问性检查清单和常用代码模板每次让 agent 创建 React 组件或者调整页面时它都会先读取规范再动手输出质量明显比裸用通用能力更稳定。社区里被广泛讨论的“frontend skills”往往还会细分比如tailwind-skills、react-component-skills、vue-migration-skills。这类细分的好处是触发更精准一个任务进来就只会加载对应的知识不会把无关的前端内容也塞进上下文。建议你在下载类似技能时先看一眼它的SKILL.md结构确认 reference 文档是否齐全、模板是否有实际价值而不是只看 README 里的吹嘘。5.2 学术写作与论文 skills写论文、写技术报告的场景是 skills 另一个大热门。社区里流行着“写论文的 skills”通常包含学术写作规范、引用格式模板、逻辑论证结构、以及行文风格示例。这类 skill 对内容创作者来说简直是救星因为学术写作的格式细节太多靠人肉提醒模型很容易遗漏。我测试过一个学术写作 skill体验比较深刻的一点是它会把任务拆成几个阶段分别是选题结构分析、段落润色、引用检查、定稿摘要。模型在每一阶段都会读取对应的 reference 文档比如reference/APA 格式.md从而保证输出符合具体规范。这比你在 prompt 里塞一整段“请按照 APA 格式改写”要可靠得多因为当参考文档被单独读取时模型对细节的注意力明显更强。如果你打算自己写一个论文写作 skill请务必把目标期刊或格式规范写得很具体比如“IEEE 格式”和“APA 格式”的引用差异非常大混用会让文章直接被退稿。5.3 分镜与内容创作 skills自媒体和短视频领域也出现了不少“分镜 skills”。这类技能的应用场景是你告诉 agent 视频主题、目标时长、受众人群它根据分镜脚本书写规范生成表格包含镜头序号、景别、画面内容、台词、音效和字幕建议。相比直接用 prompts 生成分镜skill 的按需加载优势在这里特别明显平时你看视频脚本时它不会打扰一旦你说“帮我写一个 3 分钟城市探索 vlog 的分镜脚本”它马上就知道要加载哪套模板。这类 skill 往往依赖 assets 目录里的模板文件。写模板时建议给出真实案例例如一个 30 秒广告分镜示例让模型有样可循。我见过一些内容创作 skill 只给出结构没有案例模型生成的表格会非常生硬而加了案例之后效果直接上了一个台阶。5.4 安全测试与自动化审计 skills这个方向在技术社区里讨论得也比较多所谓的“自动挖洞 skills”本质上就是把 Web 安全测试中的信息收集、漏洞扫描、结果分析等步骤标准化让 agent 在授权测试中按照规范执行。我在这里必须强调一句话所有安全测试相关的自动化操作都只能用于你有明确授权的目标。没授权的扫描无论出于什么目的都是越界行为这也是我使用此类 skill 的铁律。实践层面一个好的安全审计 skill 不会教 agent“直接掏工具乱扫”而是引导它先做信息收集、确认资产归属、再根据配置选择合理的检查项。换句话说它更像一份标准作业流程手册用来降低误操作和违规风险。我自己在测试自己的站时用过这类技能最大的启发是它把“检查输入输出边界”和“查看漏洞披露库”这类动作做成了清单不容易漏项比临时从脑子里蹦出来几个想法专业得多。如果你也考虑使用自动化审计 skill我给出三个原则第一只在自己或授权的资产上执行第二每次执行前确认目标范围和边界第三发现问题后重点关注修复建议和复测验证而不是停留在“能扫出漏洞”这一步。安全测试的最终目的是加固系统不是折腾旁人的业务。5.5 从哪找 skills如何甄别质量现在 skills 的获取渠道很多。除了各个产品自带的官方 skill 目录GitHub 上也有大量开源仓库还有一些社区站点专门做 skills 的分类和推荐。国内开发者经常问的“skills 下载平台有哪些”其实不需要迷信某个特定平台因为 skills 的本质就是文件夹和文件只要找到压缩包或者仓库放到对应目录就能用。不过下载和安装 skill 之前务必要看三点。第一看维护状态。如果仓库半年没更新里面的参考文档可能已经过时尤其前端和工具链变化非常快。第二看SKILL.md是否清晰。一个连主文档都写得含糊的 skill很难想象它实际运行起来会靠谱。第三看脚本的安全性。因为 skill 里的脚本会在你的机器上执行所以下载别人的 skill 前最好逐行看一下脚本内容确认没有可疑操作。这一点非常重要不要因为对方仓库 star 多就无条件信任。GitHub 上有个容易混淆的概念叫 “GitHub Skills”它是官方推出的交互式学习课程平台和 agent 运行时的 skills 是两回事。我最初也闹过乌龙在 GitHub Skills 的页面里找 agent 技能包找了一圈才发现自己搞混了。如果你也是冲着 agent 技能去的记得要在代码仓库或技能分享社区里搜索而不是去 GitHub 的官方学习页面。每个人用 skills 的方式都不太一样但我觉得核心就一句话把专业知识从对话里搬到文件里让模型在需要时按需取用。我自己现在维护着一个约二十个 skills 的仓库里面既有前端、写作、分镜这类内容型技能也有一些自动化脚本类技能。每次新增技能时我都会先花半小时把场景边界想清楚再动手写而不是想起什么就往里塞。用多了之后我最大的体会是 skills 的价值不在“多”而在“准”。一个描述精准、结构清晰、模板完善的 skill比十个泛泛而谈的合集管用得多。而且写 skill 这件事本身也是对自己工作流的一次梳理你会发现那些你反复让模型做的事情其实都可以沉淀成一份规范文档变成一个真正属于你的“superpower”。