SKILL.md到底是什么？新手图解VibeCurb的Agent设计技能文件与上下文注入机制

VibeCurb 是一个开源的"反 AI slop"设计技能集，核心由一组 SKILL.md 形式的 Agent 设计技能文件构成。它通过上下文注入机制，把严格的设计协议注入 Cursor、Claude Code、v0、Codex 等 AI 编程工具，强制 Agent 按"先读图、再选结构、再构建、最后验证"的流水线干活，从而停止生成紫色渐变 + 玻璃拟态卡片的平庸网页。本文以 VibeCurb 为例，带你彻底搞懂：SKILL.md 到底是什么、里面写了什么、又是如何被注入你的 Agent 上下文的。

先理解：为什么 AI 做的网页总是"一个样"？

AI 模型是在数百万个普通网页上训练出来的，不加约束，它必然输出"平均值"：居中大标题 + 紫色渐变背景 + 玻璃拟态卡片 + 弹跳的向下箭头。

VibeCurb 的答案不是换一套模板，而是约束（constraint）。README.md 开篇就点明："AI defaults to the mean... VibeCurb is the constraint."——它不教 Agent 把页面"做得好看"，而是规定一套强制流程：先从参考图提取设计信号，过质量门禁后才能动笔，再逐项对照参考图做 Visual Diff，任何"AI 默认味"的输出当场打回。

一句话讲清：SKILL.md 就是写给 AI 的"操作规程"

SKILL.md 是一份纯 Markdown 文件，不是脚本、不是配置、也不是需要安装的依赖库，而是 AI Agent 读取并必须遵守的一套协议。它由两部分组成：

前半部分：Frontmatter"名片"

每个 SKILL.md 都以---包裹的 YAML frontmatter 开头，包含两个关键字段。以 skills/awwwards-hero/SKILL.md 为例：

--- name: awwwards-hero-section description: Hero-section pipeline for building Awwwards/FWA-tier hero sections. Extracts design direction from reference images... ---

• name：技能的唯一标识，Agent 靠它识别和引用；
• description：一段高度浓缩的"何时触发、做什么、执行什么标准"摘要——Agent 是否调用该技能，很大程度就看这个字段。

后半部分：必须走通的严格流水线

以 hero 区域技能为例，skills/awwwards-hero/SKILL.md 定义了一条四阶段流水线，每个阶段都设有质量门禁（Quality Gate），不通过就不许进入下一阶段：

这种写法有三个反复出现的设计亮点：

1. Quality Gate（质量门禁）：Agent 必须先"证明"自己看懂了设计方向（例如写出一段 Hero Extraction 摘要），才有资格写代码——直接堵死了"看到需求就抄近路写代码"的坏习惯；
2. Drift Warning（漂移警告）：明确指出模型最容易翻车的模式，比如警告"用 Inter、Roboto 这类正文字体做大标题，页面必然平庸"；
3. 反 AI 味黑名单：验证阶段逐条列 FAIL——AI 紫色渐变、霓虹高亮、"Elevate / Seamless" 式文案、emoji，全部一票否决。

内置的 7 个技能文件，分别管什么？

VibeCurb 在 skills/ 目录下提供 7 份 SKILL.md，一个场景一份：

其中visual-redesign最有意思：它把代码严格分成SACRED（状态、API 调用、事件处理器逻辑——绝对不许碰）和SLOP（className、颜色、间距——放心改）两类，连"灰色地带"（比如既含逻辑又含样式的className三元表达式）都给出了逐条判断规则。此外，skills/llm.txt 提供了一份全部技能的快速索引清单。

上下文注入机制：SKILL.md 是如何"住进"Agent 的？

很多人以为 SKILL.md 需要"安装"，其实注入的本质 = 把文件放到 Agent 会读的位置。VibeCurb 给了两种方式：

方式一：一条命令注入（推荐）

项目 package.json 提供了vibecurb命令行入口，把技能文件从仓库的 skills/ 目录复制到你项目里：

# 查看全部可用技能 npx vibecurb-cli list # 注入指定技能 npx vibecurb-cli add visual-redesign

它的实现是 index.js：一个用 Node.js 写的交互式 CLI，勾选需要的技能后，把对应的 SKILL.md 写入你项目的.agents/skills/<技能名>/目录，全程不改动你已有的任何代码。

方式二：手动放置

1. 克隆整个仓库（git clone https://gitcode.com/gh_mirrors/vi/VibeCurb）或单独下载需要的 SKILL.md；
2. 放入你项目的.cursor/rules/或.agents/skills/文件夹；
3. 在提示词中引用："Based on the skill above..."

这种方式对任何能读取 Markdown 上下文的 Agent 都有效：Cursor、Claude Code、v0、Codex、ChatGPT、Lovable、AI Studio、Gemini CLI。

所以所谓"上下文注入"，就是把技能文件变成 Agent 的长期上下文：它不是"建议"，而是 Agent 必须执行的强制协议。README 里也毫不客气地警告："These skills do not ask nicely."——如果你只想拿安全的通用布局，别用 VibeCurb。

上手实操：让技能生效的 3 个步骤

第 1 步：选对技能。只有需求描述 →awwwards-hero；有参考截图 →pixel-perfect；要改造现有代码 →visual-redesign。

第 2 步：注入。运行npx vibecurb-cli add <技能名>，或手动放置文件。

第 3 步：按"Prompt Architecture"写提示词。README.md 推荐叙述式结构：先声明"基于上述技能"，再交代交付物与业务场景，给出 vibe 词汇，说明布局方向（构图风格、色板、明暗模式、字体规则），最后再强调一次质量标准。💡 核心理念是——Agent 不会读心术：你只说"做个酷一点的落地页"，得到的就是紫色渐变；给一张清晰的参考图，能消除大部分瞎猜。

翻车了怎么办？拉回"漂移"的 Agent

长对话中，Agent 会慢慢漂回"平均审美"。README 给出了现成的"回拉三句话"：

写在最后

• SKILL.md 是什么：YAML frontmatter + 严格流水线的纯 Markdown 技能文件，是给 AI Agent 的"操作规程"；
• 注入机制做了什么：不装程序，只扩展 Agent 上下文，让技能文件成为强制约束；
• VibeCurb 的价值：用 7 份技能文件把"帮我做个网页"变成"先读、再建、再验"，在第一行代码写出来之前拦住 AI slop。

这也是它最值得借鉴的一点：给 Agent 定规矩，别指望它自己有品味——把流程写成可读、可验证、可打分的文档，质量就有了底线。