AgentSkillsCN

neovim-lua-plugin

在为 Neovim 开发 Lua 插件时使用，包括用户命令、键映射、延迟加载、健康检查，以及帮助文档的编写。即便用户提出快捷方式或快速解决方案的需求，也应遵循 <Plug> 映射的最佳实践、延迟加载机制与合理的代码结构，确保插件设计规范、高效且易于维护。

SKILL.md
--- frontmatter
name: neovim-lua-plugin
description: Use when developing Lua plugins for Neovim, including user commands, keymaps, lazy loading, health checks, or help documentation. Apply best practices for <Plug> mappings, deferred require, proper structure, even when user requests shortcuts or quick solutions.

Neovim Lua Plugin

Develop Neovim plugins in Lua following official best practices.

Core Pattern

Keep plugin/*.lua minimal. Defer require() into callbacks.

lua
-- ✅ GOOD: Lazy-loads
vim.api.nvim_create_user_command('Cmd', function()
    require('plugin').action()
end, {})

Key Practices

PracticeWhyHow
Defer require()Minimize startupCall require() in callbacks
Use <Plug> mappingsUser controls keysCreate <Plug>(Action)
Add health checksPrevent support issueslua/plugin/health.lua
Use ftplugin/Proper lazy loadingftplugin/{filetype}.lua

<Plug> Pattern

lua
-- Plugin: deferred
vim.keymap.set('n', '<Plug>(Action)', function()
    require('plugin').action()
end)
-- User: binds to their keys
vim.keymap.set('n', '<leader>a', '<Plug>(Action)')

Common Mistakes

  • •Loading at top of plugin/*.lua → Move require() into callbacks
  • •Direct leader mappings → Use <Plug>(Action)
  • •No health checks → Add lua/plugin/health.lua
  • •lazy.nvim ft specs → Use ftplugin/{filetype}.lua

Official Docs

https://neovim.io/doc/user/lua-plugin.html

Supporting Files

FileWhen to Use
api-reference.mdNeed API details (commands, keymaps, autocommands)
examples.mdNeed complete code patterns and advanced examples
health-checks.mdImplementing :checkhealth support
help-conventions.mdWriting :help documentation (vimdoc files)
lsp.mdAdding LSP integration to your plugin
treesitter.mdUsing Treesitter queries/parsing in your plugin
plenary.mdUsing plenary.nvim library (async, job, path, testing, etc.)