From 5623f75c3b2a243ea9305ece4da3b266ebd04072 Mon Sep 17 00:00:00 2001 From: Paul O'Reilly Date: Thu, 23 Jul 2026 09:39:51 +1200 Subject: [PATCH] docs: impeccable skill maintenance/install reference + CLAUDE.md pointer row Claude-Session: https://claude.ai/code/session_01DTLFEx7r7AKsLerGtsnu8g --- CLAUDE.md | 1 + claude/impeccable.md | 96 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 97 insertions(+) create mode 100644 claude/impeccable.md diff --git a/CLAUDE.md b/CLAUDE.md index 7200afd..8abe7f1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -109,3 +109,4 @@ Pull one of these in only when the situation calls for it. Listed in roughly des | [`claude/script-skill-documentation.md`](./claude/script-skill-documentation.md) | Authoring or editing a script in claude-foundations or a skill in custom-claude-skills | | [`claude/knowledge-distillation.md`](./claude/knowledge-distillation.md) | Running `/log`, `/reflect-logs`, or `/distill-best-practices` | | [`claude/ask-minimax-usage.md`](./claude/ask-minimax-usage.md) | Considering delegating a file-heavy task to MiniMax | +| [`claude/impeccable.md`](./claude/impeccable.md) | Skill maintenance/install for Impeccable (design skill): updating the version, re-applying the no-auto-invoke flag, hint-shim sync, detector usage | diff --git a/claude/impeccable.md b/claude/impeccable.md new file mode 100644 index 0000000..4c11ccc --- /dev/null +++ b/claude/impeccable.md @@ -0,0 +1,96 @@ +# 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 ` 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 [--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).