feat(lua-toolkit): add lua writing skill

Trying to get more into lua development with modern neovim standards.
Curate a skillset to remind me of the modern / proper way to do things
nowadays.

Author: khaneliman

modules/common/ai-tools/skills/lua-toolkit/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: lua-toolkit
+description: Neovim Lua plugin development playbooks following mrcjkb / nvim-best-practices conventions — project architecture, self lazy-loading, vim.g configuration, scoped commands and <Plug> keymaps, health checks, type-safe tooling, busted testing, and LuaRocks distribution. Use when writing or refactoring a Neovim Lua plugin, designing vim.g/setup config, deciding command/keymap APIs, adding checkhealth, configuring lua-ls/luacheck/stylua/LuaCATS, or setting up busted/nlua tests and SemVer LuaRocks releases.
+---
+
+# Lua Toolkit
+
+Use this skill for authoring and refactoring Neovim Lua plugins targeting
+LuaJIT/Lua 5.1. It covers architecture, loading strategy, configuration design,
+public API surface, tooling, testing, and distribution.
+
+Guidance follows the mrcjkb / nvim-best-practices conventions (LuaRocks-first,
+type-safe, self-lazy-loading, no forced `setup()`). This skill is Neovim-plugin
+specific. For general Lua embedded elsewhere, only the tooling and runtime
+guardrails transfer.
+
+## How I choose what to do (progressive disclosure)
+
+When invoked, route to one mode and load only that reference unless the work
+crosses boundaries:
+
+1. **plugin-architecture** — directory layout, `plugin/` vs `lua/` separation,
+   deferred loading, modular refactoring, and LuaJIT runtime guardrails.
+2. **configuration** — `vim.g.<plugin>` config tables (not forced `setup()`),
+   `vim.tbl_deep_extend` merge semantics, `vim.validate` (0.11+ signature), and
+   `health.lua` checks.
+3. **loading-and-install** — self lazy-loading (don't rely on the plugin
+   manager), minimal install specs, native-API-over-deps, and `build` steps.
+4. **apis-and-keymaps** — single scoped command with subcommand completion,
+   `<Plug>` mappings with no default keymaps, buffer-local state, and
+   `ftplugin`/`after/ftplugin` filetype logic.
+5. **tooling-and-quality** — LuaCATS + lua-ls type safety, `.luarc.json`,
+   `.luacheckrc`, and `.stylua.toml`.
+6. **testing-and-distribution** — `busted` + `nlua` tests, CI matrices, vimCATS
+   Vimdoc generation, and SemVer LuaRocks publishing.
+
+If intent is unclear, ask for the mode before applying changes.
+
+## Playbooks
+
+- Read [plugin-architecture.md](references/plugin-architecture.md) for the
+  runtimepath directory model, no-runtime-entrypoint plugins, the
+  deferred-`require` loading pattern, the `util.lua` refactoring imperative,
+  global-pollution rules, and the `if jit then ... else` fallback pattern.
+- Read [configuration.md](references/configuration.md) for the `vim.g.<plugin>`
+  (table-or-function) config pattern, partial LuaCATS config classes,
+  dictionary-vs-list `tbl_deep_extend` behavior, the modern `vim.validate`
+  signature, and `lua/<plugin>/health.lua` checks.
+- Read [loading-and-install.md](references/loading-and-install.md) for
+  self-lazy-loading via `plugin/`+`ftplugin/`, minimal lazy.nvim install specs,
+  preferring native APIs over `plenary`, `lazy = true` deps, and coroutine
+  `build` constraints.
+- Read [apis-and-keymaps.md](references/apis-and-keymaps.md) for the scoped
+  subcommand + `complete` pattern, `<Plug>` mappings with no default keymaps,
+  buffer filetype assignment timing, and `ftplugin` vs `after/ftplugin`.
+- Read [tooling-and-quality.md](references/tooling-and-quality.md) for LuaCATS +
+  lua-ls as the primary correctness tool, `.luarc.json` (`"Lua 5.1"`), the
+  `lua51` luacheck config, and the stylua baseline.
+- Read [testing-and-distribution.md](references/testing-and-distribution.md) for
+  `busted`+`nlua` (and `neorocksTest` for Nix), the stable/nightly CI matrix,
+  vimCATS/panvimdoc generation, and SemVer `.rockspec`/`luarocks-tag-release`.
+
+## Core Rules (apply in every mode)
+
+- Target Lua 5.1 / LuaJIT 2.1. Do not use Lua 5.2+ dialect features (new `goto`
+  scoping, integer division, native bitwise operators); use `require("bit")` for
+  bit ops — Neovim guarantees it even on non-JIT builds.
+- Never declare globals. All state, caches, and functions live in `local`
+  bindings or the module table returned by the file.
+- Separate configuration from initialization. Do not force `setup()`; prefer a
+  `vim.g.<plugin>` config table read lazily.
+- Self-lazy-load: keep startup work out of `lua/`, use `plugin/`+`ftplugin/`,
+  and defer `require()` into command/keymap closures. Don't rely on the plugin
+  manager to lazy-load for you.
+- Expose one scoped command with subcommand completion, not many commands.
+- Expose user-bindable actions as `<Plug>` mappings and ship no default keymaps.
+- Prioritize type safety: LuaCATS annotations + lua-ls, gated in CI.
+- Distribute on LuaRocks with SemVer; never `0ver`.
+
+## Reference Implementations
+
+Concrete examples in this skill are drawn from these repos — consult them for
+full, working context:
+
+- `mrcjkb/nvim-best-practices` — the prose rules this skill follows.
+- `mrcjkb/nvim-lua-nix-plugin-template` — Nix CI: `.busted`, `neorocksTest`
+  stable/nightly checks, `lemmy-help` docgen, `luarocks-tag-release`,
+  release-please. Closest match for this (Nix) repo.
+- `mrcjkb/rustaceanvim` — `vim.g.<plugin>` config (table-or-function), scoped
+  `:RustLsp` command with completion, `ftplugin`-based loading (no `plugin/`),
+  `health.lua`, `.luarc.json`.
+- `mrcjkb/neotest-haskell` — adapter/library with no runtime entry points;
+  one-module-per-responsibility `lua/` tree and tree-sitter `queries/`.
+
+## Cross-Skill Boundaries
+
+- Use `writing-nix` before editing any Nix that packages or wires the plugin
+  (e.g. Nixvim/`vimUtils` derivations).
+- Use `git-toolkit` for commit strategy and local history surgery.
+- Use `github-toolkit` for PR review comments and CI check triage.
+- Prefer one-off tooling via `nix shell`/`,` (stylua, luacheck, neovim nightly)
+  instead of adding persistent dependencies just to lint or test.
+
+## Reporting Rules
+
+- Show exact commands, file paths, and minimal snippets.
+- Label snippets as one of: executed, syntax checked, or template only.
+- Separate measured facts (startup time, test output) from design guidance.
+- Name the Neovim version when behavior is version-gated (e.g. `vim.validate`
+  signature deprecated in 0.11, removed in 1.0).

