From fe0714e68562845f80b455239e74394eefab15c0 Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Wed, 23 Sep 2026 15:06:09 +0200 Subject: [PATCH] Aggiungi la scheda di obsidian-skills Co-Authored-By: Claude Opus 5.5 --- README.md | 1 + skills/obsidian-skills.md | 213 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 214 insertions(+) create mode 100644 skills/obsidian-skills.md diff --git a/README.md b/README.md index 09268da..a1f786c 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ Il mio dizionario delle skill per agenti AI (Claude Code, Codex, app di Claude e |---|---| | [claude-plugins-official](skills/claude-plugins-official.md) | Marketplace ufficiale di Anthropic per Claude Code: catalogo di plugin con integrazioni, analisi del codice e flussi di sviluppo. | | [find-skills](skills/find-skills.md) | Permette all'agente di cercare e installare da solo altre skill con `npx skills`. | +| [obsidian-skills](skills/obsidian-skills.md) | Raccolta ufficiale di sei skill per Obsidian: Markdown di Obsidian, Bases, Canvas, riga di comando, estrazione di pagine web e modelli. | | [ponytail](skills/ponytail.md) | Fa scrivere all'agente il codice più semplice e breve che funziona, evitando la sovraingegnerizzazione. | | [project-estimation](skills/project-estimation.md) | Stima durata, costi e risorse di un progetto con tecniche strutturate (PERT, bottom-up, per analogia). | | [ui-ux-pro-max](skills/ui-ux-pro-max.md) | Dà all'agente un archivio di stili, palette, font e regole di UX per progettare interfacce curate su web, mobile e desktop. | diff --git a/skills/obsidian-skills.md b/skills/obsidian-skills.md new file mode 100644 index 0000000..0c4155e --- /dev/null +++ b/skills/obsidian-skills.md @@ -0,0 +1,213 @@ +# obsidian-skills + +- **Autore:** kepano (Steph Ango, CEO di Obsidian) +- **Repository:** [kepano/obsidian-skills](https://github.com/kepano/obsidian-skills) (licenza MIT) +- **Sorgenti:** cartella [skills/](https://github.com/kepano/obsidian-skills/tree/main/skills), un `SKILL.md` per skill +- **Pagina su skills.sh:** [kepano/obsidian-skills](https://skills.sh/kepano/obsidian-skills) +- **Diffusione (settembre 2026):** circa 378.700 installazioni complessive tramite `npx skills`; il repository ha circa 48.800 stelle e 3.500 fork su GitHub +- **Controlli di sicurezza su skills.sh:** `obsidian-markdown` supera Gen Agent Trust Hub, Socket e Snyk; `obsidian-cli` supera Socket e Snyk, mentre Gen Agent Trust Hub segnala un avviso (la pagina non spiega il motivo). Le altre skill non le ho controllate. + +> Non è una sola skill ma una **raccolta di sei skill**. Con lo stesso nome esistono altri repository non ufficiali (per esempio [tpitsunov/obsidian-skills](https://github.com/tpitsunov/obsidian-skills) e [adriangrantdotorg/Obsidian-Skills](https://github.com/adriangrantdotorg/Obsidian-SKILLS)): questa scheda riguarda solo quello di kepano. + +## A cosa serve + +Insegna all'agente a lavorare con [Obsidian](https://obsidian.md): scrivere note nel suo dialetto di Markdown, creare viste a database (Bases) e lavagne (Canvas), e comandare l'app dal terminale. In più aggiunge due strumenti utili per portare contenuti nelle note: estrarre il testo pulito dalle pagine web e generare note da modelli e dati. + +## Cosa fa + +### Le sei skill + +| Skill | Installazioni | Cosa fa | +|---|---|---| +| `obsidian-markdown` | ~86.900 | scrive e modifica note nel Markdown di Obsidian | +| `obsidian-cli` | ~76.100 | comanda Obsidian dal terminale, anche per sviluppare plugin e temi | +| `obsidian-bases` | ~74.900 | crea e modifica file `.base` (viste a database sulle note) | +| `json-canvas` | ~69.900 | crea e modifica file `.canvas` (lavagne con nodi e collegamenti) | +| `defuddle` | ~69.600 | estrae Markdown pulito dalle pagine web | +| `knap` | ~1.300 | genera documenti Markdown da modelli e dati JSON o CSV | + +### obsidian-markdown + +Si attiva quando l'agente scrive o modifica note di Obsidian. Copre la sintassi propria di Obsidian, dando per scontato il Markdown standard: + +| Elemento | Esempio | +|---|---| +| Proprietà (frontmatter YAML) | `title`, `date`, `tags`, `aliases` in testa alla nota | +| Wikilink | `[[Nome nota\|Testo visibile]]` | +| Riferimenti a blocchi | `testo ^id-blocco`, poi `[[Nome nota#^id-blocco]]` | +| Incorporamenti | `![[Nome nota#Titolo]]`, `![[immagine.png\|300]]` | +| Callout | `> [!warning] Titolo` | +| Tag gerarchici | `#progetto/attivo` | +| Evidenziazione | `==testo==` | +| Formule LaTeX | `$e^{i\pi} + 1 = 0$` | +| Diagrammi Mermaid | blocco ` ```mermaid ` | +| Commenti nascosti | `%%testo%%` | +| Note a piè di pagina | `testo[^1]` | + +Regola principale: wikilink per le note del vault, perché Obsidian li aggiorna quando rinomini una nota; link Markdown normali solo per gli URL esterni. Il flusso previsto è: proprietà, contenuto, collegamenti, incorporamenti, callout, e infine controllo nella vista di lettura di Obsidian. + +### obsidian-cli + +Usa la riga di comando ufficiale di Obsidian per leggere, creare e cercare note e gestire attività, proprietà e tag. + +```bash +obsidian read file="Nota" # legge una nota +obsidian create name="Nuova nota" content="# Ciao" # crea una nota +obsidian append file="Nota" content="Nuova riga" # aggiunge in fondo +obsidian search query="termine" limit=10 # cerca nel vault +obsidian daily:append content="- [ ] Attività" # aggiunge alla nota del giorno +obsidian property:set name="status" value="done" # imposta una proprietà +obsidian tasks daily todo # elenca le attività +``` + +- **Destinazione:** `file=` cerca la nota per nome, come un wikilink; `path=` usa il percorso esatto dalla radice del vault; `vault=` sceglie il vault. Senza indicazioni lavora sull'ultimo vault usato. +- **Opzioni utili:** `silent` non apre il file, `total` conta i risultati, `--copy` copia l'output negli appunti. +- **Sviluppo di plugin:** `plugin:reload id=` ricarica il plugin; `dev:errors` e `dev:console` mostrano errori e log; `dev:screenshot` cattura lo schermo; `dev:dom` e `dev:css` ispezionano l'interfaccia; `eval code=` esegue JavaScript dentro l'app. + +**Requisiti:** Obsidian 1.12 o successivo (consigliato 1.12.7+), con l'opzione **Settings → General → Command line interface** attiva. Funziona su Windows, macOS e Linux. L'app deve essere aperta; se non lo è, il primo comando la avvia. + +### obsidian-bases + +Crea file `.base`: file YAML che trasformano un insieme di note in una vista simile a un database. + +- **Filtri:** condizioni (uguale, maggiore, tag, cartella) combinate con `and`, `or`, `not`. +- **Formule:** proprietà calcolate, per esempio `'if(done, "✅", "⏳")'`. +- **Viste:** tabella, schede, elenco e mappa (la mappa richiede il plugin Maps). +- **Riepiloghi:** somma, media, minimo, massimo, mediana per proprietà. + +```yaml +filters: + and: + - file.hasTag("task") + - 'status != "done"' +formulas: + days_left: 'if(due, (date(due) - today()).days, "")' +views: + - type: table + name: "Attività aperte" + order: [file.name, status, formula.days_left] +``` + +Errori da evitare, secondo la skill: formule con virgolette doppie non racchiuse tra apici singoli; arrotondare una durata prima di leggerne `.days`; formule senza controllo sui valori vuoti; riferimenti a formule non definite. + +### json-canvas + +Crea file `.canvas` secondo la [specifica JSON Canvas 1.0](https://jsoncanvas.org/spec/1.0/): un array di nodi e uno di collegamenti. + +- **Nodi:** testo (con Markdown), file del vault, link esterni e gruppi che contengono altri nodi. +- **Collegamenti:** da un nodo all'altro, con lato di partenza e arrivo, frecce, etichetta e colore. +- **Regole:** ID di 16 caratteri esadecimali minuscoli, unici tra nodi e collegamenti; ogni collegamento deve puntare a nodi esistenti; colori `"1"`–`"6"` o esadecimali; coordinate dall'angolo in alto a sinistra, con `y` che cresce verso il basso, e nodi distanziati di 50–100 px. + +### defuddle + +Estrae il contenuto principale di una pagina web come Markdown pulito, senza menu e pubblicità, così l'agente consuma meno token. La skill dice di preferirlo al normale recupero delle pagine web per le pagine comuni. + +```bash +npm install -g defuddle # se non è installato +defuddle parse --md # Markdown +defuddle parse --md -o contenuto.md # salva su file +defuddle parse -p title # solo un metadato (title, description, domain) +``` + +### knap + +Genera documenti Markdown da un modello con variabili, filtri e condizioni, riempito con dati JSON o CSV. Richiede Node.js 20 o successivo (`npm install -g knap`, oppure `npx knap`). + +```bash +knap render modello.md --data articolo.json -o nota.md +knap batch modello.md --data articoli.csv --output-dir note --filename '{{ title | safe_name }}.md' +knap validate modello.md +``` + +Sintassi dei modelli: `{{ variabile }}`, `{{ variabile | filtro }}`, `{% if condizione %} ... {% endif %}`. Si combina con defuddle per trasformare una pagina web in nota: + +```bash +defuddle parse https://example.com --md --json | knap render modello.md --data - +``` + +### Da sapere + +- **Le skill sui formati funzionano ovunque:** `obsidian-markdown`, `obsidian-bases` e `json-canvas` contengono solo regole di sintassi e non eseguono niente. +- **`obsidian-cli` richiede Obsidian sul computer** in cui gira l'agente. Con `eval` l'agente può eseguire JavaScript dentro l'app, con accesso a tutto il vault. +- **`defuddle` e `knap`** richiedono Node.js e installano pacchetti npm globali; `defuddle` si collega a internet per scaricare le pagine. +- **Dove installarla:** il README suggerisce, per Claude Code, di metterla nella cartella `.claude` alla radice del vault. Così Claude Code la usa quando lo apri dentro il vault. + +## Installazione + +### Claude Code come plugin + +Nella sessione di Claude Code: + +``` +/plugin marketplace add kepano/obsidian-skills +/plugin install obsidian@obsidian-skills +``` + +Il plugin si chiama `obsidian` e comprende tutte le skill. Gestione con `/plugin marketplace update obsidian-skills` e `/plugin uninstall obsidian@obsidian-skills`. + +### Claude Code e Codex con `npx skills` + +Tutte le skill: + +```bash +npx skills add kepano/obsidian-skills -g -a claude-code -a codex +``` + +Solo alcune, ripetendo `--skill`: + +```bash +npx skills add kepano/obsidian-skills --skill obsidian-markdown --skill obsidian-bases -g -a claude-code -a codex +``` + +| Opzione | Significato | +|---|---| +| `--skill ` | installa solo la skill indicata; senza, lo strumento propone tutte e sei | +| `-g` | installazione globale (`~/.claude/skills/`, `~/.codex/skills/`); senza, solo nel progetto corrente, per esempio dentro il vault | +| `-a ` | agente di destinazione, ripetibile | +| `-y` | salta le domande di conferma | + +Gestione con `npx skills list -g`, `npx skills update` e `npx skills remove `. + +### Installazione manuale + +Come indicato nel README: + +- **Claude Code:** copia il contenuto del repository nella cartella `.claude` alla radice del vault. +- **Codex:** copia la cartella `skills/` in `~/.codex/skills`. + +```bash +git clone --depth 1 https://github.com/kepano/obsidian-skills.git +cp -r obsidian-skills/skills/* ~/.codex/skills/ +``` + +Dopo l'installazione riavvia la sessione. In Codex puoi richiamare le skill con `$`, per esempio `$obsidian-markdown`. + +### App desktop di Claude e ChatGPT + +Il README non documenta l'uso nelle app desktop. Ogni skill va caricata come ZIP separato: + +```bash +git clone --depth 1 https://github.com/kepano/obsidian-skills.git +cd obsidian-skills/skills +for s in obsidian-markdown obsidian-bases json-canvas; do zip -r ~/$s.zip $s; done +``` + +- **Claude (desktop o web):** attiva l'esecuzione del codice in **Settings → Capabilities**, poi **Customize → Skills → + → Create skill → Upload a skill**, scegli lo ZIP e attiva l'interruttore. +- **ChatGPT (desktop o web):** **Skills** nella barra laterale, poi **Create → Upload from your computer**; richiamala con `@`. Le skill caricate su desktop e web non si sincronizzano. + +Qui hanno senso solo le tre skill sui formati: l'agente scrive il contenuto di note, `.base` e `.canvas` che poi copi nel vault. `obsidian-cli` non può funzionare, perché le app lavorano in un ambiente isolato senza accesso al tuo Obsidian. `defuddle` e `knap` dipendono dalla possibilità di installare pacchetti npm, che non ho verificato. + +## Fonti + +- [README di kepano/obsidian-skills](https://github.com/kepano/obsidian-skills) +- [SKILL.md di obsidian-markdown](https://github.com/kepano/obsidian-skills/blob/main/skills/obsidian-markdown/SKILL.md) +- [SKILL.md di obsidian-cli](https://github.com/kepano/obsidian-skills/blob/main/skills/obsidian-cli/SKILL.md) +- [SKILL.md di obsidian-bases](https://github.com/kepano/obsidian-skills/blob/main/skills/obsidian-bases/SKILL.md) +- [SKILL.md di json-canvas](https://github.com/kepano/obsidian-skills/blob/main/skills/json-canvas/SKILL.md) +- [SKILL.md di defuddle](https://github.com/kepano/obsidian-skills/blob/main/skills/defuddle/SKILL.md) +- [SKILL.md di knap](https://github.com/kepano/obsidian-skills/blob/main/skills/knap/SKILL.md) +- [kepano/obsidian-skills su skills.sh](https://skills.sh/kepano/obsidian-skills) +- [Obsidian CLI – Obsidian Help](https://obsidian.md/help/cli) +- [README di vercel-labs/skills](https://github.com/vercel-labs/skills) +- [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)