Impeccable Skill 使用教程：让 Codex 和 Claude Code 改掉 AI 网页味

拾光网让 AI 编程工具做一个“现代、专业、具有高级感”的网页，结果往往很熟悉：紫蓝渐变、深色背景配霓虹光、超大标题、圆角卡片套着圆角卡片，每个功能上方再放一个圆角方形图标。页面不一定难看，但很像从同一个模板里生成出来的。

Impeccable 就是为解决这类问题而生的开源设计 Skill。它没有再发明一个生成网页的平台，而是把设计语汇、项目上下文、审查命令和反模板化检测器放进 Codex、Claude Code、Cursor 等 AI 编程工具，让智能体在真实代码库里改页面。

截至本文写作时，Impeccable GitHub 仓库已有约 4.78 万个 Star，采用 Apache 2.0 许可证。项目由 Paul Bakaus 创建，官方将其概括为：1 个 Skill、23 个命令、设计上下文、浏览器实时迭代，以及一套识别 AI 网页常见套路的检测规则拾光网。

Impeccable 是什么

Impeccable 是写给 AI 编程智能体的设计工作系统。安装后，用户通过统一入口调用不同设计任务：

/impeccable <command> <target>

例如，让它审查结账页面：

/impeccable audit the checkout

让它在发布前整理设置页面：

/impeccable polish the settings page

它和普通“前端设计提示词”的差别主要有四点：

• 把设计工作拆成 23 个有明确职责的命令，而不是让模型一次完成所有事情；
• 使用 PRODUCT.md 和 DESIGN.md 保存受众、品牌语气、颜色、字体、组件和禁用风格；
• 用确定性检测器查找可定位到文件与行号的问题，不必所有检查都交给大模型判断；
• 可以在浏览器里选择真实元素、生成多个方案，并把选中的修改写回源代码。

Impeccable 最早建立在 Anthropic 的 frontend-design Skill 思路上，后来扩展成了独立项目。它不是 Anthropic、OpenAI 或 Apple 的官方产品拾光网。

它为什么专门反对“AI 网页味”

模型会优先选择训练数据中最常见、最容易组合、风险最低的视觉答案。早期常见的是紫色渐变、毛玻璃和发光球体；新一轮模板则换成暖米色背景、超大衬线标题、细边框配大阴影、编号章节和重复的功能卡片。单独使用其中一种手法没有错，问题是模型在不了解产品的情况下反复使用同一套答案。

Impeccable 将这些模式称为 slop。它的规则覆盖视觉细节、字体、颜色与对比度、布局、动效、文案、图片和通用品质。常见检查包括：

• 卡片嵌套、单侧粗色条、过大的圆角和无意义毛玻璃；
• 标题与正文尺寸过于接近、所有内容只用一种字体、超大长句标题；
• 紫蓝渐变、深色霓虹、渐变文字、彩色背景上的灰色低对比文字；
• 整页使用同一种间距、重复的等宽卡片网格、没有顺序却硬加 01/02/03；
• 弹跳动画、对宽高和边距做动画、图片悬停时机械放大；
• “赋能”“世界级”“全面提升”等空泛文案，以及破折号和口号式短句滥用；
• 图片地址为空、内容溢出、文字贴边、低于 WCAG AA 的对比度。

当前 Slop 目录共列出 46 项规则：41 项可由 CLI 或浏览器确定性执行，5 项需要 /impeccable critique 的 LLM 评审。其中 4 项模型特征规则默认关闭，需要使用 –gpt 或 –gemini 参数开启。版本更新后规则数量可能变化，使用时以当前安装版本的检测输出为准。

23 个命令分别做什么

这 23 个命令被分为创建、评估、细化、简化、加固和系统六组。分类的意义在于缩小每次任务的范围，减少模型一边重构、一边换配色、又顺手改文案造成的失控拾光网。

创建：先想清楚，再写代码

• craft：从设计方向到代码实现的完整流程；
• shape：先梳理需求、用户路径和界面方案，不急着编码；
• impeccable：用自然语言描述任务，或让系统推荐下一步。

评估：把审美意见和技术问题分开

• critique：从层级、清晰度、情绪、角色场景等角度做设计评审；
• audit：检查无障碍、响应式、性能和实现质量，并按 P0 至 P3 标记严重程度。

critique 更接近设计师评图，允许讨论风格与感受；audit 更像工程验收，重点是可以复现和修复的问题。两者不能互相替代。

细化：只改需要改的维度

