Aggiungi la scheda di diagram-design

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-17 19:27:00 +02:00
1 parent 05582b3c74
commit 38b1d95ceb
@@ -7,6 +7,7 @@ Il mio dizionario delle skill per agenti AI (Claude Code, Codex, app di Claude e
 | Skill | Descrizione |
 |---|---|
 | [claude-plugins-official](skills/claude-plugins-official.md) | Marketplace ufficiale di Anthropic per Claude Code: catalogo di plugin con integrazioni, analisi del codice e flussi di sviluppo. |
+| [diagram-design](skills/diagram-design.md) | Fa disegnare all'agente diagrammi curati (45 tipi) come file HTML con SVG, nei colori e nei font del tuo sito, e rifà quelli in draw.io, Mermaid ed Excalidraw. |
 | [find-skills](skills/find-skills.md) | Permette all'agente di cercare e installare da solo altre skill con `npx skills`. |
 | [graphify](skills/graphify.md) | Trasforma codice, documenti e media di un progetto in un grafo di conoscenza che l'agente interroga invece di rileggere i file. |
 | [obsidian-skills](skills/obsidian-skills.md) | Raccolta ufficiale di sei skill per Obsidian: Markdown di Obsidian, Bases, Canvas, riga di comando, estrazione di pagine web e modelli. |
@@ -0,0 +1,152 @@
+# diagram-design
+
+- **Autore:** Cathryn Lavery (LittleMight)
+- **Repository:** [cathrynlavery/diagram-design](https://github.com/cathrynlavery/diagram-design) (licenza MIT)
+- **Sorgente:** [skills/diagram-design/SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) (versione 2.6)
+- **Sito e galleria:** [diagramdesign.dev](https://diagramdesign.dev) · [galleria dei diagrammi](https://cathrynlavery.github.io/diagram-design/)
+- **Pagina su skills.sh:** [cathrynlavery/diagram-design/diagram-design](https://skills.sh/cathrynlavery/diagram-design/diagram-design)
+- **Diffusione (ottobre 2026):** circa 14.300 installazioni; il repository ha circa 56.800 stelle su GitHub
+- **Controlli di sicurezza su skills.sh:** Gen Agent Trust Hub, Socket e Snyk superati, senza avvisi
+
+## A cosa serve
+
+Fa disegnare all'agente diagrammi curati nello stile della tua grafica, invece dei soliti riquadri arrotondati generici. Ogni diagramma è un unico file HTML con SVG incorporato, che si apre con un doppio clic. Lo stile è editoriale e prevede un solo colore d'accento per uno o due elementi chiave, linee sottili, nessuna ombra e coordinate su una griglia di 4 pixel. Può prendere colori e font dal tuo sito e rifare in questo stile anche diagrammi già esistenti in draw.io, Mermaid ed Excalidraw.
+
+## Cosa fa
+
+### Quando si attiva
+
+Quando chiedi un diagramma a parole, per esempio:
+
+- "Fammi un diagramma di architettura della mia app: frontend, backend, database, cache Redis";
+- "Mi serve un quadrante con i progetti del secondo trimestre per impatto e sforzo";
+- "Dammi una sequenza di una chiamata con bearer token e refresh su 401";
+- "Onboard diagram-design to https://tuosito.com" (per prendere palette e font del sito);
+- "Redraw this drawio file for my deck" (rifare un diagramma esistente), oppure l'esportazione di un diagramma in PNG o SVG.
+
+Il `SKILL.md` elenca 45 tipi di visual (il README dice 45; la descrizione del repository su GitHub dice 44). Tra i principali: architettura, flowchart, sequence, macchina a stati, ER, timeline, swimlane, quadrante, radar, ciclo, albero, organigramma, Venn, piramide/funnel, grafici (barre, linee, scatter, treemap, heatmap, waterfall), Gantt, Sankey, Wardley map, kanban, user journey, UML a classi, schema di database.
+
+### Come lavora
+
+1. **Controlla lo stile (primo uso in un progetto).** Se lo style guide è ancora quello predefinito, si ferma e ti chiede se personalizzarlo: da URL di un sito, da una skill installata, da una cartella locale o design system, incollando i token a mano, tenendo il predefinito, o caricando un profilo salvato.
+2. **Sceglie il tipo.** Se conta il comportamento (code, colli di bottiglia, confini di fiducia, difese a strati), sceglie prima uno dei nove *semantic pattern* e poi il tipo di diagramma più vicino per il layout. Per un caso normale carica il `SKILL.md` e il riferimento di quel solo tipo.
+3. **Dichiara il piano prima di disegnare:** tipo, formato, dimensione e cosa verrà tagliato per stare nei limiti. Salta la pausa solo se la richiesta specifica già tutto.
+4. **Disegna** rispettando i limiti di complessità (al massimo 9 nodi, 12 frecce, 2 elementi con l'accento, 2 note), altrimenti propone di dividere in due diagrammi, e le sei regole obbligatorie sui connettori (solo angoli retti, spazio tra etichetta e linea, niente sovrapposizioni, punti di attacco distinti, nessun passaggio dietro a un riquadro, maschere prima dei nodi).
+5. **Controlla il risultato** con una lista di verifica e con `python3 scripts/self_check.py <file>`, che controlla accessibilità dell'SVG, file autonomo e contenuto dentro il `viewBox`.
+6. **Produce un unico file `.html`:** CSS incorporato, SVG in linea, nessuna immagine esterna. Ogni SVG ha `role="img"`, `<title>` e `<desc>`.
+
+Il principio di fondo è che la mossa migliore è di solito togliere: se una tabella o un paragrafo spiegano la stessa cosa, la skill suggerisce di non disegnare.
+
+### Personalizzare lo stile (onboarding)
+
+Senza personalizzazione i diagrammi escono in nero e arancio ("tangerine"). Con *"onboard diagram-design to https://tuosito.com"* l'agente legge la home, ricava i colori e i font, li assegna ai ruoli (`paper`, `ink`, `muted`, `accent`, `link`, font del titolo, dei nodi e dei sottotitoli), ti mostra le differenze e, dopo la tua conferma, scrive i valori in `references/style-guide.md`. Controlla anche il contrasto WCAG AA e, se non basta, propone un valore corretto.
+
+| Rilevato dal sito | Diventa |
+|---|---|
+| sfondo di `<body>` | `paper` |
+| colore del testo principale | `ink` |
+| testo secondario | `muted` |
+| card o contenitori | `paper-2` |
+| colore del marchio più usato | `accent` |
+| font di `<h1>` / `<body>` / `<code>` | font del titolo / dei nodi / dei sottotitoli |
+
+Per più clienti puoi salvare un **profilo** con nome (in `~/.diagram-design/profiles/`) e aggiungere a ogni progetto un file `.diagram-design` con `profile: <nome>`.
+
+### Importare ed esportare
+
+- **Import:** rifà (non converte) file `.drawio`, `.mmd`/`.mermaid` o blocchi Mermaid nel Markdown, e `.excalidraw`. Tiene i contenuti (componenti, relazioni, raggruppamenti, direzione) e scarta coordinate, colori e font della sorgente. Si regola con quattro opzioni: formato (`html`, `svg`, `png`, `html+png`), dimensione (`doc-inline`, `slide-16x9`, `social-og`, `print-a4-landscape`, `fit` e altre), livello di dettaglio (`faithful` fino a 24 nodi, `balanced` fino a 12, `simplified` fino a 7) e destinatari (`engineer`, `mixed`, `executive`, che cambiano le parole e non il numero di nodi). Alla fine riporta un elenco di cosa è stato unito, ridotto o scartato.
+- **Export:** su richiesta, salva il solo diagramma come SVG o PNG (`scripts/export_svg.py`, `scripts/export_png.py`). L'export non parte mai da solo. Il PNG usa Playwright (`pip install playwright && playwright install chromium`).
+- **Animazione (facoltativa):** modalità `none` (predefinita), `reveal`, `step`, `loop`, con il fotogramma statico sempre completo e controlli nascosti se il sistema chiede meno movimento.
+
+### Da sapere
+
+- **Rete:** per impostazione predefinita ogni diagramma carica i font Instrument Serif, Geist e Geist Mono da Google Fonts, che è l'unica richiesta di rete. Chiedendo "system fonts" il file non fa alcuna richiesta. L'onboarding da sito fa scaricare all'agente alcune pagine di quel sito, e solo se lo chiedi. Secondo PRIVACY.md non ci sono server, account né telemetria.
+- **Script eseguiti:** richiede Python 3 per `self_check.py` e per gli estrattori degli import (`drawio_extract.py`, `mermaid_extract.py`, `excalidraw_extract.py`). Il PNG richiede anche Playwright con Chromium. Il README e il `SKILL.md` descrivono gli script come locali; i file importati vanno trattati come dati non fidati, e la skill lo prevede.
+- **Limiti dichiarati nel README:** la qualità dipende dal modello e lo stesso prompt può dare layout diversi; il risultato non è un formato sorgente modificabile (niente testo da confrontare in una pull request né canvas da trascinare). Per documenti in Git che cambiano a ogni sprint, il README consiglia Mermaid. Non va usata per elenchi, confronti di soli attributi o diagrammi con una sola forma.
+- **Comandi in più solo con il plugin:** `/diagram-design:export-diagram`, `import-drawio`, `import-mermaid`, `import-excalidraw`, `profile` e `doctor` (in Pi senza prefisso). Con `npx skills` si installa solo la skill, senza questi comandi; si può chiedere tutto anche a parole.
+- **Fonte ufficiale:** il README avverte che le versioni ufficiali vengono solo da questo repository; elenchi con altro nome sono copie non ufficiali.
+
+## Installazione
+
+Il README raccomanda il marketplace quando l'agente ne ha uno, perché dà aggiornamenti e comandi; `npx skills` installa solo la skill. Non usarli entrambi sullo stesso agente.
+
+### Claude Code
+
+Nella sessione, come due messaggi separati:
+
+```text
+/plugin marketplace add cathrynlavery/diagram-design
+/plugin install diagram-design@diagram-design
+```
+
+Per gli aggiornamenti automatici: `/plugin` → **Marketplaces** → **diagram-design** → **Enable auto-update** (per i marketplace di terze parti è disattivato di default); poi `/reload-plugins` quando richiesto.
+
+### Codex
+
+```bash
+codex plugin marketplace add cathrynlavery/diagram-design
+codex plugin add diagram-design@diagram-design
+```
+
+Si aggiorna all'avvio; per forzarlo: `codex plugin marketplace upgrade diagram-design` e una nuova sessione.
+
+### Claude Code e Codex (solo la skill)
+
+```bash
+npx skills add cathrynlavery/diagram-design -g -a claude-code -a codex
+```
+
+| Opzione | Significato |
+|---|---|
+| `-g` | installazione globale (`~/.claude/skills/`, `~/.codex/skills/`); senza, solo nel progetto corrente |
+| `-a <agente>` | agente di destinazione, ripetibile |
+| `--copy` | copie indipendenti invece dei collegamenti simbolici (con più agenti il programma chiede il metodo e consiglia i collegamenti) |
+| `-y` | salta le domande di conferma |
+
+Il comando installa l'intera cartella della skill (`references/`, `assets/`, `scripts/`). Dopo l'installazione riavvia la sessione. Si può richiamare chiedendo un diagramma a parole; Claude Code la usa da solo quando la richiesta è pertinente.
+
+Gestione:
+
+```bash
+npx skills list -g                  # skill installate
+npx skills update diagram-design    # aggiornamento
+npx skills remove diagram-design    # rimozione
+```
+
+Per il plugin usa i comandi `plugin` del rispettivo agente. Il README segnala che un'installazione con `npx skills` esistente non passa da sola al marketplace: va rimossa prima di reinstallare con il plugin.
+
+### App desktop di Claude e ChatGPT
+
+Il README non documenta il caricamento come ZIP nelle app desktop di Claude e ChatGPT (PRIVACY.md cita ChatGPT tra gli agenti in cui la skill può essere installata, senza istruzioni). Si può provare con lo ZIP della sola cartella della skill:
+
+```bash
+git clone --depth 1 https://github.com/cathrynlavery/diagram-design.git
+cd diagram-design/skills && zip -r ~/diagram-design.zip diagram-design
+```
+
+Lo ZIP deve contenere la cartella `diagram-design/` con dentro `SKILL.md`, `references/`, `assets/` e `scripts/`.
+
+**Claude (desktop o web)**
+
+1. Attiva l'esecuzione del codice in **Settings → Capabilities**.
+2. Vai in **Customize → Skills → + → Create skill → Upload a skill** e scegli lo ZIP.
+3. Attiva l'interruttore della skill.
+
+**ChatGPT (desktop o web)**
+
+1. Vai in **Skills** nella barra laterale, poi **Create → Upload from your computer**, e scegli lo ZIP o la cartella.
+2. Attendi l'analisi di sicurezza di ChatGPT.
+3. Richiamala con `@` nella chat.
+
+Le skill personali caricate su desktop e web non si sincronizzano: vanno caricate su ciascuna.
+
+> **Limite:** la skill è pensata per agenti che lavorano su file locali. Nelle app di chat non ho verificato se la dimensione dello ZIP, gli script Python, il controllo con `self_check.py` e l'export PNG (che richiede Playwright) funzionino, e probabilmente l'onboarding da un sito e il profilo salvato in `~/.diagram-design/` non sono utilizzabili. Il disegno vero e proprio dei diagrammi in HTML dovrebbe restare possibile.
+
+## Fonti
+
+- [README di cathrynlavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
+- [SKILL.md di diagram-design](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md)
+- [PRIVACY.md di diagram-design](https://github.com/cathrynlavery/diagram-design/blob/main/PRIVACY.md)
+- [diagram-design su skills.sh](https://skills.sh/cathrynlavery/diagram-design/diagram-design)
+- [Use skills in Claude – Claude Help Center](https://support.claude.com/en/articles/12512180-use-skills-in-claude)
+- [Skills in ChatGPT – OpenAI Help Center](https://help.openai.com/en/articles/20001066-skills-in-chatgpt)