# Obsidian

> Obsidian Vault

- Skill: `lucadominguez/obsidian` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lucadominguez/obsidian`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lucadominguez/obsidian/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: lucadominguez (https://skillmd.com/u/lucadominguez)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lucadominguez/obsidian

---

# Obsidian Vault

Use this skill for filesystem-first Obsidian vault work: reading notes, listing notes, searching note files, creating notes, appending content, and adding wikilinks.

## Vault path

Use a known or resolved vault path before calling file tools.

The documented vault-path convention is the `OBSIDIAN_VAULT_PATH` environment variable, for example from `~/.hermes/.env`. If it is unset, use `~/Documents/Obsidian Vault`.

File tools do not expand shell variables. Do not pass paths containing `$OBSIDIAN_VAULT_PATH` to `read_file`, `write_file`, `patch`, or `search_files`; resolve the vault path first and pass a concrete absolute path. Vault paths may contain spaces, which is another reason to prefer file tools over shell commands.

If the vault path is unknown, `terminal` is acceptable for resolving `OBSIDIAN_VAULT_PATH` or checking whether the fallback path exists. Once the path is known, switch back to file tools.

### When the default path is wrong — multi-vault discovery

Users often have multiple Obsidian vaults and the active one may not be the default. If the env var is unset AND the fallback path (`~/Documents/Obsidian Vault`) doesn't exist or is the wrong vault:

1. **Scan for all vaults** — find `.obsidian` directories (the marker of an Obsidian vault):
```bash
find /mnt/c/Users/Lenovo -maxdepth 4 -name ".obsidian" -type d 2>/dev/null
```
On non-WSL systems, scan from `~` or `/Users/`:
```bash
find ~ -maxdepth 4 -name ".obsidian" -type d 2>/dev/null
```

2. **Sample each candidate** — use `search_files(target='files', pattern='*.md', path=<vault>)` to see how many notes each contains.

3. **Ask the user** which vault they use with `clarify`, listing the discovered vault paths plus a brief content summary (e.g., "Desktop/work (3 notes)").

4. **Save the correct path** to memory so future sessions don't repeat the discovery.

**Pitfall:** Do NOT assume the vault is `~/Documents/Obsidian Vault` just because it exists. A user may have multiple vaults and only use one actively. Always verify with the user when multiple vaults are found.

## Read a note

Use `read_file` with the resolved absolute path to the note. Prefer this over `cat` because it provides line numbers and pagination.

## List notes

Use `search_files` with `target: "files"` and the resolved vault path. Prefer this over `find` or `ls`.

- To list all markdown notes, use `pattern: "*.md"` under the vault path.
- To list a subfolder, search under that subfolder's absolute path.

## Search

Use `search_files` for both filename and content searches. Prefer this over `grep`, `find`, or `ls`.

- For filenames, use `search_files` with `target: "files"` and a filename `pattern`.
- For note contents, use `search_files` with `target: "content"`, the content regex as `pattern`, and `file_glob: "*.md"` when you want to restrict matches to markdown notes.

## Create a note

Use `write_file` with the resolved absolute path and the full markdown content. Prefer this over shell heredocs or `echo` because it avoids shell quoting issues and returns structured results.

## Append to a note

Prefer a native file-tool workflow when it is not awkward:

- Read the target note with `read_file`.
- Use `patch` for an anchored append when there is stable context, such as adding a section after an existing heading or appending before a known trailing block.
- Use `write_file` when rewriting the whole note is clearer than constructing a fragile patch.

For an anchored append with `patch`, replace the anchor with the anchor plus the new content.

For a simple append with no stable context, `terminal` is acceptable if it is the clearest safe option.

## Targeted edits

Use `patch` for focused note changes when the current content gives you stable context. Prefer this over shell text rewriting.

## Git Sync (cross-device)

To set up free automatic sync across devices using Git and the Obsidian Git community plugin, see `references/git-sync.md`. Covers: repository init, plugin installation, auto-commit/push configuration, and GitHub remote setup.

## Wikilinks

Obsidian links notes with `[[Note Name]]` syntax. When creating notes, use these to link related content.

## Mermaid Diagrams

Use Mermaid fenced code blocks for flowcharts, funnels, and sequence diagrams inside notes. Obsidian renders them natively. See `references/mermaid-diagrams.md` for patterns, color palettes, and funnel templates.