neovim

Use when editing ANY Neovim configuration including init.lua, plugins, keymaps, LSP settings, or theme configuration. Provides file structure guidance and VHS testing workflow.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill streamlines the management and optimization of Neovim environments. It offers comprehensive guidance for configuring init.lua, managing plugins with lazy.nvim, and setting up LSP and Treesitter. A standout feature is its integrated VHS testing workflow, which allows for automated visual verification of configuration changes in an isolated terminal, ensuring a stable and error-free editor setup.

Use Cases

  • Automated Neovim Configuration: Efficiently edit and organize init.lua, keymaps, and LSP settings using a modular and scalable file structure.
  • Plugin Management: Seamlessly add, update, or configure plugins using the lazy.nvim framework with standardized inline options and setup logic.
  • Visual Regression Testing: Execute VHS tapes to capture screenshots and verify UI/theme changes in an isolated environment before applying them to the live session.
  • Environment Troubleshooting: Quickly diagnose and fix LSP connectivity issues, Treesitter errors, or plugin conflicts using a built-in verification checklist.
nameneovim
descriptionUse when editing ANY Neovim configuration including init.lua, plugins, keymaps, LSP settings, or theme configuration. Provides file structure guidance and VHS testing workflow.

Neovim Skill

Configuration Locations

  • Main config: home/.config/nvim/init.lua
  • Plugins: home/.config/nvim/lua/plugins.lua
  • Config modules: home/.config/nvim/lua/config/
    • keymaps.lua - Key mappings
    • lsp.lua - LSP configuration
    • completion.lua - Completion settings
    • which-key.lua - Which-key mappings
    • treesitter.lua - Treesitter config
    • telescope.lua - Telescope config
    • lualine.lua - Statusline config
    • oil.lua - Oil file manager config
  • Always edit files in ~/dev/dotfiles/, not symlinked files in ~/.config/

File Structure

home/.config/nvim/
├── init.lua           # Base config, options, rustaceanvim settings
├── lua/
│   ├── plugins.lua    # Lazy.nvim plugin definitions with opts
│   └── config/
│       ├── init.lua   # Loads all config modules
│       ├── keymaps.lua
│       ├── lsp.lua
│       └── ...
├── after/             # Filetype-specific settings
├── selene.toml        # Lua linter config
└── stylua.toml        # Lua formatter config

Plugin Configuration Pattern

Plugins use lazy.nvim with inline opts or config functions:

{
  "plugin/name",
  opts = {
    setting = value,
  },
}

For plugins requiring setup logic:

{
  "plugin/name",
  config = function(_, opts)
    require("plugin").setup(opts)
  end,
}

VHS Testing

CRITICAL: NEVER run nvim commands that affect the user's active session. VHS creates its own isolated terminal.

CRITICAL: ALWAYS use the tape in this skill folder. NEVER create ad-hoc tape files with different output names.

Use VHS to verify visual changes:

  1. Run the tape: vhs .claude/skills/neovim/neovim.tape
  2. Output screenshot goes to tmp/neovim.png
  3. Read the screenshot to verify before telling user the fix is complete

The tape opens neovim in a clean environment, waits for it to load, and captures a screenshot.

Color Scheme

Uses Catppuccin Mocha theme. Set in init.lua:

vim.cmd.colorscheme("catppuccin-mocha")

Key Mappings

Leader key is Space. Mappings defined in:

  • lua/config/keymaps.lua - General keymaps
  • lua/config/which-key.lua - Which-key groups and mappings
  • lua/plugins.lua - Plugin-specific mappings in plugin specs

LSP Setup

LSP configured via:

  • Mason for LSP server installation
  • mason-lspconfig for automatic setup
  • Individual server configs in lua/config/lsp.lua
  • Rustaceanvim configured separately in init.lua (must load before plugins)

Verification Checklist

Before declaring a config change complete:

  1. Confirm you edited files in ~/dev/dotfiles/home/.config/nvim/
  2. Run VHS tape to capture screenshot
  3. Verify neovim starts without errors
  4. Test the specific feature you changed
  5. Check no Lua errors in :messages

Common Issues

  • Plugin errors: Check lazy.nvim lockfile at ~/.local/share/nvim/lazy-lock.json
  • LSP not starting: Check :LspInfo and :Mason
  • Treesitter errors: Run :TSUpdate
  • Config reload: Use <leader>R or :source % on init.lua