最近AI编程助手圈子里最热的一个词非Skills莫属。我刷GitHub趋势榜时一眼扫过去全是xxx-skills、skills-creator、awesome-claude-skills之类的仓库紧接着Codex、Cursor、OpenCode也纷纷跟进连吴恩达的Agent教程PDF里都用专门章节讲怎么给Agent装备Skills。作为从Claude Code第一版就开始折腾的老用户我想把这段时间摸爬滚打的经验梳理成一篇能直接照着用的文章——Skills到底是什么、现有生态怎么选、怎么调用MCP工具、怎么手写一个自己的Skills以及那些文档里不会写的坑。这篇文章适合所有在用或准备用AI编程助手的人。不管你是前端、后端、算法还是做学术的看完应该都能动手搭建自己的技能库而不是继续停留在靠嘴硬编提示词的阶段。1. 拆解Skills的本质它到底解决了什么问题1.1 从Prompt到Skills的进化先说背景。早期用AI写代码主流做法是把一段精心撰写的系统提示词System Prompt塞给模型让它扮演某个角色或遵循某种工作流。这种方式有个致命问题提示词越长模型越容易迷失而且无论干什么任务都得把这堆文字全部加载进去既费token又容易干扰主任务。Skills的解决思路完全不同。它把某个领域的一套完整工作方法封装成一个独立的目录目录里有一个SKILL.md作为入口里面只写最精炼的触发条件和核心指令。模型只有在判断当前任务匹配这个Skill时才会去加载完整内容。这就像你工具箱里的专用扳手——平时挂在墙上不占地方拧到对应型号的螺丝时才拿下来用。这个机制听起来简单但背后是AI应用设计思路的一次重要转变从喂给模型尽可能多的上下文变成让模型自主判断需要什么上下文。前者是被动的、静态的后者是主动的、动态的。1.2 SKILL.md的核心结构一个标准的Skill目录长这样my-skill/ ├── SKILL.md # 入口文件必须存在 ├── scripts/ # 可选的辅助脚本 ├── reference/ # 可选的参考资料、模板 └── assets/ # 可选的静态资源SKILL.md的开头是YAML格式的frontmatter用来声明两条最关键的信息name和description。description是模型判断要不要用这个Skill的依据写得好不好直接影响触发率。这里有个经验description里一定要写清楚这个Skill的适用场景、输入和输出最好带上具体例子。比如下面这样--- name: frontend-design-recovery description: 将设计稿图片还原为响应式HTML/CSS代码。适用于前端开发传入UI设计图需要输出可运行的页面代码。输入为图片路径输出为HTMLCSS文件。 ---正文则用清晰的Markdown结构说明这个Skill的工作流程。注意一个原则SKILL.md本身应该像一本书的目录而真正的章节内容放到reference目录里。这样做有两个好处——模型需要时按需读取不会把所有内容一次塞进上下文编写者也更容易维护和迭代。1.3 渐进式披露为什么这个设计很聪明Anthropic在设计Skills时用了一个概念叫Progressive Disclosure渐进式披露。核心理念是模型在对话开始时只看到每个Skill的名片name description一旦判定任务匹配才会读取SKILL.md的完整内容再按需读取reference目录下的详细文档。这个设计解决了AI工程里一个老大难问题——上下文窗口有限。假设你有20个Skill每个Skill完整展开需要3000 token一次性全部塞进上下文就是60000 token基本把窗口吃光了。有了渐进式披露模型只在需要时加载那3000 token效率和准确性都高很多。我经常跟人打个比方提示词就像把所有工具都摆在桌面上桌面上堆满了东西你反而找不到需要的那个Skills像是一个上了锁的工具柜柜门上贴着每个工具的标签需要哪个开哪个桌面始终干干净净。2. 主流工具的Skills生态Claude Code、Codex、Cursor怎么选2.1 Claude Code Skills的官方规范Claude Code在2024年底引入了Skills机制后来正式纳入官方文档。它的规则很简单把Skill目录放到项目根目录的.skills文件夹或用户级目录~/.claude/skills下Claude Code启动时会自动扫描并加载名片。官方对SKILL.md的编写有明确建议文件开头写YAML frontmatter正文用清晰的Markdown结构尽量把复杂的子步骤拆到reference目录里。实际操作中我建议大家把触发条件写进description否则模型可能不知道该在什么时候调用。比如一个专门写Git提交信息的Skilldescription里要写明当用户执行git commit或要求生成提交信息时使用而不是只写生成Git提交信息。社区里还有人专门做了skill-creator这样的辅助工具用AI帮AI写Skill绕归绕但确实能节省不少时间。这类工具通常会问你几个问题——这个Skill处理什么任务、输入是什么、输出是什么、有什么特殊要求——然后自动生成SKILL.md骨架和目录结构。2.2 Codex与OpenCode的差异OpenAI的Codex也支持Skills加载逻辑和Claude Code类似但配置路径不同需要放在~/.codex/skills下。OpenCode则有自己的一套skills机制项目默认扫描.opencode/skills目录。市面上已经有人做了转换工具可以把一份Skill同时部署到多个平台省去重复编写的麻烦。如果你主要用Claude Code又想让Codex也能用同一套技能GitHub上有不少skills-converter之类的开源项目。我实测下来纯指令型的Skills转换基本无损但涉及平台专属API比如Claude Code的Artifacts、Codex的Code Interpreter就得手动改改了。下面这张表是我整理的几个主流工具的差异方便大家快速对照工具Skills目录适用人群特别说明Claude Code.skills或~/.claude/skills全栈开发、Agent重度用户规范最早社区资源最多Codex~/.codex/skills依赖OpenAI生态的开发者同等结构转换成本低Cursor兼容Rules目录前端、轻量开发Rules常驻Skills按需加载OpenCode.opencode/skills喜欢开源CLI的人自定义程度高2.3 Cursor的Rules与Skills的关系Cursor用户经常把Rules和Skills混淆。简单说Rules是始终生效的全局/项目级规则更像是长期行为准则Skills是按需加载的能力包。Cursor 0.4x版本之后也开始兼容类似Skills的目录结构机制上跟Claude Code大同小异只是目录约定和变量注入的语法有差异。三者的关系可以用一句话总结Prompt是给AI写说明书Rules是给AI定制度Skills是给AI装技能包。制度能管住行为底线技能包则决定了它能干什么活。实际项目中三者往往配合使用——Rules里规定代码规范Skills里封装具体任务的执行流程Prompt里只留最基础的角色定义。3. Skills调用MCP工具外部能力的接入逻辑3.1 MCP是什么为什么要跟Skills搭配MCPModel Context Protocol是Anthropic提出的开放协议可以理解成AI世界的USB接口。通过MCPAI助手能访问数据库、浏览器、设计软件等外部系统。Skills负责知道怎么做MCP负责实际去执行两者是互补关系。搜索热词里很多人问skills如何调用mcp工具这确实是开发Skills时最常遇到的场景。比如你想做一个网页查资料并生成调研报告的Skill核心指令很简单——让模型先调用MCP的搜索工具去获取信息再按固定模板输出报告。这里的关键是SKILL.md里必须写清楚调用哪个MCP工具、传什么参数、拿到结果后怎么处理。3.2 在Skills中配置MCP的接入方式在Claude Code里MCP服务通过配置文件声明Skills目录本身不需要额外配置。你只需要在SKILL.md里写清楚要用到哪些MCP工具并约定好调用流程即可。一个典型的配置流程是这样在.mcp.json或Claude Code的配置里注册MCP服务比如一个搜索引擎服务、一个数据库服务。在SKILL.md的正文里明确列出本Skill依赖的MCP工具名称和用途。在工作流描述中按顺序写明先调用哪个工具、对返回结果做什么处理、再调用哪个工具。最后加上异常处理规则——比如搜索无结果时怎么办、接口报错时怎么降级。实操中我踩过一个坑模型经常分不清搜索工具返回的结果和最终答案的区别直接把搜索结果当成报告输出。解决办法是在SKILL.md里明确写入一个检查清单调用工具 → 提取关键信息 → 交叉验证 → 生成报告输出前必须确认所有信息来自工具返回结果。这个思路适用于几乎所有需要MCP协作的Skills。3.3 权限与安全边界做MCP类Skills时还有一个容易被忽略的点权限边界。不是所有Skill都需要访问所有MCP工具SKILL.md里写得越克制模型越不容易越权调用。比如一个只负责写摘要的Skill就不应该允许它调用数据库写入工具。如果你在团队里维护共用Skills这一点尤其重要——没做权限约束的Skill就像一把能开全楼门的钥匙风险太大。4. 从零开发一个Skills以前端设计稿还原为例4.1 需求拆解与目录设计热词榜里有个词很有意思——图片还原设计稿给前端开发好用的skills。这确实是前端高频需求给一张设计稿截图让AI生成对应的HTML/CSS。拿它当例子再合适不过。第一步是拆解完整工作流读取图片 → 分析布局结构 → 识别颜色/字体/间距 → 生成语义化HTML → 编写响应式CSS → 自查还原度。这个流程没有Skill时每次都要在对话里重复叮嘱有了Skill就变成一次性投资。拆解完之后目录结构长这样design-to-code/ ├── SKILL.md ├── references/ │ ├── design-tokens-template.md # 设计变量提取模板 │ ├── html-boilerplate.md # HTML基础骨架参考 │ └── css-conventions.md # CSS命名与组织规范 └── examples/ ├── input-example.png └── output-example/4.2 SKILL.md编写要点我建议把SKILL.md写成工作流说明书而不是废话大全。核心步骤包括先确认用户提供的图片路径分析整体布局结构横排/纵排/卡片/列表。提取设计稿中的关键设计变量主色/辅助色、字体族与字号、间距体系、圆角与阴影。生成HTML骨架使用语义化标签header/main/section/article等。编写CSS时遵循移动优先原则使用CSS变量承载设计变量。最后做一次还原度自查列出无法自动判断的部分让用户确认。每条指令都要明确、可执行。比如提取颜色这种描述太模糊模型不知道该怎么做改成从图片中识别主色调、辅助色、文字色输出为HEX格式的CSS变量就清晰多了。一个合格SKILL.md的标准是换一个人来看不需要额外的解释就知道该怎么执行。4.3 资源文件与参考代码的放置写Skill不是只写一个SKILL.md就完了好的Skill应该附带完善的参考资源。比如在这个设计稿还原Skill里我放了references/design-tokens-template.md设计变量提取模板强制模型按统一格式输出颜色、字体、间距。references/html-boilerplate.md推荐的HTML基础骨架保证每次生成的代码结构一致。references/css-conventions.md约定CSS类名规范比如BEM风格避免AI随机起名。examples/两三个示例输入输出模型可以参考示例理解还原到什么程度算合格。这些辅助文件的价值在于它们把重复的标准动作固化成模板模型每次执行时不用重新发挥稳定性和质量都有明显提升。我实测下来加了设计变量模板之后同一个Skill在不同版本模型下的输出一致性高了很多。4.4 测试与迭代发布前必做的三件事写完Skill不能直接上生产最好先过一遍自测。我的流程是先用一个简单的示例跑通主流程再用一个复杂用例测边界情况比如图片模糊、设计稿带深色模式最后让另一个同事或朋友按Skill的说明重新执行一遍看有没有理解偏差。这个用别人的脑子验证的步骤特别重要——你自己写的Skill脑子里已经有完整预期很容易忽略说明里写得不清楚的地方。5. 常见问题与踩坑记录5.1 Skills不生效的排查链路我明明把Skill放进去了为什么模型就是不用这是群里出现频率最高的问题。我总结了一套排查顺序按这个顺序查基本能覆盖80%的情况检查目录位置是否正确。Claude Code是.skills或~/.claude/skillsCodex是~/.codex/skills不同工具路径不一样放错位置等于没放。检查SKILL.md文件名大小写。官方规范是SKILL.md写成skill.md或Skill.md可能导致识别失败。检查frontmatter格式。YAML里name和description的格式很严格冒号后面必须有空格否则解析失败。建议写完先用YAML校验工具检查一遍。检查description是否足够详细。如果description写得太模糊模型无法判断什么时候该用自然会忽略。验证时用一个小任务测试。比如让模型用XX Skill完成……直接点名触发确认Skill本体生效了再测试自然触发。最容易被忽略的是第4步。很多人写完Skilldescription里只写一句用于生成报告模型根本不知道什么场景下该用、输入是什么、输出是什么。建议description至少包含适用场景、输入格式、输出格式三个要素。5.2 上下文膨胀问题有些同学把SKILL.md写得极长恨不得把整个知识库塞进去。但你要知道就算Skills是渐进式加载的一旦触发完整内容也会进入上下文。过长的Skill会导致模型注意力分散甚至影响主任务质量。我自己的经验是SKILL.md正文控制在200-300行以内超过的部分放进reference目录让模型按需读取。如果发现模型经常忘记执行Skill里的某个步骤别急着加更多文字先想想是不是这个步骤本身设计得不够清晰——有时候把一个大步骤拆成三个小步骤比在SKILL.md里反复强调一定要做X有效得多。5.3 版本管理与团队协作Skills本质上是代码应该纳入版本管理。我在团队里的做法是建一个skills共享仓库每个成员都可以提交新的Skill或改进已有Skill合并前过一遍变更和兼容性检查。仓库结构大概是skills-repo/ ├── claude-code/ # 各工具对应的子目录 ├── codex/ ├── cursor/ ├── shared/ # 跨平台通用指令 └── README.md # 使用说明与目录索引这里有个团队协作的坑不同成员可能用不同版本的Claude Code而Skills的目录约定在不同版本间有过调整。建议在仓库的README里写明最低支持版本并加一个简单的格式校验脚本提交时自动检查frontmatter格式和目录结构。别嫌麻烦等某天同事的Skill在别人机器上解析失败再回头排查代价大多了。6. 场景化Skills参考数学建模、学术研究、安全测试等方向6.1 数学建模类热词里数学建模Skills被反复提到这跟很多人用AI做数学建模比赛有关。一个完整的数学建模Skill应该包含问题分析模板区分优化/预测/评价问题、常用算法速查表线性规划、回归、聚类等、论文排版规范LaTeX或Word、结果验证清单。我的一个做数学建模的朋友说他最大的痛点不是算法不会而是AI给的解答过程不够规范变量定义不清晰。针对这个问题Skill里可以规定所有变量必须用表格列出定义和单位所有公式必须编号所有结论必须附带敏感性分析。把这些规范写进SKILL.mdAI的输出质量立刻上了一个档次。这类Skill很适合做成通用模板比赛的题目每年在变但建模和写作的流程几乎是固定的。6.2 学术研究类学术研究Skills主要解决文献调研、论文结构、引用格式这些流程问题。比如academic research skills这类仓库通常包含文献检索策略模板、论文大纲生成器、引用格式转换器BibTeX/APA/GB/T 7714、写作逻辑自查清单。这类Skill有个特殊要求——处理长文档。论文动辄几万字如果让模型一次性读完再总结很容易丢失关键信息。我建议把输入分段处理写进指令让模型先读摘要和结论再根据用户提问返回对应章节的详细分析。在SKILL.md里可以加一条规则——处理超过一定长度的文本时必须先给出处理计划经用户确认后再逐段执行能有效避免上下文溢出和注意力漂移。6.3 安全测试与其他方向安全测试领域的Skills同样在热词榜上。这个方向的Skill主要做三件事把测试流程标准化、把报告格式规范化、把工具链命令封装成可复用的脚本。比如一个Web应用安全测试Skill它的SKILL.md里通常写着先进行范围确认与信息梳理再按标准测试框架逐项检查最后按统一模板输出漏洞报告报告里必须包含危害等级、复现步骤和修复建议。这类使用场景有很强的专业性使用者也都是受过训练的从业人员Skill的意义在于让团队每个人的测试口径一致减少遗漏。要提醒的是这类内容必须在授权和合规的范围内使用这也是SKILL.md里应该写清楚的前提。至于移动端Skills推荐Cursor前端Skills有哪些这类问题其实没有标准答案。最靠谱的做法是去GitHub搜awesome-skills、skills-marketplace这类聚合仓库再结合自己的实际工作流筛选。不要贪多先装两三个高频的用顺手了再扩展。按我的观察一个开发者真正高频使用的Skills数量通常在5到10个之间超过这个数字的大部分时间都躺在目录里吃灰。写在最后我的几个实操体会最后说点我个人的感受。Skills这个概念火起来之后网上出现了大量什么都要做成Skill的声音我觉得没必要。Skills适合的是那些流程稳定、反复执行、有明确输出规范的任务如果是开放式的创意工作反而有可能被固定的Skill模板限制住思路。我现在的习惯是每完成一个重复出现超过三次的任务才会考虑把它沉淀成一个Skill然后在真实项目里跑两周再发布。这个过程本身就是对工作流的一次梳理收获往往比Skill本身还要大。另外再分享一个小技巧Skill不是写完就完了要像维护代码一样持续迭代。每次AI用Skill产出不满意的东西时记录下来是哪个环节出了问题然后回改SKILL.md。我的图片还原设计稿这个Skill前后改了十几版从最初只有几行提示词到现在带着完整设计变量模板还原度肉眼可见地提升了一大截。这种东西没有捷径全靠一遍遍用、一点点磨。还有一个我踩过几次的坑写在这里当提醒别在一个Skill里塞太多职责。我最早做过一个全能工作助手Skill既能写周报、又能做代码审查、还能生成PPT大纲结果模型经常不知道调用它时到底该执行哪一部分。拆成单职责的独立Skill之后触发准确率大幅提升。单一职责原则不仅在写代码时成立在写Skill时同样成立。好了关于Skills的内容就唠到这里。如果你也在折腾自己的技能包欢迎分享你的经验我这边也还在持续学习中。