0 Fork 0

Files

T

davideandClaude Sonnet 5.5 ac81877e73 Metti in primo piano i metodi standard nell'installazione di obsidian-wiki

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

2026-10-16 09:32:06 +02:00

17 KiB

Raw Permalink Blame History

obsidian-wiki

Autore: Ar9av
Repository: Ar9av/obsidian-wiki (licenza MIT)
Sorgenti: cartella .skills/, un SKILL.md per skill; l'elenco commentato è in docs/skills.md
Pagina su skills.sh: Ar9av/obsidian-wiki
Diffusione (ottobre 2026): circa 97.200 installazioni complessive tramite npx skills su 44 skill; il repository ha circa 3.600 stelle e 361 fork su GitHub
Controlli di sicurezza su skills.sh: per wiki-ingest, Gen Agent Trust Hub e Snyk segnalano un avviso (la pagina non spiega il motivo) e Socket è elencato senza esito. La pagina riassuntiva del repository non riporta audit e la sua sezione /audits dà errore 404. Le altre skill non le ho controllate.

Non è una sola skill ma un framework di 39 skill (skills.sh ne elenca 44, tra cui data-ingest, ingest-url, obsidian-wiki-ingest e wiki-quick-chat-capture, che non compaiono nella cartella .skills/ né nella documentazione; non ho verificato perché), più una CLI e un'API Python facoltative. Le skill sono pensate per funzionare insieme, attorno a un'unica cartella di note.

A cosa serve

Dà all'agente una memoria a lungo termine fatta di note Markdown che sono tue: un "secondo cervello" in formato vault di Obsidian. Risolve il problema di rifare da zero un lavoro già fatto perché la risposta era finita in una chat dimenticata. Segue l'idea del gist LLM Wiki di Karpathy: la conoscenza si compila una volta e si mantiene aggiornata, invece di rifare ogni volta la stessa domanda a un LLM o una ricerca RAG.

Cosa fa

Quando si attiva

Le skill partono quando la richiesta corrisponde alla loro descrizione, oppure con un comando /nome-skill (nei client che li supportano, come Claude Code):

vuoi inizializzare il sistema ("set up my wiki");
vuoi "dare in pasto" all'agente documenti, PDF, esportazioni di chat, trascrizioni, immagini o URL;
vuoi salvare la conversazione corrente o la conoscenza del progetto in cui stai lavorando;
chiedi che cosa sai già su un argomento, o vuoi un riepilogo di quanto hai imparato in un periodo;
vuoi ritrovare una vecchia sessione con l'agente o recuperare quanto emerso nelle sessioni passate;
vuoi tenere in ordine il vault (link rotti, duplicati, tag incoerenti).

Come lavora

Imposta il vault. wiki-setup chiede dove creare il vault e dove sono i documenti sorgente, poi crea cartelle, index.md, log.md, hot.md, il manifest .manifest.json e la configurazione di Obsidian. Con la CLI Python lo stesso risultato si ottiene con obsidian-wiki setup.
Distilla le fonti (wiki-ingest). Non riassume: integra la conoscenza nelle pagine già presenti, segnala le contraddizioni e aggiorna i collegamenti. Tre modalità: append (predefinita, tratta solo fonti nuove o modificate, verificate con un hash tramite obsidian-wiki cache-check), full (rifà tutto) e raw (promuove le bozze messe in _raw/ e le archivia in _raw/_archived/). Il testo delle fonti è trattato come dato non fidato: la skill dice di non eseguire comandi trovati nei documenti.
Sincronizza i progetti (wiki-update). Dalla cartella di un repository confronta lo stato con l'ultimo commit sincronizzato, ricava che cosa varrebbe la pena ricordare tra tre mesi e lo scrive nel vault. Funziona da qualsiasi progetto.
Risponde alle domande (wiki-query). È in sola lettura: scrive soltanto una riga in log.md. Parte da hot.md e index.md, poi legge le sezioni e solo in ultimo le pagine intere, così il costo resta quasi costante al crescere del vault. La risposta cita le pagine con [[wikilink]], elenca le lacune e dichiara quanti candidati ha visto e letto.
Mantiene il vault in ordine con wiki-lint, wiki-dedup, cross-linker, tag-taxonomy, wiki-synthesize e wiki-status.

