Vim / Neovim

Neovim is a hyperextensible Vim-based text editor configured entirely in Lua. The ~/.config/nvim/init.lua file is the entry point. Plugins are managed via lazy.nvim, LSPs via mason.nvim, syntax via nvim-treesitter, and fuzzy finding via telescope.nvim. Neovim exposes a rich Lua API (vim.api, vim.keymap, vim.opt, vim.fn) for deep customization without Vimscript.

When to use this skill

Trigger this skill when the user:

• Bootstraps or restructures an init.lua or ~/.config/nvim/ directory
• Installs or configures plugins with lazy.nvim
• Sets up an LSP server with mason.nvim + nvim-lspconfig
• Configures telescope.nvim pickers or extensions
• Installs or queries nvim-treesitter parsers
• Adds or refactors keymaps with vim.keymap.set
• Writes a custom Lua plugin, module, or autocommand

Do NOT trigger this skill for:

• Generic shell scripting or terminal multiplexer questions unrelated to Neovim
• VS Code, JetBrains, or other editors unless explicitly comparing to Neovim

Key principles

1. Lua over Vimscript - All new configuration and plugins must be written in Lua. Use vim.cmd only for legacy Vimscript interop where no Lua API exists.
2. Lazy-load everything - Plugins should specify event, ft, cmd, or keys in their lazy.nvim spec so startup time stays under 50 ms.
3. Structured config - Split concerns into lua/config/ (options, keymaps, autocmds) and lua/plugins/ (one file per plugin or logical group).
4. LSP-native features first - Prefer built-in LSP for go-to-definition, rename, diagnostics, and formatting before reaching for external plugins.
5. No global namespace pollution - Wrap plugin code in modules and return public APIs. Never define functions at the global _G level.

Core concepts

Modes

Motions

Motions describe where to move: w (word), b (back word), e (end of word), 0/^/$ (line start/first-char/end), gg/G (file start/end), % (matching bracket), f{char} (find char), t{char} (till char), /{pattern} (search forward).

Operators (d, c, y, =, >) combine with motions: dw, ci", ya{.

Text objects

i (inner) and a (around): iw (inner word), i" (inner quotes), i{ (inner braces), ip (inner paragraph), it (inner tag). Use with any operator.

Registers

• "" - default (unnamed) register
• "0 - last yank
• "+ / "* - system clipboard
• "_ - black hole (discard)
• "/ - last search pattern

Access in insert mode with <C-r>{register}.

Lua API surface

vim.opt.option = value          -- set option (OOP style)
vim.o.option = value            -- set global option (raw)
vim.keymap.set(mode, lhs, rhs, opts)  -- define keymap
vim.api.nvim_create_autocmd(event, opts)  -- autocommand
vim.api.nvim_create_user_command(name, fn, opts)  -- user command
vim.api.nvim_buf_get_lines(0, 0, -1, false)  -- buffer lines
vim.fn.expand("%:p")            -- call Vimscript function
vim.cmd("colorscheme catppuccin")  -- run Ex command

Common tasks

1. Bootstrap init.lua with lazy.nvim

-- ~/.config/nvim/init.lua
-- Bootstrap lazy.nvim
local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
if not vim.loop.fs_stat(lazypath) then
  vim.fn.system({
    "git", "clone", "--filter=blob:none",
    "https://github.com/folke/lazy.nvim.git",
    "--branch=stable", lazypath,
  })
end
vim.opt.rtp:prepend(lazypath)

-- Leader key must be set before lazy loads plugins
vim.g.mapleader = " "
vim.g.maplocalleader = "\\"

require("lazy").setup("plugins", {
  change_detection = { notify = false },
  install = { colorscheme = { "catppuccin", "habamax" } },
  performance = {
    rtp = {
      disabled_plugins = {
        "gzip", "matchit", "netrwPlugin", "tarPlugin",
        "tohtml", "tutor", "zipPlugin",
      },
    },
  },
})

require("config.options")
require("config.keymaps")
require("config.autocmds")

Each file in ~/.config/nvim/lua/plugins/ is auto-loaded by lazy.nvim and must return a plugin spec table (or array of specs).

2. Configure LSP with mason

