面向 AI Coding Agent 的设计指引。包含 1 项技能、24 条指令、实时浏览器迭代，以及 62 条针对 AI 生成前端设计的确定性检测规则。

快速上手： 在项目根目录下运行 npx impeccable install，然后在你的 AI 编程工具中执行 /impeccable init。完整文档参见：impeccable.style。

Anthropic 推出的 frontend-design 是 Claude 首个被广泛使用的设计技能（Skill），Impeccable 正是从这里起步的。

目前所有模型都是在相同的 SaaS 模板上进行训练的。如果缺少有效的设计指导，你在每个项目里都会看到那几样熟悉的通病：所有地方都用 Inter 字体、紫蓝渐变色、卡片套卡片、有色背景上的灰色文字，以及每个标题上方都带有一个圆角矩形图标块。

Impeccable 补充了以下能力：

• 统一设置流程。 /impeccable init 会将长效的产品事实记录在 PRODUCT.md 中，使后续指令明确受众、目标、运行上下文、约束条件、语调风格和事实依据，而不会将这些事实与表层的视觉方向混为一谈。
• 24 条指令。 与你的 AI 建立统一的设计词汇表：polish、audit、critique、distill、animate、bolder、quieter 等。
• 62 条确定性检测规则外加仅限 LLM 的评审检查项。CLI 与浏览器扩展可在脱离 LLM 且无需 API Key 的情况下直接运行这些确定性规则。

该技能以单个命令形式安装：

bash /impeccable

每个新项目都建议以此开始：

init 会检查项目，仅针对长效产品事实中实质性的缺失进行提问，并生成 PRODUCT.md。访客模式和视觉方向可在后续针对各个界面单独选择；既有或新建的视觉规范系统则单独记录在 DESIGN.md 中。

所有指令均通过 /impeccable 访问：

指令	功能说明
/impeccable craft	完整的“定型-构建”全流程，并支持视觉迭代
/impeccable init	一次性初始化配置：收集持久化产品上下文，写入 PRODUCT.md，在适用时配置实时模式，推荐后续步骤
/impeccable document	从现有项目代码生成根目录 DESIGN.md
/impeccable extract	将可复用组件和设计令牌（Tokens）提取到设计系统中
/impeccable shape	在编写代码前规划 UX/UI
/impeccable critique	UX 设计评审：层级、清晰度、情感共鸣
/impeccable audit	运行技术质量检查（无障碍 a11y、性能、响应式）
/impeccable polish	最终质检验收、设计系统对齐以及发布就绪检查
/impeccable bolder	增强平淡乏味的设计
/impeccable quieter	缓和过于张扬夸张的设计
/impeccable distill	删繁就简，提炼核心本质
/impeccable harden	错误处理、国际化（i18n）、文本溢出与边缘用例加固
/impeccable onboard	新手引导流程、空状态与激活转化路径
/impeccable animate	添加有明确目的与意义的动效
/impeccable colorize	引入策略性配色
/impeccable typeset	修正字体选择、排版层级与字号大小
/impeccable layout	调整布局、间距与视觉韵律
/impeccable delight	添加令人惊喜的愉悦细节
/impeccable overdrive	添加技术上令人惊艳的特效
/impeccable clarify	改进含义模糊的 UX 文案
/impeccable adapt	针对不同设备进行适配
/impeccable optimize	性能优化
/impeccable live	视觉变体模式：在浏览器中直接对元素进行交互式迭代
/impeccable generate	在实时浏览器中生成指定元素的多个变体，无需手动挑选

使用 /impeccable pin <command> 可创建独立快捷指令（例如 pin audit 会创建 /audit）。

bash /impeccable audit blog # 审计博客聚合页 + 文章页面 /impeccable critique landing # UX 设计评审 /impeccable polish settings # 交付前的最后润色 /impeccable harden checkout # 补充错误处理与边缘情况

也可以直接用自然语言描述来调用 /impeccable：

bash /impeccable redo this hero section

该技能包含关于应当避免什么的明确指引：

• 不要使用泛滥成灾的字体（Arial、Inter、系统默认字体）
• 不要在有色背景上使用灰色文字
• 不要使用纯黑/纯灰（始终使用带色彩倾向的色调）
• 不要把所有内容都套进卡片，也不要在卡片中嵌套卡片
• 不要使用弹跳/弹性缓动函数（显得过时老套）

访问 Neo Mirai 案例研究 查看真实项目在经过 Impeccable 指令改造前后的对比案例。

该 Skill 本身无需独立的运行时。每个技能副本都附带一个小型的启动脚本（scripts/impeccable，Windows 平台为 impeccable.cmd），用于运行 Impeccable 引擎。这是一个自包含的二进制文件，要么存放在启动脚本同级目录下，要么在首次运行时自动下载到 ~/.impeccable/bin/。只有在通过 npx impeccable 安装器时才会用到 Node，而该安装器本身也是基于相同二进制文件的包装层；下方的手动安装和 Git 安装方式则无需 Node 环境。

