Critique was vibes-only before. Now it scores against Nielsen's 10 heuristics
(0-4 each, /40 total) so you get a number, not just feelings. Added 5 user
personas that auto-select based on the interface type — a power user and a
first-timer break different things, turns out. Cognitive load checklist catches
the "why does this screen make my brain hurt" problems.
Audit gets the same treatment: 0-4 per dimension, /20 total, P0-P3 severity
instead of the vague Critical/High/Medium/Low labels nobody agrees on.
Both now present recommendations inline — no plan file, no /next or /fix-all
commands. Just tell the AI what to fix and it does it. Simpler.
New reference files: heuristics-scoring, personas, cognitive-load.
The build system hardcoded `/` as the command prefix for every provider,
but Codex CLI uses `$`. Added command_prefix to PROVIDER_PLACEHOLDERS
so replacePlaceholders and prefixSkillReferences use the right one.
Now `$normalize` shows up in Codex output instead of `/normalize`.
Adds the gtag.js snippet (G-TEXGHC7V34) to both HTML pages for
tracking pageviews and usage.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Slash commands do work in Antigravity, so the asterisk and tooltip
warning on the Antigravity badge were incorrect. Removes both.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Previously only .claude/skills/ was synced from dist after build. Now
all 8 provider directories are synced (.claude, .cursor, .gemini, .codex,
.agents, .kiro, .opencode, .pi) so each provider's output can be tested
directly in this repo.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Addresses #51 -- Antigravity doesn't support slash commands, only
auto-activated skills. Adds a tooltip on the Antigravity* badge in the
downloads section explaining the limitation and how to invoke skills by
name. Also adds hover tooltips showing provider names on the hero logo
icons.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
PR #50 fixed the output SKILL.md files but the source files, build
scripts, tests, docs, and server code still used the wrong spelling.
Claude Code expects `user-invocable` (with c) for slash command
autocomplete to work.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
CI was running `bun test` which ran jsdom fixture tests in bun, causing
timeouts. Now uses `bun run test` which runs unit tests in bun and fixture
tests in node.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Fix README CLI examples to use `bun bin/impeccable.mjs` instead of `npx impeccable`
- Fix classList.match() crash in Node/jsdom by converting DOMTokenList to string
- Fix overlapping page-level banners by merging all findings into a single banner
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
Hey @pbakaus 👋
I ran your skills through `tessl skill review` at work and found some targeted improvements. Here's the full before/after:
| Skill | Before | After | Change |
|-------|--------|-------|--------|
| distill | 31% | 80% | +49% |
| delight | 32% | 74% | +42% |
| polish | 44% | 80% | +36% |
| animate | 55% | 89% | +34% |
| clarify | 49% | 83% | +34% |
| critique | 51% | 85% | +34% |
| normalize | 46% | 80% | +34% |
| optimize | 49% | 83% | +34% |
| adapt | 48% | 81% | +33% |
| extract | 48% | 81% | +33% |
| harden | 49% | 79% | +30% |
| arrange | 51% | 76% | +25% |
| bolder | 51% | 76% | +25% |
| colorize | 48% | 72% | +24% |
| overdrive | 48% | 70% | +22% |
| typeset | 64% | 85% | +21% |
| audit | 61% | 81% | +20% |
| onboard | 56% | 75% | +19% |
| quieter | 59% | 76% | +17% |
| teach-impeccable | 68% | 80% | +12% |
| frontend-design | 76% | 76% | +0% |
**Note:** These skills are auto-generated from `source/skills/` via your build system, so the changes target the source files directly. The `dist/` outputs were regenerated with `bun run build`.
<details>
<summary>Changes made</summary>
All changes are limited to the `description` field in each skill's YAML frontmatter (in `source/skills/*/SKILL.md`). No skill body content was modified.
The consistent improvement across all skills was adding:
- **"Use when..." clauses** with explicit trigger terms — the #1 issue flagged by the reviewer. Without these, agents have no clear signal for when to select a skill from a large library.
- **Natural user keywords** — terms users would actually say (e.g., "too bold", "laggy", "spacing issues") rather than abstract descriptors.
- **Specific concrete actions** — listing what the skill actually does rather than describing outcomes in vague terms.
- **Quoted string format** — ensuring descriptions use standard YAML quoted strings.
`frontend-design` was already well-scored and left unchanged.
</details>
## Type of change
- [x] New / updated skill reference
## Checklist
- [x] Source files updated in `source/`
- [x] `bun run build` ran successfully
- [x] `bun test` passes
- [ ] Tested with at least one provider (Cursor / Claude Code / Gemini CLI / Codex / Copilot / Kiro / OpenCode)
- [ ] README / DEVELOP.md updated if needed
---
Honest disclosure — I work at @tesslio where we build tooling around skills like these. Not a pitch - just saw room for improvement and wanted to contribute.
Want to self-improve your skills? Just point your agent (Claude Code, Codex, etc.) at [this Tessl guide](https://docs.tessl.io/evaluate/optimize-a-skill-using-best-practices) and ask it to optimize your skill. Ping me - [@rohan-tessl](https://github.com/rohan-tessl) - if you hit any snags.
Thanks in advance 🙏
- Add {{scripts_path}} build placeholder that resolves per-provider
(${CLAUDE_PLUGIN_ROOT}/scripts for Claude Code, relative paths for others)
- Restructure critique into sub-agent architecture: LLM review and
detector run independently to avoid bias, results synthesized at end
- Browser overlay is now a visual aid for the user only -- agent reads
findings from console via [impeccable] prefix instead of scrolling
- Add scroll-to-top instruction before overlay injection
- Add allowed-tools frontmatter for detector bash commands
- Fix YAML parser to handle simple string arrays (not just - name: objects)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Claude was running the detector in parallel with the LLM review
despite the section ordering. Added explicit instruction: "Do not
run the detector before or in parallel with your LLM review."
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The detector findings were anchoring the LLM's thinking too heavily,
making the critique feel detector-driven rather than design-driven.
Now the LLM forms its own assessment first, then the detector runs
to catch anything missed. The report structure reflects this: LLM
assessment comes before deterministic scan in the Anti-Patterns
Verdict.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Detection fixes:
- Cramped padding: skip small elements (labels/badges < 100x30px)
and require >20 chars of text content
- Skip browser extension elements (claude-*, cic-*) from scan loop
and quality checks to avoid flagging the Claude Chrome indicator
Skill prompt fixes:
- Use python HTTP server + script tag injection instead of direct
javascript_tool evaluation (avoids CORS issues)
- Add cleanup step for the HTTP server
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
URLs should use browser visualization + LLM analysis instead of
the CLI detector, which would need to install Puppeteer and its
dependencies first.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The critique skill now has three layers of detection:
1. CLI-first pass (always): Runs the deterministic detector via
`node {{skills_dir}}/critique/scripts/detect-antipatterns.mjs --json`
with scope checks (file count estimation, --fast for 200-500 files,
user prompt for >500 files)
2. Browser visualization (when available): If the AI harness has
browser automation (Chrome MCP, Cursor browser), injects the
detection script into the page for live visual overlays. Reads
the browser script via cat, injects via javascript_tool.
3. LLM analysis (always): The existing deep design critique across
10 dimensions, now informed by deterministic scan results.
Add {{skills_dir}} placeholder to build system for cross-provider
script paths (.claude/skills, .cursor/skills, .gemini/skills, etc).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Usage: npx impeccable detect [file-or-dir-or-url...]
Subcommand structure designed for future expansion. The detect
subcommand delegates to the existing detection engine with all
its modes (jsdom, regex, Puppeteer).
- bin/impeccable.mjs: CLI entry point with bun shebang
- package.json: bin field added
- Export detectCli (main) from detection script
- Updated help text to show impeccable detect usage
- Updated CLAUDE.md and README.md with CLI docs
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Switch from border to CSS outline for overlays (cleaner, animatable)
- On hover: outline expands outward 4px, label shifts up to match,
tooltip slides in from below with fade, z-index elevates above others
- Exclude page banner from hover transitions via .impeccable-banner class
- Reposition overlays on window resize via requestAnimationFrame
- CSS-only hover states (no JS event listeners)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
New detections (browser-only, DOM-based):
- line-length: text wider than ~85 chars per line
- cramped-padding: <8px padding in bordered/bg containers (2+ borders)
- tight-leading: line-height < 1.3x on body text
- small-target: interactive elements < 44x44px
- skipped-heading: heading levels that skip (h1 then h3)
- justified-text: text-align: justify without hyphens: auto
- tiny-text: font-size < 12px on body text (>20 chars)
- all-caps-body: text-transform: uppercase on >30 chars of body text
- wide-tracking: letter-spacing > 0.05em on non-uppercase body text
Browser overlay improvements:
- Hover swaps label for detail tooltip (CSS-based, not JS events)
- Border goes transparent on hover to reveal element underneath
- Fixtures: quality-should-flag.html and quality-should-pass.html
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Output skills to both .trae-cn/ and .trae/ directories
- Update README with installation instructions for both versions
- Update DEVELOP.md with dual-variant documentation
- Add trae.js transformer with full metadata support (same as Claude Code)
- Update build.js to include Trae in provider transformations
- Update README.md with Trae installation instructions
- Update DEVELOP.md with Trae transformer documentation
Trae uses ~/.trae-cn/builtin_skills/ for skills installation.
Detection improvements:
- Remove SAFE_TAGS from glow check (buttons/links with glows are valid)
- Add gradient color parsing (parseGradientColors) for AI palette
detection on gradient backgrounds including buttons
- Detect cyan neon text on dark backgrounds as AI palette
- Resolve gradient backgrounds as dark for glow detection
- Fix pure-black false positive on semi-transparent overlays (a >= 0.9)
- Skip low-contrast/gray-on-color when background is a gradient
- Fix "Only font:" double-colon in browser labels
Test performance:
- Split jsdom fixture tests to Node's test runner (bun + jsdom hangs
after ~13 instances due to resource leak)
- bun test for unit/regex/CLI tests (94 tests, 4s)
- node --test for jsdom fixtures (15 tests, 1.3s)
- Total: 109 tests in ~5s (was 280s+)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Fixes#49 - Skills don't appear in / menu because Claude Code expects
user-invocable (with 'c') not user-invokable (with 'k').
This typo affected all 20 skill files, making them invisible in the
slash command autocomplete menu despite still working when invoked directly.
Extract all regex-on-HTML checks into shared checkHtmlPatterns()
function called by both browser and Node paths. Eliminates drift
between checkTypography/checkPageTypography and removes separate
checkPageMotion/checkPageGlow functions.
Add parseGradientColors() utility and checkElementGradientDOM()
to detect purple/violet gradient backgrounds on any element
including buttons (bypasses SAFE_TAGS). Fix false low-contrast
findings on gradient backgrounds by returning null from
resolveBackground when a gradient is encountered.
Fix "Only font:" double-colon in browser labels.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace the detector summary card and badge system with a simple
inline note below the tabbed Do/Don't patterns: "/critique catches
all of these. 16 deterministically, the rest through LLM analysis."
Gallery of Shame and Suggest a pattern links sit inline alongside.
Subtle divider separates the note from the patterns above.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace the buried "Gallery of Shame" inline link with a compact
detector summary card showing all 16 auto-detected anti-patterns
as chips grouped by category (Borders, Typography, Color, Layout,
Motion). Prominent gallery link in the footer. Revised lead copy
to mention the automated detector.
Keeps the tabbed Do/Don't pattern reference below unchanged.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Paul BakausandGitHub
Gabi
rohan-tessl
rohan-tesslandGitHub
shog86
Matt Van HornandClaude Opus 4.6
GujiasshandSisyphus
Jah-yee