lua-guide
/lua-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 this project's coding standards.
- Author
- ar4mirez ↗
- Repository
- samuel ↗
- Licence
- MIT
- Last repository change
- 29.04.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 10
No signals detected. Repository changed on 29.04.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
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 this project's coding standards.
Original author description
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 this project's coding standards.
How it works
- Core Principles
- Guardrails
- Key Patterns
- Testing
- Tooling
- References
- External References
SKILL.md preview
---
name: lua-guide
description: |
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 this project's coding standards.
license: MIT
metadata:
author: samuel
version: "1.0"
category: language
language: lua
extensions: ".lua"
---
# Lua Guide
> Applies to: Lua 5.4+, LuaJIT 2.1, Neovim Plugins, Love2D, Embedded Scripting
## Core Principles
1. **Tables Are Everything**: Arrays, maps, objects, modules, and namespaces -- master them
2. **Local by Default**: Always declare variables `local`; globals are a performance and correctness hazard
3. **Explicit Error Handling**: Use `pcall`/`xpcall` for recoverable errors; `error()` for programmer mistakes
4. **Minimal Metatables**: Use metatables for genuine OOP needs, not as decoration on simple data
5. **Embed-Friendly Design**: Lua exists to be embedded; keep the host/script boundary clean and narrow
## Guardrails
### Code Style
- Use `local` for every variable and function unless it must be global
- Naming: `snake_case` for variables/functions, `PascalCase` for class-like tables, `UPPER_SNAKE_CASE` for constants
- Indent with 2 spaces; one statement per line; avoid semicolons
- Use `[[ ... ]]` long strings for multi-line text and SQL/HTML templates
- Prefer `#tbl` over `table.getn()` for sequence length
### Tables
- Arrays are 1-based; `for i = 1, #arr` not `for i = 0, #arr - 1`
- Use `ipairs` for sequential iteration, `pairs` for hash-map iteration
- Do not mix array indices and string keys in the same table (undefined `#` behavior)
- Use `table.insert` / `table.remove` for array ops; avoid manual index gaps
- Freeze config tables by setting a `__newindex` metamethod that errors
### Error Handling
- Use `pcall(fn, ...)` to catch errors; `xpcall(fn, handler, ...)` for tracebacks
- Return `nil, err_msg` from functions that can fail (idiomatic two-value return)
- Reserve `error("msg", level)` for violated preconditions (programmer errors)
- Never silently swallow errors; always log or propagate
```lua
local function read_config(path)
local f, err = io.open(path, "r")
if not f then return nil, "cannot open config: " .. err end
local content = f:read("*a")
f:close()
return content
end
local ok, result = xpcall(dangerous_operation, debug.traceback)
if not ok then log.error("failed: %s", result) end
```
### Performance
- Localize hot functions: `local insert = table.insert`
- Avoid closures inside hot loops (allocates every iteration)
- Use `table.concat` instead of `..` concatenation in loops
- LuaJIT: avoid `pairs()` in hot paths (not JIT-compiled); prefer arrays with `ipairs`
- LuaJIT: use FFI (`ffi.new`, `ffi.cast`) for C struct access instead of Lua tables
### Embedding
- Keep the Lua-to-host API surface small (<20 registered functions)
- Validate all arguments from Lua in C/host bindings
- Set memory limits via `lua_setallocf` or `lua_gc` configuration
- Use `debug.sethook` instruction-count hooks for untrusted scripts
## Key Patterns
### Module Pattern
```lua
local M = {}
local TIMEOUT_MS = 5000
local function validate(data)
assert(type(data) == "table", "expected table, got " .. type(data))
assert(data.name, "missing required field: name")
end
function M.process(data)
validate(data)
return { status = "ok", name = data.name }
end
return M
```
### OOP via Metatables
```lua
local Animal = {}
Animal.__index = Animal
function Animal.new(name, sound)
return setmetatable({ name = name, sound = sound }, Animal)
end
function Animal:speak()
return string.format("%s says %s", self.name, self.sound)
end
-- Inheritance
local Dog = setmetatable({}, { __index = Animal })
Dog.__index = Dog
function Dog.new(name)
return setmetatable(Animal.new(name, "woof"), Dog)
end
function Dog:fetch(item)
return string.format("%s fetches the %s", self.name, item)
end
```
### Coroutines
```lua
local function producer(items)
return coroutine.wrap(function()
for _, item in ipairs(items) do
coroutine.yield(item)
end
end)
end
local function filter(predicate, iter)
return coroutine.wrap(function()
for item in iter do
if predicate(item) then coroutine.yield(item) end
end
end)
end
local nums = producer({ 1, 2, 3, 4, 5, 6 })
local evens = filter(function(n) return n % 2 == 0 end, nums)
for v in evens do print(v) end --> 2, 4, 6
```
### Custom Iterator
```lua
local function range(start, stop, step)
step = step or 1
local i = start - step
return function()
i = i + step
if i <= stop then return i end
end
end
for n in range(1, 10, 2) do print(n) end --> 1, 3, 5, 7, 9
```
### Neovim Lua API
```lua
local api, keymap = vim.api, vim.keymap
local M = {}
function M.setup(opts)
opts = vim.tbl_deep_extend("force", { enabled = true, width = 80 }, opts or {})
if not opts.enabled then return end
local group = api.nvim_create_augroup("MyPlugin", { clear = true })
api.nvim_create_autocmd("BufWritePre", {
group = group, pattern = "*.lua",
callback = function(ev)
local lines = api.nvim_buf_get_lines(ev.buf, 0, -1, false)
for i, line in ipairs(lines) do lines[i] = line:gsub("%s+$", "") end
api.nvim_buf_set_lines(ev.buf, 0, -1, false, lines)
end,
})
keymap.set("n", "<leader>mp", function()
vim.notify("MyPlugin activated", vim.log.levels.INFO)
end, { desc = "Activate MyPlugin" })
end
return M
```
## Testing
### Busted (Recommended)
```lua
local mymodule = require("mymodule")
describe("mymodule.process", function()
it("returns ok for valid input", function()
local result = mymodule.process({ name = "test" })
assert.are.equal("ok", result.status)
end)
it("raises on missing name", function()
assert.has_error(function() mymodule.process({}) end, "missing required field: name")
end)
end)
```
### Testing Standards
- Test files: `spec/*_spec.lua` (busted) or `test_*.lua` (luaunit)
- Test names describe behavior: `it("returns nil when file not found")`
- Coverage: >80% for library modules, >60% overall
- Test edge cases: `nil`, empty tables, boundary values, type mismatches
- Run: `busted --verbose`
## Tooling
### Luacheck
```lua
-- .luacheckrc
std = "lua54+busted" -- or "luajit+busted"
globals = { "vim" } -- for Neovim plugins
max_line_length = 120
max_cyclomatic_complexity = 10
```
### StyLua
```toml
# stylua.toml
column_width = 100
indent_type = "Spaces"
indent_width = 2
quote_style = "AutoPreferDouble"
call_parentheses = "Always"
```
### Essential Commands
```bash
lua myfile.lua # Run Lua script
luajit myfile.lua # Run with LuaJIT
busted --verbose # Run tests
luacheck . # Lint
stylua . # Format
luarocks install busted # Install test framework
luarocks install luacheck # Install linter
```
## References
For detailed patterns and examples, see:
- [references/patterns.md](references/patterns.md) -- OOP via metatables, module patterns, coroutine pipelines
## External References
- [Lua 5.4 Reference Manual](https://www.lua.org/manual/5.4/)
- [Programming in Lua (4th ed)](https://www.lua.org/pil/)
- [LuaJIT Documentation](https://luajit.org/luajit.html)
- [LuaJIT FFI Tutorial](https://luajit.org/ext_ffi_tutorial.html)
- [Neovim Lua Guide](https://neovim.io/doc/user/lua-guide.html)
- [Busted Testing Framework](https://lunarmodules.github.io/busted/)
- [Luacheck Linter](https://github.com/mpeterv/luacheck)
- [StyLua Formatter](https://github.com/JohnnyMorganz/StyLua)
- [Love2D Wiki](https://love2d.org/wiki/Main_Page)
- [Lua Style Guide](https://github.com/Olivine-Labs/lua-style-guide)
Files in this package (2)
- SKILL.md 8 KB
- references/patterns.md 4 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · ar4mirez/samuel | 100 | MIT |
| xonovex/platform | 90 | MIT |
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version c7bf3edddb85 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100lua-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. - 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… - 100lua
Expert Lua programming assistance covering tables, metatables, closures, coroutines, and C embedding. Use when writing game scripts, Neovim plugins, Nginx OpenResty modules, or embedded device logic. - 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… - 81Lua Tables Patterns
Use when lua tables as the universal data structure including arrays, dictionaries, objects, metatables, object-oriented patterns, data structures, and advanced table manipulation for building flexible, efficient Lua applications. - 86lua
Lua开发专家助手。当用户需要进行Lua脚本开发、游戏脚本、嵌入式脚本、Nginx/Redis脚本或Neovim配置时调用。