impeccable - Premium Frontend Polish

What this skill is

A registration entry pointing at the canonical install of the impeccable skill (by pbakaus, ~85.4K installs as of 2026-04-28 in the public skills ecosystem). Impeccable is a workflow for shipping production-grade frontend interfaces - websites, dashboards, app shells, components, landing pages - with committed design choices and exceptional craft.

It enforces a strict pre-mutation checklist (the four gates below) so the agent does NOT start editing files before it has loaded PRODUCT.md / DESIGN.md context, registered the surface as brand vs product, and (for craft) has a user-confirmed shape brief.

The deliverable from snappy-os's perspective is correct guidance pulled from the canonical install, not a runnable command. Eval is auto-shape - score by frontmatter shape + AGENTS.md presence.

Canonical install

• Filesystem (truth): ~/.agents/skills/impeccable/SKILL.md
• Symlinked back-compat: ~/.claude/skills/impeccable/SKILL.md
• Sub-references: ~/.agents/skills/impeccable/reference/*.md (one per command - craft.md, shape.md, polish.md, audit.md, critique.md, bolder.md, quieter.md, distill.md, harden.md, onboard.md, animate.md, colorize.md, typeset.md, layout.md, delight.md, overdrive.md, clarify.md, adapt.md, optimize.md, live.md, extract.md, teach.md, document.md, brand.md, product.md)
• Scripts: ~/.agents/skills/impeccable/scripts/load-context.mjs, pin.mjs, live.mjs

The snappy state/skills/impeccable/ folder is a thin pointer. Do NOT duplicate the canonical install's body content here - when you need a sub-command's full instructions, read directly from the canonical install.

Four gates (block file edits)

Before any Write / Edit against project files, the agent must pass these in order:

Plus an optional Image gate (visual probes / mocks generated or skipped with a reason - see shape.md / craft.md) and the final Mutation gate (all active gates above pass → file edits unlocked).

Codex-style agents must state this preflight line BEFORE editing files:

IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped:<reason> mutation=open

Workflow at a glance

teach   → set up PRODUCT.md + DESIGN.md (one-time per project)
shape   → plan UX/UI before code (required before craft)
craft   → build the feature end-to-end
polish  → final quality pass before ship
critique / audit  → evaluate (UX heuristics / a11y + perf)
bolder / quieter / distill / harden / onboard  → refine
animate / colorize / typeset / layout / delight / overdrive  → enhance
clarify / adapt / optimize  → fix
live    → live-browser variant iteration
extract → pull reusable tokens into a design system

Full command table with reference files: see canonical install ~/.agents/skills/impeccable/SKILL.md lines 127-151.

Provenance

• Author: pbakaus (publicly installable via npx skills add)
• Install count (2026-04-28): 85,400+
• Reproducibility:

  npx skills add pbakaus/impeccable

• Absorbed into snappy-os: 2026-04-28, mirroring the canonical-install

pattern landed for crayon-sdk at commit 5474aea.

Steps (when invoked as a snappy verb)

1. Read this file's "Canonical install" section to know where the truth lives.
2. Read ~/.agents/skills/impeccable/SKILL.md for the master flow.
3. If a specific sub-command is named, read its

~/.agents/skills/impeccable/reference/<command>.md.

1. Run node ~/.agents/skills/impeccable/scripts/load-context.mjs (gate 1).
2. Verify PRODUCT.md (gate 2). If thin, divert to $impeccable teach.
3. State the IMPECCABLE_PREFLIGHT: line. Then proceed.
4. Append an eval row to state/log/evals.ndjson with skill: "impeccable",

eval_mode: "shape".

Eval

Eval mode is auto-shape (no lib, no sidecar). Auto-shape scoring checks:

• frontmatter (name, description, eval) is valid
• AGENTS.md sibling exists
• canonical install path is reachable (~/.agents/skills/impeccable/SKILL.md)

impeccable - loader

Per-turn rules for the impeccable skill. Full reference: state/skills/impeccable/SKILL.md (snappy registration, thin pointer) + ~/.agents/skills/impeccable/SKILL.md (canonical install, ~170 lines, full flow). Do not skip these.

Critical Rules

• Prose-only skill, canonical install lives outside the repo. No

state/lib/impeccable.ts, no state/bin/impeccable/. The truth is at ${HOME}/.agents/skills/impeccable/ (with ${HOME}/.claude/skills/impeccable/ as a back-compat symlink). Eval is auto-shape - score frontmatter shape + AGENTS.md presence + canonical install reachability.

• Self-bootstrap when the install is missing. Subagents in stripped

shells sometimes cannot resolve ~. ALWAYS prefer the absolute form "$HOME/.agents/skills/impeccable/...". If the script is unreachable, install the canonical bundle FIRST, do not abort:

  test -x "$HOME/.agents/skills/impeccable/scripts/load-context.mjs" \
    || npx -y skills add pbakaus/impeccable -g -y

This single line makes a fresh MVH clone, a sandboxed subagent, and a newly-onboarded developer all converge on the same canonical install.

• **Four gates block file edits. ALL must pass before any Write / Edit

against project files.** In order:

1. Context - node "$HOME/.agents/skills/impeccable/scripts/load-context.mjs"

run this turn; consume the full JSON output (no piping through head / tail / grep / jq). If the script is missing, run the self-bootstrap line above first.

1. Product - PRODUCT.md at project root, ≥200 chars, no [TODO]

placeholders. Thin/missing → run $impeccable teach first, then resume.

1. Command reference - for any sub-command (craft, shape, polish,

etc.), read "$HOME/.agents/skills/impeccable/reference/<name>.md" first.

1. Shape (craft only) - $impeccable craft requires a user-confirmed

shape brief from a separate response. teach / PRODUCT.md does NOT count as shape. Run $impeccable shape and wait for explicit brief confirmation.

• State the preflight line before editing files, verbatim:

  IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped:<reason> mutation=open

Skipping this is the most common failure mode. Without the preflight, the agent has slipped past the gates without checking them.

• Brand vs product register: every design task is one or the other.

Brand = marketing, landing, campaign (design IS the product). Product = app UI, admin, dashboard (design SERVES the product). Identify before designing - priority: cue in the task → surface in focus → register field in PRODUCT.md.

• Absolute bans (match-and-refuse): side-stripe borders, gradient text

(background-clip: text + gradient bg), glassmorphism as default, hero-metric template, identical card grids, modal as first thought, em dashes (— and --). See canonical install lines 104-117.

• CRITICAL: Care about humans, not the system. Every piece of copy the user sees (empty states, sidebar items, status lines, button labels, page titles) must speak to the person in plain human language. HARD-BLOCK: machine slugs ("47 cron jobs", "eval-pending=12", "dispatch-chat.ndjson updated"), hype metrics ("47 dispatches today!"), apology stubs ("This page is coming soon"), em dashes, exclamation points. Ask: "would a thoughtful person say this to Robert?" If no, rewrite.
• CRITICAL: BEFORE + AFTER screenshot, window-targeted. Firing-offence-tier. Robert's stated rule: "if i say we need to be taking pics and confirming it is because i have determined you need that to be part of my business if you do not follow that then you are immediately fired no questions asked." Every change that affects the running UI requires a screenshot BEFORE the edit and AFTER the build+install, both Read by the agent. Capture command: WID=$(peekaboo list windows --app "Snappy Chat" --json-output | jq -r '.data.windows[] | select(.bounds[1][0] > 1000) | .window_id' | head -1) && peekaboo image --app "Snappy Chat" --window-id $WID --path /tmp/after.png. Do NOT use --window-index - it orders by isMainWindow not by bounds and grabs the wrong window. Pick the window with width > 1000 via window_id. The fix is NOT shipped until the AFTER screenshot, Read by the agent, shows the intended change. No faith-based "shipped" claims.

Commands

| ui dashboard | state/skills/impeccable/resources/ui.openui | |install (run once if missing): npx -y skills add pbakaus/impeccable -g -y |reference: state/skills/impeccable/SKILL.md (snappy thin pointer) + $HOME/.agents/skills/impeccable/SKILL.md (canonical, master) |sub-references: $HOME/.agents/skills/impeccable/reference/{craft,shape,polish,audit,critique,bolder,quieter,distill,harden,onboard,animate,colorize,typeset,layout,delight,overdrive,clarify,adapt,optimize,live,extract,teach,document,brand,product}.md (25 files) |scripts: $HOME/.agents/skills/impeccable/scripts/load-context.mjs (gate 1), pin.mjs (creates $<command> shortcut), live.mjs (live browser iteration; warms context) |library: none (prose-only) |sidecar: none (prose-only) |eval log: state/log/evals.ndjson (skill: "impeccable", eval_mode: shape)

Sub-command quick map (which reference for which question)

Self-Test

An agent reading this should correctly:

1. [ ] Know this is prose-only (no lib, no sidecar) and the eval mode is auto-shape?
2. [ ] Reach the canonical install at ~/.agents/skills/impeccable/ (NOT just the snappy pointer) for sub-command bodies?
3. [ ] Run node ~/.agents/skills/impeccable/scripts/load-context.mjs BEFORE any file edits, and consume the full JSON?
4. [ ] State the literal IMPECCABLE_PREFLIGHT: line before mutations?
5. [ ] Refuse the absolute bans (side-stripe borders, gradient text, em dashes, etc.) instead of writing them?

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] impeccable: <what was missing>" >> state/log/loader-feedback.log

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] impeccable: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> state/log/loader-feedback.log

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/impeccable/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.