obsidian-skills — Teaching Claude Code Obsidian's Syntax¶

🛑 Problem¶

An AI coding agent turned loose on an Obsidian vault writes valid Markdown that is wrong for Obsidian. The notes still open, but they quietly lose the features that make the vault a vault:

standard [link](file.md) instead of [[wikilinks]] — breaks the graph, breaks backlinks
callout blocks (> [!warning]) ignored or mangled
.base files (Obsidian Bases) treated as opaque junk
web content pasted in as raw HTML instead of clean Markdown

The agent isn't malfunctioning. It simply has no idea Obsidian Flavored Markdown exists.

✅ Fix — Agent Skills¶

obsidian-skills is maintained by Steph Ango (kepano), Obsidian's CEO. It is not a community plugin — it's a set of plain-text instruction files following the open Agent Skills spec, read by the agent before it touches the vault. Claude Code, Codex, and OpenCode all support the format.

Skill	Teaches the agent
`obsidian-markdown`	Obsidian Flavored Markdown — wikilinks, embeds, callouts, YAML properties
`obsidian-bases`	The `.base` format — filtered and formula-driven note views
`json-canvas`	The open `.canvas` format — nodes, edges, groups
`obsidian-cli`	Obsidian CLI; plugin and theme development
`defuddle`	Extract clean Markdown from web pages instead of dumping raw HTML

📦 Install¶

⚠️ Read this before you copy the upstream command¶

The commonly-published instruction is:

cd /path/to/your/obsidian-vault
git clone https://github.com/kepano/obsidian-skills.git .claude   # ← DANGEROUS if .claude exists

This is only safe on a vault that has never been used with Claude Code. If the vault already has a .claude/ directory — and any vault with settings.local.json, project skills, hooks, or permissions does — then .claude is not empty and git clone aborts. That's the good outcome. The bad outcome is following a variant of the advice that clears the directory first and takes your agent config with it.

MajorVault already had .claude/settings.local.json, so the safe method was used instead.

Safe method — temp clone, copy only `skills/`¶

git clone --depth 1 https://github.com/kepano/obsidian-skills.git /tmp/obsidian-skills
mkdir -p /path/to/vault/.claude/skills
cp -r /tmp/obsidian-skills/skills/* /path/to/vault/.claude/skills/
rm -rf /tmp/obsidian-skills

This drops the five skills alongside whatever .claude/ already holds, touching nothing else.

Alternative — the npx installer¶

npx skills add https://github.com/kepano/obsidian-skills

Interactive: Space-select all five skills, then search claude and select Claude Code explicitly. It defaults to the Universal target (.agents/skills), which Claude Code does not read — selecting Claude Code is what routes the files into .claude/.

🔎 Verify¶

Skills load from the current working directory's .claude/. Start the session from the vault root — not from ~:

cd /path/to/your/obsidian-vault
claude

Then ask:

What Obsidian-specific skills do you have access to right now?

A correct setup names all five. If it doesn't, there are only two realistic causes:

The directory isn't named exactly .claude.
The session was started outside the vault root, so the agent never saw the folder.

🧠 Why This Matters Here¶

The vault is a knowledge graph, and wikilinks are its edges. An agent writing [link](note.md) instead of [[note]] produces a note that reads fine and is structurally invisible — no backlink, no graph edge, nothing for a graph query to traverse. The damage is silent and compounds across every note the agent writes.

defuddle is the other quiet win: it pairs with the clipping workflow instead of fighting it, extracting readable Markdown rather than pasting a wall of <div>s into 10-Journal/.