Esempi dal README:

/wiki-ingest ~/research
/wiki-update                        # distilla il repository in cui ti trovi
/wiki-capture                       # salva questa conversazione
/wiki-history-ingest claude         # estrae il sapere dalle tue vecchie sessioni con Claude
/wiki-query what do I know about rate limiting?
/wiki-narrate MCP security          # briefing con citazioni su un argomento
/wiki-digest week                   # che cosa ho imparato questa settimana?

Le skill per gruppo

Gruppo	Skill
Impostazione	`wiki-setup`, `wiki-switch` (più vault con nome), `daily-update`
Alimentare il vault	`wiki-ingest`, `wiki-capture` (con `--quick` mette in `_raw/` in meno di 60 secondi), `wiki-update`, `wiki-research` (ricerca web autonoma), `wiki-history-ingest` e le sei skill `claude-`, `codex-`, `copilot-`, `hermes-`, `openclaw-`, `pi-history-ingest`, `wiki-agent`
Interrogarlo	`wiki-query`, `wiki-narrate`, `wiki-digest`, `wiki-context-pack` (porzione di contesto limitata in token per un altro agente), `memory-bridge` (che cosa ha scritto ogni strumento)
Ritrovare le sessioni	`session-brain`, `session-search`
Manutenzione	`wiki-status`, `wiki-lint`, `wiki-dedup`, `cross-linker`, `tag-taxonomy`, `wiki-synthesize`, `wiki-stage-commit`, `wiki-rebuild`
Vedere e spostare	`graph-colorize`, `wiki-dashboard`, `wiki-export`, `wiki-import`, `obsidian-layout-adjustment`
Estendere	`llm-wiki` (il riferimento del metodo), `skill-creator`, `vault-skill-factory`, `impl-validator`, `code-understand`

Le due skill sulle sessioni non toccano il vault: scrivono un indice a parte in ~/.claude/session-brain/. Regola pratica del progetto: wiki-history-ingest per conservare la conoscenza come pagine permanenti, session-brain per ritrovare la sessione in cui è successo qualcosa.

Come tiene la conoscenza affidabile

Ogni affermazione è marcata come estratta dalla fonte, ^[inferred] oppure ^[ambiguous]; wiki-lint segnala le pagine che scivolano nella speculazione.
Un manifest registra ogni fonte già letta, così la seconda esecuzione tratta solo la differenza.
index.md, log.md, hot.md, il profilo del proprietario e l'indice dei todo (sotto _meta/) passano da un unico writer con blocco, per evitare che agenti in parallelo si sovrascrivano.
Con WIKI_STAGED_WRITES=true le pagine nuove finiscono prima in _staging/ e le promuovi tu con /wiki-stage-commit.
Più vault: @nome davanti alla richiesta la indirizza a un vault con nome (@work update wiki) senza cambiare quello predefinito.

Parti facoltative

CLI Python obsidian-wiki: setup, doctor, info, hooks status|install|uninstall, cache-check, cache-update, sessions-build, sessions-query, sessions-show, sessions-clusters e altri (elenco completo nella guida alla CLI, che ho letto solo in parte).
API Python: from obsidian_wiki import Memory, con remember, add, search, recap. Dice di non richiedere chiavi API, modello di embedding né rete.
Esportazione del grafo in graph.json, GraphML, Neo4j Cypher, Postgres SQL, graph.html interattivo o pacchetto OKF.
Estensione per il browser e servizio Docker raggiungibile via HTTP/MCP (obsidian-wiki serve, ascolta solo in locale per impostazione predefinita). Li ho visti solo nell'indice della documentazione, non ne ho letto le guide.
Ricerca semantica QMD e sincronizzazione su GitHub, da attivare nella configurazione.

