97 lines
4.4 KiB
Markdown
97 lines
4.4 KiB
Markdown
# Impeccable — design skill: install, maintenance, usage
|
||
|
||
[Impeccable](https://impeccable.style/) (GitHub: `pbakaus/impeccable`, Apache 2.0) is a
|
||
design vocabulary system for AI agents: 23 design commands, a per-project DESIGN.md
|
||
contract, and a deterministic 46-rule anti-slop detector.
|
||
|
||
## How it is installed here (non-standard — do not "fix")
|
||
|
||
Two skills in the **user profile** (`~/.claude/skills/`) **and mirrored into every
|
||
`~/.claude-*` profile's `skills/` dir** (octopus, octopus-anthropic, oreillyit,
|
||
oreillyit-anthropic, oreillyit-minimax — not `-secrets`), deliberately arranged so
|
||
the full skill never auto-fires:
|
||
|
||
| Path | What | Key frontmatter |
|
||
|---|---|---|
|
||
| `~/.claude/skills/impeccable/` | Full skill (SKILL.md + `reference/` + `scripts/`), copied from repo `.claude/skills/impeccable` | `disable-model-invocation: true` **(added locally — not upstream)** |
|
||
| `~/.claude/skills/impeccable-hint/` | Hand-written ~40-line shim carrying Impeccable's original auto-trigger description | `user-invocable: false` |
|
||
|
||
Rationale: the upstream description is engineered to auto-trigger on almost any
|
||
frontend vocabulary, and a full invocation loads ~10–20k tokens (SKILL.md body +
|
||
mandatory reference reads). The shim auto-fires instead and merely *suggests*
|
||
`/impeccable <command>` to the user (once per session); only the user invokes the
|
||
real skill. Idle cost ≈ one description in the skill listing; hint invocation ≈ a few
|
||
hundred tokens.
|
||
|
||
Deliberately **not** installed globally:
|
||
- the detector **hook** (`settings.json` → `hook.mjs`) — false-positive-prone on Hugo
|
||
Go-template source (flags `src="{{ … }}"` as broken-image, em-dashes in comments)
|
||
- the `impeccable-manual-edit-applier` **agent** — only Live mode uses it, and Live
|
||
mode overlaps hugo-accelerator's editorial widget + branch previews
|
||
|
||
## Updating to a new upstream version
|
||
|
||
`npx impeccable install` / the plugin marketplace will NOT maintain this arrangement.
|
||
Update manually:
|
||
|
||
```bash
|
||
cd "$(mktemp -d)"
|
||
curl -sL https://github.com/pbakaus/impeccable/archive/refs/heads/main.tar.gz | tar xz
|
||
rm -rf ~/.claude/skills/impeccable
|
||
cp -r impeccable-main/.claude/skills/impeccable ~/.claude/skills/
|
||
```
|
||
|
||
After re-applying the frontmatter edit below, mirror both skill dirs into every
|
||
profile:
|
||
|
||
```bash
|
||
for p in ~/.claude-octopus ~/.claude-octopus-anthropic ~/.claude-oreillyit \
|
||
~/.claude-oreillyit-anthropic ~/.claude-oreillyit-minimax; do
|
||
rm -rf "$p/skills/impeccable" "$p/skills/impeccable-hint"
|
||
cp -r ~/.claude/skills/impeccable ~/.claude/skills/impeccable-hint "$p/skills/"
|
||
done
|
||
```
|
||
|
||
Then **re-apply the local edit** — add below `user-invocable: true` in
|
||
`~/.claude/skills/impeccable/SKILL.md`:
|
||
|
||
```yaml
|
||
disable-model-invocation: true
|
||
```
|
||
|
||
If upstream's `description:` changed, copy the new text into
|
||
`~/.claude/skills/impeccable-hint/SKILL.md` so the shim's trigger surface stays in
|
||
sync. If upstream added/renamed commands, refresh the shim's command table.
|
||
|
||
Installed version: check `version:` in `~/.claude/skills/impeccable/SKILL.md`
|
||
(3.9.1 as of 2026-07-22).
|
||
|
||
## Detector (no skill involvement, plain npx)
|
||
|
||
```bash
|
||
npx impeccable detect <path|url> [--json] # 46 deterministic rules, no LLM
|
||
npx impeccable ignores add-value overused-font Inter --reason "Brand font"
|
||
```
|
||
|
||
- **Output streams:** the human-readable report goes to **stderr**; `--json` goes to
|
||
stdout. In CI, capture with `2>&1 | grep -v 'npm WARN'` — a bare `2>/dev/null`
|
||
silently discards the entire text report.
|
||
|
||
- Run against **rendered output** (`public/` after a Hugo build), never template
|
||
source — raw Go templates false-positive.
|
||
- Staging URLs are Authelia-gated → the detector would score the login page; use a
|
||
local build or port-forward.
|
||
- Needs Node ≥ 22.12 per engines; observed working on Node 18 with EBADENGINE
|
||
warnings only. Pin the version in any CI use (no `@latest`).
|
||
- Ignores/config live in `.impeccable/config.json` per repo — a template-sync surface
|
||
if adopted fleet-wide (hugo-accelerator `template_consumers.json`).
|
||
|
||
## Planned integrations (recommendations, 2026-07-22)
|
||
|
||
- **hugo-ci (M13):** `npx impeccable detect public/ --json` post-render, advisory
|
||
first, gate later.
|
||
- **cms-proxy AI edit / M6 drafting:** per-customer DESIGN.md (bootstrap interview or
|
||
`/impeccable document`) injected into the AI edit prompt alongside component schemas.
|
||
- **agent-runtimes:** detector as post-task verify step for frontend tasks; full skill
|
||
baked only into design-scoped harness templates (Node 22+ images).
|