modules/common/ai-tools/skills/lua-toolkit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Lua Toolkit"
+  short_description: "Neovim Lua plugin architecture, config, lazy.nvim, tooling, tests, and distribution"
+  default_prompt: "Help architect, configure, integrate, lint, test, or distribute a Neovim Lua plugin."

modules/common/ai-tools/skills/lua-toolkit/references/apis-and-keymaps.md

@@ -0,0 +1,106 @@
+# Public APIs, Commands, Keymaps, and Filetypes
+
+Use this playbook for exposing user-facing entry points and buffer/filetype
+behavior. These follow the mrcjkb / nvim-best-practices conventions.
+
+## One Scoped Command with Subcommands
+
+Do **not** create a separate command per action (`:MyPluginInstall`,
+`:MyPluginPrune`, ...). Expose a single scoped command that dispatches
+subcommands, with completion for each: `:MyPlugin install`, `:MyPlugin update`.
+
+Register it with `nargs = "+"`, parse `opts.fargs`, and supply a `complete`
+function that filters subcommands by the current prefix.
+
+```lua
+-- File: plugin/my_plugin.lua  (template only)
+local subcommands = {
+  install = function(args) require("my_plugin.core").install(args) end,
+  update = function(args) require("my_plugin.core").update(args) end,
+}
+
+vim.api.nvim_create_user_command("MyPlugin", function(opts)
+  local name = table.remove(opts.fargs, 1)
+  local sub = subcommands[name]
+  if not sub then
+    return vim.notify("MyPlugin: unknown subcommand " .. tostring(name), vim.log.levels.ERROR)
+  end
+  sub(opts.fargs) -- defer require() into the handler
+end, {
+  nargs = "+",
+  desc = "my_plugin commands",
+  complete = function(arg_lead, cmdline)
+    -- only complete the first token as a subcommand name
+    if cmdline:match("^%s*MyPlugin%s+%S*$") then
+      return vim.tbl_filter(function(k)
+        return k:find(arg_lead, 1, true) == 1
+      end, vim.tbl_keys(subcommands))
+    end
+    return {}
+  end,
+})
+```
+
+This is the pattern behind `:Rocks <subcommand>` and `mrcjkb/rustaceanvim`'s
+`:RustLsp <subcommand>` (which also sets `range = true` so subcommands can act on
+a visual selection via `opts.range`/`opts.line1`/`opts.line2`). For complex
+argument parsing, a library such as `mega.cmdparse` reduces boilerplate.
+
+## Keymaps: Provide `<Plug>`, Set No Defaults
+
+Do **not** create automatic/default keymaps (they conflict with user configs)
+and do **not** invent a keymap-setup DSL. Expose `<Plug>` mappings and let users
+bind their own keys.
+
+`<Plug>` mappings: one-line user config, safe when the plugin is absent, support
+`expr = true`, and route by mode via Neovim's C-level mode handling — no
+hand-rolled mode checks in the payload.
+
+```lua
+-- File: plugin/my_plugin.lua  (template only)
+vim.keymap.set("n", "<Plug>(MyPluginAction)", function()
+  require("my_plugin.core").execute_action({ mode = "normal" })
+end, { desc = "my_plugin: action (normal)" })
+
+vim.keymap.set("x", "<Plug>(MyPluginAction)", function()
+  require("my_plugin.core").execute_action({ mode = "visual" })
+end, { desc = "my_plugin: action (visual)" })
+```
+
+Users bind it themselves; Neovim routes by active mode:
+
+```lua
+vim.keymap.set({ "n", "x" }, "<leader>ma", "<Plug>(MyPluginAction)")
+```
+
+If you must ship a default binding, gate it on
+`vim.fn.hasmapto("<Plug>(...)") == 0` so you never clobber a user mapping — but
+prefer shipping no default at all.
+
+## Buffer-Local State and Filetypes
+
+Plugins that present a UI buffer (file explorers, dashboards, floating
+diagnostics) should assign a custom `filetype` so users get granular control.
+
+- Set the custom filetype **as late as possible** in buffer init, so the
+  `FileType` event fires only after data structures are ready. This lets users'
+  own autocommands and `ftplugin/` scripts run against a fully realized buffer.
+
+For language-specific behavior on existing filetypes, put logic in
+`ftplugin/<lang>.lua`, not a monolithic autocommand block in core init. To
+override `$VIMRUNTIME` defaults, use `after/ftplugin/<lang>.lua`. Guard against
+re-sourcing with a buffer-local variable.
+
+```lua
+-- File: ftplugin/rust.lua  (template only)
+if vim.b.did_my_plugin_rust_setup then
+  return
+end
+vim.b.did_my_plugin_rust_setup = true
+
+local bufnr = vim.api.nvim_get_current_buf()
+
+vim.keymap.set("n", "<Plug>(MyPluginRustAnalyzer)", function()
+  require("my_plugin.rust_tools").run_analyzer()
+end, { buffer = bufnr, desc = "my_plugin: run analyzer" })
+```