方案 1：CLI 安装器（推荐）

在项目根目录下运行安装命令（如 npx impeccable install）：

这会显示其检测到的工具宿主目录或已安装的 CLI（例如 ~/.claude、~/.codex、~/.grok、~/.hermes、~/.veto，或者项目本地的 .cursor），允许你保留检测到的配置或自定义 Provider，然后询问是安装到当前项目还是全局安装。在脚本中可通过 --providers=claude,codex,replit,cursor,grok,hermes,veto 和 --scope=project|global 跳过这些交互选择。在 Claude Code、Cursor、Codex、GitHub Copilot 和 Grok Build 上，它还会为当前项目安装 Provider 原生 Hook 清单。Veto 会在 ~/.veto/skills/ 下接收打包好的技能，且不运行原生 Impeccable 编辑 Hook。兼容 Cursor、Claude Code、Gemini CLI、Codex CLI、Replit Agent、Grok Build、Hermes Agent、Veto 以及所有其他受支持的工具。安装完成后重新加载宿主环境即可。

若要刷新现有安装，请运行对应更新命令。

Codex 用户在安装或更新后应打开 /hooks，并在提示时批准项目 Hook。Codex 通过 Hook 定义来跟踪信任状态，因此修改 .codex/hooks.json 的更新可能需要重新授权。Grok Build 用户在运行 .grok/hooks/ 脚本前需要对项目文件夹进行信任授权（运行 /hooks-trust 或在启动时添加 --trust）。

有关特定宿主工具的信任与验证步骤，请参见在你的 Harness 中允许 Hook。

对于希望通过 Git 对 Impeccable 进行集中管理与更新的团队，可将该仓库添加为子模块，并将编译后的 Provider 产物软链接到你的宿主目录中：

bash git submodule add https://github.com/pbakaus/impeccable .impeccable npx impeccable link --source=.impeccable --providers=claude,cursor git add .gitmodules .impeccable .claude .cursor git commit -m "Add Impeccable skills"

选用你项目需要的 Provider，例如 claude、cursor、gemini、codex、github、grok、devin、hermes、opencode、pi、qoder、trae、trae-cn、rovo-dev、vibe 或 veto。该命令会从 .impeccable/dist/universal/ 链接各个独立的 Skill 目录，除非传入 --force，否则不会覆盖既有的真实技能目录。

后续更新方式：

bash git submodule update --remote .impeccable npx impeccable link --source=.impeccable --providers=claude,cursor

VS Code 中的 GitHub Copilot：

从 Visual Studio Marketplace 安装 Impeccable，或者运行：

bash code --install-extension renaissance-geek.impeccable

需要 VS Code 1.109.3+、Copilot Chat 权限以及受信任的本地工作区。在 Agent 模式下打开 Chat 并尝试输入 /impeccable polish。此纯技能扩展不会安装自动 Hook；请避免在同一工作区/配置文件中安装重复的 Impeccable 技能。详见 VS Code 分发细节。

Claude Code：

bash /plugin marketplace add pbakaus/impeccable

仅限 Claude Code。添加 Marketplace 后，打开 /plugin 并从列表中安装 Impeccable。

Grok Build：

bash grok plugin install pbakaus/impeccable#plugin --trust

仅限 Grok Build。#plugin 后缀用于安装精简插件包（包含 Skills、Agents 和 Hooks），而非整个 monorepo。然后在 Grok 会话中运行 /impeccable init。通过 npx impeccable install --providers=grok 进行项目级安装同样可行，会写入 .grok/skills/ 与 .grok/hooks/impeccable.json。

方案 4：从官网下载

访问 impeccable.style，下载对应工具的 ZIP 压缩包并解压至你的项目。

方案 5：从代码仓库手动复制

Cursor：

bash cp -r dist/cursor/.cursor your-project/

注意： Cursor 技能需要进行配置：

1. 在 Cursor 设置 → Beta 中切换至 Nightly 通道
2. 在 Cursor 设置 → Rules 中启用 Agent Skills

了解更多关于 Cursor skills 的信息

Claude Code：

bash

项目专属

cp -r dist/claude-code/.claude your-project/

或全局安装（适用于所有项目）

