# claude-obsidian - **Autore:** AgriciDaniel (con la community AI Marketing Hub Pro) - **Repository:** [AgriciDaniel/claude-obsidian](https://github.com/AgriciDaniel/claude-obsidian) (licenza MIT, versione 3.0.1) - **Sorgenti:** cartella [skills/](https://github.com/AgriciDaniel/claude-obsidian/tree/main/skills), un `SKILL.md` per skill; il punto d'ingresso è [skills/wiki/SKILL.md](https://github.com/AgriciDaniel/claude-obsidian/blob/main/skills/wiki/SKILL.md) - **Pagina su skills.sh:** [AgriciDaniel/claude-obsidian](https://skills.sh/AgriciDaniel/claude-obsidian) - **Diffusione (ottobre 2026):** circa 6.500 installazioni complessive tramite `npx skills` su 15 skill (da 546 per `obsidian-markdown` a 297 per `wiki-cli`); il repository ha circa 16.000 stelle e 1.600 fork su GitHub - **Controlli di sicurezza su skills.sh:** la pagina non riporta esiti per questo repository > Non è una sola skill ma un **plugin di Claude Code con 15 skill** e 3 agenti, più un programma Python (`scripts/claude-obsidian.py`) che fa le scritture sul vault. Le skill sono pensate per funzionare insieme. ## A cosa serve Fa dell'agente il custode di un "secondo cervello": un vault di [Obsidian](https://obsidian.md) fatto di note Markdown tue, sul tuo disco. Gli dai fonti (articoli, trascrizioni, appunti), lui le legge, scrive note collegate che citano la fonte e le archivia in un grafo di conoscenza. Poi risponde alle domande a partire da quelle note. Segue il pattern LLM Wiki di Karpathy: la conoscenza si compila una volta e si mantiene, invece di rifare ogni volta la stessa ricerca. ## Cosa fa ### Quando si attiva Le skill partono quando la richiesta corrisponde alla loro descrizione, oppure con `/claude-obsidian:`. Per esempio: - vuoi creare un vault, o adottarne uno che hai già ("set up a wiki", "second brain"); - vuoi dare in pasto all'agente fonti da trasformare in note; - chiedi che cosa sai già su un argomento; - vuoi salvare una risposta o un'intuizione come nota; - vuoi controllare lo stato del vault (link rotti, pagine orfane); - vuoi una ricerca web guidata, una board Canvas o una tabella Bases. ### Come lavora 1. **Cattura.** Le fonti vanno nella cartella `inbox/`. Ognuna viene conservata come copia intatta, identificata dal contenuto, prima di essere riassunta (`capture plan`, poi `capture apply`). 2. **Ancoraggio.** Le affermazioni importanti rimandano alle fonti che le sostengono; le prove deboli o in conflitto restano visibili. 3. **Accumulo.** Domande, ricerche e controlli attingono a ciò che il vault contiene già. Come sceglie il vault, in quest'ordine: l'argomento `--vault`, la variabile `CLAUDE_OBSIDIAN_VAULT`, il file `.claude-obsidian.json` più vicino, un vault inizializzato non ambiguo nella cartella corrente o sopra. Se la scelta manca o è ambigua, si ferma senza scrivere. La cartella del plugin non viene mai usata come vault. Creazione e adozione del vault sono prima un'anteprima, poi un'applicazione con l'hash del piano approvato: ```bash CORE=/percorso/assoluto/scripts/claude-obsidian.py python3 "$CORE" init /percorso/del/vault --generated-at --operation-id init-reviewed python3 "$CORE" init /percorso/del/vault --generated-at --operation-id init-reviewed \ --approved-plan-sha256 --apply ``` Per un vault Obsidian che hai già, `adopt` al posto di `init`: aggiunge solo i metadati e i file di base mancanti, senza toccare le tue note. `--force` va usato solo dopo aver controllato i conflitti. ### Le skill per gruppo **Costruire e usare il vault (5)** | Skill | A cosa serve | |---|---| | `wiki` | crea un vault nuovo o adotta uno esistente, controlla che sia pronto e smista le richieste alle altre skill | | `wiki-ingest` | trasforma le fonti catturate in pagine collegate, con le fonti registrate | | `wiki-query` | risponde dal contenuto del vault; in sola lettura | | `save` | conserva una risposta o un'intuizione come nota, solo se glielo chiedi | | `wiki-lint` | trova link rotti, pagine orfane, metadati mancanti e sezioni vuote | **Estendere il flusso (7)** | Skill | A cosa serve | |---|---| | `autoresearch` | ricerca sul web limitata da un budget, solo con il tuo consenso, unita al vault dopo revisione | | `canvas` | crea e aggiorna board Canvas di Obsidian | | `defuddle` | prepara la cattura pulita di una pagina web in Markdown; il pulitore è uno strumento esterno facoltativo | | `wiki-fold` | riassume il registro delle operazioni in sintesi brevi e tracciabili | | `wiki-mode` | decide come archiviare le note nuove: Generic, LYT, PARA o Zettelkasten | | `wiki-retrieve` | ricerca locale BM25, con riordino facoltativo dei risultati | | `wiki-cli` | legge e cerca tramite la riga di comando ufficiale di Obsidian | **Riferimento (3)** | Skill | A cosa serve | |---|---| | `obsidian-markdown` | Markdown di Obsidian corretto: link, incorporamenti, callout, proprietà | | `obsidian-bases` | file `.base` nativi: tabelle, schede, filtri e formule | | `think` | un ciclo di revisione strutturato per le decisioni difficili | I tre agenti (`wiki-ingest`, `wiki-lint`, `verifier`) sono in sola lettura: restituiscono bozze e rapporti, e scrive nel vault solo il programma Python. ### Modalità di archiviazione `wiki-mode` cambia dove finiscono le note nuove; cambiare modalità non sposta quelle esistenti. | Modalità | Come archivia | |---|---| | Generic (predefinita) | fonti, concetti, entità e sessioni | | LYT | Maps of Content e note atomiche collegate | | PARA | Projects, Areas, Resources, Archives | | Zettelkasten | ID stabili, note atomiche, molti collegamenti | ### Cosa legge davvero | Ingresso | Supporto | |---|---| | File locali | copiati e identificati dal contenuto | | Immagini | metadati, hash, dimensioni | | PDF ed EPUB | solo metadati, hash e dimensione; nessuna estrazione del testo integrata | | Pagine web e YouTube | preparate come piano da approvare; per scaricarle serve un esecutore separato | | OCR | richiede uno strumento esterno configurato | | Ricerca BM25 | locale e deterministica | | Riordino o modelli remoti | facoltativi, con consenso esplicito | ### Da sapere - **Scritture sicure:** legge ogni nota che toccherà e ne registra l'impronta SHA-256; gli aiutanti restituiscono solo bozze e Claude le fonde in un unico piano applicato come una sola transazione. Se una nota cambia nel frattempo, la scrittura si ferma invece di sovrascrivere. Un registro tiene i backup, e `transaction recover` annulla una scrittura interrotta. Non fa commit Git da solo. - **Consensi separati:** ricerca web, checkpoint Git e qualunque dato inviato fuori dal computer sono passaggi a parte che richiedono approvazione. La configurazione di base non usa la rete. - **Blocco:** coordina solo scrittori locali che cooperano; altri dispositivi ed editor esterni non lo condividono, quindi servono i backup. - **Limiti dichiarati:** non registra le trascrizioni da solo, non è un servizio di sincronizzazione né un verificatore di fatti, e non sostituisce i backup. - **Hook:** il README non ne menziona. - **Requisiti:** Python 3.11 o più recente, Claude Code (o un altro agente compatibile con le Agent Skills), Bash per gli script di installazione; Obsidian per la parte visiva; Git solo per sviluppo o checkpoint. - **Windows:** le scritture sul vault richiedono WSL; su Windows nativo si possono solo ispezionare e vedere le anteprime. ## Installazione ### Claude Code e Codex **Plugin di Claude Code** (metodo consigliato): ```bash claude plugin marketplace add AgriciDaniel/claude-obsidian claude plugin install claude-obsidian@agricidaniel-claude-obsidian claude plugin list ``` Poi apri la cartella che vuoi come vault e avvia Claude Code lì: ```text claude /claude-obsidian:wiki # crea o adotta il vault (mostra prima un'anteprima) /claude-obsidian:wiki-ingest # trasforma il contenuto di inbox/ in note collegate /claude-obsidian:wiki-query # fai una domanda, risposta dalle tue note /claude-obsidian:save # conserva una buona risposta come nota /claude-obsidian:wiki-lint # controllo: link rotti, orfane, lacune ``` Apri la stessa cartella in Obsidian con **Open folder as vault**. Le skill hanno il prefisso del plugin, per esempio `/claude-obsidian:wiki`. **Codex e altri agenti** (OpenCode, Gemini, ZCode, Cursor, Windsurf): da un clone del repository, uno script collega le skill. Senza `--apply` mostra solo l'anteprima. ```bash git clone https://github.com/AgriciDaniel/claude-obsidian.git cd claude-obsidian bash scripts/setup-multi-agent.sh --host codex # anteprima, non scrive bash scripts/setup-multi-agent.sh --host codex --apply # collega le skill bash scripts/setup-multi-agent.sh --check # verifica ``` | Opzione | Significato | |---|---| | `--host ` | agente di destinazione: `codex`, `opencode`, `gemini`, `zcode`, `cursor`, `windsurf` (ripetibile) | | `--apply` | applica le modifiche; senza, è solo un'anteprima | | `--check` | controlla che i collegamenti funzionino | | `--workspace ` | cartella di lavoro, obbligatoria per Cursor e Windsurf | Lo script crea i collegamenti solo dove non c'è già niente e non sostituisce mai una skill o un collegamento esistente. Per Codex le skill finiscono in `~/.agents/skills/`. Dopo l'installazione riavvia la sessione. Gestione: ```bash claude plugin marketplace update agricidaniel-claude-obsidian # aggiornamento (1) claude plugin update claude-obsidian@agricidaniel-claude-obsidian # aggiornamento (2) claude plugin uninstall claude-obsidian@agricidaniel-claude-obsidian # rimozione (non toglie il vault) claude plugin marketplace remove agricidaniel-claude-obsidian ``` Dopo l'aggiornamento riavvia Claude Code. Chi ha installato la 3.0.0 con il vecchio nome `agricidaniel-obsidian` deve reinstallare con il nome nuovo (guida `docs/namespace-migration.md`). Per gli altri agenti, rimuovi solo i collegamenti che lo script ti ha elencato. Esiste anche `npx skills add AgriciDaniel/claude-obsidian` (la pagina su skills.sh lo elenca), ma l'installazione documentata dal progetto è quella sopra. Non ho verificato come si comporti il programma Python con questo metodo. ### App desktop di Claude e ChatGPT La documentazione del progetto non dice niente sulle app desktop di Claude e ChatGPT. Il caricamento di una skill come ZIP segue la procedura generale: 1. Prepara lo ZIP con la cartella di una skill (per esempio `skills/wiki-query`), che deve contenere `SKILL.md`. 2. **Claude (desktop o web):** attiva l'esecuzione del codice in **Settings → Capabilities**, poi **Customize → Skills → + → Create skill → Upload a skill** e scegli lo ZIP; attiva l'interruttore. 3. **ChatGPT (desktop o web):** **Skills** nella barra laterale, **Create → Upload from your computer**, attendi l'analisi di sicurezza e 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 chiamano lo script `scripts/claude-obsidian.py` per percorso assoluto e lavorano su un vault nel tuo disco, mentre le app di chat girano in un ambiente isolato senza accesso a questi file. Serve un agente che giri in locale, come Claude Code o Codex. ## Fonti - [README di AgriciDaniel/claude-obsidian](https://github.com/AgriciDaniel/claude-obsidian) - [docs/install-guide.md](https://github.com/AgriciDaniel/claude-obsidian/blob/main/docs/install-guide.md) - [Cartella skills/](https://github.com/AgriciDaniel/claude-obsidian/tree/main/skills) - [SKILL.md di wiki](https://github.com/AgriciDaniel/claude-obsidian/blob/main/skills/wiki/SKILL.md) - [claude-obsidian su skills.sh](https://skills.sh/AgriciDaniel/claude-obsidian) - [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)