diff --git a/README.md b/README.md index a1f786c..6a0f8fe 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ Il mio dizionario delle skill per agenti AI (Claude Code, Codex, app di Claude e |---|---| | [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. | | [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. | | [ponytail](skills/ponytail.md) | Fa scrivere all'agente il codice più semplice e breve che funziona, evitando la sovraingegnerizzazione. | | [project-estimation](skills/project-estimation.md) | Stima durata, costi e risorse di un progetto con tecniche strutturate (PERT, bottom-up, per analogia). | diff --git a/skills/graphify.md b/skills/graphify.md new file mode 100644 index 0000000..4e0ef9d --- /dev/null +++ b/skills/graphify.md @@ -0,0 +1,164 @@ +# graphify + +- **Autore:** Graphify Labs +- **Repository:** [Graphify-Labs/graphify](https://github.com/Graphify-Labs/graphify) (licenza Apache-2.0; branch principale `v8`) +- **Sorgente:** [graphify/skill.md](https://github.com/Graphify-Labs/graphify/blob/v8/graphify/skill.md) (versione per Claude Code; le versioni per gli altri agenti sono in `graphify/skill-.md`, le guide di dettaglio in `graphify/skills//references/`) +- **Pacchetto Python:** `graphifyy` (con due y); il comando si chiama `graphify` +- **Pagina su skills.sh:** [graphify-labs/graphify/graphify](https://skills.sh/graphify-labs/graphify/graphify) +- **Versione:** v0.9.66 (22 settembre 2026) +- **Diffusione (settembre 2026):** circa 7.900 installazioni tramite `npx skills` (su skills.sh dal 7 aprile 2026); il repository ha circa 120.700 stelle e 11.700 fork su GitHub. La maggior parte degli utenti installa tramite il pacchetto Python, che skills.sh non conta. +- **Controlli di sicurezza su skills.sh:** Gen Agent Trust Hub e Snyk superati; Socket segnala un avviso (la pagina non spiega il motivo) + +> Esistono siti di terzi con nomi simili. Questa scheda si basa solo sul repository ufficiale Graphify-Labs/graphify. + +## A cosa serve + +Trasforma una cartella (codice, documentazione, PDF, immagini, video) in un **grafo di conoscenza** interrogabile: nodi come classi, funzioni e concetti, collegati da relazioni come chiamate, import ed ereditarietà. Invece di cercare nei file con grep e rileggerli ogni volta, l'agente interroga il grafo, e così spende meno token sui progetti grandi e vede collegamenti tra parti lontane del progetto. + +## Cosa fa + +### Quando si attiva + +Con il comando `/graphify`, oppure per qualsiasi domanda su un progetto (architettura, relazioni tra file, contenuti), soprattutto se la cartella `graphify-out/` esiste già. In quel caso l'agente risponde interrogando il grafo invece di ricostruirlo. + +### Come lavora + +1. **Controlla l'installazione:** se il pacchetto `graphifyy` manca, l'agente lo installa da solo con `uv tool install`, oppure con `pip` (se necessario anche con `--break-system-packages`). +2. **Conta i file** e ne mostra il riepilogo per tipo (codice, documenti, articoli, immagini, video). Segnala i file saltati perché ritenuti sensibili. Sopra i 500 file o i 2 milioni di parole avvisa e chiede su quale sottocartella lavorare. +3. **Estrae entità e relazioni** in due parti parallele: + - **codice:** analisi sintattica locale con tree-sitter, deterministica e gratuita, senza modelli linguistici e senza chiavi API; + - **documenti, PDF e immagini:** estrazione del significato con un modello linguistico. Se è impostata `GEMINI_API_KEY` o `GOOGLE_API_KEY` usa Gemini; altrimenti lo fa l'agente stesso (in Claude Code con dei subagenti), consumando token della sessione. La skill dice esplicitamente di non chiedere mai altre chiavi API. + - Audio e video vengono prima trascritti in locale con Whisper. +4. **Costruisce il grafo**, raggruppa i nodi in comunità (algoritmo di Leiden) e ne controlla l'integrità. +5. **Dà un nome alle comunità** e genera i risultati. +6. **Riassume in chat** i nodi più collegati, i collegamenti inattesi e le domande suggerite, poi propone la domanda più interessante da esplorare insieme. + +Ogni relazione è etichettata `EXTRACTED` (scritta nel sorgente), `INFERRED` (dedotta) o `AMBIGUOUS` (incerta). Le regole di onestà della skill vietano di inventare relazioni, e impongono di mostrare sempre il costo in token e di avvisare prima di visualizzare grafi con più di 5.000 nodi. + +### Risultati + +Nella cartella `graphify-out/`: + +| File | Contenuto | +|---|---| +| `graph.html` | mappa interattiva del grafo, con filtri e ricerca | +| `GRAPH_REPORT.md` | rapporto leggibile: nodi più collegati, collegamenti inattesi, motivazioni trovate nei commenti (`# WHY:`, `# NOTE:`), domande suggerite | +| `graph.json` | il grafo completo, per interrogarlo | + +A richiesta produce anche SVG, GraphML (Gephi, yEd), script per Neo4j o FalkorDB, una wiki Markdown e un vault di Obsidian. + +### Comandi principali + +``` +/graphify # grafo della cartella corrente +/graphify # grafo di una cartella +/graphify https://github.com// # clona il repository e ne fa il grafo +/graphify --update # rielabora solo i file nuovi o modificati +/graphify --mode deep # estrazione più approfondita +/graphify --watch # ricostruisce il grafo quando il codice cambia +/graphify --obsidian # esporta anche un vault di Obsidian +/graphify --wiki # wiki Markdown, un articolo per comunità +/graphify --mcp # avvia un server MCP sul grafo +/graphify query "" # risponde usando il grafo +/graphify path "ModuloA" "ModuloB" # percorso più breve tra due concetti +/graphify explain "NomeFunzione" # spiega un nodo +/graphify add # aggiunge una pagina web al corpus +``` + +Da terminale, fuori dall'agente: + +```bash +graphify update ./src # aggiorna il grafo dopo un git pull +graphify hook install # ricostruisce il grafo a ogni commit +graphify extract ./src --code-only # solo codice, nessuna chiamata esterna +``` + +### Supporto + +- **Codice:** circa 37 linguaggi, tra cui Python, TypeScript, JavaScript, Go, Rust, Java, C/C++, C#, Ruby, PHP, Swift e Kotlin, più Terraform e i file di configurazione dei pacchetti. +- **Documenti:** Markdown, reStructuredText, HTML, YAML, testo, PDF, DOCX e XLSX. +- **Media:** immagini, audio e video, e anche URL di YouTube (richiede l'extra `video`). + +### Da sapere + +- **Requisiti:** Python 3.10 o successivo; `uv` consigliato (va bene anche `pipx` o `pip`). +- **Privacy:** l'analisi del codice è interamente locale. Documenti, PDF e immagini passano dal modello linguistico usato: Gemini, se hai impostato la chiave, oppure l'agente stesso. Il README dichiara che non c'è telemetria. Il registro delle interrogazioni è facoltativo e locale (`~/.cache/graphify-queries.log`); si disattiva con `GRAPHIFY_QUERY_LOG_DISABLE=1`. +- **Chiavi API:** dentro l'agente la skill usa solo Gemini o l'agente stesso. Il comando da terminale `graphify extract --backend `, pensato per l'automazione, secondo il README supporta anche Anthropic, OpenAI, DeepSeek, Kimi, Bedrock e Ollama in locale. +- **Costi:** un corpus di solo codice non costa token per la costruzione. Con documenti e immagini senza chiave Gemini, l'estrazione consuma token della sessione dell'agente. +- **Modifiche al sistema e al progetto:** la skill installa pacchetti Python da sola e crea `graphify-out/` nel progetto. L'integrazione "sempre attiva" modifica `CLAUDE.md` o `AGENTS.md` e aggiunge hook che spingono l'agente a interrogare il grafo prima di leggere o cercare nei file (vedi sotto). +- **Grafo da aggiornare:** il grafo è una fotografia del codice. Va aggiornato con `--update`, `graphify update`, `--watch` o l'hook sui commit. + +## Installazione + +### Claude Code (metodo ufficiale) + +```bash +uv tool install graphifyy # oppure: pipx install graphifyy / pip install graphifyy +graphify install # installa la skill in ~/.claude/skills/graphify/ +``` + +Con `graphify install --project` la installa solo nel progetto corrente (`.claude/skills/`). Poi in Claude Code, dalla cartella del progetto: + +``` +/graphify . +``` + +**Integrazione sempre attiva** (facoltativa, dopo aver costruito il grafo): aggiunge una sezione a `CLAUDE.md` e un hook `PreToolUse` che, prima di ogni lettura o ricerca nei file, invita Claude a usare il grafo. + +```bash +graphify claude install +graphify install --project --strict # variante rigida: blocca la prima lettura diretta dei file +``` + +La modalità rigida si attiva o disattiva al momento con `GRAPHIFY_HOOK_STRICT=1` o `GRAPHIFY_HOOK_STRICT=0`. + +### Codex + +```bash +uv tool install graphifyy +graphify install --platform codex +graphify codex install # integrazione sempre attiva tramite AGENTS.md +``` + +Per Codex l'installazione scrive le istruzioni in `AGENTS.md` e un hook in `.codex/hooks.json`, che secondo il README di proposito non fa niente, perché Codex rifiuta alcuni output degli hook. + +Altre piattaforme: `graphify cursor install`, `graphify install --platform gemini`, `--platform copilot`, `--platform aider`, `--platform agents` (formato Agent Skills, in `~/.agents/skills/graphify/`). + +### Con `npx skills` + +```bash +npx skills add Graphify-Labs/graphify --skill graphify -g -a claude-code -a codex +``` + +Installa solo le istruzioni della skill. Il pacchetto Python viene installato dall'agente al primo `/graphify`, ma l'integrazione sempre attiva e gli hook no: per quelli serve comunque il comando `graphify`. Il metodo documentato nel README è quello con `uv tool install` + `graphify install`. + +### Estensioni facoltative + +```bash +uv tool install "graphifyy[pdf]" # PDF +uv tool install "graphifyy[video]" # audio e video (trascrizione locale) +uv tool install "graphifyy[neo4j]" # esportazione verso Neo4j +uv tool install "graphifyy[all]" # tutto +``` + +### Aggiornamento e rimozione + +```bash +uv tool upgrade graphifyy && graphify install # aggiorna pacchetto e skill +graphify hook uninstall # rimuove l'hook sui commit +graphify uninstall # rimuove la skill da tutte le piattaforme +graphify uninstall --project # solo i file del progetto +graphify uninstall --purge # rimuove anche graphify-out/ +``` + +### App desktop di Claude e ChatGPT + +Il README non prevede l'uso nelle app di chat. La skill ha bisogno di installare un pacchetto Python, eseguire comandi nel terminale e leggere una cartella di progetto sul tuo computer, quindi nell'ambiente isolato delle app probabilmente non è utilizzabile. Non l'ho verificato. + +## Fonti + +- [README di Graphify-Labs/graphify](https://github.com/Graphify-Labs/graphify) +- [graphify/skill.md](https://github.com/Graphify-Labs/graphify/blob/v8/graphify/skill.md) +- [Release del repository](https://github.com/Graphify-Labs/graphify/releases) +- [graphify su skills.sh](https://skills.sh/graphify-labs/graphify/graphify) +- [README di vercel-labs/skills](https://github.com/vercel-labs/skills)