obsidian-nvim

Q: How do I install obsidian-nvim?

Run npx skills add https://github.com/julianobarbosa/claude-code-skills --skill obsidian-nvim in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/obsidian-nvim/ (personal) or .claude/skills/obsidian-nvim/ (project).

by julianobarbosaProductivity & Automation

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.

Installs: 114
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/julianobarbosa/claude-code-skills --skill obsidian-nvim

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads obsidian-nvim automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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)

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 for complete configuration options.

Essential Configuration Options

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 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>`)

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

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:

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

completion = {
  blink = true,
  nvim_cmp = false,
  min_chars = 2,
},

With nvim-cmp

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

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

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 for comprehensive troubleshooting.

Health Check

: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

log_level = vim.log.levels.DEBUG,

Examples

See references/examples.md for practical configuration examples.

Resources

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.

FAQ

What does the obsidian-nvim skill do?

How do I install obsidian-nvim?

Run npx skills add https://github.com/julianobarbosa/claude-code-skills --skill obsidian-nvim in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/obsidian-nvim/ (personal) or .claude/skills/obsidian-nvim/ (project).

Which AI agents can use obsidian-nvim?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is obsidian-nvim safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains obsidian-nvim?

It is published by julianobarbosa in julianobarbosa/claude-code-skills. It has 114 recorded installs.