⛶  base.nvim  ⛶

A template for writing Neovim plugins

---

💡 Motivation

A minimal Neovim plugin is just a lua/ directory and a plugin/ autocommand. But a maintainable one needs tests, docs, types, CI, and a release workflow. base.nvim fills that gap — no framework, no abstraction, just the smallest possible set of opinionated defaults that work.

Starting a plugin shouldn't mean reinventing project structure and CI pipelines from scratch. base.nvim bundles the conventions used in production plugins so you can focus on writing plugin logic from day one:

• Proper directory layout following nvim-best-practices
• LuaCATS type annotations with LuaLS checking
• mini.test + luassert test suite
• StyLua formatting and linting
• CI with lint, typecheck, and test (stable + nightly)
• Automated releases via release-please with GitHub and LuaRocks publishing
• Health checks and vimdoc documentation
• Agent Skills for AI-assisted development (.agents/skills/)

Note

v3.0 ships with built-in Agent Skills for AI coding agents. Plugins derived from this template now include specialized skills for plugin development, testing, documentation, and commit conventions. See the AI Coding Agent section for details.

⚡️ Requirements

• Neovim ≥ 0.12.2
• StyLua: code formatting and linting
• LuaLS: type checking via LuaCATS annotations
• git: version control and lazy.nvim bootstrap
• Make: task runner for build and test commands

Optional:

• lazydev.nvim: Lua LSP configuration for plugin development

📦 Installation

1. Ensure you have requirements installed
2. Click "Use this template" → "Create a new repository" at the top of this page.
3. Choose a name with the .nvim extension (e.g., your-plugin.nvim).
4. Clone your new repository and cd into it.
5. Install your-plugin.nvim using your preferred plugin manager and configure Neovim for plugin development:

-- Install and configure your plugin during development
{
  "your-plugin.nvim",
  dir = "/path/to/your-plugin.nvim", -- So we are using the local version of the plugin
  branch = "main", -- Select the branch of the plugin to use
  lazy = false,
  opts = {},
  keys = {
    {
      "<leader>rb", -- Choose a key binding for reloading the plugin
      "<cmd>Lazy reload your-plugin.nvim<cr>",
      desc = "Reload your-plugin.nvim",
      mode = { "n", "v" },
    },
  },
}

-- Enable Lua language server support external libraries
{
  "folke/lazydev.nvim",
  ft = "lua",
  opts = {
    library = {
      "your-plugin.nvim",
    }
  },
}

🤖 AI Coding Agent

This template ships with Agent Skills in .agents/skills/, providing specialized instructions for AI coding agents. Skills follow the Agent Skills specification — the same SKILL.md format works across many agents (e.g. pi, Claude Code, GitHub Copilot, Cursor, Amp). Note that agents discover skills from different directories (e.g. .claude/skills/, .github/skills/). If your agent doesn't pick them up, try renaming .agents/ to its expected directory (e.g. mv .agents .claude for Claude Code).

Skill	Description
nvim-init	Initialize plugin project and verify development environment
nvim-plugin	Plugin development best practices and patterns
nvim-test	Execute tests and diagnose failures
nvim-doc	Write and update vimdoc help documentation
nvim-commit	Create conventional commits for release-please
nvim-help	Search Neovim's built-in :help documentation

🚀 Usage

Get started by reading the comprehensive documentation with :help base, which covers all plugin features and configuration options.

Note

Most Vim/Neovim plugins include built-in :help documentation. If you're new to this, start with :help to learn the basics.

🙏 Acknowledgments

• nvim-best-practices: Collection of DOs and DON'Ts for modern Neovim Lua plugin development
• nvim-lua-plugin-template: another template for Neovim Lua plugins
• LuaCATS annotations: type annotations to your Lua code
• mini.test: minimal test framework with child-process isolation