skills.rest
mmgeorge
mmgeorgeCOMMUNITY
Explore all skills by this author →
GitHub

neovim-lua-dev

Develop and debug Neovim Lua plugins with modular architecture and live RPC inspection.

1|Updated Sep 3, 2017
Search Tags:#debugging#plugin development#async#lua#neovim#tree-sitter#rpc
One-click install
npx skills add https://github.com/mmgeorge/config --skill neovim-lua-dev-mmgeorge
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: neovim-lua-dev
Source: https://github.com/mmgeorge/config/tree/main/.rulesync/skills/neovim-lua-dev
Command: npx skills add https://github.com/mmgeorge/config --skill neovim-lua-dev-mmgeorge

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Writing Neovim plugins in Lua involves subtle pitfalls: blocking the UI with synchronous process calls, circular module dependencies, stale asynchronous state, fold resets, and cursor jumps. This Skill provides architectural rules, debugging patterns, and live-instance verification procedures so plugin code stays responsive, modular, and correct. ## Core Features & Use Cases - Plugin Architecture Guidance: Enforces layered module structure (views -> render -> git -> infra), thin init.lua facades, dependency-free session state, and EmmyLua/LuaLS type annotations. - Asynchronous Execution Patterns: Covers vim.system-based async Git/CLI calls, monotonic request ID cancellation, optimistic UI journals, and serialized index mutations. - Rendering and Debugging References: Documents viewport-scoped decoration providers, native folding, Tree-sitter async parsing, Trouble.nvim v3 sources, Snacks.nvim diff rendering, and a catalog of 14 common failure modes with fixes. - Live Editor Verification: Drives running Neovim instances over the $NVIM socket to hot-reload modules, execute commands, and inspect buffers, diagnostics, and extmarks. - Use Case: When refactoring a Git status plugin, follow the layering rules to break circular requires, convert synchronous git calls to vim.system callbacks, then hot-reload the module in a running Neovim instance via --remote-expr to verify behavior without restarting the editor. ## Quick Start Ask the assistant to refactor your Neovim plugin's synchronous git calls into asynchronous vim.system callbacks following the neovim-lua-dev guidelines.

Frequently Asked Questions about neovim-lua-dev

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run Git commands asynchronously in a Neovim plugin?▼

Use vim.system with explicit text, stdout, and stderr options and a callback, never vim.fn.system or vim.system():wait() in render paths or keymaps. Wrap buffer mutations from the callback in vim.schedule and check result.code before updating state.

How do I inspect a running Neovim instance from the terminal?▼

Use nvim --server "$NVIM" --remote-expr with luaeval expressions to query buffers, cursor positions, LSP clients, and diagnostics. Encode complex results with vim.json.encode and filter out NVIM_APPNAME warnings before parsing output.

How do I fix circular require dependencies in Lua Neovim plugins?▼

Keep static top-of-file requires for acyclic edges and convert only cycle-closing back-edges into lazy in-function accessors like local function mod() return require("...") end. Identify strongly connected components in the dependency graph and lazify the minimal feedback arc set.

Why does my Neovim plugin freeze when rendering large diffs?▼

Freezing usually comes from synchronous process calls, eager syntax highlighting, or extmark allocation across off-screen lines. Store full text in the buffer but scope decorations to the visible viewport with nvim_set_decoration_provider and enforce a row rendering budget.

Why do folds reset when my Neovim plugin refreshes?▼

Calling fold level functions on every refresh overrides manual fold expansions made by the user. Apply default fold levels only once during initial render and preserve fold state across refreshes by keying fold models with stable node IDs.

How do I hot-reload a Neovim plugin without restarting the editor?▼

Clear each modified submodule from package.loaded over the $NVIM socket, then call setup() and execute your plugin command via --remote-expr. Every submodule is cached separately, so clear all affected paths explicitly before reloading the parent package.

Related Skills

Explore More Software Engineering Skills→
AbsolutelySkilledAbsolutelySkilled
207

vim-neovim

Automate Neovim configuration and plugin management with Lua workflows.

Official
Advanced
tkancftkancf
1

nvim-plugin-add

Add and configure Neovim plugins with lazy.nvim while preventing keymap conflicts.

Community
Intermediate
yankeeinlondonyankeeinlondon
3

crossterm

Cross-platform terminal UI development for Rust with cursor, keyboard, mouse, and screen management.

Community
Advanced
ThePrimeagenThePrimeagen
232

vim

Reference the Neovim Lua API for functions, types, and Vimscript equivalents.

Community
Intermediate