-- lua/plugins/lsp.lua
return {
  {
    "williamboman/mason.nvim",
    build = ":MasonUpdate",
    opts = {},
  },
  {
    "williamboman/mason-lspconfig.nvim",
    dependencies = { "williamboman/mason.nvim", "neovim/nvim-lspconfig" },
    opts = {
      ensure_installed = { "lua_ls", "ts_ls", "pyright", "rust_analyzer" },
      automatic_installation = true,
    },
  },
  {
    "neovim/nvim-lspconfig",
    event = { "BufReadPre", "BufNewFile" },
    config = function()
      local lspconfig = require("lspconfig")
      local capabilities = require("cmp_nvim_lsp").default_capabilities()

      local on_attach = function(_, bufnr)
        local opts = { buffer = bufnr, silent = true }
        vim.keymap.set("n", "gd", vim.lsp.buf.definition, opts)
        vim.keymap.set("n", "gr", vim.lsp.buf.references, opts)
        vim.keymap.set("n", "K",  vim.lsp.buf.hover, opts)
        vim.keymap.set("n", "<leader>rn", vim.lsp.buf.rename, opts)
        vim.keymap.set({ "n", "v" }, "<leader>ca", vim.lsp.buf.code_action, opts)
        vim.keymap.set("n", "<leader>f", function()
          vim.lsp.buf.format({ async = true })
        end, opts)
      end

      local servers = { "lua_ls", "ts_ls", "pyright", "rust_analyzer" }
      for _, server in ipairs(servers) do
        lspconfig[server].setup({ capabilities = capabilities, on_attach = on_attach })
      end

      -- Diagnostics UI
      vim.diagnostic.config({
        virtual_text = { prefix = "●" },
        signs = true,
        underline = true,
        update_in_insert = false,
        severity_sort = true,
      })
    end,
  },
}

3. Set up telescope

-- lua/plugins/telescope.lua
return {
  {
    "nvim-telescope/telescope.nvim",
    cmd = "Telescope",
    keys = {
      { "<leader>ff", "<cmd>Telescope find_files<cr>",  desc = "Find files" },
      { "<leader>fg", "<cmd>Telescope live_grep<cr>",   desc = "Live grep" },
      { "<leader>fb", "<cmd>Telescope buffers<cr>",     desc = "Buffers" },
      { "<leader>fh", "<cmd>Telescope help_tags<cr>",   desc = "Help tags" },
      { "<leader>fr", "<cmd>Telescope oldfiles<cr>",    desc = "Recent files" },
    },
    dependencies = {
      "nvim-lua/plenary.nvim",
      { "nvim-telescope/telescope-fzf-native.nvim", build = "make" },
    },
    config = function()
      local telescope = require("telescope")
      telescope.setup({
        defaults = {
          sorting_strategy = "ascending",
          layout_config = { prompt_position = "top" },
          mappings = {
            i = {
              ["<C-j>"] = "move_selection_next",
              ["<C-k>"] = "move_selection_previous",
              ["<C-q>"] = "send_selected_to_qflist",
            },
          },
        },
      })
      telescope.load_extension("fzf")
    end,
  },
}

4. Configure treesitter

-- lua/plugins/treesitter.lua
return {
  {
    "nvim-treesitter/nvim-treesitter",
    build = ":TSUpdate",
    event = { "BufReadPost", "BufNewFile" },
    dependencies = { "nvim-treesitter/nvim-treesitter-textobjects" },
    config = function()
      require("nvim-treesitter.configs").setup({
        ensure_installed = {
          "lua", "vim", "vimdoc", "typescript", "javascript",
          "python", "rust", "go", "json", "yaml", "markdown",
        },
        highlight = { enable = true },
        indent    = { enable = true },
        textobjects = {
          select = {
            enable = true,
            lookahead = true,
            keymaps = {
              ["af"] = "@function.outer",
              ["if"] = "@function.inner",
              ["ac"] = "@class.outer",
              ["ic"] = "@class.inner",
              ["aa"] = "@parameter.outer",
              ["ia"] = "@parameter.inner",
            },
          },
          move = {
            enable = true,
            goto_next_start     = { ["]f"] = "@function.outer" },
            goto_previous_start = { ["[f"] = "@function.outer" },
          },
        },
      })
    end,
  },
}

