过去两个月我在好几个AI编程社群里反复看到同一个词skills。Claude Code 刚宣布支持 Agent Skills 的时候我还觉得这不过是把提示词换个目录存放直到我真正把一套前端代码审查的 Skills 接进日常流水线才发现这东西和普通 prompt 完全不是一个量级的玩法。这篇文章我就从底层逻辑讲起把这几个月在 Claude Code、Codex、Cursor 上折腾 Skills 的踩坑记录、开发模板、调用 MCP 工具的完整链路一次说清楚适合已经用过 AI 编程助手但总感觉回答不够稳定的开发者也适合刚听说 Skills 想从零上手的新手。先说结论Skills 的本质是给模型一套“按需加载的岗位手册”。它不像 system prompt 那样每次都把几千字规则硬塞进上下文而是等模型发现“这件事我需要一个专门的工作流”时再去读对应目录里的 SKILL.md把步骤、脚本、模板加载进来执行。这种机制既省 context又能让 AI 在复杂任务里保持稳定输出。下面我会从设计原理、平台差异、开发实战、资源推荐和问题排查五个部分展开你完全可以照着操作。1. Skills到底解决什么问题不只是“把提示词放进文件夹”1.1 从一次失败的长对话说起我最早接触 Skills 是因为一次 PPT 制作翻车现场。当时我用 Claude Code 帮我做一个技术分享的演示文稿我在对话里把需求、大纲、风格要求、页数限制一股脑全打字进去。前两轮模型表现还不错但聊到第 10 轮修改时它突然忘了最开始说的“每页不超过 20 个字”开始大段大段往幻灯片上堆文字。我重复解释了好几遍效果还是不理想。这个问题的根源在于普通对话里你给的指令是“一次性消费”的。模型处理完当前回合后你的规则就慢慢被新内容挤出注意力窗口。如果每轮都重新强调规则不仅浪费 token还特别容易前后矛盾。Skills 解决的正是这件事——它把一套完整的工作规范存成文件模型在需要的时候主动加载不需要的时候完全不占用上下文。另一个常见场景是团队协作。以前我会把常用的代码规范、提交信息格式、测试要求全部写进项目根目录的 CLAUDE.md但随着项目变大这个文件越来越长每次对话都在消耗大量 token而且里面大部分内容跟当前任务无关。Skills 相当于把这些规范拆成一个个独立模块按场景触发既提升准确率也大幅降低使用成本。1.2 Skills、Prompt、插件与MCP的区别我经常看到有人把 Skills 和 MCP 混为一谈这俩其实是完全不同的东西。MCPModel Context Protocol解决的是“模型能调用什么工具”的问题比如它可以帮你读文件、执行命令、访问数据库而 Skills 解决的是“模型应该用什么方法完成一件复杂任务”的问题比如做 PPT 时应该先列大纲、再写标题、最后补备注。你可以这样理解MCP 是给模型提供外挂工具Skills 是给模型提供工作方法和步骤。一个 Skill 内部完全可以调用 MCP 工具来完成具体动作。比如我做“前端项目审查”这个 Skill 时步骤里就明确写了“先调用 MCP 的 filesystem 工具读取项目目录结构再调用 grep 工具搜索关键依赖”这样模型很清楚每一步该用什么工具而不是自己临场乱猜。相比传统插件Skills 更像是“提示词 脚本 模板”的组合包。插件通常是一个深度集成到编辑器里的扩展程序需要写 UI、注册命令、处理事件而 Skills 的形态非常简单本质上就是一个包含 SKILL.md 说明文件和若干辅助脚本的文件夹模型通过语义匹配决定是否加载它。这种轻量设计最大的好处是生态门槛很低会写 Markdown 就能开发自己的 Skill。1.3 为什么约定用 SKILL.md 这个文件如果你看过 Anthropic 官方的 Agent Skills 设计会发现所有 Skills 都围绕一个核心文件SKILL.md。它采用类似 Markdown 的格式顶部是 YAML 格式的 frontmatter里面有 name技能名字和 description技能说明正文则是具体的指令内容。这里最关键的是 description。它不只是给人看的注释而是模型判断“这个任务要不要加载该 Skill”的依据。如果你的 description 写得太泛比如“帮助用户处理各种问题”模型根本不知道什么时候该调用它但如果你写“当用户要求生成 PPT、演示文稿、slides 或教学课件时使用”模型就能在合适的场景精准触发。SKILL.md 正文通常会包含适用场景、所需输入、执行步骤、输出格式、注意事项这几块。一份好的 SKILL.md 不是长篇大论而是像给一个聪明同事的交接文档——告诉他目标是什么、流程是什么、边界在哪剩下的交给模型自己发挥。2. 主流工具里如何安装和使用Skills2.1 Claude Code的Skills目录与启用流程Claude Code 是最早让我感受到 Skills 威力的工具。它支持两种存放位置项目级目录.claude/skills/和用户级目录~/.claude/skills/。项目级适合跟团队共享的规范用户级适合个人常用的工作流。实际操作很简单比如你想装一个“PPT 生成助手”的 Skill只需要创建这样的目录结构~/.claude/skills/presentation-builder/ ├── SKILL.md └── scripts/ └── build_ppt.py然后在 SKILL.md 里写好名称和触发描述重新打开一个 Claude Code 会话模型就会自动识别这个 Skill。这里有个前提Claude Code 只在会话开始时或任务切换到相关语义时去扫描 Skills 目录所以你在添加新 Skill 之后最好重启会话或者用/skills命令手动查看当前可用的技能列表。我实测下来Claude Code 对 Skills 的触发准确率还不错但前提是描述得足够具体。还有一个调试小技巧启动时加--debug参数Claude Code 会打印出模型加载了哪些 Skill、调用了哪些工具排查“为什么模型没用我的 Skill”时特别有用。2.2 Codex、Cursor、OpenCode里的差异OpenAI 的 Codex CLI 也支持 Skills路径配置在~/.codex/skills/下。和 Claude Code 类似每个 Skill 也是一个包含 SKILL.md 的文件夹。Codex 的好处是它本身对 MCP 工具支持很完善你可以在 Skill 里写清楚“需要调用 mcp__github 工具来读取 issue”Codex 会自动去连对应的服务。Cursor 在 0.46 版本之后加入了类似能力路径是项目下的.cursor/skills/。由于 Cursor 本身是编辑器形态它对 Skill 的加载更偏“上下文注入”——当你选中一段代码或者打开某个文件时Cursor 会根据当前文件类型去匹配相关 Skill并把内容注入到对话上下文中。这意味着 Cursor 的 Skill 更适合跟编辑器行为绑定比如“当你打开一个 Python 测试文件时自动加载测试风格规范”。OpenCode 这类开源 CLI 终端工具也有自己的约定一般放在~/.config/opencode/skill/或项目级.opencode/skill/。如果你同时在用多个工具最省心的做法是把 Skills 仓库用 git 管理起来然后在不同机器上软链到对应目录避免重复维护。2.3 三个拿来即用的场景示例为了让你更直观地理解我举三个高频场景的例子。第一个是“网页查资料并整理笔记”。这个 Skill 的 SKILL.md 会这样设计模型先调用 MCP 的浏览器工具或搜索工具获取网页内容然后提取重点再按“摘要、关键结论、原文引用、待办事项”四段式输出。以前我直接让 AI 查资料它经常只给一段干巴巴的总结没有来源、没有结构化信息用这个 Skill 之后输出质量稳定多了。第二个是“前端图片还原设计稿”。社区里很多好用的 Skill 就是干这个的拿到一张设计稿截图后模型先分析布局结构、字体、间距、配色再依次生成 HTML 骨架、CSS 样式、响应式适配方案。关键是 SKILL.md 里会规定一系列步骤比如“先描述整体布局、再识别组件、最后输出可运行代码”避免模型一上来就盲目写代码。第三个是“PPT 生成”。一个成熟的 PPT Skill 会要求模型调用 MCP 工具里的幻灯片操作能力并且在 SKILL.md 里明确“标题不超过 20 字、每页要点不超过 5 条、备注栏写演讲提示词”。这样你只需要说一句话“把这篇博客改成 10 页分享稿”模型就会按既定流程生成而不是临时自由发挥。3. 手把手开发自己的第一个Skill3.1 设计Skill前先回答三个问题我见过很多人一上来就照着模板写 SKILL.md结果写出来的东西模型根本不知道怎么用。开发之前建议先回答三个问题触发场景是什么、输入是什么、输出是什么。触发场景决定你的 description 怎么写。比如你公司前端项目要求所有组件必须用 TypeScript、必须写测试、必须带 Storybook 演示那触发场景就是“用户提到组件开发、前端编码、React/Vue 修改”等情景。输入是指这个 Skill 需要哪些外部信息比如“项目目录路径”“需求文档内容”还是“技术栈说明”。输出则要定义清楚交付物格式比如“改动清单、测试文件、注意事项”。我在实际开发中会先在纸上写一遍这个 Skill 的执行流程假设模型现在要做这件事第一步干什么第二步干什么什么情况下用哪个工具最后交付什么。这个过程很像写工作流 SOP想清楚了再写 SKILL.md 会高效很多。我的经验是一份好的 Skill 通常包含 5 到 10 个执行步骤超过 15 步就说明任务分得太粗应该拆成两个 Skill。3.2 完整实战做一个“前端代码审查Skill”我以自己最常用的“前端代码审查 Skill”为例展示完整结构。这个 Skill 的作用是让 AI 按统一的审查标准检查前端代码变更而不是泛泛而谈“代码挺不错的”“有些地方可以优化”。目录结构~/.claude/skills/frontend-code-review/ ├── SKILL.md └── scripts/ └── review_summary.pySKILL.md 的简化版本如下实际使用时可以根据团队规范扩充--- name: frontend-code-review description: 当用户要求审查前端代码、Rerun代码审查、检查React/Vue组件质量、分析Pull Request时使用。适用于TypeScript/JavaScript项目。 --- # 前端代码审查 ## 适用场景 - 用户要求审查代码变更或Pull Request - 用户想检查组件实现是否符合团队规范 - 用户希望发现潜在的样式、逻辑或性能问题 ## 输入 - 待审查代码的路径或diff内容 - 项目技术栈默认React TypeScript - 需要关注的规范如有 ## 执行步骤 1. 读取代码文件或diff内容先梳理变更的整体结构和影响范围。 2. 依次检查以下维度 - 类型安全是否存在any、未使用变量、隐式类型转换问题 - 组件规范是否拆分合理、是否有关键副作用、props是否有效约束 - 样式问题是否使用设计token、是否有魔法数字、是否包含内联样式 - 性能隐患是否存在不必要的重渲染、大列表是否缺少key、是否有内存泄漏风险 3. 对发现的问题按严重程度分级阻塞、建议、可选。 4. 输出审查报告包含问题定位、修改建议、参考代码片段。 ## 输出格式 - 变更总览 - 问题列表按严重程度排列 - 修复建议代码 - 自检清单写完后我发现模型在这个 Skill 的约束下给出的审查意见明显更专业、更有条理而不是以前那种“感觉没什么大问题”的敷衍回答。当然这个 Skill 还很依赖代码文件能被正确读取所以我在步骤里特意加上了“先读取代码文件或 diff 内容”确保模型不会凭空猜测。3.3 在Skill里调用MCP工具很多场景下Skill 需要配合 MCP 工具才能真正跑通。比如做 PPT 的 Skill如果模型没有操作 pptx 文件的能力就算步骤写得再详细也只能输出 Markdown 大纲无法生成真正的演示文稿。这时你应该在 Skill 的步骤里明确写“调用 MCP 的 pptx 工具创建幻灯片并通过 add_slide 方法逐页添加内容”。MCP 工具在模型眼里就是一组带命名前缀的函数常见的命名格式是mcp__服务器名__工具名。比如你连了一个文件系统服务工具名可能是mcp__filesystem__read_file。在 SKILL.md 里你不一定需要写出完整前缀只要写清楚“使用文件系统工具读取 xxx”模型在执行时会自动匹配可用的 MCP 工具。但为了避免歧义对于多 MCP 服务的情况我建议还是写出明确的工具名或者至少标明是哪个 MCP 服务提供的。这里有一个容易踩的坑如果某个 MCP 服务没连接成功模型会卡在“尝试调用工具却失败”的状态。所以我在不少 Skill 的第一条步骤里都会写“先检查所需 MCP 工具是否可用若不可用则告知用户并提供降级方案”。这个小小的防御性设计能省去很多排查时间。3.4 调试技巧Skill 开发完成后调试是必经环节。我遇到最多的问题是“模型根本不加载我的 Skill”。这时我会先确认目录路径是否正确再检查 SKILL.md 顶部的 frontmatter 是否完整尤其是 name 和 description。有时候 description 里缺少触发关键词模型就会把它当成普通知识文档而不是可执行的技能。另外一个技巧是利用工具的调试日志。Claude Code 的--debug模式会输出模型加载了哪些 SKILL.md看不懂的话就重点搜索 “loaded skill” 或 “skill” 关键字。Codex 也可以用-v或 verbose 模式查看日志。如果你写的 Skill 包含 shell 脚本或 Python 脚本不要忘了给脚本执行权限用chmod x处理一下否则模型会告诉你“没有权限执行该文件”但这个报错真正含义可能只是你忘了设置权限。4. 值得收藏的场景型Skills推荐4.1 从社区仓库找Skills的姿势现在 GitHub 上已经有不少 Skills 合集质量参差不齐。我一般会优先看 Anthropic 官方仓库anthropics/skills里面维护了一组经过验证的示例比如生成 PDF、构建幻灯片、处理电子表格、从截图生成代码等这些是最适合入门的参考资料。社区里 star 很高的合集也值得关注比如 Matt Pocock 基于个人工作流程整理的 TypeScript 相关 Skills还有各种 awesome 系列仓库里面按场景做了分类。但我不建议看到什么 Skill 就往本机里塞。每个 Skill 都是作者基于自己的工作流设计的直接拿来用可能会跟你现有的工具链冲突。我的做法是把感兴趣的 Skill clone 下来当作模板通读它的 SKILL.md保留核心步骤然后按自己的项目和习惯改造。4.2 按场景的推荐清单我按自己在实际工作中验证过的场景整理了一个清单你可以作为参考。需要说明的是这些 Skills 不一定要去网上找现成的很多完全可以根据这里列出的设计思路自己写。场景核心步骤设计适合工具备注Web 前端开发读取需求 - 生成组件结构 - 输出样式方案 - 补充测试Claude Code / Cursor重点约束代码规范与响应式适配学术研究搜索文献 - 提炼观点 - 整理引用 - 生成文献综述Codex / Claude Code建议接入学术搜索 MCP 服务数学建模识别问题类型 - 建立数学模型 - 编写求解脚本 - 验证边界条件Codex / OpenCodeSKILL.md 里写清常见模型的应用场景测试用例设计解析需求 - 划分等价类 - 补充边界值 - 输出测试矩阵Claude Code适合 QA 或需要自测的开发场景前端图片还原分析截图布局 - 识别字体与间距 - 生成 HTML/CSS - 响应式适配Cursor / Claude Code截图需清晰必要时先让模型描述PPT 生成确认主题 - 编写大纲 - 分页生成 - 填充备注Claude Code需配合支持 pptx 的 MCP 工具安全巡检收集系统信息 - 检查开放端口 - 分析弱配置 - 输出整改建议任何 CLI 工具只用于授权范围内的安全检查禁止未授权测试这里重点说一下数学建模类的 Skill。很多参赛同学问我要“数学建模 Skills 推荐”其实比起用别人写好的我更建议自己做一个“建模流程 Skill”让模型遇到问题后先判断是优化问题、统计问题还是微分方程问题然后列出数学假设和符号定义再生成求解脚本并用测试用例验证边界。这个逻辑写进 SKILL.md 后AI 给出的建模方案会专业很多而不是看到题目就堆一堆公式。4.3 用Skills搭一个个人工作台用好 Skills 的关键是持续积累。我给自己定了一个规矩凡是让 AI 成功完成过两三次以上的重复任务就把过程沉淀成 Skill。比如我经常需要把设计稿还原成前端页面一开始是每次在对话里重新描述要求后来直接写了一个“image-to-frontend” Skill现在只要把图片路径扔进去模型就能走完整套流程。沉淀下来的 Skills 我会放到一个独立的 git 仓库里命名规范统一为“场景-能力”的格式比如frontend-code-review、docs-article-builder。这样换电脑或者带新同事时直接把仓库 clone 下来再让每个人按自己的工具链软链到对应目录团队的知识积累就能持续复用。个人工作台的核心价值就是你的高效工作流不需要每次从零开始和 AI 沟通它会越来越懂你的习惯。5. 常见问题与排查技巧实录5.1 模型就是不用我的Skill这个问题出现频率最高。我排查时一般按三个顺序来第一检查目录路径和 frontmatter 格式第二检查 description 是否包含明显的触发词第三检查是否重启了会话。经常有人改了 SKILL.md 之后忘记新开会话然后抱怨“怎么不生效”其实模型在做任务规划时根本没重新扫描目录。如果你确认这些都正常还有一招是手动“点一下”该 Skill。Claude Code 里可以用/skills命令查看可用技能有时候直接指定“使用 skills 里的前端审查规范来检查这段代码”模型就会明确去读取对应文件。这不算作弊更像是对模型的一种提醒方式。5.2 Skills与MCP工具协调失败另一类常见问题是 Skill 里写了“调用 MCP 工具”但模型根本找不到。我遇到的大部分原因是 MCP 服务没启动或者服务名对不上。比如我在一个 Skill 里写“使用 server 的 fetch 工具”但实际配置的服务器名是http-server模型就会迷茫。解决办法是在 SKILL.md 里写得再具体一点比如“使用 mcp__http-server__fetch 工具获取网页内容”。还有一个不容易注意的坑同时安装多个功能重叠的 MCP 服务时模型可能不知道该选哪个。我在做学术研究 Skill 时机器上同时配了浏览器搜索和学术搜索引擎SKILL.md 里如果不指定优先级模型就会随机选一个输出质量很不稳定。后来我在步骤里明确写上“优先使用学术搜索 MCP其次才用通用搜索”问题立刻消失了。5.3 Skill体积过大导致上下文浪费有人以为 Skill 内容越详细越好其实不是。SKILL.md 也会被模型读进上下文如果正文写了一万字即使按需加载也会消耗大量 token而且在长任务中反而容易让模型抓不住重点。我的经验是SKILL.md 正文控制在 2000 字以内写清步骤和输出格式即可详细的模板、代码、数据都放到 scripts 或其他文件中让模型按需读取。比如我的前端代码审查 SkillSKILL.md 只写了审查的六个维度和输出格式而详细的规范清单放在docs/style-rules.md里SKILL.md 中的某个步骤写着“如有疑问读取 docs/style-rules.md 中的详细规范”。这样既保证了 Skill 轻量又保留了大而全的细节。5.4 安全提醒谨慎使用第三方Skills最后必须提醒一点Skills 本质上是可以引导模型执行任意操作的文件。一个来路不明的 Skill 可能包含恶意脚本让模型在本地执行危险命令或者在无人注意时读取敏感文件后外传。我自己从社区下载 Skills 后第一件事就是完整阅读 SKILL.md 和所有关联脚本确认没有可疑的网络请求或高危命令然后才会放进技能目录。安全巡检类的 Skills 尤其要小心。如果你做的是内部授权范围内的安全检查可以放心使用但绝对不能把这类 Skill 用在未经授权的目标上。安全技能的设计也应遵循同样的原则先收集信息、再评估、最后输出修复建议而不是直接下载攻击脚本。在我个人的实际使用习惯里还会定期清理不再使用的 Skills因为技能目录越多模型在语义匹配时的干扰就越大。每保留一个 Skill我都会确认它在过去两周内确实被用到过或者即将用于某个明确任务。说到底Skills 是给人用的效率工具不是收藏品精简和持续迭代才是让它发挥作用的关键。如果你也想尝试建议从一个小场景开始比如把一个你经常重复的操作流程写成最简单的 SKILL.md哪怕只有 20 行跑通一次你就会明白它的价值。