Impeccable: installare e usare la skill per agenti AI

Quando un agente AI modifica una UI, il problema non è solo scrivere codice valido. Il problema è fargli rispettare contesto, registro, design system, accessibilità, comportamento responsive e casi limite.

Senza istruzioni precise, un modello tende a riempire i vuoti con pattern ricorrenti: card tutte uguali, abuso di gradienti, testi poco leggibili, hero section da SaaS generico. Il risultato può anche sembrare corretto a prima vista, ma resta difficile da mantenere quando il progetto cresce.

Impeccable, creato da Paul Bakaus, nasce per risolvere proprio questo pezzo del problema: portare dentro gli agenti AI una disciplina di design più esplicita, più verificabile e meno dipendente dal “gusto implicito” del modello.

Non è una libreria di componenti. Non è un framework CSS. Non è un template.

Impeccable è una skill per agenti AI che aggiunge un linguaggio operativo per progettare, valutare, rifinire e correggere interfacce front-end. La documentazione ufficiale la sintetizza così: una skill, 23 comandi, iterazione visuale nel browser e un rilevatore con regole deterministiche per riconoscere pattern tipici del front-end generato male.

A chi serve?

• A me, per esempio, per correggere alcuni dettagli dell’aspetto delle pagine di questo journal/blog. Sì, avevo fatto gran parte del lavoro manualmente. No, non sono contrario all’AI
• A sviluppatori senior che stanno già usando Codex, Claude Code, Cursor o strumenti simili e vogliono evitare che in onore alla produttività vengano consegnate UI mediocri
• A team front-end che hanno un design system e vogliono che gli agenti lo rispettino (@Encodia, questo articolo parla di noi!)
• Ad agenzie e consulenti che lavorano su landing, siti corporate, dashboard e prodotti SaaS senza voler delegare le scelte visuali a istruzioni generiche
• A responsabili tecnici che vogliono introdurre AI nel flusso di lavoro, ma con revisioni, contesto e regole condivise

Che cosa fa Impeccable

Impeccable aggiunge tre cose che, in un flusso con agenti AI, mancano spesso.

La prima è il contesto persistente. Con /impeccable init il progetto produce file come PRODUCT.md e DESIGN.md, cioè documenti che spiegano audience, obiettivi, registro visivo, voce, anti-riferimenti, colori, tipografia, componenti e regole. Non sono note decorative. Sono materiale che l’agente rilegge prima di intervenire.

La seconda è un vocabolario di comandi. Invece di scrivere ogni volta “rendi questa pagina più bella, professionale, ma non troppo”, usi comandi mirati:

• /impeccable critique per una revisione di UX e visual design
• /impeccable audit per controlli tecnici su accessibilità, responsive, performance e implementazione
• /impeccable polish per il passaggio finale prima di consegnare
• /impeccable harden per edge case, overflow, i18n, stati vuoti ed errori
• /impeccable typeset, layout, colorize, animate, distill, bolder, quieter per interventi più specifici

La terza è il rilevatore. Impeccable include una CLI di rilevazione che scansiona file o URL e segnala anti-pattern deterministici: non richiede un LLM, non richiede una chiave API e può essere usata anche fuori dal flusso conversazionale.

1
npx impeccable detect src/
2
npx impeccable detect index.html
3
npx impeccable detect https://example.com
4
npx impeccable detect --json .

Questo è importante perché un agente può giustificare una modifica anche quando sta introducendo difetti di UI. Un rilevatore non sostituisce la revisione, ma riduce alcune classi di regressione: font scelti per riflesso, padding troppo stretti, aree cliccabili troppo piccole, gerarchie saltate, pattern visivi consumati, scelte cromatiche fragili.

Prima di installare

I prerequisiti pratici:

• un progetto front-end reale, con repository Git e una struttura riconoscibile;
• Node.js, npm e npx disponibili nello stesso ambiente in cui userai l’agente;
• un agente AI supportato, per esempio Codex CLI, Claude Code, Cursor, Gemini CLI, GitHub Copilot o OpenCode;
• area di lavoro Git pulita o comunque con modifiche già comprese e separate dalla configurazione di Impeccable.

Verifica versioni e stato Git:

1
node --version
2
npm --version
3
npx --version
4
git status --short

Da qui in poi, quando non indicato diversamente, i comandi sono identici su macOS, Linux e Windows PowerShell.

Nota su Windows

Da molti anni non uso Windows come ambiente principale. Ho controllato i comandi PowerShell riportati in questo articolo, anche con il supporto di strumenti AI, ma se lavori stabilmente su Windows ti consiglio di verificarli nel tuo ambiente prima di inserirli in procedure condivise.

Esegui i comandi dal root del progetto. Per spostarti nella cartella del repository, su macOS e Linux:

1
cd /percorso/del/progetto