cp -r dist/claude-code/.claude/* ~/.claude/

OpenCode：

bash cp -r dist/opencode/.opencode your-project/

DeepSeek Harness：

bash

项目专属

cp -r dist/dsh/.dsh your-project/

或全局安装（适用于所有项目）

mkdir -p "${DSH_HOME:-$HOME/.dsh}/skills" cp -r dist/dsh/.dsh/skills/* "${DSH_HOME:-$HOME/.dsh}/skills/"

CLI 仅在 DSH_HOME 解析为你家目录内部（或家目录本身）时才会认可该环境变量；否则将使用 ~/.dsh。位于家目录之外的手动复制无法通过 impeccable install/update 进行管理。

Devin：

bash

项目专属（Devin 网页版、CLI 和桌面版均读取 .devin/skills/）

cp -r dist/devin/.devin your-project/

或全局安装（Devin CLI 和桌面版；Windows 下请使用 %APPDATA%\devin\skills）

mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/devin/skills" cp -r dist/devin/.devin/skills/* "${XDG_CONFIG_HOME:-$HOME/.config}/devin/skills/"

Hermes Agent：

bash

全局安装（适用于所有项目；使用当前活动 profile，默认为 ~/.hermes）

cp -r dist/hermes/.hermes/skills/* "${HERMES_HOME:-$HOME/.hermes}/skills/"

或项目专属

cp -r dist/hermes/.hermes your-project/

注意： Hermes 对项目本地技能设有逐仓库信任决策机制（由于技能属于操作规程文档，因此自动加载来自任意克隆仓库的技能被视为一种 Prompt 注入风险矢量）。完成项目级安装后，请在项目根目录下执行一次 hermes skills trust。安装到当前 $HERMES_HOME/skills/（未设置时默认为 ~/.hermes/skills/）的全局技能无需信任步骤即可直接加载。之后 /impeccable <command> 将通过技能的 Commands 表进行路由；设计 Hook 不会安装在 Hermes 上（因其缺乏 Hook 扩展面）。

了解更多关于 Hermes skills 的信息

Pi：

bash cp -r dist/pi/.pi your-project/

Gemini CLI：

bash cp -r dist/gemini/.gemini your-project/

注意： Gemini CLI 技能需要进行配置：

1. 安装预览版：npm i -g @google/gemini-cli@preview
2. 运行 /settings 并启用 "Skills"
3. 运行 /skills list 验证安装

了解更多关于 Gemini CLI skills 的信息

Codex CLI：

bash

项目本地

cp -r dist/agents/.agents your-project/ mkdir -p your-project/.codex cp dist/codex/.codex/hooks.json your-project/.codex/hooks.json

或在用户全局范围安装技能。将 .codex/hooks.json 复制到希望运行设计 Hook 的各个项目中。

mkdir -p ~/.agents/skills cp -r dist/agents/.agents/skills/* ~/.agents/skills/

资源生产子 Agent（asset-producer subagent）直接嵌套在技能自身的 agents/ 目录下提供，Codex 会自动发现该目录，无需单独复制 .codex/agents/。Hook 采用项目本地配置，因为 Codex 是从受信任项目配置旁的 .codex/hooks.json 中发现 Hook 的。

GitHub Copilot：

bash cp -r dist/github/.github your-project/

Trae：

bash

Trae 国内版（国内特供版）

cp -r dist/trae/.trae-cn/skills/* ~/.trae-cn/skills/

Trae 国际版

cp -r dist/trae/.trae/skills/* ~/.trae/skills/

注意： Trae 有两个版本，其配置目录不同：

• Trae 国内版：~/.trae-cn/skills/
• Trae 国际版：~/.trae/skills/

复制完成后，重启 Trae IDE 即可激活技能。

Rovo Dev：

bash

项目专属

cp -r dist/rovo-dev/.rovodev your-project/

或全局安装（适用于所有项目）

cp -r dist/rovo-dev/.rovodev/skills/* ~/.rovodev/skills/

Qoder：

bash

项目专属

cp -r dist/qoder/.qoder your-project/

或全局安装（适用于所有项目）

cp -r dist/qoder/.qoder/skills/* ~/.qoder/skills/

Mistral Vibe：

bash

项目专属

cp -r dist/vibe/.vibe your-project/

或全局安装（适用于所有项目）

cp -r dist/vibe/.vibe/skills/* ~/.vibe/skills/

Grok Build：

bash

项目专属

cp -r dist/grok/.grok your-project/

或全局安装（适用于所有项目）

cp -r dist/grok/.grok/skills/* ~/.grok/skills/

推荐使用 npx impeccable install --providers=grok 或 grok plugin install pbakaus/impeccable#plugin --trust，以便同时安装设计 Hook。项目 Hook 需要针对每个文件夹执行一次 /hooks-trust（或启动时传入 --trust）。

Google Antigravity：

bash

项目专属

cp -r dist/antigravity/.agent your-project/

或全局安装（适用于所有项目）

mkdir -p ~/.gemini/config/skills cp -r dist/antigravity/.agent/skills/* ~/.gemini/config/skills/

安装完成后，所有命令均通过单个 /impeccable 技能运行：

bash /impeccable audit # 查找问题 /impeccable polish # 最终清理与润色 /impeccable distill # 提炼精简

Design guidance for AI coding agents. 1 skill, 24 commands, live browser iteration, and 62 deterministic detector rules for AI-generated frontend design.

Quick start: From your project root, run npx impeccable install, then run /impeccable init inside your AI coding tool. Full docs: impeccable.style.

Anthropic's frontend-design was the first widely-used design skill for Claude. Impeccable started from there.

Every model trained on the same SaaS templates. Skip the guidance and you get the same handful of tells on every project: Inter for everything, purple-to-blue gradients, cards nested in cards, gray text on colored backgrounds, the rounded-square icon tile above every heading.

Impeccable adds:

• One setup flow. /impeccable init records durable product truth in PRODUCT.md, so later commands know the audience, purpose, operating context, constraints, voice, and evidence without confusing those facts with surface-level visual direction.
• 24 commands. A shared design vocabulary with your AI: polish, audit, critique, distill, animate, bolder, quieter, and more.
• 62 deterministic detector rules plus LLM-only critique checks. The CLI and browser extension run the deterministic rules with no LLM and no API key.

The skill installs as one command:

/impeccable <command> <target>

Start every new project with:

init inspects the project, asks only for material gaps in durable product truth, and writes PRODUCT.md. Visitor mode and visual direction are chosen later for each surface; incumbent or newly built visual systems are recorded separately in DESIGN.md.

All commands are accessed through /impeccable:

Command	What it does
/impeccable craft	Full shape-then-build flow with visual iteration
/impeccable init	One-time setup: gather durable product context, write PRODUCT.md, configure live mode when applicable, recommend next steps
/impeccable document	Generate root DESIGN.md from existing project code
/impeccable extract	Pull reusable components and tokens into the design system
/impeccable shape	Plan UX/UI before writing code
/impeccable critique	UX design review: hierarchy, clarity, emotional resonance
/impeccable audit	Run technical quality checks (a11y, performance, responsive)
/impeccable polish	Final pass, design system alignment, and shipping readiness
/impeccable bolder	Amplify boring designs
/impeccable quieter	Tone down overly bold designs
/impeccable distill	Strip to essence
/impeccable harden	Error handling, i18n, text overflow, edge cases
/impeccable onboard	First-run flows, empty states, activation paths
/impeccable animate	Add purposeful motion
/impeccable colorize	Introduce strategic color
/impeccable typeset	Fix font choices, hierarchy, sizing
/impeccable layout	Fix layout, spacing, visual rhythm
/impeccable delight	Add moments of joy
/impeccable overdrive	Add technically extraordinary effects
/impeccable clarify	Improve unclear UX copy
/impeccable adapt	Adapt for different devices
/impeccable optimize	Performance improvements
/impeccable live	Visual variant mode: iterate on elements in the browser
/impeccable generate	Generate variants of a named element in the live browser, no manual picking

Use /impeccable pin <command> to create standalone shortcuts (e.g., pin audit creates /audit).

/impeccable audit blog           # Audit blog hub + post pages
/impeccable critique landing     # UX design review
/impeccable polish settings      # Final pass before shipping
/impeccable harden checkout      # Add error handling + edge cases

Or use /impeccable directly with a description:

/impeccable redo this hero section

The skill includes explicit guidance on what to avoid:

• Don't use overused fonts (Arial, Inter, system defaults)
• Don't use gray text on colored backgrounds
• Don't use pure black/gray (always tint)
• Don't wrap everything in cards or nest cards inside cards
• Don't use bounce/elastic easing (feels dated)

Visit the Neo Mirai case study to see a before/after case study of a real project transformed with Impeccable commands.

The skill needs no runtime of its own. Every skill copy ships a small launcher (scripts/impeccable, plus impeccable.cmd for Windows) that runs the Impeccable engine, a self-contained binary that either sits next to the launcher or is downloaded once on first run into ~/.impeccable/bin/. Node is only involved if you use the npx impeccable installer, which is a shim around the same binary; the manual and Git options below work without it.

Option 1: CLI installer (Recommended)

From the root of your project, run:

This shows the harness folders or installed CLIs it detected (for example ~/.claude, ~/.codex, ~/.grok, ~/.hermes, ~/.veto, or project-local .cursor), lets you keep the detected set or customize providers, then asks whether to install into the current project or globally. Use --providers=claude,codex,replit,cursor,grok,hermes,veto and --scope=project|global to skip those choices in scripts. On Claude Code, Cursor, Codex, GitHub Copilot, and Grok Build, it also installs the provider-native hook manifest for the current project. Veto receives the packaged skill under ~/.veto/skills/ and does not run native Impeccable edit hooks. Works with Cursor, Claude Code, Gemini CLI, Codex CLI, Replit Agent, Grok Build, Hermes Agent, Veto, and every other supported tool. Reload your harness afterward.

To refresh an existing install, run:

Codex users should open /hooks after install or update and approve the project hook when prompted. Codex tracks trust by hook definition, so updates that change .codex/hooks.json can require approval again. Grok Build users need project folder trust (/hooks-trust or launch with --trust) before .grok/hooks/ scripts run.

See Allow the hook in your harness for harness-specific trust and verification steps.

For teams that want to keep Impeccable vendored and updated through Git, add this repo as a submodule and link the compiled provider build into your harness folders:

git submodule add https://github.com/pbakaus/impeccable .impeccable
npx impeccable link --source=.impeccable --providers=claude,cursor
git add .gitmodules .impeccable .claude .cursor
git commit -m "Add Impeccable skills"

Use the providers your project needs, for example claude, cursor, gemini, codex, github, grok, devin, hermes, opencode, pi, qoder, trae, trae-cn, rovo-dev, vibe, or veto. The command links individual skill folders from .impeccable/dist/universal/ and leaves existing real skill directories untouched unless you pass --force.

To update later:

git submodule update --remote .impeccable
npx impeccable link --source=.impeccable --providers=claude,cursor

GitHub Copilot in VS Code:

Install Impeccable from the Visual Studio Marketplace, or run:

code --install-extension renaissance-geek.impeccable

Requires VS Code 1.109.3+, Copilot Chat access, and a trusted local workspace. Open Chat in Agent mode and try /impeccable polish. This skill-only extension does not install automatic hooks; avoid a duplicate Impeccable skill in the same workspace/profile. See VS Code distribution details.

Claude Code:

/plugin marketplace add pbakaus/impeccable

Claude Code only. After adding the marketplace, open /plugin and install Impeccable from the list.

Grok Build:

grok plugin install pbakaus/impeccable#plugin --trust

Grok Build only. The #plugin suffix installs the slim plugin package (skills, agents, and hooks) instead of the full monorepo. Then run /impeccable init in a Grok session. Project-scoped installs via npx impeccable install --providers=grok also work and write .grok/skills/ plus .grok/hooks/impeccable.json.

Option 4: Download from Website

Visit impeccable.style, download the ZIP for your tool, and extract to your project.

Option 5: Copy from Repository

Cursor:

cp -r dist/cursor/.cursor your-project/

Note: Cursor skills require setup:

1. Switch to Nightly channel in Cursor Settings → Beta
2. Enable Agent Skills in Cursor Settings → Rules

Learn more about Cursor skills

Claude Code:

# Project-specific
cp -r dist/claude-code/.claude your-project/

# Or global (applies to all projects)
cp -r dist/claude-code/.claude/* ~/.claude/

OpenCode:

cp -r dist/opencode/.opencode your-project/

DeepSeek Harness:

# Project-specific
cp -r dist/dsh/.dsh your-project/

# Or global (applies to all projects)
mkdir -p "${DSH_HOME:-$HOME/.dsh}/skills"
cp -r dist/dsh/.dsh/skills/* "${DSH_HOME:-$HOME/.dsh}/skills/"

The CLI honors DSH_HOME only when it resolves inside your home directory (or to home itself); otherwise it uses ~/.dsh. An outside-home manual copy is not managed by impeccable install/update.

Devin:

# Project-specific (Devin web, CLI, and Desktop all read .devin/skills/)
cp -r dist/devin/.devin your-project/

# Or global (Devin CLI and Desktop; use %APPDATA%\devin\skills on Windows)
mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/devin/skills"
cp -r dist/devin/.devin/skills/* "${XDG_CONFIG_HOME:-$HOME/.config}/devin/skills/"

Hermes Agent:

# Global (applies to all projects; uses the active profile, or ~/.hermes by default)
cp -r dist/hermes/.hermes/skills/* "${HERMES_HOME:-$HOME/.hermes}/skills/"

# Or project-specific
cp -r dist/hermes/.hermes your-project/

Note: Hermes gates project-local skills behind a per-repo trust decision (they are procedure documents, so auto-loading them from any cloned repo is treated as a prompt-injection vector). After a project-scoped install, run hermes skills trust once from the project root. Global installs into the active $HERMES_HOME/skills/ (or ~/.hermes/skills/ when unset) load without a trust step. /impeccable <command> then routes through the skill's Commands table; the design hook does not install on Hermes (no hook surface).

Learn more about Hermes skills

Pi:

cp -r dist/pi/.pi your-project/

Gemini CLI:

cp -r dist/gemini/.gemini your-project/

Note: Gemini CLI skills require setup:

1. Install preview version: npm i -g @google/gemini-cli@preview
2. Run /settings and enable "Skills"
3. Run /skills list to verify installation

Learn more about Gemini CLI skills

Codex CLI:

# Project-local
cp -r dist/agents/.agents your-project/
mkdir -p your-project/.codex
cp dist/codex/.codex/hooks.json your-project/.codex/hooks.json

# Or install the skill user-wide. Copy .codex/hooks.json into each project
# where you want the design hook to run.
mkdir -p ~/.agents/skills
cp -r dist/agents/.agents/skills/* ~/.agents/skills/

The asset-producer subagent ships nested inside the skill's own agents/ folder, which Codex auto-discovers. No separate .codex/agents/ copy is needed. The hook is project-local because Codex discovers hooks from .codex/hooks.json next to trusted project config.

GitHub Copilot:

cp -r dist/github/.github your-project/

Trae:

# Trae China (domestic version)
cp -r dist/trae/.trae-cn/skills/* ~/.trae-cn/skills/

# Trae International
cp -r dist/trae/.trae/skills/* ~/.trae/skills/

Note: Trae has two versions with different config directories:

• Trae China : ~/.trae-cn/skills/
• Trae International : ~/.trae/skills/

After copying, restart Trae IDE to activate the skills.

Rovo Dev:

# Project-specific
cp -r dist/rovo-dev/.rovodev your-project/

# Or global (applies to all projects)
cp -r dist/rovo-dev/.rovodev/skills/* ~/.rovodev/skills/

Qoder:

# Project-specific
cp -r dist/qoder/.qoder your-project/

# Or global (applies to all projects)
cp -r dist/qoder/.qoder/skills/* ~/.qoder/skills/

Mistral Vibe:

# Project-specific
cp -r dist/vibe/.vibe your-project/

# Or global (applies to all projects)
cp -r dist/vibe/.vibe/skills/* ~/.vibe/skills/

Grok Build:

# Project-specific
cp -r dist/grok/.grok your-project/

# Or global (applies to all projects)
cp -r dist/grok/.grok/skills/* ~/.grok/skills/

Prefer npx impeccable install --providers=grok or grok plugin install pbakaus/impeccable#plugin --trust so the design hook installs too. Project hooks need /hooks-trust (or --trust) once per folder.

Google Antigravity:

# Project-specific
cp -r dist/antigravity/.agent your-project/

# Or global (applies to all projects)
mkdir -p ~/.gemini/config/skills
cp -r dist/antigravity/.agent/skills/* ~/.gemini/config/skills/

Once installed, every command runs through the single /impeccable skill:

/impeccable audit        # Find issues
/impeccable polish       # Final cleanup
/impeccable distill      # Remove complexity
/impeccable critique     # Full design review

Type /impeccable alone to see the full command list.

Most commands accept an optional argument to focus on a specific area:

/impeccable audit the header
/impeccable polish the checkout form

If you reach for one command often, pin it with /impeccable pin audit to get /audit as a standalone shortcut.

Note: Codex uses skills here, not /prompts: commands. Open /skills or type $impeccable. Repo-local installs live in .agents/skills/; user-wide installs live in ~/.agents/skills/. GitHub Copilot uses .github/skills/. Restart the tool if a newly installed skill does not appear.

Keeping .impeccable out of git

As you run commands, Impeccable writes working files under .impeccable/: critique and polish screenshots, live-mode session and preview state, runtime caches, and per-developer config. Most of it is ephemeral and should not be committed, while a few files are shared project artifacts that belong in the repo. Add this block to your project's .gitignore:

# impeccable-ignore-start
# Ephemeral output, runtime state, and per-dev overrides.
# The **/ prefix covers .impeccable at the repo root or in a nested workspace.
# Shared artifacts stay tracked: config.json, live/config.json,
# design.json, surfaces/*.md, critique/*.md.
**/.impeccable/config.local.json
**/.impeccable/hook.cache.json
**/.impeccable/hook.pending.json
**/.impeccable/*.png
**/.impeccable/review/
**/.impeccable/questions/
**/.impeccable/live/server.json
**/.impeccable/live/sessions/
**/.impeccable/live/previews/
**/.impeccable/live/annotations/
**/.impeccable/live/cache/
**/.impeccable/live/manual-edit-apply-transaction.json
**/.impeccable/live/manual-edit-events.jsonl
**/.impeccable/live/manual-edit-evidence/
**/.impeccable/live/pending-manual-edits.json
**/.impeccable/live/deferred-svelte-component-accepts.json
**/.impeccable/live/*.png
# impeccable-ignore-end

The block is wrapped in # impeccable-ignore-start / # impeccable-ignore-end markers so you can recognize and refresh it later. The **/ prefix makes each pattern match whether the active project's .impeccable/ directory is at the repository root or under a nested workspace path like apps/web/.

