Skip to main content
skill CX Codex

roblox-luau · el4cteo — Claude Code skill: features and installation

The roblox-luau Claude Code skill supports writing and explaining Roblox scripts in Luau. It activates for script creation, refactoring, type-error fixes, and updates to older Lua code.

MIT 1,300 installs ★ 131 updated 2026-11-03

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add EL4CTEO/roblox-skills --skill roblox-luau -a claude-code
Open on GitHub

What roblox-luau does

The skill sets out modern Luau practices for Roblox, including --!strict, typed functions, generics, and newer language syntax. It also covers module patterns, error handling, and retries for calls that can fail.

For new scripts, it recommends getting services with game:GetService, using the task library, and cleaning up connections and instances. String paths in require do not wait for an instance to appear, so a module that may not have replicated yet needs an instance path with WaitForChild.

What it helps with

  • write a Roblox script with strict type checking
  • fix Luau type errors
  • update older Lua code to modern Luau patterns
  • explain what a Roblox script does

Example prompts for the agent

  • Write a Roblox script in Luau with strict type checking.
  • Fix the type errors in this Roblox script.
  • Update this older Lua code using modern Luau practices.

How to install roblox-luau

1Skills CLI (Vercel)

npx skills add EL4CTEO/roblox-skills --skill roblox-luau -a claude-code

2Manually: put the files in place

~/.claude/skills/roblox-luau/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/roblox-luau/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about roblox-luau

How do I install roblox-luau in Claude Code?

Run npx skills add EL4CTEO/roblox-skills --skill roblox-luau -a claude-code. The skill file is at ~/.claude/skills/roblox-luau/SKILL.md.

What does roblox-luau do?

It helps create, refactor, and explain Roblox scripts in Luau, fix type errors, and update older Lua code.

How does roblox-luau handle modules that have not appeared yet?

String paths in require do not wait for instances to appear. For a module that may not have replicated yet, the skill recommends an instance path with WaitForChild.

Source text

SKILL.md · MIT
---
name: roblox-luau
description: Modern, type-safe Luau for Roblox, covering --!strict and the new type solver, generics, string interpolation, if-expressions, task library, require-by-string, module/OOP patterns, error handling with retries, buffer/vector, and legacy APIs to avoid. Use when writing, refactoring, or explaining any Roblox script, fixing type errors, or modernizing old Lua code.
---

# Modern Luau for Roblox

Luau is Roblox's gradually-typed Lua 5.1 derivative. Engine and language move fast; many
patterns from older tutorials (and older training data) are deprecated. Apply these defaults
to **every** script you write unless the project clearly uses another convention.

## Defaults for all generated code

1. `--!strict` at the top of new ModuleScripts (and Scripts when practical). Type public functions.
2. Get services with `game:GetService("Name")` at the top of the file, never `game.Name`.
3. Use the `task` library: `task.wait`, `task.spawn`, `task.defer`, `task.delay`, `task.cancel`.
   Never `wait`, `spawn`, `delay` (deprecated, throttled, imprecise).
4. Yielding engine calls that can fail (DataStore, HTTP, Marketplace, Teleport, `*Async`) go inside `pcall`.
5. Prefer the `*Async` variants of APIs; Roblox renamed most yielding methods
   (`LoadCharacterAsync`, `GetProductInfoAsync`, `UserHasBadgeAsync`, ...). See the table below.
6. Disconnect connections / destroy instances you create (see "Cleanup" below).
7. Naming: `PascalCase` for services, modules, classes, types, and instance names;
   `camelCase` for locals and functions; `SCREAMING_SNAKE_CASE` for constants.
8. Tabs for indentation (StyLua default in the Roblox ecosystem), double quotes.

## Modern syntax cheat sheet

