skills/pbakaus_impeccable
1
0
Fork 0
mirror of https://github.com/pbakaus/impeccable.git synced 2026-09-15 07:36:50 +03:00
Code Issues Packages Projects Releases Wiki Activity

Consolidate 18 skills into 1 /impeccable skill with 20 commands

Browse Source 
Biggest change in a while. Users previously had 18 standalone skill
entries cluttering their /menu; now they have one entry (/impeccable)
that routes to 20 specialized commands via argument dispatch. The pin
mechanism (/impeccable pin audit) restores standalone shortcuts on
demand for commands users hit all the time.

## Architecture

- Single /impeccable skill with command router section in SKILL.md
- 20 commands served via reference files under source/skills/impeccable/reference/
- /impeccable pin <command> creates a lightweight redirect shim so users
  who prefer /audit, /polish, etc. can still have them
- Context gathering (teach) auto-runs on first use
- command-metadata.json is the single source of truth for command
  descriptions, argument hints, and relationships

## Site rewrite

- Docs URL: /skills renamed to /docs (with /skills permanent redirects)
- Homepage hero frames Impeccable as "one skill with 20 commands"
- "Get Started" split into 50/50 install + how-to-use with editorial
  numbered steps, /impeccable shown as the home command with three modes
- New /docs overview: home command hero card + dense category rows
  matching the old cheatsheet density, with leads-to/pairs-with/
  combines-with relationship metadata served from a shared source
- Cheatsheet merged into /docs, /cheatsheet redirects
- Magazine spread and mobile cards show /impeccable as a stacked
  namespace label above the command name at full display size
- Periodic table updated with craft/teach/extract as first-class cells
- Skill detail pages generate from reference files, with an editorial
  wrapper per command for tagline + body
- Tutorials and anti-patterns pages updated to use /impeccable <cmd>

## Build system

- Dead code removed (scripts/lib/transformers/shared.js)
- Build log wording fixed ("1 skill" not "1 skills (1 user-invocable)")
- generateApiData fallback branch removed (throws loudly if metadata
  missing instead of silently degrading)
- Commands API includes editorial tagline alongside the long description;
  UI surfaces prefer tagline for human display, description for auto-
  trigger keyword matching

## Gitignore

- Added .claude/scheduled_tasks.lock, .claude/settings.local.json to
  ignore list (local Claude Code state that should not be tracked).
- Harness skill directories (.claude/skills/, .agents/skills/, etc.)
  remain tracked by design: npx skills reads them from this repo at
  install time and they enable clean submodule use.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Paul Bakaus
