Impeccable: a design skill for coding agents

What the Impeccable design skill does

Impeccable is a design skill for coding agents such as Claude Code, Cursor, Codex and GitHub Copilot. It adds one skill with 24 design commands. It also adds a command-line detector that flags common design habits of AI (artificial intelligence) models in your HTML and CSS without calling a model. You install it pinned to a release, run the detector on a page, apply one command, and run the detector again to see what changed.

The rest of this guide explains what the skill adds and how it differs from other ways to give an agent design guidance. Then it walks through one full loop on a real page. It ends with the cost: what the skill puts into the agent's context, and what goes wrong when two design skills want the same files.

What Impeccable adds to a coding agent

A coding agent writes frontend code that works, but it falls back to the same visual defaults again and again. Purple gradients, a card inside a card, gray text on a colored panel, the Inter font everywhere. Impeccable was written by Paul Bakaus and is released under the Apache 2.0 license. It handles this problem in two ways.

The first part is guidance the model reads. The skill is one SKILL.md file of about 800 lines, plus reference files that load only for the command you run. Every command uses the form /impeccable <command> <target>. These are the ones you will use most:

• init asks about your product and audience, then writes PRODUCT.md, so later commands know who the page is for.
• craft plans a screen and then builds it, with visual checks along the way.
• critique reviews a design for hierarchy and clarity, the way a human design reviewer would.
• audit runs technical checks such as accessibility and performance.
• polish is the final pass before you ship.
• typeset, layout, colorize and animate each fix one dimension of a page.
• document reads your existing code and writes a DESIGN.md file from it.

The second part is a detector that runs as plain code. npx impeccable detect parses your files and applies fixed rules. The same input always gives the same findings. That is what makes it useful as a check on the model's work.

What the detector rules check

The rule catalogue on the Impeccable site groups more than 60 rules into categories. It tags each rule by what it needs to run. Rules tagged CLI (command-line interface) are deterministic and run in npx impeccable detect. Rules tagged LLM (large language model) need the model's judgment, such as "glassmorphism everywhere" or "identical card grids", so only the agent applies them. A third group is tagged as browser checks, because they measure a rendered page: content overflowing its container, or text covered by another element.

The deterministic rules check things you can measure in source code:

• Contrast below WCAG (Web Content Accessibility Guidelines) level AA, which means a ratio under 4.5:1 for normal text.
• Body text smaller than 16px, tight line height, justified paragraphs, and wide letter spacing on body text.
• A skipped heading level, such as an h2 followed directly by an h4.
• Overused fonts, and all-caps body text.
• Gray text on a colored background, gradient text, glowing accents on a dark theme, and the purple and cyan palette that marks a lot of generated pages.
• Nested cards, side-tab accent borders, decorative grid-line backgrounds, and monotonous spacing.
• Bounce or elastic easing, auto-scrolling marquees, pulsing status dots, and animations that shift the layout.
• Copy problems: the same text repeated inside one container, generic marketing claims, slogan-style forced contrast, and em-dash overuse.
• Your own design system: a font, color, corner radius or font size that is not listed in your DESIGN.md.

That last group connects the detector to a design file. Without a DESIGN.md, the detector only knows general rules. With one, it can also tell you that a page used a color your system never defined.

How Impeccable differs from DESIGN.md and from anti-slop

A DESIGN.md file for AI agents is a static description of your design system: tokens, type scale, colors and component rules. The agent reads it as context. It tells the agent what your design is. It does not run anything, so it cannot tell you when the agent ignored it. Impeccable can write that file for you with /impeccable document, and its detector then checks your pages against it.

The anti-slop skill for coding agents is a set of instructions that tells the agent which generic patterns to avoid. Impeccable covers some of the same ground, with two differences. It is a command set, so you choose the job (audit first, then typeset) instead of loading one large instruction file for every request. And its rules exist as code, so the check does not depend on the model remembering them.

If you are new to the format itself, what agent skills are and how agents load them explains the mechanism that both of these tools use.

Install Impeccable, pinned to a release