```luau
local Players = game:GetService("Players")

local count = 0
count += 1 -- compound assignment: += -= *= /= //= %= ^= ..=

local label = if count > 1 then "many" else "one" -- if-expression (no `and/or` pitfalls)
print(`Player count: {#Players:GetPlayers()} ({label})`) -- string interpolation

for index, player in Players:GetPlayers() do -- generalized iteration: no pairs/ipairs needed
	if player.AccountAge < 1 then
		continue -- continue is a keyword
	end
	print(index, player.Name)
end

local half = 7 // 2 -- floor division → 3
local frozen = table.freeze({ Speed = 16 }) -- read-only table; writes throw
local list = table.create(100, 0) -- preallocated array
local copy = table.clone(frozen) -- shallow copy (unfrozen)
local mid = math.lerp(0, 10, 0.5) -- also: math.map, math.clamp, math.round, math.sign
print(half, list[1], copy.Speed, mid)
```

- `pairs`/`ipairs` still work; generalized iteration is preferred and iterates arrays in order.
- `#t` is only defined for arrays without holes. Setting `t[i] = nil` in the middle creates holes.
- Numbers are doubles: integers are exact to 2^53. Use `math.floor`/`//` for integer math.
- `tick()` is discouraged: use `os.clock()` for benchmarks, `workspace:GetServerTimeNow()` for
  synced time across clients/server, `os.time()`/`DateTime.now()` for wall-clock UTC.

## Types (new type solver)

Roblox's **new type solver** is generally available (Nov 2025) and `Workspace.UseNewLuauTypeSolver`
controls it; `Workspace.LuauTypeCheckMode` sets the default mode. Write code that checks cleanly
under `--!strict`.

```luau
--!strict
export type Item = {
	id: string,
	name: string,
	stack: number,
	tags: { string }?, -- optional field
}

type Rarity = "Common" | "Rare" | "Legendary" -- singleton (literal) union

local function totalStack(items: { Item }, filter: ((Item) -> boolean)?): number
	local total = 0
	for _, item in items do
		if filter == nil or filter(item) then
			total += item.stack
		end
	end
	return total
end

local function first<T>(list: { T }): T? -- generics
	return list[1]
end

local rarity: Rarity = "Rare"
local part = workspace:FindFirstChild("Door") :: BasePart? -- cast with ::
print(totalStack({}, nil), first({ 1, 2 }), rarity, part)
```

- Refine before use: `if part then ... end`, `if typeof(x) == "Instance" and x:IsA("BasePart") then`.
- `typeof(v)` knows Roblox types (`"Vector3"`, `"Instance"`, ...); `type(v)` only knows Lua types.
- Instance types come from `IsA` refinement or `FindFirstChildOfClass`/`FindFirstChildWhichIsA`.
- Avoid `any` except at trust boundaries (remote payloads, decoded JSON) — validate there, then narrow.

Details: generics, type packs, `read`/`write` properties, user-defined type functions, typing
OOP classes, and migrating legacy code to strict: [references/type-system.md](references/type-system.md).

## Modules and require

ModuleScripts run once per environment (server or each client) and return one value, cached for every
later `require`. A module in `ReplicatedStorage` required by both sides runs twice, once per side, with
separate state.

```luau
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local Signal = require(ReplicatedStorage.Packages.Signal) -- instance path (always works)
local Config = require("./Config") -- require-by-string: sibling of this script (script.Parent)
local Utils = require("@self/Utils") -- child of this script
local Shared = require("@game/ReplicatedStorage/Shared") -- absolute from game
print(Signal, Config, Utils, Shared)
```

- String paths: `./` = `script.Parent`, `../` = `script.Parent.Parent`, `@self/` = `script`,
  `@game/` = `game`. They **do not wait** for instances to exist. Use instance paths with
  `WaitForChild` when the module may not have replicated yet.
- Never create circular requires; they deadlock/error. Break cycles with dependency injection or events.
- Don't yield at module top level (no `WaitForChild` chains on things that may never exist, no
  DataStore calls): every requirer blocks until the module returns.

### Module / class pattern

```luau
--!strict
local Counter = {}
Counter.__index = Counter

export type Counter = typeof(setmetatable({} :: { value: number, step: number }, Counter))

function Counter.new(step: number?): Counter
	return setmetatable({ value = 0, step = step or 1 }, Counter)
end

function Counter.increment(self: Counter): number
	self.value += self.step
	return self.value
end

return Counter
```

Prefer plain modules of functions + data tables over deep inheritance. Use composition.

## Errors and retries

```luau
local DataStoreService = game:GetService("DataStoreService")
local store = DataStoreService:GetDataStore("PlayerData")

local function retry<T...>(attempts: number, fn: () -> T...): (boolean, T...)
	local delaySeconds = 1
	for attempt = 1, attempts do
		local result = table.pack(pcall(fn))
		if result[1] then
			return table.unpack(result, 1, result.n)
		end
		if attempt < attempts then
			warn(`attempt {attempt} failed: {result[2]}`)
			task.wait(delaySeconds)
			delaySeconds *= 2 -- exponential backoff
		end
	end
	return false
end

local ok, data = retry(3, function()
	return store:GetAsync("Player_1")
end)
print(ok, data)
```