modules/common/ai-tools/skills/lua-toolkit/references/configuration.md

@@ -0,0 +1,144 @@
+# Configuration UX
+
+Use this playbook for designing the user-facing configuration interface and
+runtime health checks. These follow the mrcjkb / nvim-best-practices
+conventions.
+
+## Separate Configuration from Initialization
+
+Two distinct concerns:
+
+- **Configuration** — the user's chosen options. Should be declarable with no
+  side effects and no mandatory function call.
+- **Initialization** — wiring commands, autocommands, and state. Should happen
+  automatically and lazily (see plugin-architecture), not be forced on the user.
+
+## `setup()` Is Not a Gate — Prefer `vim.g.<plugin>`
+
+Do not force users to call `setup()` to use the plugin. The preferred interface
+is a `vim.g.<plugin>` (or `vim.b.<plugin>` for buffer-local) namespace table: it
+is Vimscript-compatible, requires no initialization call, and can be read lazily
+so users may set it before _or_ after the plugin loads.
+
+Allow the value to be a table or a function returning a table (rustaceanvim
+style), so users can compute config lazily:
+
+```lua
+-- User config (no setup() needed):
+---@type my_plugin.Opts
+vim.g.my_plugin = {
+  strategy = "incremental",
+  ui = { border = "rounded" },
+}
+-- or a function, evaluated when the plugin reads it:
+vim.g.my_plugin = function()
+  return { strategy = "incremental" }
+end
+```
+
+This is the `vim.g.<plugin>` interface documented by `mrcjkb/rustaceanvim`
+(`vim.g.rustaceanvim`, a `rustaceanvim.Opts` table or function).
+
+Read and merge it lazily inside the plugin, with type annotations marking the
+user-facing table as partial and the internal config as fully-defaulted:
+
+```lua
+-- File: lua/my_plugin/config.lua  (template only)
+local M = {}
+
+---@class my_plugin.Config       -- internal: every field non-nil
+local default_config = {
+  strategy = "incremental",
+  ui = {
+    border = "rounded",
+    icons = true,
+    colors = { error = "#ff0000", warn = "#ffff00" }, -- dict: deep-merged
+  },
+  capabilities = { "formatting", "diagnostics" },       -- list: overwritten
+}
+
+--- Resolve user config (table or function) and merge over defaults.
+---@return my_plugin.Config
+function M.get()
+  ---@type my_plugin.Opts | fun():my_plugin.Opts | nil
+  local user = vim.g.my_plugin
+  if type(user) == "function" then
+    user = user()
+  end
+  local merged = vim.tbl_deep_extend("force", default_config, user or {})
+  M.validate(merged)
+  return merged
+end
+
+return M
+```
+
+And the user-facing class, declared partial so all fields are optional:
+
+```lua
+---@class (partial) my_plugin.Opts: my_plugin.Config
+```
+
+Keep a `setup()` only as an optional convenience for users who prefer it; it
+must not be the sole entry point.
+
+## Merge Semantics: `vim.tbl_deep_extend`
+
+`vim.tbl_deep_extend(behavior, ...)` (usually `"force"`) merges tables but
+treats the two table shapes differently:
+
+- **Dictionary-like** (string keys): merged recursively.
+- **List-like** (sequential integer keys): opaque, **overwritten** wholesale,
+  not concatenated.
+
+Intentional: lists usually represent atomic, ordered collections (tool order,
+flags). If the default is `capabilities = { "formatting", "diagnostics" }` and
+the user passes `capabilities = { "formatting" }`, the result is exactly the
+user's single-item list — no merge, no dedup.
+
+## Validation: `vim.validate`
+
+Validate the merged table to fail fast with a clear path to the bad field.
+
+The table-spec signature `vim.validate({ name = { value, type } })` is
+**deprecated in Neovim 0.11** (removal in 1.0): it allocates transient tables
+and is slower. Use the per-argument signature
+`vim.validate(name, value, validator, optional_or_msg)`:
+
+```lua
+-- File: lua/my_plugin/config.lua (continued) — template only
+function M.validate(cfg)
+  vim.validate("strategy", cfg.strategy, "string")
+  vim.validate("ui_border", cfg.ui.border, "string", true) -- optional
+  vim.validate("icons", cfg.ui.icons, "boolean")
+  vim.validate("capabilities", cfg.capabilities, "table")
+end
+```
+
+## Health Checks: `lua/<plugin>/health.lua`
+
+Provide a `:checkhealth` report via `lua/<plugin>/health.lua` using `vim.health`
+(`:h vim.health`, `:h health-dev`). This is the right home for the expensive
+checks you should _not_ run synchronously in init, including unknown-field /
+typo detection. Validate:
+
+- user configuration correctness (types, unknown keys),
+- that the plugin initialized as expected,
+- presence of required Lua dependencies,
+- presence of external (binary) dependencies.
+
+```lua
+-- File: lua/my_plugin/health.lua  (template only)
+local M = {}
+
+function M.check()
+  vim.health.start("my_plugin")
+  if vim.fn.executable("some-cli") == 1 then
+    vim.health.ok("`some-cli` found")
+  else
+    vim.health.error("`some-cli` not found", { "install some-cli and re-run" })
+  end
+end
+
+return M
+```