As of October 2026, the skill's latest tag is skill-v4.5.0, and the npm package that holds the command-line tool is at version 4.1.0. The two are versioned separately. Pin both, so the install you test today is the install your teammate gets next week. The npm package requires Node.js 22.18.0 or later. Check that first:

node --version

The output must read v22.18.0 or a higher version. Older Node versions cannot run the package, so fix that before you go further. If you run your agent on a server, as in Claude Code on a VPS inside tmux, run this check on the server, not on your laptop.

Choose one of the two routes below. Do not use both. Each route installs its own copy of the skill and its own set of hooks, so every edit would trigger the detector twice.

Route 1: the command-line installer

Run it from the root of your project:

npx impeccable@4.1.0 install

The installer looks for agent folders such as ~/.claude, ~/.cursor and ~/.codex, and lets you choose which ones to install for. On Claude Code, Cursor, Codex, GitHub Copilot and Grok Build it also installs a design hook. On Claude Code that hook goes into .claude/settings.local.json, which is not committed to git. Start a new agent session afterwards, so the agent picks up the new skill.

The npm package and the skill have separate version numbers, so check which skill version you received. The version: line in the skill's frontmatter tells you:

grep -r '^version:' ~/.claude/skills/impeccable/SKILL.md .claude/skills/impeccable/SKILL.md 2>/dev/null

One of the two paths should print a line such as version: 4.5.0. Which path depends on whether you chose a global or a project install. If neither prints anything, the installer wrote to a different agent folder than the one you are checking.

Route 2: the Claude Code plugin

Claude Code can add a marketplace at a specific git tag when you add #ref to the repository name. Run these in your shell:

claude plugin marketplace add pbakaus/impeccable#skill-v4.5.0
claude plugin install impeccable@impeccable
claude plugin list

claude plugin list should show impeccable@impeccable with an enabled status. The tag pins the plugin as well, because the marketplace file at that tag points to a plugin folder in the same repository. The plugin ships three hooks. One runs at session start, one runs after every Edit or Write tool call, and one runs when the agent stops. The stop hook runs a longer "design deep pass" with a 30 second timeout.

Plugin skills carry the plugin name as a prefix, so in a session the full command is /impeccable:impeccable audit. Type /impeccable and choose from the list. If you want short names, /impeccable pin audit creates a standalone /audit command.

A realistic loop: audit, fix one thing, measure again

This loop uses an existing landing page at site/index.html. Commit your work first, so every change the agent makes shows up in git diff.

Step 1: record a baseline with the detector

npx impeccable@4.1.0 detect site/
echo "exit code: $?"

The exit code is the signal. 0 means no findings. 2 means the detector found problems. 1 means the scan itself failed. Save a machine-readable copy for later:

npx impeccable@4.1.0 detect --json site/ > before.json

Step 2: give the skill context, then audit

If the project has no PRODUCT.md, start a Claude Code session and run /impeccable init first. It asks who the product is for, and the other commands read that file. Then run the audit:

/impeccable audit site/index.html

Read the report before you change anything. Look for findings that share one cause. Small text, flat headings and tight line height usually point to one typography problem, so one command can fix all of them.

Step 3: apply one command

Pick the command that matches the largest group of findings. For a typography problem:

/impeccable typeset site/index.html

Run one command per pass. Two commands in one pass produce one large diff, so when a finding gets worse you cannot tell which command caused it. Review the result with git diff site/. The changes should stay inside the scope of the command: font sizes, weights, line heights and the font stack, not a new color palette.

Step 4: run the detector again

npx impeccable@4.1.0 detect site/
echo "exit code: $?"
npx impeccable@4.1.0 detect --json site/ > after.json

Compare this run with the baseline. The typography findings from step 1 should be gone, or at least fewer. No new rule should appear in a category the command was not asked to touch. Watch the design-system rules in particular. A typeset pass that adds a new font trips "font outside DESIGN.md" if you have a DESIGN.md, or "overused font" if the agent chose a common default.