- `error("message", 2)` blames the caller; `error({ code = "X" })` throws a table for structured errors.
- `xpcall(fn, debug.traceback)` keeps the stack trace.
- Don't wrap everything in `pcall` — only calls that can fail for reasons outside your code.

## Concurrency: the task library

| Call | Behavior |
| --- | --- |
| `task.spawn(fn, ...)` | Run now (until first yield) on a new thread. |
| `task.defer(fn, ...)` | Run at the end of the current resumption cycle. Good for "after this finishes". |
| `task.delay(t, fn, ...)` | Run after `t` seconds. Returns a thread you can `task.cancel`. |
| `task.wait(t?)` | Yield ≥ `t` seconds (one frame if omitted); returns elapsed time. |
| `task.cancel(thread)` | Stop a spawned/delayed thread. |
| `task.desynchronize()` / `task.synchronize()` | Parallel Luau (inside Actors) — see `roblox-performance`. |

- Per-frame work: `RunService.Heartbeat` (after physics), `RunService.PreSimulation`/`PostSimulation`,
  `RunService:BindToRenderStep` (client, before render, ordered). Don't `while true do task.wait() end` for
  per-frame logic; connect to an event and use its `deltaTime`.
- Write handlers that work under **deferred** signal behavior (`Workspace.SignalBehavior`): handlers run
  later in the frame, not inline. New template places use `Deferred`, `Default` will switch to it, and
  server authority requires it. Don't rely on handler side effects being visible right after `:Fire()`.
- Never yield inside metamethods or `Changed`-style callbacks that must be synchronous.

## Cleanup (memory leaks are the #1 Roblox bug)

```luau
local Players = game:GetService("Players")

local connections: { RBXScriptConnection } = {}

table.insert(
	connections,
	Players.PlayerRemoving:Connect(function(player)
		print(`{player.Name} left`)
	end)
)

local function cleanup()
	for _, connection in connections do
		connection:Disconnect()
	end
	table.clear(connections)
end

cleanup()
```

- `Instance:Destroy()` disconnects that instance's connections and locks `Parent`; it does **not**
  clear your Lua references — nil out tables that hold players/instances on `PlayerRemoving`.
- Use `:Once()` for one-shot connections. Use a Trove/Janitor/Maid-style helper for groups.
- Keys that are Player/Instance objects in long-lived tables leak unless removed on leave/destroy.

## Buffers and vectors (performance-sensitive data)

```luau
local packet = buffer.create(10)
buffer.writeu16(packet, 0, 513) -- item id
buffer.writef32(packet, 2, 12.5) -- amount
buffer.writei32(packet, 6, -4)
print(buffer.readu16(packet, 0), buffer.readf32(packet, 2), buffer.len(packet))

local v = vector.create(1, 2, 3) -- native 3-float vector (same type as Vector3 at runtime)
print(vector.magnitude(v), vector.normalize(v), vector.dot(v, vector.one))
```

`buffer` is the right tool for compact network payloads, large grids, and binary serialization.
Standard-library quick reference: [references/stdlib-cheatsheet.md](references/stdlib-cheatsheet.md).

## Legacy → current (most common mistakes)

| Don't write | Write instead |
| --- | --- |
| `wait()`, `spawn()`, `delay()` | `task.wait()`, `task.spawn()`, `task.delay()` |
| `game.Workspace`, `game.Players` | `workspace`, `game:GetService("Players")` |
| `Instance.new("Part", parent)` | create, set properties, **then** set `.Parent` last |
| `Humanoid:LoadAnimation()` | `Animator:LoadAnimation()` |
| `Model:SetPrimaryPartCFrame()` | `Model:PivotTo()` / `Model:GetPivot()` |
| `workspace:FindPartOnRay(Ray.new(...))` | `workspace:Raycast(origin, direction, params)` |
| `BodyVelocity`, `BodyPosition`, `BodyGyro` | `LinearVelocity`, `AlignPosition`, `AlignOrientation` |
| `player:LoadCharacter()` | `player:LoadCharacterAsync()` |
| `MarketplaceService:GetProductInfo()` | `:GetProductInfoAsync()` |
| `BadgeService:AwardBadge()` | `:AwardBadgeAsync()` |
| `player:GetRankInGroup()` | `GroupService:GetRolesInGroupAsync()` / `player:IsInGroupAsync()` |
| `TeleportService:Teleport*()` variants | `TeleportService:TeleportAsync()` |
| `Chat` service / `ChatService` modules | `TextChatService` |
| `GuiObject.Draggable` | `UIDragDetector` |
| `table.getn`, `table.foreach`, `getfenv` | `#t`, `for ... in`, nothing |