Keep these tracked (they are shared project artifacts, do not add them to .gitignore):

• .impeccable/config.json (unified shared config)
• .impeccable/live/config.json (live-mode framework wiring)
• .impeccable/design.json (shared design spec)
• .impeccable/surfaces/*.md (route- or artifact-specific strategy and direction contracts)
• .impeccable/critique/*.md (review reports)

Impeccable also keeps its own .gitignore in the folders that hold decision-round state: .impeccable/questions/ and .impeccable/mocks/worlds/ ignore everything in them, and .impeccable/build/ ignores state.json. That keeps new runtime files out of commits even in a project without the block above. A .gitignore cannot untrack a file git already tracks, though: when one of these files was committed earlier, the next roll prints a one-time notice with the fix, git rm -r --cached .impeccable/questions (plus any other folder it names), and writes its roll record to an untracked file until then.

If an ephemeral file (a screenshot, config.local.json) was committed before you added the block, .gitignore will not untrack it automatically. Run git rm --cached <path> to stop tracking it without deleting your local copy.

When a new design starts, the skill asks the roll API at impeccable.style to deal a hand of visual worlds from the catalog. That request is the feature, so it always happens. Unless you opt out, it also feeds an anonymous record of which hand was shown and which card won, which is how the catalog learns what works.

What is sent, on the roll request and on the choice that follows it:

• the roll key (a random value per decision round), scope (direction or surface), visitor mode, and re-roll round
• the catalog revision the hand came from, and on the choice the kind of card that won (assigned, pick, challenger, canon, or a re-roll), its catalog id when a catalog world won, and its position on the page
• the client version, whether the choice came from the decision page or the agent, and a random id for that choice so a report sent twice is counted once

Never sent: your project's name, files, code, PRODUCT.md, or the names of the directions your agent wrote. Committed files such as surface briefs record only a seed reference, a hash of the roll key under a random salt kept in ~/.impeccable/seed-salt, never the key itself. If no salt can be kept on a machine, the brief records no seed at all rather than a weaker hash. Roll keys are 128 random bits. If you pass your own short key with --from, its reference is easy to guess, so do not rely on it to keep that key private.

To turn it off, run npx impeccable telemetry off (stored in ~/.impeccable/config.json), or set DO_NOT_TRACK=1 or IMPECCABLE_NO_TELEMETRY=1. A project can opt everyone out with "telemetry": false in .impeccable/config.json. npx impeccable telemetry status shows the current state. Opted out, the roll still works and the API is told not to record it. Details: https://impeccable.style/privacy

On Claude Code, GitHub Copilot, Codex, Cursor, and Grok Build, npx impeccable install and npx impeccable update install a provider-native hook manifest along with the skill payload. The hook runs the Impeccable design detector on direct UI file edits and surfaces findings back into the agent flow. Claude Code, GitHub Copilot, Codex, and Cursor surface findings after the edit (and run a deeper pass on Stop where supported). Grok Build scans after the edit to warm Stop, then surfaces on Stop; PostToolUse stdout never reaches the model.

Installed hook surfaces:

• Claude Code: .claude/settings.local.json (gitignored, machine-local) runs ${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/impeccable hook. A hook moved into the shared settings.json is honored in place.
• GitHub Copilot: .github/hooks/impeccable.json (committed, shared by the Copilot CLI and the cloud agent) runs .github/skills/impeccable/scripts/impeccable hook. The Copilot CLI activates it once the file is on the repository's default branch and the folder is trusted.
• Cursor: .cursor/hooks.json runs .cursor/skills/impeccable/scripts/impeccable hook on postToolUse for file writes. Projects set up with the older preToolUse write gate keep working; npx impeccable update moves them to the post-edit hook.
• Codex: .codex/hooks.json runs .agents/skills/impeccable/scripts/impeccable hook, with a commandWindows sibling that calls impeccable.cmd for cmd.exe.
• Grok Build: .grok/hooks/impeccable.json runs .grok/skills/impeccable/scripts/impeccable hook. Requires /hooks-trust or --trust. Findings reach the model on Stop, not after each edit.

Every command goes through the launcher shipped in the skill's scripts/ directory (impeccable, or impeccable.cmd on Windows), guarded so a missing launcher is a silent no-op. The launcher runs the engine binary that ships next to it, or downloads the pinned version once into ~/.impeccable/bin/. No Node or other runtime is required for the hook or the skill.

In Claude Code, installed command hooks run independently of model-tool approval. The first edit or Stop event can therefore download and cache the engine even if the session denies the model's launcher command. Review installed hooks before unattended runs; to disable all Claude Code hooks for a run, pass --settings '{"disableAllHooks": true}'. See Claude Code's hook security guidance.

The installer preserves unrelated hook entries and settings. If a hook manifest is malformed, install/update aborts by default; rerun with --force to back up the malformed file as .bak and replace it.

On an interactive install/update, Impeccable explains the hook and offers to install it (default yes). Your choice is remembered per-developer in the gitignored .impeccable/config.local.json, so you are not asked again; --no-hooks skips it for that run without recording anything. Hook lifecycle settings live under the hook key of .impeccable/config.json; detector ignores live under detector, shared by /impeccable hooks and npx impeccable detect.

For debugging, set hook.auditLog in .impeccable/config.json to a path (or the legacy IMPECCABLE_HOOK_LOG env var) to write one NDJSON line per hook invocation. Leave it unset for normal use.

Build path: comp-first or code-first

When a new surface gets designed, Impeccable either generates a full-fidelity comp first and builds to match it, or builds straight in code with the ambition written into a development-only direction contract in the surface brief and checked at the finish. Comp-first composes bolder and takes longer; code-first is leaner and faster. The choice covers landing pages and showcase surfaces. App screens and documents are built code-first either way, because they come out better built than pictured. /impeccable init asks once and records the answer as buildPath in .impeccable/config.json:

The values are comp and code, and nothing else is read. Set it in the gitignored .impeccable/config.local.json to override the team's committed value on one machine, which is what you want when your harness has no image generation. In a monorepo, commit it once at the repo root and any workspace that wants something else sets its own. The choice appears at all only where image generation is available, since without it there is nothing to comp.

You do not have to re-run init to set it on a project that predates the setting, and you do not have to edit the file by hand either. Whatever is recorded is a default rather than a lock: every decision page carries a footer toggle, and flipping it binds that session only. Flip it on a project that has recorded nothing and Impeccable asks once, after the round, whether to keep it, then writes your answer. That is the whole migration path for an existing project: use the toggle when the default is wrong, and answer the question that follows.

Codex requires one platform step that Impeccable cannot safely skip: open /hooks after install or update and approve the project hook. There is no Codex marketplace/plugin install flow for this hook.

Full hook docs: impeccable.style/docs/hooks.

The Stop pass suppresses confirmed pre-existing findings when a verified before-edit baseline is available (currently Claude Edit/Write results for text scans). Other findings are marked new or attribution unknown; unknown is not evidence that your session caused the problem. Explicit detect scans remain unchanged.

Manual copy commands are fallback/debug instructions. The normal path is:

npx impeccable install
npx impeccable update

Live mode and production sites

Live mode edits a local checkout through a development server or local static HTML. Injecting its localhost HTTP helper into a deployed production site, including an HTTPS site, is not supported. Do not disable browser security or weaken production CSP to make it work.

Use live mode only in projects you trust to run locally. Applying copy edits automatically runs package.json's optional scripts["impeccable:manual-edit-validate"] command in a shell, with your user permissions; review that script before using live mode in an unfamiliar checkout.

For production inspection, use npx impeccable detect https://example.com or the browser extension. These inspect the rendered page; they do not provide live variant editing or write changes back to your source.

Impeccable includes a standalone CLI for detecting anti-patterns without an AI harness. npx impeccable is a small shim that runs the same engine binary the skill uses (installed as a platform-specific optional dependency, or fetched once into ~/.impeccable/bin/); Node is needed only for npx itself, and you can also download the binary directly and put it on your PATH.

npx impeccable detect src/                   # scan a directory
npx impeccable detect index.html             # scan an HTML file
npx impeccable detect https://example.com    # scan a URL (uses an installed Chrome, Chromium, or Edge)
npx impeccable detect --json .               # CI-friendly JSON output
npx impeccable detect --github src/          # GitHub Actions annotations on stdout
npx impeccable detect --list-rules           # catalog of detector rule ids, names, and descriptions
npx impeccable detect --no-config src/       # raw scan, ignoring project config/context
npx impeccable ignores list                  # show detector ignores
npx impeccable ignores add-file "src/legacy/**"
npx impeccable ignores add-value overused-font Inter --reason "Brand font"

The detector catches 62 deterministic issues across AI slop (side-tab borders, purple gradients, bounce easing, dark glows) and general design quality (line length, cramped padding, small touch targets, skipped headings, and more).

Human-readable findings are diagnostics written to stderr, so redirect them with 2> findings.txt. Use --json for machine-readable results on stdout, or --github for GitHub Actions annotations (one workflow command per finding). GitHub displays at most 10 annotations of each type per step and 50 per job, and the rest stay in the log; findings from the HTML engine may carry no line number, so they annotate the file. --list-rules prints the detector catalog to stdout and does not scan. Exit 0 means the scan completed without primary findings, exit 2 means it completed with primary findings, and exit 1 means at least one requested target could not be scanned; operational failure takes precedence for a partial multi-target scan. URL scans inspect the rendered DOM, computed layout, and accessible linked stylesheets; browser security still prevents reading cross-origin CSS without CORS. A clean detector run is evidence, not proof of visual or accessibility quality: it does not replace inspecting the rendered experience across relevant viewports.

By default, detect respects the same .impeccable/config.json and .impeccable/config.local.json detector config as the design hook: detector.ignoreRules, detector.ignoreFiles, detector.ignoreValues, and detector.designSystem.enabled. Hook lifecycle settings such as hook.enabled only affect automatic hook execution.

For a waiver that should travel with one file instead of the repo config, add an inline comment in the file: <!-- impeccable-disable overused-font: exported brand doc -->. The marker works in any comment syntax, scopes to the whole file (or one line with impeccable-disable-line / impeccable-disable-next-line), and is bypassed by --no-inline-ignores or --no-config.

Full detector docs: impeccable.style/docs/detector.

Community & Ecosystem

Join the community and ecosystem conversations:

• GitHub Discussions: file bugs, request features, and help newcomers.
• Impeccable on npm: grab the CLI, follow releases, and star the package.
• Follow @pbakaus on Twitter for release notes, sample lint reports, and video highlights of new rules.

See DEVELOP.md for contributor guidelines and build instructions.

Apache 2.0. See LICENSE.

---

Created by Paul Bakaus