With the hook installed, the agent already sees detector findings after each edit. Run the detector yourself anyway. The agent can misreport or skip a finding when it summarizes, and your own run does not depend on the model.

When a rule is wrong for your project

Some findings are correct by the rule and wrong for your brand. If your brand font is Inter, the overused-font rule will flag it every time. Record the exception once instead of arguing with the agent:

npx impeccable@4.1.0 ignores add-value overused-font Inter --reason "Brand font"
npx impeccable@4.1.0 ignores list

For a single file, an inline comment waives one rule:

<!-- impeccable-disable overused-font: exported brand doc -->

Keep .impeccable/config.json in git, so every teammate and every CI (continuous integration) run uses the same exceptions. In CI, the exit code of detect is enough, because exit code 2 fails the job.

What Impeccable costs in context on every call

An agent skill is never free. The agent sees the name and description of every installed skill in every turn, because that is how it decides when to load one. Impeccable's description lists more than a dozen design verbs, from "design" and "redesign" to "polish" and "animate". It is short, but it matches almost any frontend request. The full body, about 800 lines, loads only when the skill is used. Each command's reference file loads only for that command.

The hooks cost more than the description. The PostToolUse hook runs after every Edit or Write, and its findings come back into the conversation as text the model must read. A long session of small edits to UI (user interface) files adds that output again and again. The stop hook adds a deeper pass at the end of each turn. To see the real number for the plugin route, run:

claude plugin details impeccable

The Always-on line is the number of tokens the plugin adds to every session where it is enabled. Compare it with your other plugins before you leave Impeccable on for every project. How Claude Code manages its context window explains why this matters on long sessions.

When two design skills claim the same files

Problems start when you install Impeccable next to another design skill. Both descriptions match any request about a frontend page, so the agent may load both for the same task. Each one then gives its own rules for the same CSS. When the rules disagree, the agent follows one in one edit and the other in the next, and the page moves back and forth between two styles. If both skills install hooks, every edit to a UI file also triggers two checks, and both outputs land in context.

The anti-slop guide's section on overlapping design skills covers this case in detail. The short rule: one design skill owns a project. With the plugin route, disable Impeccable for one repository only:

claude plugin disable impeccable@impeccable --scope local

The local scope writes the change to .claude/settings.local.json, so the plugin stays on in your other projects. If you want rules from both tools, copy the specific rule you need into one skill instead of running both. Writing your own agent skill shows how to do that without starting from zero.

FAQ

Does the Impeccable detector need an API key or a model?

No. npx impeccable detect runs fixed rules over your files and needs only Node.js 22.18.0 or later. The same files always give the same findings. Rules that need judgment, such as "identical card grids", are applied by the agent when you run a command like /impeccable critique, and those do use the model.

Why does npx impeccable detect exit with code 2?

Exit code 2 means the scan worked and found at least one problem. Exit code 1 means the scan itself failed. Exit code 0 means no findings. In CI any non-zero exit fails the job, so record real exceptions with npx impeccable ignores add-value or an inline impeccable-disable comment instead of hiding the exit code.

Is Impeccable a replacement for a DESIGN.md file?

No, the two work together. A DESIGN.md describes your design system, and the agent reads it as context. Impeccable can generate that file with /impeccable document, and its detector then flags any font, color, corner radius or font size that the file does not list. Without a DESIGN.md, the detector checks only its general rules.

How do I pin Impeccable to a specific version?

For the Claude Code plugin, add the marketplace at a tag with claude plugin marketplace add pbakaus/impeccable#skill-v4.5.0, then run claude plugin install impeccable@impeccable. For the installer, pin the npm package with npx impeccable@4.1.0 install. Then check the version: line in the installed SKILL.md, because the npm package and the skill have separate version numbers.

Can I run Impeccable and the anti-slop skill together?

You can, but it is a bad idea on the same project. Both skills match any frontend request, so the agent may load both and follow conflicting rules in different edits. If both install hooks, every UI edit is checked twice. Pick one design skill per project, and disable the other at local scope.