2026-04-10 19:45:17 -07:00
co-authored by Claude Opus 4.6
parent f957fcad20
commit b0f44f83c6
469 changed files with 25435 additions and 22231 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/site/tutorials/critique-with-overlay.md
+10 -10
View File
@@ -1,6 +1,6 @@
---
title: Critique with the visual overlay
tagline: "Use /critique plus the browser overlay to review a live page with ground truth."
tagline: "Use /impeccable critique plus the browser overlay to review a live page with ground truth."
order: 2
description: "Run a full design critique that combines LLM assessment, the automated detector, and a live browser overlay so you can see exactly which elements trigger which anti-patterns on the page you're looking at."
---
@@ -17,12 +17,12 @@ Total time: about ten minutes.
- A harness with browser automation available (Claude Code with the Chrome extension, or similar).
- A page you want to critique, either local (`localhost:3000/pricing`) or deployed.
## Step 1. Run /critique
## Step 1. Run /impeccable critique
From your harness, run:
```
/critique the pricing page at localhost:3000/pricing
/impeccable critique the pricing page at localhost:3000/pricing
```
The skill kicks off two independent assessments in parallel. They run in separate sub-agents so one does not bias the other.
@@ -58,14 +58,14 @@ Every outlined element has a floating label naming the rule that fired. Hover an
You have three ways to open it:
1. **[Chrome extension](https://chromewebstore.google.com/detail/impeccable/bdkgmiklpdmaojlpflclinlofgjfpabf)**: one-click activation on any page. Click the Impeccable icon in the toolbar and every anti-pattern gets highlighted instantly.
2. **Inside `/critique`**: the skill opens a browser tab labeled `[Human]` with the detector active during the browser portion of the assessment. You do not need to do anything extra.
2. **Inside `/impeccable critique`**: the skill opens a browser tab labeled `[Human]` with the detector active during the browser portion of the assessment. You do not need to do anything extra.
3. **Standalone CLI**: `npx impeccable live` starts a local server that serves the detector script. You inject it into any page by adding a `<script>` tag.
For this tutorial, the easiest option is the Chrome extension. Install it, navigate to your pricing page, and click the Impeccable icon. You will see the overlay appear immediately on the live page.
## Step 3. Merge the two assessments
Back in your harness, `/critique` has finished and produced a combined report. It looks something like:
Back in your harness, `/impeccable critique` has finished and produced a combined report. It looks something like:
```
AI slop verdict: FAIL
@@ -110,17 +110,17 @@ The report gives you a priority list. You can work through them one at a time, a
This feedback loop is the reason the overlay matters. You see fixes land in real time, and you never ship a "fix" that did not actually satisfy the rule.
## Step 5. Re-run /critique when you are done
## Step 5. Re-run when you are done
After you have worked through the priority list, run `/critique` again. The goal is a clean AI slop verdict and at least a 3.5 average on the heuristics. Cognitive load should be below 2 failures.
After you have worked through the priority list, run `/impeccable critique` again. The goal is a clean AI slop verdict and at least a 3.5 average on the heuristics. Cognitive load should be below 2 failures.
If something still fires, fix it or write a suppression comment explaining why the rule does not apply in your context (the detector respects a small set of opt-out pragmas, but use them sparingly).
## What to try next
- `/audit the same page` to catch the implementation issues critique does not cover (accessibility, performance, theming).
- `/polish` if the critique report is clean and you want the last-mile refinement pass.
- `/distill` if critique flagged "too busy" or "cognitive load". Distill removes what should not be there.
- `/impeccable audit the same page` to catch the implementation issues critique does not cover (accessibility, performance, theming).
- `/impeccable polish` if the critique report is clean and you want the last-mile refinement pass.
- `/impeccable distill` if critique flagged "too busy" or "cognitive load". Distill removes what should not be there.
## Common issues
content/site/tutorials/getting-started.md
+21 -8
View File
@@ -1,19 +1,31 @@
---
title: Getting started
tagline: "From zero to your first /polish pass in five minutes."
tagline: "From zero to your first polish pass in five minutes."
order: 1
description: "Install Impeccable, run /impeccable teach once to establish project context, and run /polish on something that already exists. The fastest path to seeing what Impeccable changes about AI-generated design."
description: "Install Impeccable, run /impeccable teach once to establish project context, and run /impeccable polish on something that already exists. The fastest path to seeing what Impeccable changes about AI-generated design."
---
## What you'll build
You will end this tutorial with Impeccable installed in your project, a `.impeccable.md` file that captures your brand and audience, and one hand-polished page that went through a `/polish` pass. Total time: about five minutes.
You will end this tutorial with Impeccable installed in your project, a `.impeccable.md` file that captures your brand and audience, and one hand-polished page that went through a polish pass. Total time: about five minutes.
## Prerequisites
- An AI coding harness: Claude Code, Cursor, Gemini CLI, Codex CLI, or any of the other supported tools.
- A project with at least one HTML or component file you want to improve. A fresh scaffolded landing page works fine.
## How Impeccable works
Impeccable installs as a single agent skill called `impeccable`. You access all 20 design commands through it:
```
/impeccable <command> <target>
```
For example: `/impeccable polish the pricing page`, or `/impeccable audit the checkout`. Type `/impeccable` alone to see the full list.
If you use a command often, pin it with `/impeccable pin <command>` to create a standalone shortcut (e.g., `/impeccable pin audit` gives you `/audit` directly).
## Step 1. Install
From the root of your project, run:
@@ -22,7 +34,7 @@ From the root of your project, run:
npx skills add pbakaus/impeccable
```
This auto-detects your harness and writes the skill files to the right location (e.g., `.claude/skills/`, `.cursor/skills/`). Reload your harness and type `/`. You should see `/impeccable`, `/polish`, `/critique`, and the other commands in the autocomplete.
This auto-detects your harness and writes the skill files to the right location (e.g., `.claude/skills/`, `.cursor/skills/`). Reload your harness and type `/`. You should see `/impeccable` in the autocomplete. Type it and the skill's argument hint will show all available commands.
## Step 2. Teach Impeccable about your project
@@ -42,7 +54,7 @@ The skill will ask you a handful of questions:
- **Any visual references?** Screenshots, sites, design systems you admire.
- **Anti-references?** Things the product should explicitly not look like.
Answer in your own words. The skill writes a `.impeccable.md` file with the answers. Every future skill call reads it automatically.
Answer in your own words. The skill writes a `.impeccable.md` file with the answers. Every future command run reads it automatically.
Open `.impeccable.md` and read what it wrote. Edit anything that does not feel right. The file is yours.
@@ -51,7 +63,7 @@ Open `.impeccable.md` and read what it wrote. Edit anything that does not feel r
Pick a page that already exists. An about page, a settings screen, a pricing table, anything. Run:
```
/polish the pricing page
/impeccable polish the pricing page
```
The skill will walk through alignment, spacing, typography, color, interaction states, transitions, and copy. It makes targeted fixes, not a rewrite. Expect a handful of small diffs that together lift the page from "done" to "done well".
@@ -71,9 +83,10 @@ Review the diff. If something does not feel right, ask the model to explain the
## What to try next
- `/critique the landing page` runs a full design review with scoring, persona tests, and automated detection. It is the best way to find what to fix next.
- `/audit the checkout` runs accessibility, performance, theming, responsive, and anti-pattern checks against the implementation. Useful before shipping.
- `/impeccable critique the landing page` runs a full design review with scoring, persona tests, and automated detection. It is the best way to find what to fix next.
- `/impeccable audit the checkout` runs accessibility, performance, theming, responsive, and anti-pattern checks against the implementation. Useful before shipping.
- `/impeccable craft a pricing page for enterprise customers` runs the full shape-then-build flow on a brand new feature.
- `/impeccable redo this hero section` works too. Any description after `/impeccable` applies the design principles to the task.
## Common issues