# 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.

- Skill: `majiayu000/neovim-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/neovim-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/neovim-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/neovim-2

---


# 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:

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

For plugins requiring setup logic:

```lua
{
  "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:
```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