5. Create custom keymaps

-- lua/config/keymaps.lua
local map = vim.keymap.set

-- Window navigation (replaces <C-w>h/j/k/l)
map("n", "<C-h>", "<C-w>h", { desc = "Move to left window" })
map("n", "<C-j>", "<C-w>j", { desc = "Move to lower window" })
map("n", "<C-k>", "<C-w>k", { desc = "Move to upper window" })
map("n", "<C-l>", "<C-w>l", { desc = "Move to right window" })

-- Stay in visual mode after indenting
map("v", "<", "<gv", { desc = "Indent left" })
map("v", ">", ">gv", { desc = "Indent right" })

-- Paste without overwriting register
map("v", "p", '"_dP', { desc = "Paste without yank" })

Always set desc - it powers which-key.nvim and :help lookups.

6. Write a simple plugin

-- lua/myplugin/init.lua
local M = {}

M.config = {
  greeting = "Hello from Neovim!",
}

---Setup the plugin.
---@param opts? table Optional config overrides
function M.setup(opts)
  M.config = vim.tbl_deep_extend("force", M.config, opts or {})

  vim.api.nvim_create_user_command("Greet", function()
    vim.notify(M.config.greeting, vim.log.levels.INFO)
  end, { desc = "Show greeting" })
end

return M

Load in init.lua:

require("myplugin").setup({ greeting = "Hello, world!" })

Use vim.tbl_deep_extend("force", defaults, overrides) for option merging. Expose only setup() and intentional public functions; keep internals local.

7. Set up autocommands

-- lua/config/autocmds.lua
local augroup = function(name)
  return vim.api.nvim_create_augroup(name, { clear = true })
end

-- Highlight yanked text briefly
vim.api.nvim_create_autocmd("TextYankPost", {
  group = augroup("highlight_yank"),
  callback = function()
    vim.highlight.on_yank({ higroup = "IncSearch", timeout = 150 })
  end,
})

-- Restore cursor position on file open
vim.api.nvim_create_autocmd("BufReadPost", {
  group = augroup("restore_cursor"),
  callback = function()
    local mark = vim.api.nvim_buf_get_mark(0, '"')
    if mark[1] > 0 and mark[1] <= vim.api.nvim_buf_line_count(0) then
      vim.api.nvim_win_set_cursor(0, mark)
    end
  end,
})

Always pass a named augroup with clear = true to prevent duplicate autocmds on re-sourcing.

Anti-patterns

Gotchas

1. mapleader must be set before lazy.setup() - If you set vim.g.mapleader after calling require("lazy").setup(...), plugins that define keymaps using <leader> in their spec will use the default \ leader instead. Always set leader keys before the lazy setup call in init.lua.

2. Autocommands duplicate on re-sourcing if not cleared - Every time you :source $MYVIMRC or a module is re-required, nvim_create_autocmd appends another listener. Without a named augroup with clear = true, you accumulate duplicate handlers that fire multiple times. This is especially visible with format-on-save callbacks.

3. LSP on_attach runs once per buffer, not per server - If multiple LSP servers attach to the same buffer, on_attach runs for each. Keymaps defined in on_attach without buffer = bufnr scope become global and conflict. Always pass { buffer = bufnr } to all keymaps defined in on_attach.

4. Lazy-loading by cmd breaks if the plugin registers the command in setup() - If a plugin's command only exists after setup() is called, and you lazy-load it with cmd = "PluginCommand", Neovim will try to open the plugin to run the command but the command won't exist yet. Either eager-load plugins that register commands dynamically or use event = "VeryLazy".

5. Treesitter and LSP syntax highlighting conflict when both are enabled for the same language - With both highlight.enable = true in treesitter and an active LSP, you may see double-highlighted tokens or incorrect colors. Disable LSP semantic token highlighting explicitly: client.server_capabilities.semanticTokensProvider = nil in on_attach if treesitter handles highlighting.

References

For detailed content on specific Neovim sub-domains, read the relevant file from the references/ folder:

• references/plugin-ecosystem.md - Essential plugins by category with lazy.nvim specs

Only load a references file if the current task requires it.