最近不管刷推特、翻知乎还是逛 GitHub总能撞见同一个词skills。先有 Claude Code 官方文档把 skills 当成主角接着 Codex 跟了上来Cursor 也悄悄改了配置目录的名字吴恩达的 Agent Skills 教程 PDF 更是被转得到处都是。区别在这儿以前你要的是一个能聊天的模型现在你要的是一个能接手某类具体任务的“数字员工”——而 skills就是给这个员工写的岗位说明书加操作手册。skill人工智能 skills / agent skills本质上是一组放在固定目录里的文本文件加辅助脚本它们描述某项任务的目标、约束和详细步骤。当模型遇到合适的场景时会主动读取相关 skills然后照着里面的流程干活。它不是提示词也不是插件它介于两者之间像提示词一样指导思维像插件一样携带能力。这篇文章不打算给你一份“标准教程”我想直接聊清楚它到底解决了什么、内部长什么样、怎么从零写一个属于自己的 skill以及我在反复踩坑之后总结出来的经验。1. 从“会聊”到“会干活”Agent Skills到底解决了什么问题1.1 一个Prompt打天下的时代结束了AI 编程和智能体工具刚火起来的时候大家习惯把“专家经验”一股脑塞进系统提示词写代码要注意什么、周报要用什么结构、遇到报错先做什么检查。问题很快暴露——上下文窗口再大也扛不住无休止的规则堆叠。当你的“万能提示词”从几百字膨胀到几千字、甚至上万字模型在前半段还记得后半段就开始忘指令之间互相冲突输出质量断崖式下降。skills 换了一种思路把知识按“抽屉”分好而不是全贴在一面墙上。平时模型只读一个很短的技能清单等用户真说要写周报它才去打开“周报生成”那个抽屉把里面的操作手册读进上下文。这就好比一个办公室规范不是写在一本一千页的《员工手册》里而是把每个岗位的 SOP 放在标签明确的文件柜中谁干活谁拿哪份。上下文干净了任务精准了模型犯糊涂的概率也大幅度下降。1.2 Skills、MCP、Prompt三者别搞混了很多刚接触的人会把 skills 和 MCP 放在一个篮子里比较甚至觉得它们功能重叠。我的区分方式很简单Prompt一次性自然语言请求没有结构、没有文件、用完即弃。MCP为模型提供调用外部工具和数据的统一协议解决“模型能不能访问某个资源”的问题。Skill可复用的任务流程与专家知识包解决“模型会不会把事情做好”的问题。三者是协作关系不是替代关系。举个“竞品分析”的例子分析流程本身有完整方法论适合做成 skill过程中需要去抓网页、查数据库这些能力来自 MCP server而用户随口问一句“帮我看看这个产品怎么样”那是 prompt。Skill 告诉模型应该分几步做、每一步产出什么、遇到异常怎么处理MCP 告诉模型可以调动哪些手模型在 skill 的指引下自然地调用 MCP 工具完成任务。1.3 为什么吴恩达和各家官方都在推吴恩达在 Agent Skills 教程里反复强调要让 Agent 真正落地光靠基础模型不够得给 Agent 一种可以积累、共享、版本化的能力资产。他在课件里示范了如何把“报表分析”“周报生成”“研究助手”这些场景固化成 skill并指出技能目录本身应当像代码一样放进 Git 仓库支持 review、迭代、回滚。这其实是对“提示词工程”的一次升级——以前 Prompt 是散落在聊天记录里的灵光一现现在它是可以被管理、被复用、被团队共享的工程制品。各家工具厂商跟进速度也很快。Claude Code 把 skills 纳入官方机制Codex 在项目里支持类似结构Cursor 的规则体系也在向这个方向靠拢。搜索热词里“claude code skills 官方文档”“codex使用skills”“cursor 前端使用的skills有哪些”的高频出现说明大家已经在实操中意识到光会聊天不解决问题能把经验沉淀成技能文件才是让 AI 真正为项目效力的临界点。2. 拆解一套Skill的内部结构SKILL.md、脚本与元数据2.1 一套典型Skill的目录骨架在多数工具约定里一个 skill 就是一个目录典型结构如下my-skill/ ├── SKILL.md ├── scripts/ │ └── process.py ├── references/ │ ├── style-guide.md │ └── example-output.json └── assets/ └── template.html各部分的角色我按实际使用频率排序SKILL.md技能的核心写目标、步骤、约束、验收标准。模型决定是否加载一个技能时首先看它的 description然后读这份文件。scripts/可执行的辅助脚本用来做模型不擅长或不适合纯文本推理的确定性工作比如提取图片主色、批量重命名文件、调用 API 并清洗数据。references/参考资料供技能执行时查询比如团队编码规范、历史成功案例、字段映射表。assets/模板与静态资源比如要给前端生成页面时这里的 HTML 模板可以被直接拷贝。模型加载技能时以 SKILL.md 为主必要时按其中的路径引用 scripts、references、assets。目录名最好一眼可见它负责什么避免出现untitled-skill、test这种无法识别的名字。2.2 SKILL.md的头部信息与正文规范玩转 skills 的一个核心条件是把 SKILL.md 写规范。头部 frontmatter 是模型判断“是否在该场景加载我”的依据通常长这样--- name: weekly-report description: 当用户要求生成周报、状态更新或项目进度总结时使用。输入支持本周日志、git 提交记录输出为结构化 Markdown 周报。 ---description 的写法有讲究。它要明确三件事触发条件、输入形式、输出形式。如果只写“用于工作总结”用户在问“今天干了什么”的时候模型都有可能错误加载。我还习惯在 description 里加上“绝不适用”的条件例如“不用于日报生成不用于分析 git 历史性能问题”这能有效降低误触发率。正文部分一份顺手的 SKILL.md 应当包含下面几个模块目标一句话说明这个技能为了达成什么结果。使用步骤按顺序列出要执行的步骤每一步注明期望产出。约束和禁忌哪些事情不允许做什么情况必须停下来问用户。验收标准完成一个任务后如何判断结果合格。常见失败模式模型经常会在哪里翻车提前写好应对方式。要把“说给模型听”的常见失败模式写进去。比如“设计稿还原”技能里很多模型会把稿件中的图片占位符替换成网上随便拉来的图这就要在约束里明确“图片占位符保持原样不得自行替换素材”。2.3 按需加载和“子技能”的组织思路模型不会在读入整个仓库的情况下执行所有技能。它根据用户问题、会话上下文和工具列表再结合每个技能的 description 做“语义匹配”决定先加载哪一个。这带来一个实践原则description 的区分度决定整套技能库的质量。两个描述过于接近的技能模型可能同时加载或者选错一个导致流程混乱。规模大起来之后可以拆“子技能”。一个主技能负责总体流程更细的子技能负责可独立验收的子任务。比如“生成技术方案”是主技能内部遇到“需要画架构图”时可以在步骤中写明“调用 network-diagram skill 生成架构图”。子技能和主技能放在同一个 skills 目录下通过名称互相引用。拆分粒度我建议以“单独交给一个人是否能完成”为标准能独立验证的才拆否则只是增加加载开销。3. 从零开发一个自己的Skill以“图片还原设计稿”为例的完整流程3.1 先把边界想清楚输入、输出、验收标准热词里“图片还原设计稿给前端开发 好用的skills”被反复提及说明这是一个高频痛点。开发这类技能前先别急着写文件把边界定义清楚输入一张设计稿图片PNG/JPG/Figma 导出图可选附加说明风格偏好、目标框架、断点要求。输出一套 HTML/CSS 或 React 组件文件未填充的图片资源用占位符标注。验收标准肉眼对比还原度 90% 以上颜色严格取自设计稿而不是模型“觉得好看”的配色响应式布局符合常见屏幕断点。不定义这些边界AI 会把整个任务做成“自由发挥”。它能跑出像一个网页的东西但不是你要的还原。3.2 搭建目录与核心文档创建目录design-to-code先写 SKILL.md。description 写成“当用户提供设计稿图片并要求还原为网页、前端页面、组件时使用核心目的是保持视觉还原度”。正文步骤我建议这样定先用视觉能力整体分析设计稿确定页面结构、模块层级和栅格体系。提取所有颜色进入 scripts/color_extract.py 二次核对得到色板文件。确认字体、字号、间距、圆角等关键样式变量。按区块生成 HTML/CSS优先使用 CSS Grid 和 Flex 布局。将页面截图对比设计稿列出未覆盖细节写入 TODO。约束和禁忌部分强调图片分辨率过低时先停止请用户提供原稿而不是硬编不擅自替换素材图产出文件的目录结构要与项目现有规范一致。3.3 加入辅助脚本让Skill真正“可执行”skill 和普通提示词最大的区别就是可以带脚本。在“图片还原设计稿”这个例子里颜色提取脚本非常管用# scripts/color_extract.py from PIL import Image from collections import Counter def extract_colors(image_path, top_n10): img Image.open(image_path).convert(RGB) img.thumbnail((200, 200)) pixels list(img.getdata()) counter Counter(pixels) for color, count in counter.most_common(top_n): print(#{:02x}{:02x}{:02x}.format(*color)) if __name__ __main__: extract_colors(design.png)SKILL.md 中写着“执行 python scripts/color_extract.py design.png 获得色板必须严格使用该色板”。模型自己直接用眼睛看到的颜色会有偏差脚本能给出确定性的十六进制值杜绝“差不多”的视觉判断。脚本还承担很多其他脏活批量切图、图片压缩、生成目录结构、调用设计令牌的 API。核心原则是凡是靠代码能精确完成的就不要让模型靠感觉随便做。3.4 测试与迭代从“能跑”到“好用”把技能放进 Claude Code 或 Codex 的 skills 目录后准备三五张真实设计稿开始测试。我每次迭代都关注三件事模型有没有在用户说出需求时自动加载这个技能输出能不能达到验收标准脚本在目标环境里是否稳定运行。第一版往往漏洞百出。可能模型没有加载技能可能是 step 描述太抽象也可能是脚本路径写成了绝对路径换台机器就报错。不要指望一次成功把这些失败记录补充回 SKILL.md第二次会明显改观。我在实际使用中发现真正花时间的不是写 SKILL.md而是把平时口头叮嘱的细节一条条写下来——但一旦写好之后每次任务至少能节省半小时这笔账是值的。4. Skills与MCP的正确关系与协作方式4.1 MCP解决“通没通”Skills解决“会不会干”“skills如何调用mcp工具”这个搜索词很能说明问题。大家能理解 skill 是“说明书”但一到真正要调用外部工具时就卡住。先给结论MCP 负责把能力接口暴露给模型skill 负责告诉模型该用哪些接口、按什么顺序用。MCP 是水管skill 是用水的 SOP。没有 MCPskill 只能靠模型自带的知识输出拿不到实时数据没有 skillMCP 工具散落在一大串工具列表里模型不知道什么时候该把哪一个捡起来组合使用。4.2 在SKILL.md里要求调用MCP工具的写法以“网页查资料”技能为例这类技能通常依赖 fetch 或 browser 类 MCP server。我在 SKILL.md 中的写法是首先调用fetch工具获取目标 URL 的内容确认页面可读。如果返回的是非结构化文本或动态渲染页面改用browserMCP 打开页面截图并提取正文。将关键信息按“来源、时间、要点”整理到输出文件。页面加载失败时换用searchMCP server 查找备用来源。关键在于把“先试什么、失败后怎么办”写清楚而不是给模型一句“查一下资料”就完事。模型不是不会调用工具它是不确定“什么时候该调用”。skill 的职责就是消除这种不确定性。还需要考虑模型在执行时如何找到正确的 MCP 工具。如果允许多个 MCP server 同时挂载技能里直接写出工具名或 server 名能大幅减少“模型用错工具”的情况。比如“用 github 相关 MCP server 创建 issue”比“调用工具创建 issue”要稳得多。4.3 依赖声明与错误恢复最稳妥的做法是在 SKILL.md 的 frontmatter 或正文中显式声明依赖requires-mcp: - fetch - browser这样做的好处是换新机器、换新环境时一眼就能看出缺了什么。我把所有技能的 MCP 依赖汇总成一张环境安装表每次搭新环境照着装一遍避免“技能明明放在了正确位置却一直报错”的尴尬。错误恢复同样值得重视。“浏览器打不开”不能成为技能终止的理由。设计技能时提前留好降级路径抓不到动态内容就退化到只抓静态 HTML页面完全不可达就把手头已有信息整理成“部分结果”输出而不是从模型记忆中编造。初版技能经常缺这个分支结果模型遇到异常就胡编这是最需要防的坑。5. 被高频搜索的高口碑Skills盘点5.1 数学建模类“数学建模skills”和“数学建模skills推荐”被搜得很多。这类技能通常覆盖从题目中提取变量与约束、选择合适的模型线性规划、微分方程、排队论、机器学习、生成 LaTeX 论文结构、输出可运行的 Python 代码和可视化图表。核心价值在于把“赛前准备”标准化。组队参赛时把队伍里惯用的模型模板和论文格式变成 skill每个成员都能快速生成风格统一、符号体系一致的初稿。它不能替你做创新但能把繁琐的格式工作从脑子里卸掉让你把注意力放在真正要解决的问题上。5.2 渗透测试与安全分析类安全类技能有一个绝对前提授权。只能在授权范围、自建靶场或自家系统里使用这是底线也是我在任何场合都会强调的合规要求。合规前提下的渗透测试技能通常包括信息收集子域名、开放端口、目录扫描、漏洞分类按 OWASP Top 10、证据留存、报告生成。它们让模型按步骤执行而不是瞎猜漏洞。我建议不仅在文档里写明授权要求还要把“非法目标禁止使用”直接写进 SKILL.md 的禁忌栏。技能本身不应该替用户判断目标是否合法但至少要在流程开始前设计一个“确认授权”的检查步骤强制用户先确认目标属于自己或已获得书面授权。安全不是口头说说是要体现在流程设计里。5.3 学术研究与网页查资料类“academic research skills”和“claude code 网页查资料的skills”指向的都是科研场景的痛点。学术研究技能通常负责把研究问题拆成检索关键词调用文献数据库 MCP 工具进行检索批量提取 PDF 摘要生成规范引用格式整理参考文献列表。真实使用中最影响体验的是“AI 一本正经地引用不存在的论文”。所以这类技能必须写死一条硬约束只输出检索接口真实返回的条目禁止在参考文献列表里编造任何来源。宁可结果少一点也不能假一点。网页查资料技能同样强调信息溯源要求每一步保留 URL用不同来源交叉验证最后输出带出处的结论。5.4 PPT、前端、移动端、测试用例等其他热门PPT skillsGitHub 上“github claude code ppt skills”很活跃常见做法是让 Claude Code 读取 Markdown 大纲借助 HTML 加 reveal.js 或 python-pptx 生成幻灯片。核心步骤是先定视觉风格再填充内容而不是一上来就让模型写满页文字。前端开发 skills除了“图片还原设计稿”还有“web前端 mcp skills”。这类技能通常结合 MCP 开发服务器和浏览器预览工具实现改代码、看效果、继续调整的闭环。它解决的最大问题是前端开发中“模型改代码但你看不到结果”的焦虑。移动端 skills面向 iOS/Android侧重适配规则、栅格系统、常用组件库。模型如果不清楚移动端断点和触摸目标尺寸写出来的页面会停留在“理想屏幕”里。测试用例 skills基于需求描述生成覆盖矩阵、边界值、等价类用例并标注优先级和自动化脚本模板。测试用例设计是有章法的正好适合用技能把方法论固化下来。结构图 skills从文档半自动生成流程图、架构图、思维导图。这类技能通常需要调用绘图工具格式生成文本描述再做可视化渲染。你不需要一次性全装。每个技能的加载和维护成本都是真实存在的装得越多模型选择负担越重。按自己最高频的任务挑两三个远比囤积几百个没用的技能更有效率。6. Skills开发与调用中的避坑指南6.1 过度拆分把“思考”也做成了Skill接触“skills creator”和“skills开发”之后最容易犯的错是过度拆分。有人把“写代码”拆成一百个技能写 Python、写 JavaScript、写 SQL、写 Dockerfile……结果每次遇到编程任务模型要先在一堆技能里做选择题反而拖慢速度。我的判断标准很简单如果一件事靠半屏提示词就能说清楚不需要做成技能如果一件事需要三步以上、涉及约定和检查项、并且你希望下次直接复用才值得固化成技能。思维方法类的内容慎做技能因为思维的通用性和迁移性太强硬固化成技能会让模型僵化。6.2 描述词写得太宽泛模型不知道该不该加载description 是技能和模型之间的“索引”它的质量直接影响加载命中率。太宽泛模型容易在不该用的场景加载太窄模型在该用的时候找不到。建议格式是“当用户做了 X 并且期望 Y 时使用输入是 A输出是 B绝不用于 C”。这种写法把触发条件、输入、输出、禁区一次说清。我在“代码审查”技能里是这样写的当用户要求评估代码质量、审核合并请求或补丁时使用不用于编写新代码、不用于解释语法。实际跑下来误触发率低了很多。6.3 多端兼容性Claude Code / Codex / Cursor的差异别指望一个技能目录通吃所有工具。Claude Code 官方支持.claude/skills/目录Codex 更习惯用AGENTS.md或它自己的技能机制Cursor 则有.cursor/rules体系。跨端运行时需要做格式适配SKILL.md 的 frontmatter 在两端可能写法和识别规则都不同。我的做法是技能正文保持工具无关讲清楚目标和步骤frontmatter 和各端的配置单独维护。用一个脚本从同一份 Markdown 生成不同工具需要的文件既能保留单一事实来源又能适配多个环境。没有这套适配技能在这家用得好好的换到那家就完全不认。6.4 安全红线直接执行陌生Skill的风险GitHub 上第三方 skills 很多搜索“skills下载”“skills推荐”时尤其要小心。引入一个陌生技能等同于让模型按别人写好的指令脚本执行存在提示注入和恶意代码风险。我的安全清单不盲目运行git clone进来的技能先读 SKILL.md 的 frontmatter 和 scripts 目录逐个确认命令的作用。在沙箱环境或单独目录中测试跑通后再放进正式工作区。对技能内部的下载和安装动作做白名单禁止未经确认的curl | bash类操作。不让 AI 编程工具以管理员权限直接运行陌生技能。这些步骤不是小题大做。技能的危害比普通提示词大得多因为脚本部分真的会在你机器上执行代码。检查一遍远好过事后收拾残局。回到我自己的使用习惯。从去年开始我把周报生成、发布检查、图片压缩、竞品信息收集、接口文档转类型定义这五件事做成了技能存放在一个 Git 仓库里。最直接的体会是换电脑、换工具时不再需要一遍遍给新模型解释背景知识更重要的是我在技能里沉淀下的那些“注意边界”和“常见失败解决办法”其实比模型版本升级更值钱。技能不是一次写完就完事的它像代码一样需要持续 review 和迭代。如果你现在开始建议先别做一整套洋洋洒洒的技能库只挑一个你本周就要反复干的任务做成第一个技能然后立刻用起来。用的过程中发现问题回头改让技能跟着你的真实工作一起生长。 
长河君 · 2026/9/9 2:01:21 · 阅读 1.2k Agent Skills完全指南：从原理到实战，构建你的AI技能库
最近不管刷推特、翻知乎还是逛 GitHub总能撞见同一个词skills。先有 Claude Code 官方文档把 skills 当成主角接着 Codex 跟了上来Cursor 也悄悄改了配置目录的名字吴恩达的 Agent Skills 教程 PDF 更是被转得到处都是。区别在这儿以前你要的是一个能聊天的模型现在你要的是一个能接手某类具体任务的“数字员工”——而 skills就是给这个员工写的岗位说明书加操作手册。skill人工智能 skills / agent skills本质上是一组放在固定目录里的文本文件加辅助脚本它们描述某项任务的目标、约束和详细步骤。当模型遇到合适的场景时会主动读取相关 skills然后照着里面的流程干活。它不是提示词也不是插件它介于两者之间像提示词一样指导思维像插件一样携带能力。这篇文章不打算给你一份“标准教程”我想直接聊清楚它到底解决了什么、内部长什么样、怎么从零写一个属于自己的 skill以及我在反复踩坑之后总结出来的经验。1. 从“会聊”到“会干活”Agent Skills到底解决了什么问题1.1 一个Prompt打天下的时代结束了AI 编程和智能体工具刚火起来的时候大家习惯把“专家经验”一股脑塞进系统提示词写代码要注意什么、周报要用什么结构、遇到报错先做什么检查。问题很快暴露——上下文窗口再大也扛不住无休止的规则堆叠。当你的“万能提示词”从几百字膨胀到几千字、甚至上万字模型在前半段还记得后半段就开始忘指令之间互相冲突输出质量断崖式下降。skills 换了一种思路把知识按“抽屉”分好而不是全贴在一面墙上。平时模型只读一个很短的技能清单等用户真说要写周报它才去打开“周报生成”那个抽屉把里面的操作手册读进上下文。这就好比一个办公室规范不是写在一本一千页的《员工手册》里而是把每个岗位的 SOP 放在标签明确的文件柜中谁干活谁拿哪份。上下文干净了任务精准了模型犯糊涂的概率也大幅度下降。1.2 Skills、MCP、Prompt三者别搞混了很多刚接触的人会把 skills 和 MCP 放在一个篮子里比较甚至觉得它们功能重叠。我的区分方式很简单Prompt一次性自然语言请求没有结构、没有文件、用完即弃。MCP为模型提供调用外部工具和数据的统一协议解决“模型能不能访问某个资源”的问题。Skill可复用的任务流程与专家知识包解决“模型会不会把事情做好”的问题。三者是协作关系不是替代关系。举个“竞品分析”的例子分析流程本身有完整方法论适合做成 skill过程中需要去抓网页、查数据库这些能力来自 MCP server而用户随口问一句“帮我看看这个产品怎么样”那是 prompt。Skill 告诉模型应该分几步做、每一步产出什么、遇到异常怎么处理MCP 告诉模型可以调动哪些手模型在 skill 的指引下自然地调用 MCP 工具完成任务。1.3 为什么吴恩达和各家官方都在推吴恩达在 Agent Skills 教程里反复强调要让 Agent 真正落地光靠基础模型不够得给 Agent 一种可以积累、共享、版本化的能力资产。他在课件里示范了如何把“报表分析”“周报生成”“研究助手”这些场景固化成 skill并指出技能目录本身应当像代码一样放进 Git 仓库支持 review、迭代、回滚。这其实是对“提示词工程”的一次升级——以前 Prompt 是散落在聊天记录里的灵光一现现在它是可以被管理、被复用、被团队共享的工程制品。各家工具厂商跟进速度也很快。Claude Code 把 skills 纳入官方机制Codex 在项目里支持类似结构Cursor 的规则体系也在向这个方向靠拢。搜索热词里“claude code skills 官方文档”“codex使用skills”“cursor 前端使用的skills有哪些”的高频出现说明大家已经在实操中意识到光会聊天不解决问题能把经验沉淀成技能文件才是让 AI 真正为项目效力的临界点。2. 拆解一套Skill的内部结构SKILL.md、脚本与元数据2.1 一套典型Skill的目录骨架在多数工具约定里一个 skill 就是一个目录典型结构如下my-skill/ ├── SKILL.md ├── scripts/ │ └── process.py ├── references/ │ ├── style-guide.md │ └── example-output.json └── assets/ └── template.html各部分的角色我按实际使用频率排序SKILL.md技能的核心写目标、步骤、约束、验收标准。模型决定是否加载一个技能时首先看它的 description然后读这份文件。scripts/可执行的辅助脚本用来做模型不擅长或不适合纯文本推理的确定性工作比如提取图片主色、批量重命名文件、调用 API 并清洗数据。references/参考资料供技能执行时查询比如团队编码规范、历史成功案例、字段映射表。assets/模板与静态资源比如要给前端生成页面时这里的 HTML 模板可以被直接拷贝。模型加载技能时以 SKILL.md 为主必要时按其中的路径引用 scripts、references、assets。目录名最好一眼可见它负责什么避免出现untitled-skill、test这种无法识别的名字。2.2 SKILL.md的头部信息与正文规范玩转 skills 的一个核心条件是把 SKILL.md 写规范。头部 frontmatter 是模型判断“是否在该场景加载我”的依据通常长这样--- name: weekly-report description: 当用户要求生成周报、状态更新或项目进度总结时使用。输入支持本周日志、git 提交记录输出为结构化 Markdown 周报。 ---description 的写法有讲究。它要明确三件事触发条件、输入形式、输出形式。如果只写“用于工作总结”用户在问“今天干了什么”的时候模型都有可能错误加载。我还习惯在 description 里加上“绝不适用”的条件例如“不用于日报生成不用于分析 git 历史性能问题”这能有效降低误触发率。正文部分一份顺手的 SKILL.md 应当包含下面几个模块目标一句话说明这个技能为了达成什么结果。使用步骤按顺序列出要执行的步骤每一步注明期望产出。约束和禁忌哪些事情不允许做什么情况必须停下来问用户。验收标准完成一个任务后如何判断结果合格。常见失败模式模型经常会在哪里翻车提前写好应对方式。要把“说给模型听”的常见失败模式写进去。比如“设计稿还原”技能里很多模型会把稿件中的图片占位符替换成网上随便拉来的图这就要在约束里明确“图片占位符保持原样不得自行替换素材”。2.3 按需加载和“子技能”的组织思路模型不会在读入整个仓库的情况下执行所有技能。它根据用户问题、会话上下文和工具列表再结合每个技能的 description 做“语义匹配”决定先加载哪一个。这带来一个实践原则description 的区分度决定整套技能库的质量。两个描述过于接近的技能模型可能同时加载或者选错一个导致流程混乱。规模大起来之后可以拆“子技能”。一个主技能负责总体流程更细的子技能负责可独立验收的子任务。比如“生成技术方案”是主技能内部遇到“需要画架构图”时可以在步骤中写明“调用 network-diagram skill 生成架构图”。子技能和主技能放在同一个 skills 目录下通过名称互相引用。拆分粒度我建议以“单独交给一个人是否能完成”为标准能独立验证的才拆否则只是增加加载开销。3. 从零开发一个自己的Skill以“图片还原设计稿”为例的完整流程3.1 先把边界想清楚输入、输出、验收标准热词里“图片还原设计稿给前端开发 好用的skills”被反复提及说明这是一个高频痛点。开发这类技能前先别急着写文件把边界定义清楚输入一张设计稿图片PNG/JPG/Figma 导出图可选附加说明风格偏好、目标框架、断点要求。输出一套 HTML/CSS 或 React 组件文件未填充的图片资源用占位符标注。验收标准肉眼对比还原度 90% 以上颜色严格取自设计稿而不是模型“觉得好看”的配色响应式布局符合常见屏幕断点。不定义这些边界AI 会把整个任务做成“自由发挥”。它能跑出像一个网页的东西但不是你要的还原。3.2 搭建目录与核心文档创建目录design-to-code先写 SKILL.md。description 写成“当用户提供设计稿图片并要求还原为网页、前端页面、组件时使用核心目的是保持视觉还原度”。正文步骤我建议这样定先用视觉能力整体分析设计稿确定页面结构、模块层级和栅格体系。提取所有颜色进入 scripts/color_extract.py 二次核对得到色板文件。确认字体、字号、间距、圆角等关键样式变量。按区块生成 HTML/CSS优先使用 CSS Grid 和 Flex 布局。将页面截图对比设计稿列出未覆盖细节写入 TODO。约束和禁忌部分强调图片分辨率过低时先停止请用户提供原稿而不是硬编不擅自替换素材图产出文件的目录结构要与项目现有规范一致。3.3 加入辅助脚本让Skill真正“可执行”skill 和普通提示词最大的区别就是可以带脚本。在“图片还原设计稿”这个例子里颜色提取脚本非常管用# scripts/color_extract.py from PIL import Image from collections import Counter def extract_colors(image_path, top_n10): img Image.open(image_path).convert(RGB) img.thumbnail((200, 200)) pixels list(img.getdata()) counter Counter(pixels) for color, count in counter.most_common(top_n): print(#{:02x}{:02x}{:02x}.format(*color)) if __name__ __main__: extract_colors(design.png)SKILL.md 中写着“执行 python scripts/color_extract.py design.png 获得色板必须严格使用该色板”。模型自己直接用眼睛看到的颜色会有偏差脚本能给出确定性的十六进制值杜绝“差不多”的视觉判断。脚本还承担很多其他脏活批量切图、图片压缩、生成目录结构、调用设计令牌的 API。核心原则是凡是靠代码能精确完成的就不要让模型靠感觉随便做。3.4 测试与迭代从“能跑”到“好用”把技能放进 Claude Code 或 Codex 的 skills 目录后准备三五张真实设计稿开始测试。我每次迭代都关注三件事模型有没有在用户说出需求时自动加载这个技能输出能不能达到验收标准脚本在目标环境里是否稳定运行。第一版往往漏洞百出。可能模型没有加载技能可能是 step 描述太抽象也可能是脚本路径写成了绝对路径换台机器就报错。不要指望一次成功把这些失败记录补充回 SKILL.md第二次会明显改观。我在实际使用中发现真正花时间的不是写 SKILL.md而是把平时口头叮嘱的细节一条条写下来——但一旦写好之后每次任务至少能节省半小时这笔账是值的。4. Skills与MCP的正确关系与协作方式4.1 MCP解决“通没通”Skills解决“会不会干”“skills如何调用mcp工具”这个搜索词很能说明问题。大家能理解 skill 是“说明书”但一到真正要调用外部工具时就卡住。先给结论MCP 负责把能力接口暴露给模型skill 负责告诉模型该用哪些接口、按什么顺序用。MCP 是水管skill 是用水的 SOP。没有 MCPskill 只能靠模型自带的知识输出拿不到实时数据没有 skillMCP 工具散落在一大串工具列表里模型不知道什么时候该把哪一个捡起来组合使用。4.2 在SKILL.md里要求调用MCP工具的写法以“网页查资料”技能为例这类技能通常依赖 fetch 或 browser 类 MCP server。我在 SKILL.md 中的写法是首先调用fetch工具获取目标 URL 的内容确认页面可读。如果返回的是非结构化文本或动态渲染页面改用browserMCP 打开页面截图并提取正文。将关键信息按“来源、时间、要点”整理到输出文件。页面加载失败时换用searchMCP server 查找备用来源。关键在于把“先试什么、失败后怎么办”写清楚而不是给模型一句“查一下资料”就完事。模型不是不会调用工具它是不确定“什么时候该调用”。skill 的职责就是消除这种不确定性。还需要考虑模型在执行时如何找到正确的 MCP 工具。如果允许多个 MCP server 同时挂载技能里直接写出工具名或 server 名能大幅减少“模型用错工具”的情况。比如“用 github 相关 MCP server 创建 issue”比“调用工具创建 issue”要稳得多。4.3 依赖声明与错误恢复最稳妥的做法是在 SKILL.md 的 frontmatter 或正文中显式声明依赖requires-mcp: - fetch - browser这样做的好处是换新机器、换新环境时一眼就能看出缺了什么。我把所有技能的 MCP 依赖汇总成一张环境安装表每次搭新环境照着装一遍避免“技能明明放在了正确位置却一直报错”的尴尬。错误恢复同样值得重视。“浏览器打不开”不能成为技能终止的理由。设计技能时提前留好降级路径抓不到动态内容就退化到只抓静态 HTML页面完全不可达就把手头已有信息整理成“部分结果”输出而不是从模型记忆中编造。初版技能经常缺这个分支结果模型遇到异常就胡编这是最需要防的坑。5. 被高频搜索的高口碑Skills盘点5.1 数学建模类“数学建模skills”和“数学建模skills推荐”被搜得很多。这类技能通常覆盖从题目中提取变量与约束、选择合适的模型线性规划、微分方程、排队论、机器学习、生成 LaTeX 论文结构、输出可运行的 Python 代码和可视化图表。核心价值在于把“赛前准备”标准化。组队参赛时把队伍里惯用的模型模板和论文格式变成 skill每个成员都能快速生成风格统一、符号体系一致的初稿。它不能替你做创新但能把繁琐的格式工作从脑子里卸掉让你把注意力放在真正要解决的问题上。5.2 渗透测试与安全分析类安全类技能有一个绝对前提授权。只能在授权范围、自建靶场或自家系统里使用这是底线也是我在任何场合都会强调的合规要求。合规前提下的渗透测试技能通常包括信息收集子域名、开放端口、目录扫描、漏洞分类按 OWASP Top 10、证据留存、报告生成。它们让模型按步骤执行而不是瞎猜漏洞。我建议不仅在文档里写明授权要求还要把“非法目标禁止使用”直接写进 SKILL.md 的禁忌栏。技能本身不应该替用户判断目标是否合法但至少要在流程开始前设计一个“确认授权”的检查步骤强制用户先确认目标属于自己或已获得书面授权。安全不是口头说说是要体现在流程设计里。5.3 学术研究与网页查资料类“academic research skills”和“claude code 网页查资料的skills”指向的都是科研场景的痛点。学术研究技能通常负责把研究问题拆成检索关键词调用文献数据库 MCP 工具进行检索批量提取 PDF 摘要生成规范引用格式整理参考文献列表。真实使用中最影响体验的是“AI 一本正经地引用不存在的论文”。所以这类技能必须写死一条硬约束只输出检索接口真实返回的条目禁止在参考文献列表里编造任何来源。宁可结果少一点也不能假一点。网页查资料技能同样强调信息溯源要求每一步保留 URL用不同来源交叉验证最后输出带出处的结论。5.4 PPT、前端、移动端、测试用例等其他热门PPT skillsGitHub 上“github claude code ppt skills”很活跃常见做法是让 Claude Code 读取 Markdown 大纲借助 HTML 加 reveal.js 或 python-pptx 生成幻灯片。核心步骤是先定视觉风格再填充内容而不是一上来就让模型写满页文字。前端开发 skills除了“图片还原设计稿”还有“web前端 mcp skills”。这类技能通常结合 MCP 开发服务器和浏览器预览工具实现改代码、看效果、继续调整的闭环。它解决的最大问题是前端开发中“模型改代码但你看不到结果”的焦虑。移动端 skills面向 iOS/Android侧重适配规则、栅格系统、常用组件库。模型如果不清楚移动端断点和触摸目标尺寸写出来的页面会停留在“理想屏幕”里。测试用例 skills基于需求描述生成覆盖矩阵、边界值、等价类用例并标注优先级和自动化脚本模板。测试用例设计是有章法的正好适合用技能把方法论固化下来。结构图 skills从文档半自动生成流程图、架构图、思维导图。这类技能通常需要调用绘图工具格式生成文本描述再做可视化渲染。你不需要一次性全装。每个技能的加载和维护成本都是真实存在的装得越多模型选择负担越重。按自己最高频的任务挑两三个远比囤积几百个没用的技能更有效率。6. Skills开发与调用中的避坑指南6.1 过度拆分把“思考”也做成了Skill接触“skills creator”和“skills开发”之后最容易犯的错是过度拆分。有人把“写代码”拆成一百个技能写 Python、写 JavaScript、写 SQL、写 Dockerfile……结果每次遇到编程任务模型要先在一堆技能里做选择题反而拖慢速度。我的判断标准很简单如果一件事靠半屏提示词就能说清楚不需要做成技能如果一件事需要三步以上、涉及约定和检查项、并且你希望下次直接复用才值得固化成技能。思维方法类的内容慎做技能因为思维的通用性和迁移性太强硬固化成技能会让模型僵化。6.2 描述词写得太宽泛模型不知道该不该加载description 是技能和模型之间的“索引”它的质量直接影响加载命中率。太宽泛模型容易在不该用的场景加载太窄模型在该用的时候找不到。建议格式是“当用户做了 X 并且期望 Y 时使用输入是 A输出是 B绝不用于 C”。这种写法把触发条件、输入、输出、禁区一次说清。我在“代码审查”技能里是这样写的当用户要求评估代码质量、审核合并请求或补丁时使用不用于编写新代码、不用于解释语法。实际跑下来误触发率低了很多。6.3 多端兼容性Claude Code / Codex / Cursor的差异别指望一个技能目录通吃所有工具。Claude Code 官方支持.claude/skills/目录Codex 更习惯用AGENTS.md或它自己的技能机制Cursor 则有.cursor/rules体系。跨端运行时需要做格式适配SKILL.md 的 frontmatter 在两端可能写法和识别规则都不同。我的做法是技能正文保持工具无关讲清楚目标和步骤frontmatter 和各端的配置单独维护。用一个脚本从同一份 Markdown 生成不同工具需要的文件既能保留单一事实来源又能适配多个环境。没有这套适配技能在这家用得好好的换到那家就完全不认。6.4 安全红线直接执行陌生Skill的风险GitHub 上第三方 skills 很多搜索“skills下载”“skills推荐”时尤其要小心。引入一个陌生技能等同于让模型按别人写好的指令脚本执行存在提示注入和恶意代码风险。我的安全清单不盲目运行git clone进来的技能先读 SKILL.md 的 frontmatter 和 scripts 目录逐个确认命令的作用。在沙箱环境或单独目录中测试跑通后再放进正式工作区。对技能内部的下载和安装动作做白名单禁止未经确认的curl | bash类操作。不让 AI 编程工具以管理员权限直接运行陌生技能。这些步骤不是小题大做。技能的危害比普通提示词大得多因为脚本部分真的会在你机器上执行代码。检查一遍远好过事后收拾残局。回到我自己的使用习惯。从去年开始我把周报生成、发布检查、图片压缩、竞品信息收集、接口文档转类型定义这五件事做成了技能存放在一个 Git 仓库里。最直接的体会是换电脑、换工具时不再需要一遍遍给新模型解释背景知识更重要的是我在技能里沉淀下的那些“注意边界”和“常见失败解决办法”其实比模型版本升级更值钱。技能不是一次写完就完事的它像代码一样需要持续 review 和迭代。如果你现在开始建议先别做一整套洋洋洒洒的技能库只挑一个你本周就要反复干的任务做成第一个技能然后立刻用起来。用的过程中发现问题回头改让技能跟着你的真实工作一起生长。