• animate：增加表达状态变化的动效，而不是装饰性乱动；
• bolder：增强层级、比例与表现力；
• quieter：降低过度强调、阴影和视觉噪声；
• colorize：为单调页面加入有目的的颜色；
• typeset：修正字体选择、字号、行高和层级；
• layout：调整布局、间距和视觉节奏；
• delight：添加少量个性化反馈；
• overdrive：处理着色器、物理效果和电影式转场等高强度表现。

简化：处理复杂与含糊

• adapt：适配不同屏幕、设备和使用环境；
• clarify：改写看不懂或容易误解的界面文案；
• distill：删除不必要的元素，把页面收束到核心任务。

加固：让演示页面可以真正上线

• harden：补齐错误状态、长文本、国际化和边界情况；
• onboard：设计首次使用、空状态和激活路径；
• optimize：检查 LCP、资源体积和界面性能；
• polish：发布前统一设计系统并做最后一轮整理。

系统：让设计规则可以沉淀

• init：建立项目上下文；
• document：从现有项目生成 DESIGN.md；
• extract：把重复样式和组件抽取到设计系统；
• live：在浏览器中选择元素、生成变体并写回源码。

官方文档把 live 计入系统命令，完整命令表总数仍为 23。实际使用时不必记住全部名称，输入 /impeccable 可以查看菜单或获得下一步建议。

PRODUCT.md 和 DESIGN.md 为什么重要

多数 AI 网页趋同，并不是模型完全不会设计，而是任务没有提供足够上下文。只告诉模型“做一个 SaaS 首页”，它只能从平均答案开始。

运行 /impeccable init 后，系统会先判断当前页面属于哪一种工作模式：

• Brand：营销网站、活动页、作品集，页面本身需要形成印象；
• Product：后台、应用、工作流工具，设计首先服务于完成任务。

随后它会询问具体受众、品牌语气、视觉参照和明确不想要的风格，并将结果写入 PRODUCT.md。现有项目还可以生成 DESIGN.md，记录颜色、字体、圆角、组件和其他视觉约束。

以后每次运行命令，Impeccable 都会读取这些文件。这样，“让页面更大胆”不再等于擅自增加新渐变，而是先在已有颜色、组件和排版系统内提高层级与比例。团队也能把这两个文件纳入版本控制，让不同成员和不同 AI 工具遵守同一套设计条件。

不要在这些文件中写入 API Key、客户隐私或内部密码。它们是项目设计文档，不是密钥存储。

安装前需要准备什么

当前官方安装器要求 Node.js 22.12 或更高版本。支持的工具包括 Codex CLI、Claude Code、Cursor、GitHub Copilot、Gemini CLI、OpenCode、Pi、Grok Build、Trae、Qoder 和 Rovo Dev 等。

推荐从项目根目录执行：

npx impeccable install

安装器会识别当前项目使用的 AI 编程工具，并询问安装到项目还是全局。项目级安装更适合正式开发：规则可以随仓库版本管理，不同项目也能使用不同版本。

需要在脚本中明确指定 Codex，并避免交互式选择时，可以运行：

npx impeccable install –providers=codex –scope=project

同时安装 Codex、Claude Code 和 Cursor：

npx impeccable install –providers=codex,claude,cursor –scope=project

安装完成后重启 AI 编程工具，再执行：

/impeccable init

检查版本和更新：

npx impeccable check
npx impeccable update

重新安装可使用：

npx impeccable install –force

在 Codex 中怎样调用

Codex 对 Skill 的入口与 Claude Code 不完全相同。官方 FAQ 特别说明：Impeccable 不一定出现在普通的斜杠命令菜单中。可以打开 /skills，或者输入 $ 查找 Skill；需要明确触发时，可在任务里写“使用 impeccable skill”。

项目级 Skill 通常位于：

.agents/skills/

用户级安装通常位于：

~/.agents/skills/

Impeccable 还可以为 Codex 安装项目级设计 Hook。安装或更新后打开：

/hooks

检查并批准项目 Hook。它会在 AI 修改界面文件后运行检测，把新发现的问题反馈给 Codex。Hook 定义更新后，Codex 可能要求重新批准，这是正常的信任机制，不应通过关闭安全检查来绕过。

一个适合现有项目的 Codex 工作流如下：

1. 使用 impeccable skill 初始化当前项目，
先读取现有组件、设计令牌和目标用户，不修改代码。

2. 使用 impeccable audit 检查结账页，
按 P0-P3 列出问题和文件位置。

3. 只修复 P0、P1 问题，保留现有组件 API。