Su Windows PowerShell:

1
Set-Location "C:\percorso\del\progetto"

Se lavori in WSL, installa ed esegui Node, l’agente e Impeccable dentro WSL. Evita configurazioni miste in cui il repository sta nel file system Linux ma lo strumento AI o Node girano da Windows: percorsi e hook diventano più difficili da diagnosticare.

Un’area di lavoro Git pulita non è un requisito tecnico assoluto, ma è una buona pratica. L’installer può aggiungere cartelle di skill, manifest degli hook e file di configurazione. Se il progetto ha già modifiche in corso, diventa più difficile capire cosa sia cambiato.

Installazione consigliata

Dal root del progetto:

1
npx impeccable install

Se PowerShell non risolve npx, usa l’eseguibile esplicito:

1
npx.cmd impeccable install

La stessa regola vale per gli altri comandi: sostituisci npx con npx.cmd solo se PowerShell non trova npx.

L’installer rileva gli strumenti disponibili, per esempio cartelle come ~/.claude, ~/.codex o .cursor, e chiede dove installare la skill: nel progetto oppure a livello globale.

In un team, io tendo a preferire l’installazione nel progetto quando la skill deve essere parte del flusso di lavoro di quel repository: la configurazione resta nel codice e può essere rivista come qualsiasi altra modifica.

Per script o configurazioni ripetibili puoi saltare le domande interattive:

1
npx impeccable install --providers=codex,cursor,claude --scope=project

Aggiornamento:

1
npx impeccable update

Questo è il percorso normale. Il repository documenta anche alternative come submodule Git, archivio ZIP o copia manuale dall’output dist/, ma le considererei opzioni di ripiego o scelte da team che vogliono includere esplicitamente il codice di Impeccable nel repository.

Installazione con submodule Git

Se vuoi tenere il codice di Impeccable dentro il repository, puoi usare un submodule Git:

1
git submodule add https://github.com/pbakaus/impeccable .impeccable
2
npx impeccable link --source=.impeccable --providers=codex,cursor

Su PowerShell resta valido lo stesso comando; se necessario, sostituisci solo npx con npx.cmd nella seconda riga.

È una scelta più esplicita, ma anche più pesante: devi aggiornare il submodule e rieseguire impeccable link quando vuoi cambiare versione.

Nota specifica per Codex

Con Codex ci sono due dettagli da sapere.

Il primo: Impeccable installa skill, non “prompt” nel senso generico del termine. Nel README ufficiale viene chiarito che gli utenti Codex possono aprire /skills oppure invocare la skill con $impeccable, a seconda dell’interfaccia usata. Nei documenti ufficiali molti esempi sono scritti nella forma slash:

1
/impeccable audit
2
/impeccable polish the header
3
/impeccable live

In Codex, se il comando slash non viene risolto come skill, usa la forma:

1
$impeccable audit src/pages/index.astro
2
$impeccable polish the contact section

Il secondo dettaglio riguarda gli hook. Per Codex, l’installer può creare .codex/hooks.json, ma l’approvazione resta esplicita. Dopo l’installazione o l’aggiornamento apri:

1
/hooks

e approva il design hook del progetto. Codex traccia la fiducia in base alla definizione dell’hook, quindi dopo un aggiornamento potrebbe chiederti di approvarlo di nuovo.

Inizializzare il contesto

Installare la skill non basta. Il passaggio decisivo è:

1
/impeccable init

oppure, in Codex:

1
$impeccable init

init fa domande sul progetto e scrive contesto persistente. La distinzione più importante è fra brand e product.

Un sito marketing, una landing, un portfolio o un long-form editoriale sono superfici in cui il design è parte del prodotto percepito. Una dashboard, un back office o uno strumento operativo sono superfici in cui il design deve servire velocità, chiarezza, controllo e ripetizione d’uso.

Questa distinzione sembra banale, ma evita molte risposte sbagliate. Una pagina di vendita non deve essere trattata come una tabella amministrativa. Una console operativa non deve sembrare una campagna di brand. Senza contesto, il modello tende a mescolare registri.

Nei progetti già avviati può avere senso aggiungere anche:

1
/impeccable document

Questo comando analizza il codice esistente e aiuta a generare un DESIGN.md coerente con quello che il progetto sta già facendo: token, colori, tipografia, componenti, ritmo, pattern ricorrenti. È particolarmente utile quando la UI esiste già e non vuoi che l’agente reinventi tutto.

Un flusso di lavoro realistico

Il modo peggiore di usare Impeccable è chiamarlo solo alla fine, dopo aver accettato trecento righe di front-end generico.

Un flusso più sano è questo:

1
/impeccable init
2
/impeccable audit src/pages/index.astro
3
/impeccable critique homepage
4
/impeccable polish homepage

Su un nuovo blocco di interfaccia:

