my-skills/skills/diagram-design.md

diagram-design

• Autore: Cathryn Lavery (LittleMight)
• Repository: cathrynlavery/diagram-design (licenza MIT)
• Sorgente: skills/diagram-design/SKILL.md (versione 2.6)
• Sito e galleria: diagramdesign.dev · galleria dei diagrammi
• Pagina su 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:

/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

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)

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:

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:

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
• SKILL.md di diagram-design
• PRIVACY.md di diagram-design
• diagram-design su skills.sh
• Use skills in Claude – Claude Help Center
• Skills in ChatGPT – OpenAI Help Center