The full deprecation map lives in the `roblox-code-review` skill.

## Performance idioms (only where it matters)

- Measure first (`debug.profilebegin/profileend`, MicroProfiler, Script Profiler).
- `--!native` at the top of a script, or `@native` on a function, compiles hot numeric code natively.
  Use it on math-heavy modules, not everywhere (compile time + memory limits). Type annotations help it.
- Cache `Instance` lookups and service references outside loops; avoid `FindFirstChild` chains per frame.
- Build large strings with `table.concat` or `buffer`, not repeated `..` in loops.
- Reuse `RaycastParams`/`OverlapParams` objects instead of creating them per call.

## Related skills

`roblox-architecture` (project structure, client/server), `roblox-networking` (remotes),
`roblox-performance` (profiling, Parallel Luau), `roblox-code-review` (review checklist, full deprecation map).

© EL4CTEO · MIT · EL4CTEO/roblox-skills

Similar skills

All skills for Game dev and 3D: Unity, Unreal, Godot, Blender →

roblox-luau by other authors comes first.

roblox-luau gamedev-skills This Claude Code skill helps write Roblox Luau and run project checks. It activates for a LocalScript that will not run, a client-side nil after joining, or legacy wait() calls. CX Codex +1 12,300installs roblox-luau-patterns TabooHarmony roblox-luau-patterns — a skill for writing and refactoring Roblox Luau modules: object lifecycles, signals, task scheduling, pcall and cleanup. CX Codex +1 3,500installs roblox-luau-types TabooHarmony roblox-luau-types — a skill for Luau type annotations: generics, unions, narrowing, strict mode, module type exports. Useful when migrating to --!strict. CX Codex +1 3,400installs scenario-roblox-luau scenario-labs scenario-roblox-luau — a skill for Claude Code and Cursor that reviews, debugs, and writes Luau code in Roblox experiences. CX Codex +1 351installs luau-best-practices dig1t luau-best-practices is a Claude Code skill for writing, reviewing, and refactoring Roblox Luau code. It activates for work on module structure, memory leaks, and server-side security. CX Codex +1 736installs luau-type-expert dig1t luau-type-expert works through Luau type errors and gets a file to --!strict: generics, unions, narrowing with type(), and :: casts. CX Codex +1 308installs roblox-datastores gamedev-skills A skill for Claude Code automates Roblox DataStoreService persistence, profile loading, and conflict prevention. Use it when player data goes missing or items duplicate after teleportation. CX Codex +1 11,400installs

From the same set22

The whole set →
roblox-code-review The roblox-code-review Claude Code skill reviews Roblox code for security flaws, data loss, and lifecycle bugs. It runs for PR or script reviews, game audits, and legacy-code updates. CX Codex +1 1,300installs roblox-security roblox-security — a skill for Claude Code enforces server-authoritative security for Roblox experiences. Runs during reviews of remote event handlers, combat calculations, inventory transactions, and character physics. CX Codex +1 1,300installs roblox-characters-animation roblox-characters-animation — a Claude Code skill for Roblox characters and animation. It applies to work on movement, damage, respawns, avatars, weapons, and tweens. CX Codex +1 1,300installs roblox-game-systems roblox-game-systems — a skill for Claude Code and Codex providing server-authoritative Roblox gameplay recipes. Activates when building currencies, inventory, weapons, round loops, or progression. CX Codex +1 1,300installs roblox-ui roblox-ui — a skill for Claude Code and Codex constructs responsive Roblox interfaces. Runs when building HUDs, inventories, storefronts, or fixing layouts across mobile devices and consoles. CX Codex +1 1,300installs roblox-testing The roblox-testing Claude Code skill covers testing Roblox code and checking gameplay changes. It applies when adding tests, configuring a runner, or setting up CI. CX Codex +1 1,300installs roblox-open-cloud This Claude Code skill covers Roblox Open Cloud APIs and HttpService. It applies to external tools, bots, CI/CD, and web requests from a game. CX Codex +1 1,200installs roblox-text-chat roblox-text-chat is a Claude Code and Cursor skill that configures TextChatService and text filtering in Roblox for adding chat, commands, or player-authored signs. CX Codex +1 1,200installs

Project sponsors

Companies that keep this analytics open