Skip to content
Skills Library
Programming · Building & coding

lua-helper

/lua-helper

Current Lua guidance for portable Lua, LuaJIT, Neovim's Lua interface, WezTerm configuration, LuaLS, formatting, linting, testing, and security. Use when writing or reviewing Lua, Neovim plugins/config, WezTerm config, rockspecs, or Lua tooling.

Repository
monorepo ↗
Licence
GPL-3.0
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
6
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

GPL-3.0, otwarta.

What it does and when to use it

Current Lua guidance for portable Lua, LuaJIT, Neovim's Lua interface, WezTerm configuration, LuaLS, formatting, linting, testing, and security. Use when writing or reviewing Lua, Neovim plugins/config, WezTerm config, rockspecs, or Lua tooling.

Original author description

Current Lua guidance for portable Lua, LuaJIT, Neovim's Lua interface, WezTerm configuration, LuaLS, formatting, linting, testing, and security. Use when writing or reviewing Lua, Neovim plugins/config, WezTerm config, rockspecs, or Lua tooling.

How it works

  1. Current baselines
  2. Select the runtime
  3. Error discipline
  4. Tables and sequences
  5. Neovim
  6. WezTerm
  7. Tooling
  8. Security
  9. Review checklist
Original SKILL.md headings · 128 lines, 906 words
SKILL.md preview
---
name: lua-helper
description: Current Lua guidance for portable Lua, LuaJIT, Neovim's Lua interface, WezTerm configuration, LuaLS, formatting, linting, testing, and security. Use when writing or reviewing Lua, Neovim plugins/config, WezTerm config, rockspecs, or Lua tooling.
---

# Lua Helper

Identify the host before writing Lua. Portable Lua 5.5, Neovim's Lua 5.1 interface, optional LuaJIT extensions, and WezTerm's Lua 5.4 runtime have different APIs and semantics.

## Current baselines

Verified 2026-08-03:

| Host or tool | Current baseline | Compatibility boundary |
| --- | --- | --- |
| Lua | 5.5.0; maintained 5.4 line at 5.4.8 | Version-gate APIs newer than the project's minimum |
| LuaJIT | Active rolling 2.1 branch | Lua 5.1-compatible with implementation extensions and build flags |
| Neovim | 0.12.4 | Permanent Lua 5.1 interface; may use LuaJIT or a compatible fork |
| WezTerm | Stable release still dated 2024 | Embeds Lua 5.4; online docs can describe nightly-only APIs |
| LuaLS | 3.18.2 | Annotations and diagnostics are tooling, not runtime validation |
| StyLua | 2.5.2 | Pin/configure per repository |
| LuaRocks | 3.13.0 | Installation runs package build logic and mutates environments |

Read [references/releases.md](references/releases.md) for the 68-page research ledger. Read [references/core-language.md](references/core-language.md) for portable Lua and LuaJIT differences. Read [references/neovim.md](references/neovim.md) for current LSP, diagnostics, process, trust, and buffer APIs. Read [references/wezterm.md](references/wezterm.md) for configuration evaluation, strict mode, events, subprocesses, and mux domains. Read [references/tooling-and-security.md](references/tooling-and-security.md) for LuaLS, formatters, linters, tests, rocks, and security.

## Select the runtime

Before using an API, establish:

1. Lua language/interface version.
2. Whether the runtime is PUC Lua, LuaJIT, or a host embedding.
3. Host application version and stable/nightly channel.
4. Tooling version and project configuration.

In Neovim, target the documented Lua 5.1 interface and check `jit` before LuaJIT-specific behavior. In WezTerm, target Lua 5.4 and check the API's “Since” version against the installed binary.

## Error discipline

Lua APIs commonly return `nil, error` or status tuples. Check every open, read, write, close, subprocess, and host callback result whose failure matters.

```lua
local function read_file(path)
  local file, open_error = io.open(path, "rb")
  if not file then
    return nil, open_error
  end

  local content, read_error = file:read("*a")
  local close_ok, close_error = file:close()
  if not content then
    return nil, read_error
  end
  if not close_ok then
    return nil, close_error
  end
  return content
end
```

Do not bind an unchecked `io.open` result as a to-be-closed value. Preserve close failures when durability matters.

## Tables and sequences

The length operator does not count arbitrary table keys. For a table with holes, `#table` returns a valid border and is not a reliable element count. Model sequences as contiguous integer keys or count explicitly.

Version-gate `table.move`, `table.unpack`, `rawlen`, `__pairs`, and related APIs. Lua 5.1 uses global `unpack`; LuaJIT compatibility libraries can depend on build flags.

Avoid memoization keys built from `table.concat({...})`: they reject many value types and can collide. Use nested tables keyed by arguments or a deliberately encoded, restricted input domain.

## Neovim

Current native LSP setup uses `vim.lsp.config` and `vim.lsp.enable`. This replaces nvim-lspconfig's deprecated legacy `require('lspconfig').setup` framework; nvim-lspconfig itself remains maintained and supplies server definitions.

