如果你过去几天刷过技术社区大概率已经被“skills”这个词刷屏了。前端开发有 skills测试用例有 skills连数学建模、PPT、图片还原设计稿这种偏流程性的活儿也开始有一堆现成的 skills 可以直接抄。我最初觉得这就是把提示词换个马甲打包一下后来深入用了一圈发现这个理解太浅了。skills 不仅仅是“写一段话教 AI 怎么干活”它更接近给 AI 编码智能体配一套固定 SOP、干粮和工具说明书让它在面对具体任务时不靠猜而是按一套经过验证的流程往下走。这篇文章我会把我自己从接触 skills、拆解 skills、到动手写 skills 的完整过程梳理一遍包括目录结构、description 怎么写、怎么挂到 Claude Code、Cursor 这类工具里、怎么配合 MCP 使用以及我踩过的各种坑。如果你想知道“skills 到底怎么用”“怎么开发自己的 skills”“为什么别人下载的 skills 好用但自己套用总是翻车”这篇文章应该能给你一个比较系统、可以直接上手的答案。1. 先搞清楚AI 编程语境下的 skills 到底解决什么问题1.1 从“会聊天”到“有固定 SOP”的分水岭我们在日常使用 AI 编程工具时最常见的做法是在对话框里丢需求“帮我写一个登录页”“给这段代码补测试”“看看这个 bug 在哪”。AI 每次都能接上话但出来的东西质量起伏很大。同一个需求上午问和下午问甚至换一个模型版本结果可能完全不一样。原因很简单模型每次都在“现场发挥”没有人告诉它这一类任务应该按什么顺序想、先做哪一步后做哪一步、哪些边界情况必须覆盖。skills 解决的就是这个问题。它把“这一类任务的标准处理流程”固化成文件在 AI 开始干活之前就强制加载一套行为规范。比如你给它配了一个“前端设计稿还原”的 skill它拿到图片后不会直接上手乱写而是先分析设计稿的布局结构梳理颜色、字号、间距这些设计变量再决定用 Flex 还是 Grid最后才生成组件代码。整个过程像给新手员工发了一份员工手册而不是让他靠悟性自由发挥。我在自己的项目里实际对比过同样一个“把设计稿转成网页”的需求不带 skill 时 AI 会按自己理解生成一版“看起来差不多”的页面但细节上经常出现字号不对、圆角不符、响应式断点缺失带上 skill 之后它会先输出一份设计稿解析结果再逐区块实现最终代码的还原度有明显提升。这个差距不是模型能力造成的而是任务约束和流程清晰度造成的。1.2 和提示词、插件、MCP 到底差在哪很多人会问skills 和普通提示词有什么区别和插件有什么区别和 MCPModel Context Protocol又是什么关系这三个概念确实容易混在一起我一开始也犯迷糊。普通提示词是“一次性指令”。你写在对话里的那段要求只对当前对话生效下次新开一个会话就失效了。skills 是“可复用指令包”它不仅有指令文本还带元信息、示例、资源文件能被 AI 工具在合适的时机自动识别和加载。一个 skill 写好后可以跨项目、跨团队复用这才是它跟提示词的根本差异。插件是“扩展能力”的代码包。插件能真正执行代码、调用系统 API、处理文件读写它补的是 AI 的工具能力。skills 大部分情况下只是文本和规范它补的是 AI 的“做事方法”。你可以把插件理解为给 AI 加了手和脚把 skills 理解为给 AI 装了大脑里的操作流程。MCP 是“连接外部工具”的标准协议。通过 MCPAI 可以调用外部服务、数据库、浏览器、设计软件等。skills 本身不是协议它是一套指令文件。两者协作的关系是skill 告诉 AI “你应该调用哪个 MCP 工具、按什么顺序调、调用结果怎么用”MCP 负责真正去执行调用。没有 skillAI 面对一堆 MCP 工具时往往会挑错工具或者反复试错没有 MCPskill 能指挥的外部资源就非常有限。所以它们是协作关系不是替代关系。辅助理解的话MCP 是工具箱里的电动螺丝刀skills 是贴在墙上的“家具安装步骤图”。你既需要工具也需要步骤图才能把一个柜子装好。1.3 现在社区里哪些 skills 最值得关注最近 GitHub 上各种 skills 合集非常多搜索“awesome skills”或“agent skills”能翻到大量项目。比较有代表性的是围绕 Claude Code 生态衍生出来的一批 skills 仓库比如 baoyu 的 skills 项目里面收录了很多中文场景下适用的技能文件覆盖前端开发、文案写作、代码 review 等场景社区活跃度很高。GitHub 上还有一个叫“superpower skills”的合集主打的是把复杂工作流拆成多个互相配合的技能包让 AI 在写代码、调试、重构时分别加载不同的技能模块整体上像给智能体叠了一层“buff”。除了现成合集几个重量级的公开教程也值得关注。吴恩达团队发布过一套关于 Agent Skills 的教程PDF 在社区流传得很广内容偏方法论讲了怎么设计技能、怎么评估技能效果、怎么避免技能之间互相冲突。Matt Pocock 也做过相关的技能分享他在 TypeScript 和前端工程化方面的积累很深他写的 skills 风格偏向“让 AI 严格按类型安全和代码规范执行”对做前端工程化的人来说启发很大。这些项目和教程看下来你会发现一个共同趋势真正好用的 skills 不是大而全的模板而是“场景切得很细、边界划得很清、操作步骤写得很死”的小文件。与其做一个“万能软件开发助手”技能不如做“React 组件从设计稿到代码的还原流程”“GraphQL API 错误处理规范”这类聚焦的小技能。每个技能只解决一类问题组合起来才是一套强大的工作流。2. 拆解一个标准 skills 包目录、元信息与核心指令2.1 “SKILL.md 资产目录”的文件约定社区里目前比较通用的 skills 组织方式是每个 skill 放在一个独立目录下目录名就是技能名里面至少包含一个SKILL.md文件。这个命名规范最早来自 Anthropic 的 Agent Skills 实践后来被 Claude Code、OpenCode 等工具沿用了下来。目录结构大致是这样design-to-code/ ├── SKILL.md ├── assets/ │ ├── example-input.png │ └── example-output.tsx └── references/ └── design-token-mapping.mdSKILL.md是技能的“主文件”所有核心指令都写在这里。assets目录用来放示例产出物比如一个输入样例和对应的输出样例AI 在生成内容时可以对照参考。references目录放更详细的背景知识比如设计令牌映射表、组件库使用规范、内部 API 文档这些内容不需要全部写进主文件需要时 AI 会主动去查。我自己的习惯是主文件控制在两百行以内只写“必须做的事”和“不能做的事”更细节的背景知识全部拆到 references 里按需加载。这样既不会让主文件太重又能保证 AI 在关键时刻有参照物。2.2 description 才是真正的“开机密码”很多人写SKILL.md时会把绝大部分精力放在正文指令上却忽略了最开头的元信息尤其是description字段。实际上description 才是决定 skill 能不能被正确触发的关键。可以这样理解AI 编码工具在处理用户需求时会先扫一遍所有可用的 skills根据每个 skill 的 description 来判断当前任务是否匹配。如果 description 写得太宽泛比如“帮助写前端代码”那么你问任何前端问题它都可能触发这个 skill结果是把一个写登录页的技能套用到写复杂状态管理的问题上反而帮倒忙。如果 description 写得太窄比如“只处理蓝湖设计稿还原且仅限 375px 宽移动端页面”那很多本该触发的场景它又会漏掉。我写 description 的经验是包含任务类型、输入形态、输出形态、关键约束四个要素。一个还算合格的 description 长这样将设计稿图片或 Figma 链接转换为高保真 React 组件代码。 适用于移动端页面还原、PC 端后台界面搭建、设计系统组件提取。 输入为图片或设计文件 URL输出为 TSX 组件、CSS 变量声明和响应式断点建议。 不适用于已有完整代码库的功能开发。这样的描述让 AI 能快速判断“该不该用”也能避免误触发。2.3 为什么我坚持把一个 skill 控制在 200 行以内技能包跟需求文档不一样不是写得越详细越好。我自己最早写过一份接近五百行的前端开发技能文件把组件命名规范、目录结构规范、代码风格、提交信息规范全部塞进去了。结果是 AI 每次加载这个技能都要消耗大量上下文模型没聊几句就开始“忘记”技能后半部分的内容执行效果反而不如精简版。后来我把技能拆成了三个小技能分别是“页面还原”“组件提取”“代码规范检查”每个都控制在 150 行左右。这样的好处很明显触发更精准、上下文占用更少、出问题时排查更快。AI 只需要在当前任务匹配的技能加载时读取必要信息不需要为无关细节买单。另外还有一个容易被忽略的点行数少意味着技能之间的依赖关系更清晰。如果一个技能需要用到另一个技能的输出可以直接在指令里写“产出结果应为 XX 技能所需的输入格式”而不是把另一个技能的整个流程复制过来。这种“组合式”的设计比“全家桶式”的大文件健康得多。3. 实操开发并挂载一个自己的 skills3.1 从零写一个“图片还原设计稿”的 skill现在进入实际动手环节。我以“图片还原设计稿给前端开发”这个场景为例完整走一遍开发流程。这个场景在最近的热搜里出现频率很高因为它直接对应前端日常工作里最耗时的“对照设计稿写页面”环节。先建目录和元信息mkdir -p ~/.claude/skills/design-screenshot-to-react然后创建SKILL.md--- name: design-screenshot-to-react description: 将截图或设计稿图片转换为高保真 React 组件代码。适用于移动端页面还原、Web 页面切图、现有页面改版。输入为 PNG/JPEG 图片输出为 TSX 组件、CSS 变量和响应式断点说明。 risk: medium --- # 设计稿还原为 React 组件 ## 第一步分析设计稿 - 识别页面整体布局头部、主体、底部、侧边栏、浮动层。 - 提取设计变量主色、次要色、文字颜色、字号、间距、圆角、阴影。 - 明确响应式行为在 375px、768px、1440px 三种宽度下分别如何排列。 ## 第二步建立组件树 - 将页面拆分为组件树遵循“页面 → 区块 → 组件”三层结构。 - 相同视觉样式的元素必须抽成公共组件禁止逐个复制。 ## 第三步生成代码 - 使用 TypeScript 编写组件Props 需定义联合类型或 interface。 - CSS 采用 CSS 变量颜色、间距、字号全部引用变量。 - 布局优先使用 flex 与 grid禁止使用绝对定位于主要布局。 - 图片资源使用占位符并在代码注释中写明需要替换的链接。 ## 禁止事项 - 禁止猜测设计稿中不存在的字号与颜色如设计稿模糊用系统默认值并标注 TODO。 - 禁止输出整站代码只输出当前页面相关组件。 - 禁止使用内联样式替代 CSS 变量。写完后在references目录下放一个design-token-mapping.md里面列明常见的 Tailwind 色值映射规则和间距倍数体系方便 AI 在还原时套用统一的设计语言。这个技能从创建到落地大概半小时。效果比我想象中好很多——AI 在还原一张移动端个人中心页面截图时能准确抽出色彩变量并把三个功能区块拆成独立组件而不是像以前那样只给一个扁平的长页面。3.2 把 skill 接入常用 AI 编码工具写好了技能文件还要让工具能加载到它。目前我在 Claude Code 和 Cursor 里都用过类似结构的技能加载方式略有差异。Claude Code 支持从项目级目录或用户级目录加载技能。用户级目录一般放在~/.claude/skills/下项目级目录放在项目根目录的.claude/skills/下。启动 Claude Code 后会读取这些技能当对话内容与某个技能的 description 匹配时自动把对应文件注入上下文。团队协作时更推荐放到项目级目录这样所有成员拉取代码库后就有同样一套技能可用。Cursor 没有官方意义的 skills 概念但可以把技能内容转成项目规则文件放到.cursor/rules/目录下或写进.mdc文件。实际效果与 skills 类似区别是 Cursor 的规则触发机制对文件名的语义依赖更强建议把触发场景直接写到文件名里比如design-screenshot-to-react.mdc。我实际测试下来的结果它能稳定触发但上下文消耗比 Claude Code 的按需加载略高一点。OpenCode 这类命令行工具对 skills 的集成也在慢慢成熟。如果你用的是它可以在配置目录下写一个 workflow 节点把SKILL.md作为提示词模板引用。流程上相当于把技能文件作为“子代理任务”交给模型执行。无论哪种工具核心逻辑都是相同的让 AI 在正确的时机读到正确的指令。工具只是载体技能文件本身的可维护性才决定这套体系能走多远。3.3 验证效果比随机调提示词强在哪技能写完后不要急着拿来跑一次就下结论。我建议准备三组测试用例分别覆盖典型场景、边界场景、异常场景。典型场景是“一张清晰的页面截图还原成 React 代码”重点看代码质量和组件拆分是否合理。边界场景是“设计稿带深色模式图片只给了浅色版本”重点看技能有没有引导 AI 补充深色变量。异常场景是“设计稿是一张空白图或模糊缩略图”重点看技能是否会让 AI 停下来询问而不是硬生成一版毫无根据的代码。我用这三组用例跑了五六个技能版本发现最开始写的“禁止猜测设计稿中不存在的字号与颜色”这条规则帮了大忙。没有这条规则前AI 遇到模糊图片会自行脑补设计值输出很漂亮但离稿很远加上这条规则后它会在注释里明确标注“设计稿分辨率不足字号为默认值”后续人工调整成本大幅降低。验证环节还有个细节一定要新开会话测试不要在同一个对话里反复修改技能并继续测试。因为 AI 的上下文会保留之前的结果影响你对技能真实效果的判断。每次修改后都清空会话重新跑同一组用例才能看出改动是否真的有效。4. 场景化组合数学建模、测试用例、PPT 怎么配 skills4.1 数学建模赛事的 skills 推荐打法数学建模这个场景比较特殊因为它不是一个纯工程问题而是“建模思路、编程实现、论文写作”三件事的组合。如果你参加建模竞赛与其写一个“数学建模万能技能”不如把建模流程拆成四个小技能问题分析、模型设计、代码实现、论文写作。问题分析技能负责引导 AI 做需求拆解帮助判断这是优化问题、预测问题还是评价问题并生成一个解题思路框架。模型设计技能负责针对特定问题类型给出候选模型清单比如回归、时间序列、决策树、神经网络附上模型适用条件和复杂度权衡。代码实现技能负责把选定的模型转成 Python 代码统一用 pandas 做数据处理、matplotlib 做可视化并输出运行结果。论文写作技能负责把以上结果组织成抽象、问题重述、模型假设、模型建立、模型求解、灵敏度分析这样的标准结构。我在实际竞赛中用的就是这套四件套。效果最明显的是论文写作这个技能它能把 AI 生成的“口语化解释”自动改写成竞赛论文风格突出公式推导和结果分析而不会跑偏成宣传稿或项目总结。对于准备参赛的人我强烈建议自己在赛前先按自己的习惯把四个技能写好不要直接用网上下载的通用版因为每个团队的建模风格和代码习惯不同技能越贴合自己的习惯后期修改成本越低。4.2 测试用例把需求评审的直觉沉淀成 skill测试用例是另一个非常适合用 skills 固化经验的场景。资深测试人员看到一条需求时脑海里的反应往往是无意识的“这个字段要不要做为空校验”“这个按钮在弱网下怎么表现”“这个操作的权限级别是什么”这些经验很难手把手教给新人但可以写成技能。我见过一个不错的测试用例技能它的运行流程是第一步解析需求文本提取功能点第二步对每个功能点生成正向用例、反向用例、边界用例第三步补充异常场景比如网络中断、接口超时、数据为空、权限不足第四步给每条用例标注优先级P0/P1/P2和前置条件第五步按用户故事或需求编号输出测试矩阵。写这种技能时最关键的是把“边界值”和“异常值”的规则描述清楚。否则模型很容易只输出“输入合法值返回成功输入非法值返回失败”这种正确但没营养的用例。我的建议是在技能里内置一份常见漏洞清单数值型边界、字符串长度边界、枚举值遗漏、接口幂等性、并发操作、缓存一致性。每次生成用例时强制对照检查一遍用例质量就上来了。4.3 演示文稿与前端效率场景的“小快灵”组合PPT 类的 skills 之所以火是因为很多人发现自己让 AI 写 PPT 时模型常常把几十页大纲直接铺开视觉节奏和结构化程度都很差。一个好的 PPT 技能不需要“设计能力很强”它只需要管三件事内容分层、页面拆解、图示建议。内容分层指先定主题目标再分级提炼论点禁止把细节直接堆到首页。页面拆解指按“开场页 → 目录页 → 章节页 → 内容页 → 总结页”的组织方式规划页面每页只表达一个核心观点。图示建议指针对特定内容推荐图表类型比如流程类用流程图、对比类用表格、增长趋势用折线图这个环节可以衔接 MCP 去调用绘图服务。前端效率场景里也值得配一套“小快灵”技能。比如“API 联调技能”它会规定 AI 先生成 TypeScript 接口类型再生成 mock 数据最后才写调用逻辑避免页面组件和接口数据模型耦合过深。再比如“代码提交信息规范技能”会要求 AI 根据 diff 内容生成符合 Conventional Commits 规范的提交信息。这些都是单个任务很小但使用频率极高的技能配置一次长期受益。5. 排查实录skills 不生效、调不动 MCP 怎么办5.1 skills 加载不出来的几种原因我在折腾 skills 的初期遇到最多的问题是“明明把技能文件放好了但 AI 就是不按照技能执行”。经过反复排查常见的坑无非这么几类。第一类是大小写问题。很多工具对技能目录名和文件名是区分大小写的SKILL.md写成了skill.md就可能导致加载失败。这个我至少踩过三次坑后来干脆把基础目录模板固定成脚本生成杜绝手抖。第二类是 description 与触发场景不匹配。如果 description 里的关键词和用户实际表述差异过大AI 就判断不出来要调用这个技能。解决办法是在 description 里写清楚同义表达比如“设计稿”“截图”“UI 图”“Figma 设计”都列出来。第三类是缓存与会话状态问题。Claude Code 这类工具在启动时会扫描一次技能目录如果你在会话中途新增了技能文件往往要重启会话才能生效。我一度以为是技能写错了后来发现是没重启白折腾了好久。第四类是技能输出与后续步骤的衔接断裂。技能本身写得没问题但它的输出要求和其他配置冲突比如项目里有另外一套规则文件要求代码风格使用 React 类组件而技能要求使用函数组件两者会互相打架。这种情况处理起来比较隐蔽我的排查思路是先把所有规则文件逐份读一遍确认是否有冲突再继续。做一个常见的技能排查速查表症状可能原因处理方式技能从未被触发description 关键词不匹配补充同义表述精确化触发条件技能触发了但效果差主文件过长上下文被截断拆分技能把背景知识移到 references技能启用了但和预期冲突与项目其他规则文件冲突逐份阅读规则文件消解优先级矛盾修改技能后无变化会话缓存未刷新清空会话重启工具再测试5.2 skills 与 MCP 工具的正确协作姿势关于 skills 和 MCP 的关系我前面提过它们是“步骤图”和“工具箱”的关系但在实际配置时很多人会踩一个坑以为写了技能就能直接调用 MCP 服务。技能文件本身不会建立任何网络连接也不会读取任何外部服务它只是告诉 AI“你应该去调用哪个工具”。真正的调用还是要靠 MCP 服务器配置和工具授权。正确做法是分两层准备。第一层是 MCP 服务器本身已配置好比如你要在技能里使用浏览器操作就得先把对应的 MCP 服务注册到工具里并确保 API Key 或本地服务能连通。第二层才是在技能的指令中描述使用方式比如识别出需要访问网站数据时调用 MCP 的 browser 工具跳转到目标页面定位元素提取文本或截图。技能可以把步骤写得很细但“能不能连上”不是技能能决定的。我见过一个典型的反面案例有人下载了一套“自动化渗透测试”的 skills里面写了调用各种扫描工具的流程但完全没有配置对应的 MCP 服务也没有安装依赖工具。运行结果自然是技能东一句西一句地建议用这个工具那个命令什么都执行不了。这类问题排查时顺序永远是先验证 MCP 单独能用再套用技能。另外如果你的技能涉及敏感操作比如读取密钥、修改文件权限、执行高权限命令我建议在技能里明确加一条“高风险操作必须输出命令让用户确认执行禁止自动运行”。这是底线不能省。5.3 三条我个人踩坑后的防线讲了这么多最后分享三条我个人的经验防线每一条都是花钱买来的教训。第一条所有 skills 一律进入版本管理。不要直接在工具目录里裸改要放到 Git 仓库里改完后提交。别小看这一步技能文件一旦多起来改来改去很容易忘记哪次改动是有效的。版本历史不仅能让你回滚还能对比不同版本在测试用例上的表现差异。第二条控制技能的上下文成本。每个 skill 被加载都会占用上下文窗口如果你一口气给 AI 配了二十个技能哪怕一次任务只触发一个整体响应速度和效果也会受影响。我现在的做法是保持“默认轻量、按需加装”全局只放三五条高频技能项目目录里再根据项目类型放特定技能绝不给同一个会话塞过多技能。第三条定期用真实任务做回归测试。AI 模型更新很快同一个技能在新版本模型下表现可能完全不同。我每隔一两周会用固定的测试任务跑一遍自己常用的几个技能看输出是否还符合预期。如果发现偏差通常是因为模型能力变强或变弱导致旧指令不再适用需要微调技能内容。skills 这个东西本质上不是一种高深技术它更像是一种“经验工程化”的实践。把你知道的做事方法、踩过的坑、积累的规范用结构化的方式沉淀到一个能被 AI 随时查阅的地方然后再把你的工作流像拼积木一样组合起来。试过的团队会明显感觉到AI 输出的稳定性上了一个台阶试过之后再回头用纯提示词你会觉得像是在让一个熟练工只凭感觉干活。所以如果你还没动手建议今晚就写一个最简单的技能哪怕是“生成 Git 提交信息”这种三五十行的技能跑通流程之后你会对这套玩法有完全不一样的理解。