Files

192 lines
12 KiB
Markdown
Raw Permalink Normal View History

# 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)