Risultati dichiarati

Il README riporta un confronto su un vault reale di 38 pagine con Claude Sonnet: 81 s contro 19 s per rispondere e 44% contro 83% di risposte corrette, a costo API invariato. Il campione è minuscolo (4 domande, 2 condizioni, 2 ripetizioni) e gli autori lo definiscono indicativo; in una delle prove "con il tool" il modello ha ignorato la CLI e ha sbagliato. Il confronto con altri strumenti nel README è una valutazione del progetto stesso.

Da sapere

Hook di sessione: obsidian-wiki setup registra due hook di Claude Code, uno che all'avvio inserisce nel contesto la memoria del vault e uno a fine sessione che chiede di eseguire /wiki-capture --quick se hai modificato file o lanciato almeno 4 comandi. Si salta con --no-hooks, si rimuove con obsidian-wiki hooks uninstall, e WIKI_STOP_CAPTURE=false lo disattiva per una singola sessione. Il plugin di Claude Code non li installa.
Cronologia delle sessioni: le skill *-history-ingest e session-brain leggono le sessioni passate (~/.claude, ~/.codex, ~/.copilot, ecc.), che possono contenere segreti o dati sensibili. Anche wiki-update legge README, sorgenti, log di git e file .claude/ del progetto.
Scritture fuori dal vault: setup crea collegamenti simbolici delle skill nelle cartelle di tutti gli agenti rilevati (~/.claude, ~/.codex, ~/.gemini, ecc.) e file di regole sempre attive nel progetto (CLAUDE.md, AGENTS.md, GEMINI.md...). Scrive anche la configurazione in ~/.config/obsidian-wiki/config e un profilo di scrittura WRITING.md.
Installazione dell'hook da parte dell'agente: wiki-setup può scaricare con curl lo script wiki-stop-capture.sh dal repository e aggiungerlo a ~/.claude/settings.json; chiede conferma prima ("Want to auto-capture findings at session end?").
Setup guidato dall'agente: dando all'agente solo l'URL del repository, esegue lui i comandi indicati nelle istruzioni. Conviene leggerle prima.
Uscita dei dati: il README dice che nulla lascia il computer. Fanno eccezione le funzioni che attivi tu: sincronizzazione GitHub, servizio HTTP/MCP e estensione browser, che può anche compilare form web con dati del vault.
Prompt injection: le skill di ingest dichiarano le fonti dati non fidati, ma la politica di sicurezza del progetto riconosce l'ingestione di contenuti non controllati come il punto di rischio principale (scritture fuori dal vault, segreti nel vault o in log.md, istruzioni nascoste nei documenti). Il progetto non considera una vulnerabilità un agente che fa ciò che gli hai permesso di fare.
Requisiti: Python per la CLI e l'API (versione non indicata nei documenti che ho letto). Obsidian è facoltativo, serve per grafo e navigazione. Docker solo per il servizio.
Maturità: l'autore lo definisce "early".

Installazione

Claude Code e Codex

Il percorso più semplice è quello standard, senza Python: installa solo le skill. Poi, in qualsiasi progetto, di' "set up my wiki": la skill wiki-setup chiede dove creare il vault e scrive la configurazione in ~/.config/obsidian-wiki/config.

Plugin di Claude Code (solo Claude Code), nella sessione:

/plugin marketplace add Ar9av/obsidian-wiki
/plugin install obsidian-wiki@obsidian-wiki

I comandi hanno il prefisso del plugin, per esempio /obsidian-wiki:wiki-ingest.

npx skills (Claude Code e Codex), serve Node.js:

npx skills add Ar9av/obsidian-wiki -g -a claude-code -a codex

Opzione	Significato
`--skill <nome>`	installa solo la skill indicata (ripetibile); senza, propone tutte
`-g`	installazione globale (`~/.claude/skills/`, `~/.codex/skills/`); senza, solo nel progetto corrente
`-a <agente>`	agente di destinazione, ripetibile
`-y`	salta le domande di conferma