1
/impeccable shape technical consulting hero
2
/impeccable craft technical consulting hero
3
/impeccable polish hero

Su un’interfaccia già funzionante ma ancora grezza:

1
/impeccable layout customer dashboard
2
/impeccable typeset customer dashboard
3
/impeccable harden customer dashboard

La logica è semplice:

1. Shape quando devi ragionare prima di costruire.
2. Craft quando vuoi far seguire implementazione alla direzione definita.
3. Critique quando vuoi una revisione, anche severa.
4. Audit quando ti interessano i controlli tecnici.
5. Polish quando il pezzo funziona, ma deve arrivare a livello consegnabile.
6. Harden quando il problema non è più estetico, ma di robustezza in produzione.

Questi comandi servono a limitare il perimetro del lavoro. L’agente non sta “migliorando la pagina” in modo generico: sta facendo un audit, una critique, un polish o un hardening con criteri diversi.

Audit, critique e polish non sono sinonimi

Vale la pena separarli, perché nel lavoro quotidiano si finisce spesso a usarli come se fossero tre varianti di “controlla questa cosa”.

audit ha un taglio tecnico. Si usa quando vuoi trovare problemi verificabili: accessibilità, responsive, performance, interazioni, implementazione, stati mancanti.

1
/impeccable audit blog post page

critique è più vicino a una revisione di UX e direzione visiva. Serve a capire se la pagina comunica bene, se la gerarchia tiene, se l’impressione è coerente con il pubblico e se il registro è quello giusto.

1
/impeccable critique landing page

polish è il passaggio da “funziona” a “si può consegnare”. Non dovrebbe inventare un’altra direzione. Dovrebbe eliminare frizioni, incoerenze, piccoli problemi di ritmo, spaziatura, overflow, stati hover/focus e scelte non allineate al design system.

1
/impeccable polish pricing section

Per un team, questa distinzione aiuta anche nella revisione umana. Un audit può produrre ticket tecnici. Una critique può produrre decisioni di direzione. Un polish dovrebbe produrre una diff piccola e intenzionale.

Usare i design hook

Gli hook sono uno dei pezzi più interessanti, perché spostano il controllo vicino al momento in cui il problema nasce.

Secondo la documentazione sugli hook, Impeccable può installare hook specifici per Claude Code, GitHub Copilot, Codex e Cursor. Il comportamento cambia leggermente in base allo strumento: alcuni eseguono il controllo dopo la modifica, Cursor può intervenire prima che una proposta venga applicata.

Per controllare lo stato:

1
/impeccable hooks status

Per abilitarli o disabilitarli:

1
/impeccable hooks on
2
/impeccable hooks off

Quando un finding è intenzionale, non bisogna silenziarlo a caso. Meglio registrare eccezioni strette, con una ragione:

1
/impeccable hooks ignore-value overused-font Inter --shared --reason "Brand font"
2
/impeccable hooks ignore-file "src/legacy/Card.tsx"
3
/impeccable hooks ignore-rule side-tab

Un rilevatore utile produce anche falsi positivi. Il punto non è obbedire sempre, ma mantenere traccia delle eccezioni.

Live Mode

/impeccable live è la parte più sperimentale e, al tempo stesso, una delle più interessanti.

L’idea è lavorare nel browser su un dev server reale. Prima avvii il progetto:

1
npm run dev

Poi lanci:

1
/impeccable live

poi selezioni un elemento nella pagina: hero, scheda, modulo, blocco prezzi. Puoi descrivere cosa vuoi ottenere, scegliere azioni come bolder, quieter, distill, polish, typeset, colorize, layout, animate, delight, oppure lasciare commenti e segni sull’elemento. Impeccable genera varianti, le mostra nella pagina tramite HMR e, quando ne accetti una, scrive le modifiche nella sorgente.

La documentazione lo dichiara ancora in stato alpha. Va quindi usato con lo stesso criterio con cui si usa qualsiasi strumento potente ma giovane: branch Git dedicato, diff controllata, revisione attenta.

Non lo userei per “rifare tutta la pagina”. Lo userei per esplorare alternative su un elemento circoscritto, quando la UI è già leggibile e il contenuto è già reale.

La CLI di rilevazione fuori dall’agente

Il rilevatore non serve solo dentro la conversazione con l’agente. Puoi usarlo anche da terminale:

1
npx impeccable detect src/
2
npx impeccable detect --json src/

Puoi scansionare anche un file o un URL:

1
npx impeccable detect index.html
2
npx impeccable detect https://example.com

In PowerShell puoi usare anche la forma .\index.html per un file nella cartella corrente. Se npx non viene risolto, applica la stessa regola già vista: npx.cmd impeccable detect .\index.html.

La scansione URL usa un browser tramite Puppeteer. In CI o su macchine minimali può richiedere dipendenze di sistema aggiuntive; per partire, la scansione di src/ è più prevedibile.

