# Kriscard Kriscard Claude Plugins Neovim Best Practices

> Neovim Best Practices

- Skill: `tomevault-io/kriscard-kriscard-claude-plugins-neovim-best-practices` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/kriscard-kriscard-claude-plugins-neovim-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/kriscard-kriscard-claude-plugins-neovim-best-practices/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/kriscard-kriscard-claude-plugins-neovim-best-practices

---


# Neovim Best Practices

Opinionated guidance for modern Neovim configuration. This skill covers the decisions and patterns that matter — not documentation you can look up.

## Core Decisions

These are the opinionated choices this config follows. Apply these unless the user explicitly wants something different.

### Lua Only, No Vimscript

All configuration in Lua. No `vim.cmd()` wrappers around Vimscript unless there's no Lua API equivalent. Use `vim.opt` for options, `vim.keymap.set` for keymaps, `vim.api.nvim_create_autocmd` for autocommands.

### lazy.nvim for Plugin Management

One plugin per file in `lua/plugins/`. Every plugin lazy-loaded unless needed at startup (colorscheme, treesitter, statusline). See the `lazy-nvim-optimization` skill for deep lazy-loading guidance.

### Namespace Under Username

```
~/.config/nvim/
├── init.lua
└── lua/
    └── kriscard/
        ├── init.lua
        ├── options.lua
        ├── keymaps.lua
        ├── autocmds.lua
        └── lazy.lua
```

This prevents collisions with plugin module names. Entry point is just `require("kriscard")`.

### LSP via Mason + nvim-lspconfig

Mason manages server installations. nvim-lspconfig provides server configurations. Use `cmp_nvim_lsp` capabilities for completion integration. Set keymaps in `on_attach` so they're buffer-local.

### Leader Key Conventions

`<Space>` as leader, set before any plugins load. Organized by prefix:
- `f` = find/search (telescope)
- `g` = git operations
- `b` = buffer management
- `w` = window management
- `l` = LSP operations
- `t` = terminal/tests

Every keymap requires a `desc` field for which-key discoverability.

## Version-Specific Features (0.10+)

Take advantage of these — they replace plugins:

- **Built-in commenting**: `gcc`/`gc` work natively. Can replace Comment.nvim.
- **Inlay hints**: `vim.lsp.inlay_hint.enable(true)` — no plugin needed.
- **Improved diagnostics**: `vim.diagnostic.config()` with `float.border` for better display.

## Deprecated Patterns to Avoid

| Instead of... | Use... |
|---------------|--------|
| `vim.cmd("set number")` | `vim.opt.number = true` |
| `vim.api.nvim_set_keymap()` | `vim.keymap.set()` |
| `vim.cmd("augroup...")` | `vim.api.nvim_create_autocmd()` |
| Vimscript autocommands | Lua with `callback` |
| Comment.nvim (on 0.10+) | Built-in `gcc` |

## Checklists

### Config Structure

- [ ] `init.lua` is entry point only (just `require("kriscard")`)
- [ ] Config namespaced under username in `lua/`
- [ ] Plugin specs in `lua/plugins/` (one per file or logical group)
- [ ] Options, keymaps, autocmds in separate files
- [ ] Using lazy.nvim for plugin management

### Code Quality

- [ ] All config in Lua (no Vimscript)
- [ ] `vim.opt` for options
- [ ] `vim.keymap.set` with `desc` for keymaps
- [ ] `vim.api.nvim_create_autocmd` for autocommands
- [ ] No deprecated APIs
- [ ] Leader key set before plugin loading

### Performance

- [ ] Startup under 50ms (`nvim --startuptime`)
- [ ] Plugins lazy-loaded by cmd/keys/ft/event
- [ ] Heavy plugins deferred with `VeryLazy`
- [ ] No synchronous system calls at startup

## Reference Files

For detailed information:
- **`references/plugin-recommendations.md`** - Curated plugin list by category
- **`references/lsp-setup.md`** - Comprehensive LSP configuration guide
- **`references/migration-guide.md`** - Migrating from Vimscript to Lua

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/kriscard) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->