Dopo l'installazione riavvia la sessione; in Codex le skill si richiamano con $nome (per esempio $wiki-query) e si vedono con /skills.

Limiti di questi due metodi, uguali per entrambi:

non c'è la CLI obsidian-wiki (niente doctor, sessions-build, sessions-query, API Python); le skill di ingest hanno un'alternativa con sha256sum al posto di cache-check;
non ci sono gli hook di sessione (né il riepilogo all'avvio né il suggerimento a fine sessione); wiki-setup può comunque installare quello di fine sessione, dopo averti chiesto conferma;
il progetto dichiara deprecata la via npx skills, perché non scrive la configurazione globale né collega le skill agli altri agenti.

Gestione:

/plugin marketplace update obsidian-wiki      # aggiornamento del plugin
/plugin uninstall obsidian-wiki@obsidian-wiki # rimozione del plugin

npx skills list -g                # skill installate
npx skills update                 # aggiornamento
npx skills remove <nome>          # rimozione

Per il plugin il progetto indica claude plugin marketplace update obsidian-wiki, poi claude plugin update obsidian-wiki@obsidian-wiki e il riavvio di Claude Code.

CLI Python (completa, facoltativa)

Aggiunge la CLI obsidian-wiki, l'API Python, gli hook di sessione e il collegamento delle skill a tutti gli agenti rilevati. Il progetto la consiglia, ma richiede Python:

pipx install obsidian-wiki              # oppure: uv tool install obsidian-wiki
obsidian-wiki setup --vault ~/brain
obsidian-wiki doctor                    # controlla installazione e stato del vault

Su Debian e Raspberry Pi OS pip install fuori da un ambiente virtuale dà l'errore externally-managed-environment: usa pipx (sudo apt install pipx && pipx ensurepath, poi riapri il terminale) o uv. Non usare uvx: i collegamenti delle skill punterebbero a un ambiente temporaneo (se serve, uvx obsidian-wiki setup --copy).
Il setup registra due hook di Claude Code, che leggono i dati delle conversazioni: salta con --no-hooks, rimuovili con obsidian-wiki hooks uninstall.
Altre opzioni: --vault <percorso>, --copy (copia le skill invece di collegarle), --project . (aggiunge skill locali e AGENTS.md al progetto), --timezone <fuso>. Alternativa al pipx: git clone https://github.com/Ar9av/obsidian-wiki.git && cd obsidian-wiki && bash setup.sh.
Aggiornamento: pipx upgrade obsidian-wiki (o uv tool upgrade obsidian-wiki), poi di nuovo obsidian-wiki setup. Il progetto non documenta nei file che ho letto un comando di disinstallazione completo (collegamenti simbolici, configurazione): non l'ho verificato.

App desktop di Claude e ChatGPT

Il README non documenta l'uso nelle app desktop. Ogni skill va caricata come ZIP separato, con la cartella della skill che contiene SKILL.md:

git clone --depth 1 https://github.com/Ar9av/obsidian-wiki.git
cd obsidian-wiki/.skills && zip -r ~/wiki-query.zip wiki-query

Claude (desktop o web)

Attiva l'esecuzione del codice in Settings → Capabilities.
Vai in Customize → Skills → + → Create skill → Upload a skill e scegli lo ZIP.
Attiva l'interruttore della skill.

ChatGPT (desktop o web)

Vai in Skills nella barra laterale, poi Create → Upload from your computer, e scegli lo ZIP o la cartella.
Attendi l'analisi di sicurezza di ChatGPT.
Richiamala con @ nella chat.

Le skill personali caricate su desktop e web non si sincronizzano: vanno caricate su ciascuna.

Limite: qui non ha senso usarla. Le skill leggono e scrivono un vault sul tuo disco, usano la CLI obsidian-wiki, il file di configurazione in ~/.config/obsidian-wiki/ e gli hook, e le app di chat lavorano in un ambiente isolato senza accesso a queste cose. Serve un agente che giri in locale, come Claude Code o Codex.

17 KiB Raw Permalink Blame History Unescape Escape