Impeccable: a design vocabulary for your AI harness

Impeccable is a free, Apache-2.0 Agent Skill by Paul Bakaus that gives a coding agent and its user one design vocabulary: a single /impeccable skill with named commands such as audit, typeset, and quieter. It also ships a deterministic detector, with no LLM and no API key, that flags AI-generated UI patterns in an edit hook or a CI check.

This page is for frontend developers who build UI with Claude Code, Codex, or Cursor, and for tech leads who want a design-quality gate that does not depend on a designer reading every pull request. The situation it solves: the agent’s settings page works, but it has the purple-to-cyan gradient, Inter everywhere, and cards nested in cards. You ask for “better spacing” and get a guess.

What you’ll walk away with from Impeccable

• A working install for Claude Code, Codex, or Cursor, with the context files every command reads.
• The commands that matter first, and the order to run them in on a real surface.
• A pull-request gate built on npx impeccable detect, with its exit codes and an exception policy.
• Two copy-paste prompts: an audit-then-fix loop and a new-surface build with a direction you approve.
• The traps: hooks that run outside the permission prompt, stale context files, and ignore lists that grow in silence.

As of 2026-09-26, pbakaus/impeccable has 71.3k GitHub stars (read on GitHub). skills.sh lists 293,766 installs, a SECONDARY figure from the third-party LinklyAI/best-skills scrape of the same date; re-read it on skills.sh before quoting it. This page was checked against the impeccable CLI 4.1.0 on npm and the skill source on main (SKILL.md version 4.4.0).

Install Impeccable in Claude Code, Codex, or Cursor

The recommended route is the npm installer, from the project root. It detects the harness folders you use, asks whether to install into the project or globally, and on Claude Code, Codex, Cursor, GitHub Copilot, and Grok Build also installs the design hook (see the hook section). The installer downloads a self-contained engine binary; Node.js 22.18 or later is needed only for npx.

Claude Code

# Terminal, project root
npx impeccable install --providers=claude --scope=project

# Alternative: the plugin marketplace (skill plus the plugin's own design hooks; run init afterwards)
claude plugin marketplace add pbakaus/impeccable
claude plugin install impeccable@impeccable

The skill lands in .claude/skills/impeccable/. The hook goes into .claude/settings.local.json, which is gitignored, so each developer opts in on their own machine. After the npx route, invoke it as /impeccable. With the plugin route the skill is namespaced (/impeccable:impeccable); check /help after install.

With the plugin route, the hooks ship inside the plugin (SessionStart, PostToolUse on Edit|Write, and Stop in plugin 4.4.0), so you manage them by enabling or disabling the plugin (claude plugin disable impeccable@impeccable), not by editing .claude/settings.local.json.

Codex

# Terminal, project root
npx impeccable install --providers=codex --scope=project

The skill lands in .agents/skills/impeccable/ and the hook in .codex/hooks.json. Open /hooks in Codex and approve the project hook: Codex tracks trust by hook definition, so an npx impeccable update that changes the hook can ask again. Invoke the skill as $impeccable or pick it from /skills; Codex does not use /prompts: commands for it (checked against Codex CLI 0.157.1).

Cursor

# Terminal, project root
npx impeccable install --providers=cursor --scope=project

The skill lands in .cursor/skills/impeccable/ and the hook in .cursor/hooks.json. Check that Cursor has picked up .cursor/hooks.json (the hook runs before each write); restart Cursor if it has not. Because it runs before the write, it can block it. Invoke the skill as /impeccable.

The universal skills CLI also finds the skill (npx skills add pbakaus/impeccable --list reports one skill, impeccable, with skills 1.7.0). It copies the skill only, with no hook, so use it when you want the vocabulary without the automation. For how skills load and how to update them, see installing and managing skills.

Then, inside the agent, run the one-time setup:

/impeccable init

Refresh later with npx impeccable update. Reload the harness after either command.

Context cost

Impeccable is one skill, so only its name and description sit in context until you invoke it; the command references load on demand. The plugin route also runs a SessionStart hook in every session. Measure it in your own setup: run /context in Claude Code before and after install, or claude plugin details impeccable@impeccable for a plugin install, which prints the plugin’s projected token cost.

