Nvim Plugin Audit Skill for Claude

Audit the Neovim plugins in this repository together with the user: build the facts for every plugin, let the user decide one by one, then apply and verify the decisions. Claude Code only (it relies on AskUserQuestion).

Where things are

• Neovim config: home/.config/nvim/ in this repo (~/.config links to home/.config)
• Plugin specs: lua/plugins/*.lua (lazy.nvim, one file per area)
• Lockfile: lazy-lock.json; plugin list with sections and counts: lua/plugins/README.md
• Options, keymaps, autocmds: lua/config/{options,keymaps,autocmds}.lua
• Neovim itself, LSP servers and treesitter parsers come from Nix: nix/home/tools/neovim.nix. Never install servers or parsers from inside Neovim (no mason, no :TSInstall).
• The work Mac applies changes made here after pulling; see AGENTS.md.

Step 1: Establish the baseline

• Get the Neovim version (nvim --version) and read the bundled release notes: $(dirname $(dirname $(readlink -f $(command -v nvim))))/share/nvim/runtime/doc/news*.txt. List what the core now covers (commands, default keymaps, options, built-in plugins under runtime/pack/dist/opt).
• Search the web for recent changes in the plugin ecosystem that affect this config: archived or rewritten plugins, deprecated setup styles, new de facto choices. Keep the source URLs.

Step 2: Build the inventory

For every plugin in lazy-lock.json (and every spec in lua/plugins/, including disabled ones):

• Role, in one line, and the keymaps and commands this config gives it (grep the spec)
• Maintenance: last push and archived flag via gh api repos/<owner>/<repo> --jq '{pushed_at, archived}'
• What replaces it, if anything: a core feature (Step 1), another plugin already in the config (e.g. snacks.nvim), or a successor
• Recent news from the web when it matters (archival, breaking rewrite, deprecation)
• Dependents: other specs that list it in dependencies or call require('<it>')

Classify each as keep, replace, remove or ask. Judge by how the user works now: agents write most of the code, and Neovim is mainly for reading files and pointing Claude Code at them (claudecode.nvim), so reading and navigation matter more than writing aids. When the user wants to go conservatively, handle "replaced by core or a duplicate" first and leave writing aids for later.

Show the user a short summary (counts, the notable findings such as archived plugins or config that silently does nothing) before asking.

Step 3: Ask plugin by plugin

Use AskUserQuestion, at most 4 questions per call, one plugin (or one tight group, e.g. a plugin and its only dependency) per question:

• The question says what the plugin does in this config, its keymaps, and the last update date (plus "archived" when true)
• Options are concrete actions, not yes/no: "Keep", "Remove", "Replace with <core feature or plugin>". Put the recommended one first with "(Recommended)"
• Each option's description gives the reason and what takes over (the core feature, the other plugin, or nothing), including news found on the web
• Do not ask about plugins whose fate is obvious and already agreed (e.g. disabled specs); list them as done instead

If the user rejects the question to clarify, stop and ask what they want to know before continuing.

Step 4: Apply

For each removal or replacement:

• Delete the spec (or the block inside a shared file) and any dependencies entries pointing at it
• Reroute keymaps the user relies on to the replacement (usually in lua/config/keymaps.lua), keeping the same keys when possible
• Update lua/plugins/README.md: remove the entry, fix the section counts, and note replacements under "Replaced by Neovim itself"
• Run nvim --headless '+Lazy! clean' +qa so the plugin is removed and lazy-lock.json is updated
• If the change needs something outside Neovim (a server, a parser), add it to nix/home/tools/neovim.nix, build both hosts as AGENTS.md describes, and ask the user to run darwin-rebuild

Step 5: Verify

With headless Neovim (nvim --headless -c 'lua ...'), check:

• No messages after startup (vim.api.nvim_exec2('messages', { output = true })) with a real file open
• Every rerouted keymap exists (vim.fn.maparg(...)) and does what it should (e.g. feed the keys and inspect the buffer)
• For LSP or treesitter changes: vim.lsp.get_clients({ bufnr = buf }) and vim.treesitter.highlighter.active[buf] on a file of each affected language

Say plainly what could not be checked headless (rendering, popups) and ask the user to look.

Step 6: Commit and report

• Other sessions work in this repo at the same time: git pull --ff-only, then git status and git diff --cached, and stage only the files this audit changed
• Commit in English: an imperative summary, then a short body with the reasons (see AGENTS.md; no session links or attribution trailers)
• Report: a table of decisions, keymaps that changed, what was verified and what the user should check by eye, and the steps for the work Mac (pull, nvim --headless '+Lazy! restore' '+Lazy! clean' +qa, and darwin-rebuild when Nix changed)