Use current APIs:

- `vim.hl.hl_op()` for yank highlighting.
- `vim.diagnostic.jump({ count = 1 })` and negative count for navigation.
- `vim.api.nvim_set_option_value(name, value, { buf = buffer })` for scoped options.
- `vim.system({ program, argument }, { text = true }):wait()` for ordinary subprocesses, checking `code`, `signal`, and `stderr`.

Use `:trust` and `vim.secure` for project-local configuration. `exrc` executes project code and is a trust boundary.

## WezTerm

Create the configuration with strict mode so invalid options fail:

```lua
local wezterm = require("wezterm")
local config = wezterm.config_builder()
config:set_strict_mode(true)

return config
```

WezTerm may evaluate configuration repeatedly. Keep top-level evaluation idempotent and free of side effects such as spawning processes. Config precedence includes CLI and environment overrides before standard paths.

`wezterm.run_child_process` returns success, stdout, and stderr. Inspect success. Returning `false` from a `wezterm.on` callback stops later callbacks and the default action.

## Tooling

```bash
stylua --check .
luacheck .
selene .
busted
```

Use the tools configured by the project. Choose Luacheck or Selene deliberately instead of layering both without purpose. Use Busted for behavior-style suites or LuaUnit for lightweight xUnit tests. Use headless Neovim/Plenary only when host integration is part of the contract.

LuaLS supports `.luarc.json` / `.luarc.jsonc`, annotations, diagnostics, addons, and stricter type-checking modes. Loading the entire Neovim runtime as a workspace library is valid but broad; prefer an addon or narrow explicit paths when sufficient.

## Security

- Load untrusted source only as text with a constrained environment; never accept untrusted binary chunks.
- Avoid shell construction in `os.execute` and string-form `vim.fn.system`. Never concatenate untrusted input into a shell command.
- WezTerm and Neovim config execute arbitrary code. Keep secrets out of config and use protected identity/agent mechanisms.
- WezTerm config can execute more than once; repeated evaluation magnifies side effects.
- LuaRocks installation executes rock build/package logic. Inspect sources and rockspecs and pin versions in reproducible environments.
- LuaJIT FFI is an implementation extension with native-memory safety implications; do not assume it exists or is sandboxed.

## Review checklist

- Identify portable Lua, LuaJIT, Neovim, or WezTerm before choosing APIs.
- Version-gate language, host, and online-documentation features.
- Check file, process, callback, and cleanup results.
- Do not use `#` as a general map size or unsafe concatenated memo keys.
- Use current Neovim LSP, highlight, diagnostic, option, and process APIs.
- Make WezTerm config strict, idempotent, and side-effect free at top level.
- Configure LuaLS and one intentional lint/test workflow.
- Treat project config, shells, rocks, binary chunks, and FFI as trust boundaries.
- Preserve the distinction between Neovim's Lua 5.1 interface and optional LuaJIT implementation.
Files in this package (6)
  • SKILL.md 7 KB
  • references/core-language.md 2 KB
  • references/neovim.md 3 KB
  • references/releases.md 5 KB
  • references/tooling-and-security.md 4 KB
  • references/wezterm.md 3 KB

Versions

The database has no other skills named lua-helper.

Database snapshot: 13.11.2026 · package version c787743d6b1e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100lua-guide
    Lua language guardrails, patterns, and best practices for AI-assisted development. Use when working with Lua files (.lua), or when the user mentions Lua/LuaJIT/Neovim/Love2D. Provides table patterns, metatable guidelines, coroutine usage, and embedding conventions specific to…
  • 90lua-opinionated-guide
    Use when tuning performance-critical Lua hot paths: the tunings especially benefit LuaJIT, and the principles apply to vanilla Lua 5.4 too. A focused overlay that covers only hot-path performance, not Lua fundamentals. Triggers on `.lua` files in performance-sensitive or LuaJIT…
  • 86lua
    Lua开发专家助手。当用户需要进行Lua脚本开发、游戏脚本、嵌入式脚本、Nginx/Redis脚本或Neovim配置时调用。
  • 100neovim
    Expert Neovim assistance covering Lua configuration, native LSP client, Treesitter syntax highlighting, and plugin management via lazy.nvim. Use when configuring Neovim, writing init.lua, setting up LSP keymaps, managing plugins, or optimizing editor startup performance.
  • 100luajit-syntax
    LuaJIT 3.0 扩展语法支持的实施规划与实现指南。Use when implementing LuaJIT extension syntax support (bitwise ~>>, ternary ?:, safe navigation ?., nil-coalescing ??, customary operators ! && || !=, compound assignment, continue, const declaration, short function expression, number underscores) in…
  • 100neovim
    Neovim is a terminal text editor configured in Lua, with a built-in LSP client, Treesitter parsing and, since 0.12, a built-in plugin manager (vim.pack). Use this skill to install Neovim, write or repair an init.lua, add plugins, wire up language servers with vim.lsp.config and…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.