4. 使用 impeccable polish 做发布前整理，
不新增颜色、字体和卡片样式。

5. 运行确定性检测和项目测试，
展示 git diff 后再结束。

这里最重要的不是命令名称，而是限制修改范围。已有设计系统时，应明确要求先读取并保留现有 Token、组件和交互约定。

Claude Code、Cursor 等工具怎么装

Claude Code 可以直接使用推荐安装器，也可以从插件市场安装：

/plugin marketplace add pbakaus/impeccable

添加市场后，再从 /plugin 菜单安装 Impeccable。插件用户也通过该菜单更新。

通用 Skills CLI 仍然可用：

npx skills add pbakaus/impeccable

但官方说明，这种方式安装的是所有工具共用的通用构建，不包含针对特定编程工具编译的命令路径和原生 Hook。能用，但不如 npx impeccable install 完整。

Cursor 目前需要 Nightly 频道，并在 Settings → Rules 中开启 Agent Skills；Gemini CLI 则需要预览版并在设置中开启 Skills。具体要求变化较快，应以官方 Getting Started 和 FAQ 为准。

怎样使用反模板化检测器

只运行静态检查时，不需要大模型 API Key：

npx impeccable detect src/

命令会返回文件、行号、规则名称和退出码，因此可以加入 CI 或 Pull Request 检查。只检查字体或布局：

npx impeccable detect src/ –scope type
npx impeccable detect src/ –scope layout

检查 GPT/Codex 常见特征：

npx impeccable detect src/ –gpt

这类规则可能出现误报。例如，地图、测量工具或蓝图界面使用网格背景有明确业务意义，不应该因为“Codex 常用网格”就机械删除。Impeccable 支持规则、文件和值级别的忽略配置，但每个例外都应写清楚原因，而不是为了让 CI 变绿而全部关闭。

Live Mode 能做什么

/impeccable live 目前仍是 Beta。它允许你在本地运行的网页中选择一个真实元素，添加“更克制”“标题更有力量”等方向，生成多个变体，再接受其中一个。接受后，修改会通过框架的热更新写回实际源文件，而不是停留在无法复用的截图或临时原型中。

它适合快速比较文案、排版和局部结构，但不应该跳过代码审查。接受变体后仍要查看 git diff、运行测试，并确认没有破坏组件复用、响应式布局和无障碍语义。

和 frontend-design、Apple Design Skill 有什么区别

三者并非必须三选一。需要精细手势时，可以让 Apple Design Skill 负责运动原则，让 Impeccable 负责整体设计上下文与发布前审查。但规则同时加载过多时也可能互相冲突，最好明确优先级：现有产品设计系统优先，其次是任务专用 Skill，最后才是通用风格建议。

它的局限

规则会过时。今天被识别为 AI 网页套路的米色背景、衬线标题和网格线，本来都是正常设计手段。问题在于无差别滥用，而不是这些元素天然错误。

检测不等于设计。消除紫色渐变、卡片嵌套和低对比文字，只能减少常见问题。产品定位、用户研究、信息架构和品牌判断仍需要人来负责。

LLM 评审仍可能不稳定。critique 依赖当前 AI 工具的模型与上下文，同一页面可能得到不同意见。确定性 CLI 适合做门禁，主观评审适合提供候选意见，两者要分开看。

Live Mode 仍在测试阶段。复杂框架、状态管理和非标准构建流程可能影响预览或写回。正式项目中必须先提交当前代码，保留可回退点。

安装要求较新。当前 CLI 需要 Node.js 22.12+。旧项目不必为此直接升级生产运行时，可以使用版本管理工具，为 Impeccable CLI 单独准备兼容的 Node 环境。

是否值得安装

如果你经常让 Codex、Claude Code 或 Cursor 直接生成和修改前端，Impeccable 值得试。它的强项不是替你决定什么叫“好看”，而是把含糊的设计意见拆成可以执行、检查和回滚的任务。

第一次使用不必一次跑完 23 个命令。先完成三步就够了：

npx impeccable install
/impeccable init
/impeccable polish the page you care about

然后再运行 npx impeccable detect src/，查看它指出的问题是否符合当前产品语境。能解释、能验证、能安全写回代码，才是这套 Skill 比“帮我把页面做高级一点”更有价值的地方。

资料来源

• Impeccable 官方网站
• Impeccable 命令文档
• 官方安装与入门教程
• Slop 检测规则目录
• 官方 FAQ
• pbakaus/impeccable GitHub 仓库
• 文章配图：Daniil Komov / Pexels