obsidian-nvim — Claude Code skill: what it does, how to install
Guides AI agents through configuring obsidian.nvim in Neovim, covering vaults, templates, daily notes, and picker integrations.
MIT 116 installs ★ 17 updated 2026-10-14
npx skills add julianobarbosa/claude-code-skills --skill obsidian-nvim -a claude-codeWhat obsidian-nvim does
This skill gives your coding assistant reference material for obsidian.nvim. It covers setup via lazy.nvim, workspace definitions, template configuration, frontmatter handling, and Zettelkasten-style identifier generation.
The guide details picker setups for Telescope, fzf-lua, and mini.pick, alongside auto-completion setups for both nvim-cmp and blink.cmp. Ripgrep must be installed on your machine; without it, note search and completion fail.
Image pasting depends on system utilities: pngpaste on macOS, and xclip or wl-clipboard on Linux. Template paths and date parameters expect Lua os.date syntax like %Y-%m-%d instead of Obsidian date tokens.
What it helps with
- Configure obsidian.nvim workspaces with lazy.nvim
- Set up wiki-link completion for blink.cmp or nvim-cmp
- Map keybindings for link navigation and note extraction
- Connect note search to Telescope or fzf-lua
Example prompts for the agent
- Configure obsidian.nvim in Neovim with personal and work workspaces
- Set up wiki link auto-completion for obsidian.nvim using blink.cmp
- Troubleshoot why note search is failing in obsidian.nvim
How to install obsidian-nvim
1Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill obsidian-nvim -a claude-code2Manually: put the files in place
~/.claude/skills/obsidian-nvim/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/obsidian-nvim/
1Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill obsidian-nvim -a codex2Manually: put the files in place
.agents/skills/obsidian-nvim/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill obsidian-nvim -a cursor2Manually: put the files in place
.cursor/skills/obsidian-nvim/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install julianobarbosa/claude-code-skills skills/obsidian-nvim2Manually: put the files in place
.github/skills/obsidian-nvim/SKILL.md1Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill obsidian-nvim -a gemini-cli2Platform CLI
gemini skills install https://github.com/julianobarbosa/claude-code-skills --path skills/obsidian-nvimManually: put the files in place
.devin/skills/obsidian-nvim/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill obsidian-nvim -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about obsidian-nvim
How do I install obsidian-nvim for Claude Code?
Run npx skills add julianobarbosa/claude-code-skills --skill obsidian-nvim -a claude-code.
What does the obsidian-nvim skill do?
It provides instructions and code patterns to configure the obsidian.nvim plugin, set keymaps, and manage Obsidian vaults from Neovim.
What external tools are required for obsidian.nvim?
You need Neovim 0.10.0 or higher and ripgrep. For pasting images directly into notes, macOS requires pngpaste while Linux needs xclip or wl-clipboard.
Source text
SKILL.md · MIT
---
name: obsidian-nvim
description: Guide for implementing obsidian.nvim - a Neovim plugin for Obsidian vault management. Use when configuring, troubleshooting, or extending obsidian.nvim features including workspace setup, daily notes, templates, completion, pickers, and UI customization.
---
# obsidian.nvim Skill
A comprehensive guide for implementing and configuring obsidian.nvim - the Neovim plugin for managing Obsidian vaults.
## Quick Start
### Minimal Installation (lazy.nvim)
```lua
return {
"obsidian-nvim/obsidian.nvim",
version = "*",
ft = "markdown",
opts = {
workspaces = {
{ name = "personal", path = "~/vaults/personal" },
},
},
}
```
### System Requirements
- **Neovim**: >= 0.10.0
- **ripgrep**: Required for completion and search (`brew install ripgrep`)
- **pngpaste** (macOS): For image pasting (`brew install pngpaste`)
- **xclip/wl-clipboard** (Linux): For image pasting
## Configuration
See [references/configuration.md](references/configuration.md) for complete configuration options.
### Essential Configuration Options
```lua
require("obsidian").setup({
-- Workspace configuration (required)
workspaces = {
{ name = "personal", path = "~/vaults/personal" },
{ name = "work", path = "~/vaults/work" },
},
-- Daily notes
daily_notes = {
folder = "daily",
date_format = "%Y-%m-%d",
alias_format = "%B %-d, %Y",
default_tags = { "daily-notes" },
},
-- Templates
templates = {
folder = "templates",
date_format = "%Y-%m-%d",
time_format = "%H:%M",
},
-- Note ID generation (Zettelkasten-style by default)
note_id_func = function(title)
local suffix = ""
if title ~= nil then
suffix = title:gsub(" ", "-"):gsub("[^A-Za-z0-9-]", ""):lower()
else
for _ = 1, 4 do
suffix = suffix .. string.char(math.random(65, 90))
end
end
return tostring(os.time()) .. "-" .. suffix
end,
-- Completion settings
completion = {
nvim_cmp = true, -- or blink = true for blink.cmp
min_chars = 2,
},
-- UI customization
ui = {
enable = true,
checkboxes = {
[" "] = { char = "", hl_group = "ObsidianTodo" },
["x"] = { char = "", hl_group = "ObsidianDone" },
},
},
})
```
## Commands
See [references/commands.md](references/commands.md) for complete command reference.
### Primary Commands
| Command | Description |
|---------|-------------|
| `:Obsidian` | Open command picker |
| `:Obsidian today [OFFSET]` | Open/create daily note |
| `:Obsidian new [TITLE]` | Create new note |
| `:Obsidian search [QUERY]` | Search vault with ripgrep |
| `:Obsidian quick_switch` | Fuzzy find notes |
| `:Obsidian backlinks` | Show references to current note |
| `:Obsidian template [NAME]` | Insert template |
| `:Obsidian workspace [NAME]` | Switch workspace |
### Visual Mode Commands
| Command | Description |
|---------|-------------|
| `:Obsidian link [QUERY]` | Link selection to existing note |
| `:Obsidian link_new [TITLE]` | Create note and link selection |
| `:Obsidian extract_note [TITLE]` | Extract selection to new note |
## Keymaps
### Smart Action (Recommended: `<CR>`)
```lua
vim.keymap.set("n", "<CR>", function()
if require("obsidian").util.cursor_on_markdown_link() then
return "<cmd>Obsidian follow_link<CR>"
else
return "<CR>"
end
end, { expr = true })
```
### Navigation Links
```lua
vim.keymap.set("n", "[o", function()
require("obsidian").util.nav_link("prev")
end, { buffer = true, desc = "Previous link" })
vim.keymap.set("n", "]o", function()
require("obsidian").util.nav_link("next")
end, { buffer = true, desc = "Next link" })
```
## Picker Integration
Configure your preferred picker:
```lua
picker = {
name = "telescope", -- or "fzf-lua", "mini.pick", "snacks.picker"
note_mappings = {
new = "<C-x>",
insert_link = "<C-l>",
},
tag_mappings = {
tag_note = "<C-x>",
insert_tag = "<C-l>",
},
},
```
## Completion Integration
### With blink.cmp
```lua
completion = {
blink = true,
nvim_cmp = false,
min_chars = 2,
},
```
### With nvim-cmp
```lua
completion = {
nvim_cmp = true,
blink = false,
min_chars = 2,
},
```
**Triggers:**
- `[[` - Wiki link completion
- `[` - Markdown link completion
- `#` - Tag completion
## Templates
### Template Variables
| Variable | Description |
|----------|-------------|
| `{{title}}` | Note title |
| `{{date}}` | Current date |
| `{{time}}` | Current time |
| `{{id}}` | Note ID |
### Custom Substitutions
```lua
templates = {
folder = "templates",
substitutions = {
yesterday = function()
return os.date("%Y-%m-%d", os.time() - 86400)
end,
tomorrow = function()
return os.date("%Y-%m-%d", os.time() + 86400)
end,
},
},
```
## Frontmatter Management
```lua
frontmatter = {
enabled = true,
func = function(note)
local out = { id = note.id, aliases = note.aliases, tags = note.tags }
if note.metadata ~= nil and not vim.tbl_isempty(note.metadata) then
for k, v in pairs(note.metadata) do
out[k] = v
end
end
return out
end,
sort = { "id", "aliases", "tags" },
},
```
## Troubleshooting
See [references/troubleshooting.md](references/troubleshooting.md) for comprehensive troubleshooting.
### Health Check
```vim
:checkhealth obsidian
```
### Quick Fixes
| Issue | Solution |
|-------|----------|
| Completion not working | Install ripgrep: `brew install ripgrep` |
| Picker not opening | Verify picker name matches installed plugin |
| Images not pasting | macOS: `brew install pngpaste` |
| Links not following | Ensure cursor is on `[[link]]` or `[text](link)` |
| Checkboxes not rendering | Set `:set conceallevel=2` |
| Workspace not found | Verify path exists and file is inside vault |
### Debug Mode
```lua
log_level = vim.log.levels.DEBUG,
```
## Examples
See [references/examples.md](references/examples.md) for practical configuration examples.
## Resources
- [GitHub Repository](https://github.com/obsidian-nvim/obsidian.nvim)
- [Wiki Documentation](https://github.com/obsidian-nvim/obsidian.nvim/wiki)
- [Breaking Changes](https://github.com/obsidian-nvim/obsidian.nvim/wiki/Breaking-Changes)
---
## Gotchas
- **The plugin requires Obsidian to be running for live updates** — vault changes from Neovim don't propagate to Obsidian's index until the app is open AND has focused the vault.
- **Completion source ordering conflicts with `cmp-buffer`** — LSP completion may not show note suggestions if buffer source ranks higher; explicit `sorting.priority_weight` adjustment needed.
- **Daily-note template paths use Lua's `os.date` format**, not Obsidian's natural-language date format — `%Y-%m-%d` in nvim, `YYYY-MM-DD` in Obsidian.
- **`require("obsidian").get_client():resolve_link()` returns nil for an unindexed file** — even if the file exists. Force a `:ObsidianRefresh` after creating notes outside the plugin.
- **lazy.nvim lazy-loading on `BufRead`: the first vault file you open before plugin spec evaluation doesn't get note features** — set `lazy=false` for obsidian.nvim or use a `VeryLazy` event.
© julianobarbosa · MIT · julianobarbosa/claude-code-skills