Files
my-skills/skills/claude-obsidian.md
davideandClaude Sonnet 5.5 5051b50902 Aggiungi le schede di claude-obsidian, ecc, pdf, pptx e xlsx
Nel README nascono gli argomenti Ufficio e Second brain (presenti in
entrambi i gruppi, anche se vuoti): pdf, pptx e xlsx vanno sotto Ufficio,
claude-obsidian, obsidian-skills e obsidian-wiki sotto Second brain.
Conoscenza e note resta per graphify; ecc si affianca a superpowers.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-30 09:38:54 +01:00

193 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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)