In pratica, questo apre tre possibilità:

• controllo manuale prima della revisione;
• integrazione in CI con output JSON;
• configurazione di eccezioni condivise per pattern intenzionali del design system.

Le eccezioni possono vivere nella configurazione Impeccable o anche come commenti inline, per esempio quando una regola va disattivata in un file specifico per ragioni documentate.

Non bisogna confondere rilevatore e qualità complessiva. Un rilevatore vede alcune cose. Non vede la strategia, non conosce il posizionamento, non capisce da solo se una scelta forte è giusta per quel brand. Va usato come rete di controllo, non come criterio unico.

Come parlarci bene

Con una skill così, la qualità dell’input resta fondamentale.

Un comando povero:

1
/impeccable make this better

Un comando più utile:

1
/impeccable polish src/pages/index.astro focusing on mobile spacing, CTA hierarchy and text overflow

Ancora meglio, se il progetto ha contesto:

1
/impeccable critique the homepage against PRODUCT.md and DESIGN.md. Focus on whether the first viewport communicates senior technical consulting, not generic agency positioning.

Esempi pratici:

1
/impeccable audit src/components/ContactForm.astro
2
/impeccable harden the onboarding flow for empty states, long labels and error messages
3
/impeccable typeset the article page so code blocks, h2 and long Italian headings feel balanced
4
/impeccable quieter the pricing section without losing conversion intent
5
/impeccable distill the customer panel header to the controls operators actually need every day

La regola è: dai un bersaglio, un criterio e un limite.

Il bersaglio è il file, la route o la sezione. Il criterio è cosa deve migliorare. Il limite è cosa non deve cambiare.

Dove Impeccable non basta

Impeccable non risolve problemi che non riguardano l’esecuzione front-end.

Se il posizionamento è debole, la skill non lo inventa al posto tuo. Se i testi non dicono nulla, può ripulirli, ma non può sapere quale promessa commerciale sia vera. Se il design system è incoerente, può documentare quello che trova, ma servirà comunque una decisione umana su cosa tenere e cosa buttare.

Non sostituisce:

• una direzione creativa;
• una ricerca utente;
• un design system governato;
• una revisione di accessibilità completa;
• una persona responsabile della qualità finale.

Il valore è un altro: rende l’agente meno generico, più consapevole del contesto e più controllabile.

Come lo introdurrei in un team

Non partirei da Live Mode. Non partirei nemmeno dagli hook.

Partirei così:

1. installazione nel progetto su un branch Git dedicato;
2. /impeccable init con un tecnico e una persona di prodotto/design presenti;
3. revisione manuale di PRODUCT.md e DESIGN.md;
4. primo /impeccable audit su una pagina reale;
5. primo /impeccable polish su una sezione circoscritta;
6. confronto della diff in revisione del codice;
7. solo dopo, attivazione degli hook.

Questo evita l’errore classico: installare uno strumento, lasciargli scrivere regole e poi subire le sue correzioni.

Impeccable va trattato come un collaboratore tecnico con una lista di controllo forte, non come un arbitro assoluto.

Una nota sul gusto

La parte più interessante di Impeccable non è che “sa fare design”. È che prova a trasformare parte del gusto in criteri leggibili dall’agente.

Questa è una differenza sostanziale.

Dire “non voglio una UI da template SaaS” è meglio di dire “fammi una cosa più curata”. Dire “questo brand usa un solo accento, niente gradient text, niente card annidate, niente hero metric” è ancora meglio. Dire “il pubblico è composto da decisori tecnici che stanno valutando un consulente, non da utenti che comprano un prodotto self-service” cambia il tipo di interfaccia che l’agente dovrebbe produrre.

Un senior questo lo fa già mentalmente.

Impeccable serve a renderlo esplicito, versionabile e riusabile.

Conclusione

Gli agenti AI accelerano il lavoro, ma peggiorano il front-end se non hanno vincoli buoni. Questo si vede presto, perché la UI è il punto in cui scelte tecniche, percezione, accessibilità, contenuto e brand si incontrano.

Impeccable è interessante perché non promette solo di “migliorare il design”. Porta un metodo: contesto, comandi, rilevazione, hook e iterazione nel browser.

Installarlo è semplice:

1
npx impeccable install

Usarlo bene richiede più disciplina:

1
/impeccable init
2
/impeccable audit
3
/impeccable critique
4
/impeccable polish

La differenza sta lì. Non nello strumento in sé, ma nel modo in cui lo inserisci nel processo.

Se lo usi solo alla fine, come rifinitura estetica, lo stai usando male. Se lo inserisci nel processo, può aiutarti a far produrre agli agenti AI interfacce più coerenti, più robuste e meno riconoscibili come output generico.