192 lines
12 KiB
Markdown
192 lines
12 KiB
Markdown
# 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:<skill>`. 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 <ISO-UTC> --operation-id init-reviewed
|
|||
|
|
python3 "$CORE" init /percorso/del/vault --generated-at <ISO-UTC> --operation-id init-reviewed \
|
|||
|
|
--approved-plan-sha256 <hash-rivisto> --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>` | 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>` | 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/<nome>`. 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)
|