Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add julianobarbosa/claude-code-skills --skill obsidian-nvim -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/obsidian-nvim/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/obsidian-nvim/

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

Similar skills

All skills for Notes, tasks and projects →

From the same set37

The whole set →
shellcheck shellcheck runs static analysis on bash and sh scripts to catch quoting bugs, syntax errors, and POSIX mismatches while generating automated diff patches. CX Codex +1 129installs shell-prompt The shell-prompt skill for Claude Code provides zsh prompt configs with Powerlevel10k, vi mode, mode-specific cursor shapes, and NORMAL/INSERT indicators for tracking the current mode. CX Codex +1 125installs azure-ad-sso azure-ad-sso wires a Kubernetes app to Azure AD (Entra ID) sign-in over OAuth2/OIDC: app registration, group claims, client secret in Key Vault. CX Codex +1 124installs mimir Teaches the agent how to stand up Grafana Mimir on Kubernetes and wire S3, GCS or Azure Blob for long-term Prometheus metric retention. CX Codex +1 118installs repomix repomix packs a repository into one file an LLM can read, with path filters, signature compression and token counts. Useful before a review or when code has to fit a context window. CX Codex +1 115installs managing-infra managing-infra guides Kubernetes architectural choices, Terraform module structuring, Helm usage, and GitHub Actions CI/CD workflows. CX Codex +1 115installs iterm2 This skill helps an agent work with iTerm2 and tmux, from split panes to persistent sessions. Use it for terminal setup and troubleshooting on macOS. CX Codex +1 115installs context7 Look up version-specific library documentation and code examples through Context7. Use it before coding against an API or framework behavior you’re unsure about. CX Codex +1 114installs

Project sponsors

Companies that keep this analytics open