Which files does Impeccable read, and which should you commit?

Every command reads the same small set of files, so the agent knows what your product should look like instead of falling back to its defaults:

File	Holds	Written by	Commit it?
PRODUCT.md	Audience, purpose, constraints, voice, evidence you actually have	init	Yes. Edit it; it is yours
DESIGN.md	Colors, type, components, and rules of the visual system	document, or the finish of a new build	Yes
.impeccable/design.json	Structured sidecar of DESIGN.md for the detector and Live Mode	document	Yes
.impeccable/surfaces/*.md	Per-route strategy and the direction contract of a new build	Written during work	Yes
.impeccable/config.json	Hook settings, detector ignores, buildPath	/impeccable hooks …, npx impeccable ignores …	Yes
.impeccable/config.local.json, screenshots, live-mode state	Per-developer overrides and ephemeral output	Impeccable	No. Add the README’s .gitignore block

Two rules in the skill shape everything downstream. init records only what is true, including absences such as “no customer logos yet”, so later commands do not invent a logo wall. And each surface gets a mode chosen by what the visitor came to do: Persuade (landing pages, pricing), Operate (apps, dashboards), Read (docs, changelogs), or Experience (portfolios, galleries). A developer tool’s landing page is Persuade even though the product is Operate, and the commands change their priorities accordingly.

Which Impeccable commands should you learn first?

Every command runs as /impeccable <command> <target> ($impeccable in Codex). The skill lists 24 entries: 23 working commands plus craft, which is now a deprecated alias. Describe the surface instead (/impeccable a pricing page for enterprise buyers) and the skill picks the flow. Bare /impeccable shows a menu based on the state of your project and never runs a command on its own.

Group	Commands	Reach for them when
Set up	init, document, extract	Starting a project, or when the same button exists in 12 places
Plan	shape	The ticket is vague. It interviews you and returns a brief, with no code
Evaluate	audit, critique	You need findings before anyone edits anything
Fix	harden, clarify, adapt, optimize, onboard	Edge cases, UX copy, other devices, speed, first-run flows
Adjust the voice	bolder, quieter, distill, colorize, typeset, layout, animate, delight, overdrive	The surface works but looks generic, loud, crowded, or flat
Finish	polish	The last pass before shipping
Iterate in the browser	live, generate	You want three variants of one element on your running dev server

Learn four first: audit, critique, harden, and polish. The others are more precise words for what you would otherwise describe in a paragraph. Three distinctions save rework:

• audit documents; it does not fix. It scores five dimensions from 0 to 4 each: accessibility, performance, theming, responsive behaviour, and implementation integrity, which covers detector findings and design-system drift. It tags every finding P0 to P3. You route the findings to harden, optimize, or polish.
• critique is the judgement layer. It scores Nielsen’s ten heuristics from 0 to 4, runs persona checks, and asks questions the interface cannot answer for itself. Run it on finished work only.
• quieter and distill fix different problems. Too loud (neon, gradients, six accents) is quieter. Too many things is distill.

/impeccable pin audit creates a standalone /audit shortcut for a command you use daily; unpin removes it.

Refine an existing surface: the audit-then-fix loop

This is the workflow for most days: a surface the agent built that works but needs to meet your standard before it merges. It follows plan, build, verify, review, and ship, with the evidence written down at each step.

1. Scan before you ask for taste. Run npx impeccable detect src/app/settings in the terminal. It costs nothing and gives you a baseline count of deterministic findings.

2. Audit. /impeccable audit settings returns an Audit Health Score out of 20 and a P0–P3 list. Save the report with the pull request, not in chat.

3. Fix by severity. P0 and P1 go to harden (edge cases, errors, i18n, overflow) or optimize; the rest wait for polish. One command per pass keeps each diff reviewable.

4. Re-verify with the same instruments. Re-run detect and audit. The finding count and the health score must move in the right direction; if a P0 is still open, the pass is not done.

5. Critique and polish last. /impeccable critique settings for the heuristic review, then /impeccable polish settings. A healthy polish pass makes small fixes. If it starts rewriting the layout, stop and run layout or critique instead.

Copy-paste prompt: audit, fix the blockers, prove it

/impeccable audit src/app/settings

Then, without asking me again:
1. Run `npx impeccable detect src/app/settings --json` and record the finding count.
2. Fix every P0 and P1 finding from the audit, using /impeccable harden for edge cases and
   /impeccable optimize for performance. Do not touch P2/P3 findings or files outside src/app/settings.
3. Re-run the audit and the detector.
4. Reply with a table: finding, severity, fixed (yes/no), file:line, and the before/after
   Audit Health Score and detector count. List anything you could not fix and why.
Do not add any detector ignore to make a finding disappear.

The last line matters. An agent under pressure to turn a check green will reach for an ignore; Impeccable’s own hook guidance tells the agent to fix real problems and to self-serve only narrow, evidenced value ignores, so say it in the prompt as well.

Build a new surface with a direction you approve

For a new page or a redesign, Impeccable does not let the model build its first idea. The skill’s new-work flow runs a concept-seed script that deals the directions you choose from, so repeated runs do not converge on the category default:

1. Classify the job. An addition to an existing page inherits that page’s look; a redesign treats the old look as evidence to replace, not polish.
2. Deal directions. The agent derives several directions from your product and its audience; the script picks which ones reach you and can deal challengers from a catalogue of visual systems. You accept one, re-roll, or steer in one line (“too corporate”). A plain, category-standard option is always on the table if you want it.
3. Comp first or code first. With image generation available, Impeccable can render a full comp and build to match it ("buildPath": "comp" in .impeccable/config.json); without it, or when you prefer speed, it builds straight in code ("code").
4. Write the contract, then check against it. Before code, the agent records a short direction contract under ## Direction contract in the surface brief (.impeccable/surfaces/), never in shipped source. The finishing review checks the build against that contract, and DESIGN.md is written from the built result.

Copy-paste prompt: a new pricing page, reviewed before code

/impeccable a pricing page for engineering managers comparing our Team and Enterprise plans.

Constraints: reuse our existing components in src/components/ui, keep the current brand colours
from DESIGN.md, and every price and feature must come from src/lib/plans.ts (do not invent
logos, testimonials, or numbers). Show me the directions before writing any code and wait for my
pick. After building, run `npx impeccable detect src/app/pricing` and /impeccable audit pricing,
fix every P0/P1, and report the direction contract, the detector count, and the audit score.

To take a spec further than one page (visual direction, prototype, design contract, implementation with proof), use the four-artifact design-to-code pipeline; Impeccable fits its build and polish steps.

Gate pull requests with the detector

The detector is the part of Impeccable a tech lead can enforce. It runs the deterministic rules with no model and no API key, on files, folders, stdin, or a URL:

npx impeccable detect src/                   # a folder
npx impeccable detect index.html             # one file
npx impeccable detect https://example.com    # a rendered page (uses installed Chrome/Chromium/Edge)
npx impeccable detect --json src/            # machine-readable, on stdout
npx impeccable detect --scope type src/      # one design domain (type, layout)

Exit codes make it a CI check: 0 means no primary findings, 2 means findings, and 1 means a target could not be scanned. Some rules, such as em-dash overuse, are advisory: they are listed but never change the exit code. Human-readable findings go to stderr, so redirect them with 2> findings.txt. The README counts 61 deterministic rules. With a DESIGN.md present, some of them flag drift from your system, such as a font outside your stack.

A minimal GitHub Actions job, with read-only permissions and no secrets:

.github/workflows/design-gate.yml

name: design-gate
on: pull_request
permissions:
  contents: read
jobs:
  detect:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: 22
      - run: npx -y impeccable@4.1.0 detect src/

Pin the version so a new rule does not fail every open pull request on the day it ships; bump it in its own pull request.

Who signs off. The detector proves the absence of known patterns, not good design. The Impeccable README itself calls a clean run “evidence, not proof”. So split the sign-off: CI owns the deterministic rules, the author attaches the audit report (health score and P0–P3 list) to the pull request, and a human looks at the rendered page at two viewports. Nobody has to read the CSS line by line. For the wider practice of catching generated-code tells, see slop detection; for accessibility beyond the detector, see accessibility testing.

Exceptions are part of the policy, not a workaround. Record them with a reason:

npx impeccable ignores add-value overused-font Inter --reason "Brand font, approved by design"
npx impeccable ignores add-file "src/legacy/**"

Both write to .impeccable/config.json, which the CI run reads from the pull request’s own checkout. Put that file and .github/workflows/ under CODEOWNERS and turn on required code-owner review in branch protection or a ruleset, so a pull request cannot silence a rule, or edit the job that enforces it, without review. On pull_request, GitHub runs the workflow YAML from the pull request’s merge ref, so the workflow file needs the same protection as the config. The same applies to inline impeccable-disable-next-line comments; --no-inline-ignores makes CI ignore them.

Run the detector on every agent edit

The design hook runs the same detector while the agent works, so findings reach the agent before you do. The installer offers it by default; /impeccable hooks on, off, and status manage it per project.

Harness	Hook file	Behaviour
Claude Code	.claude/settings.local.json	Reminder after each UI edit; deeper pass at Stop
Codex	.codex/hooks.json	Reminder after each UI edit; deeper pass at Stop; approve via /hooks
Cursor	.cursor/hooks.json	Checks a proposed write first and blocks it on a real finding

Per-edit checks surface only the unambiguous problems: broken images, overflow, contrast failures, gradient text, glow, and drift from DESIGN.md. The taste-level rules wait for one deduplicated pass at the end of the session. Set hook.perEditRules to "all" in .impeccable/config.json if you want every rule on every edit.

When Impeccable goes wrong, and how to recover

Traps with Impeccable

• Hooks run outside the permission prompt. In Claude Code, installed command hooks run independently of tool approval; the first edit can download and cache the engine even if you denied the launcher. Review .claude/settings.local.json (or, for a plugin install, claude plugin details impeccable@impeccable) before unattended runs, or pass --settings '{"disableAllHooks": true}'. See skill supply-chain security.
• Live Mode runs a script from your repo. Applying copy edits runs package.json’s optional impeccable:manual-edit-validate script with your permissions. Use Live Mode only in checkouts you trust, and never against a production site.
• craft is deprecated. Older tutorials start with /impeccable craft; describe the surface instead.

The output drifts toward generic defaults. PRODUCT.md or DESIGN.md is missing or stale. Run /impeccable doctor: it reports drift between your Impeccable files and what the installed version reads, repairs what is mechanical, and routes judgement calls to init or document. In a monorepo, check which apps inherit the root’s context.

The Codex hook does nothing. You did not approve it in /hooks, or an update changed its definition and it needs approval again. /impeccable hooks status shows the state.

CI turns red on every pull request after a bump. A new rule fired on existing code. Pin the previous version, run detect on main, and fix or record the exceptions in one pull request before you bump again.

The ignore list keeps growing. The agent is silencing instead of fixing. Review .impeccable/config.json like code, reject new detector.ignoreFiles and detector.ignoreRules entries that nobody asked for, and keep the “no new ignores” line in your prompts.

bolder makes a dashboard shout. Boldness belongs on Persuade surfaces. Run quieter on the result and check that the surface’s mode is Operate.

Native iOS or Android code gets no detector findings. The detector, Live Mode, and the hook read HTML and CSS. On native projects audit and adapt load native references instead, so rely on those and on platform tests.

How Impeccable compares with the other design skills

• Taste Skill constrains generation up front with one curated set of rules. Impeccable derives directions from your product, makes you choose, and adds the audit and refine vocabulary for everything after. Pick one per project; two design skills firing on one request give two conflicting procedures.
• shadcn/improve audits component architecture, not visual design. The two are complementary.
• Anthropic’s frontend-design is where Impeccable started, per its README. The frontend skills roundup compares it with the other options.

Where to go next with Impeccable

Four-artifact design-to-code pipeline The gated direction → prototype → contract → code workflow that Impeccable's build and polish steps fit into.

Slop detection Catch the tells of generated code and UI in review and CI, beyond one detector.

Best frontend skills Pair Impeccable with framework skills so the agent writes current React, Vue, or Svelte.

Grill Me and Grill With Docs Impeccable decides how it looks; grilling decides what you are building before any code.

Skill supply-chain security Review hooks and bundled scripts before a skill runs in your repo.