nvim-plugin-audit
Audit the Neovim plugins in this dotfiles repo one by one. Researches what current Neovim already covers and each plugin's maintenance status and news, asks the user to keep, replace or remove each one with AskUserQuestion, then applies the decisions (keymaps rerouted, :Lazy clea
Install
npx skills add https://github.com/babarot/dotfiles/tree/main/.claude/skills/nvim-plugin-audit
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install babarot-dotfiles@llmmart
git clone https://github.com/babarot/dotfiles.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole babarot/dotfiles collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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- 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
- Plugin specs:
- Neovim itself, LSP servers and treesitter parsers come from Nix:
nix/home-manager/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.
Run Neovim against the worktree
Work happens in a git worktree, but ~/.config links to home/.config of the main checkout. A plain nvim therefore reads the main checkout's config, and :Lazy clean writes its lazy-lock.json. From the worktree root, run every Neovim command in this skill as
XDG_CONFIG_HOME="$PWD/home/.config" nvim --headless ...
so it reads the worktree's edits and updates the worktree's lockfile. Plugins themselves are shared in ~/.local/share/nvim/lazy: a Lazy! clean also removes them from the Neovim the user runs until the change lands. Say so before running it.
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 underruntime/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
dependenciesor callrequire('<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
- 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
dependenciesentries 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
XDG_CONFIG_HOME="$PWD/home/.config" nvim --headless '+Lazy! clean' +qaso the plugin is removed and the worktree'slazy-lock.jsonis updated - If the change needs something outside Neovim (a server, a parser), add it to
nix/home-manager/tools/neovim.nix, build both hosts as AGENTS.md describes, and ask the user to run darwin-rebuild
Step 5: Verify
With headless Neovim against the worktree (XDG_CONFIG_HOME="$PWD/home/.config" 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 })andvim.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: check
git statusandgit diff --cached, and stage only the files this audit changed - Commit in the worktree, in English: an imperative summary, then a short body with the reasons (no session links or attribution trailers)
- Land in main only when the user asks, with the land skill (
git land); push only when asked - Report: a table of decisions, keymaps that changed, what was verified and what the user should check by eye, and the steps once it lands, on this Mac (run
nvim --headless '+Lazy! restore' +qaso the shared plugins match main's lockfile) and on the work Mac (pull,nvim --headless '+Lazy! restore' '+Lazy! clean' +qa, and darwin-rebuild when Nix changed)
Files (dotfiles)
-
SKILL.md 6.6 KB
--- name: nvim-plugin-audit description: Audit the Neovim plugins in this dotfiles repo one by one. Researches what current Neovim already covers and each plugin's maintenance status and news, asks the user to keep, replace or remove each one with AskUserQuestion, then applies the decisions (keymaps rerouted, :Lazy clean, README), verifies with headless Neovim and commits in the worktree. Use for "audit my Neovim plugins", "棚卸しして", "Neovim のプラグインを整理したい". allowed-tools: Read, Edit, Write, Grep, Glob, AskUserQuestion, WebSearch, WebFetch, Bash(nvim:*), Bash(gh api:*), Bash(gh repo view:*), Bash(git status:*), Bash(git diff:*), Bash(git log:*), Bash(git add:*), Bash(git rm:*), Bash(git commit:*), Bash(ls:*), Bash(grep:*), Bash(sed:*), Bash(cat:*) --- 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 - 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-manager/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. ## Run Neovim against the worktree Work happens in a git worktree, but `~/.config` links to `home/.config` of the main checkout. A plain `nvim` therefore reads the main checkout's config, and `:Lazy clean` writes its `lazy-lock.json`. From the worktree root, run every Neovim command in this skill as ```sh XDG_CONFIG_HOME="$PWD/home/.config" nvim --headless ... ``` so it reads the worktree's edits and updates the worktree's lockfile. Plugins themselves are shared in `~/.local/share/nvim/lazy`: a `Lazy! clean` also removes them from the Neovim the user runs until the change lands. Say so before running it. ## Step 1: Establish the baseline 1. 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`). 2. 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 `XDG_CONFIG_HOME="$PWD/home/.config" nvim --headless '+Lazy! clean' +qa` so the plugin is removed and the worktree's `lazy-lock.json` is updated - If the change needs something outside Neovim (a server, a parser), add it to `nix/home-manager/tools/neovim.nix`, build both hosts as AGENTS.md describes, and ask the user to run darwin-rebuild ## Step 5: Verify With headless Neovim against the worktree (`XDG_CONFIG_HOME="$PWD/home/.config" 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: check `git status` and `git diff --cached`, and stage only the files this audit changed - Commit in the worktree, in English: an imperative summary, then a short body with the reasons (no session links or attribution trailers) - Land in main only when the user asks, with the land skill (`git land`); push only when asked - Report: a table of decisions, keymaps that changed, what was verified and what the user should check by eye, and the steps once it lands, on this Mac (run `nvim --headless '+Lazy! restore' +qa` so the shared plugins match main's lockfile) and on the work Mac (pull, `nvim --headless '+Lazy! restore' '+Lazy! clean' +qa`, and darwin-rebuild when Nix changed)
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.