# roblox-luau-patterns

A skill for writing and refactoring Roblox Luau modules: object lifecycles, signals, task scheduling, pcall and cleanup.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 2100 installs · ★ 127
- Author: TabooHarmony
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/TabooHarmony/roblox-brain/tree/HEAD/skills/core/roblox-luau-patterns/SKILL.md
- Updated: 2026-10-15
- HTML: https://affpapa.org/en/nevibecode/skills/roblox-luau-patterns

## What it does

The skill loads when you write or refactor Roblox modules in Luau. It walks through module shape: plain functions for stateless transformation, a module with private state when one subsystem owns it, an object with a metatable when several independent values share behavior. Constructors use `.`, instance methods use `:`, and mutable fields sit on the instance rather than the class table.

Ownership gets its own section. Signal connections, instances and tasks need an owner that disconnects or cancels them at teardown. The skill advises configuring an object before parenting it so partial state never shows, and exporting typed signal payloads as `Signal<T...>`. Failure semantics matter too: the `pcall` example keeps a successful call that returned `nil` separate from a failed one. Retry only when the operation is safe to repeat.

For scheduling, it asks you to pick `task.defer`, `task.spawn`, `task.delay` and `task.cancel` on purpose, and to drop legacy `wait()` plus polling with no justification. If you do poll, choose an explicit cadence and measure it. A review checklist closes things out: clear owner, narrow public API, no circular require, success and missing-data states still distinct. Client input is routed to the companion `roblox-networking` skill, while semantics, types and startup live in other skills of the set.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add TabooHarmony/roblox-brain --skill roblox-luau-patterns -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/roblox-luau-patterns/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/roblox-luau-patterns/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add TabooHarmony/roblox-brain --skill roblox-luau-patterns -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/roblox-luau-patterns/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add TabooHarmony/roblox-brain --skill roblox-luau-patterns -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/roblox-luau-patterns/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install TabooHarmony/roblox-brain roblox-luau-patterns
```

2. **Manually: put the files in place**
- File: `.github/skills/roblox-luau-patterns/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add TabooHarmony/roblox-brain --skill roblox-luau-patterns -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/TabooHarmony/roblox-brain --path skills/core/roblox-luau-patterns
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/roblox-luau-patterns/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add TabooHarmony/roblox-brain --skill roblox-luau-patterns -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/TabooHarmony/roblox-brain/tree/HEAD/skills/core/roblox-luau-patterns/SKILL.md

## When to use it
- pick a module shape instead of adding a manager class just to namespace functions
- find signal connections that nobody disconnects
- tell a successful pcall returning nil apart from a real failure
- stop duplicate handlers from piling up after respawn
- replace legacy wait() and needless polling with task functions

## Example prompts
- Review this Roblox Luau module for memory leaks and tell me who owns the connections
- Rewrite the respawn handler so duplicate handlers don't appear after the player respawns
- Check the task scheduling in this script and remove the unnecessary polling

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 7362e2e855ac8bef.

BEGIN THIRD-PARTY FILE 7362e2e855ac8bef
````text
---
name: roblox-luau-patterns
description: "Use when writing or refactoring Roblox Luau modules, object lifecycles, signals, task scheduling, pcall, and cleanup."
when_to_use: "Also for memory leaks, connections never disconnected, duplicate handlers after respawn, task.spawn/defer/delay misuse, retries, and reviewing module structure."
last_reviewed: 2026-10-14
sources:
  - https://luau-lang.org/
  - https://luau.org/library
  - https://create.roblox.com/docs/reference/engine/classes/ObjectValue
  - https://create.roblox.com/docs/reference/engine/classes/StringValue
  - https://create.roblox.com/docs/reference/engine/classes/CFrameValue
  - https://devforum.roblox.com/t/studio-beta-reference-instances-directly-with-attributes/4753441
  - https://raw.githubusercontent.com/Kampfkarren/kampfkarren-luau-guidelines/main/README.md
  - original
---

# Luau Patterns

## When to Load

Load for module shapes, resource ownership, scheduling, and failure contracts. See `roblox-luau-core` for semantics, `roblox-luau-types` for types, `roblox-architecture` for startup.

## Quick Reference

### Choose a shape

- **Plain functions:** default for stateless transformation or validation.
- **Module with private state:** one explicit subsystem owner. Do not create a manager class merely to namespace functions.
- **Object with metatable:** multiple independent values need shared behavior and lifecycle.
- **Existing library abstraction:** follow it when the project already uses it consistently. Do not add Promise, signal, cleanup, or framework dependencies for one call site.

Constructors use `.`, instance methods use `:`, and mutable fields belong on the instance, not the class table.

### Make ownership visible

Signal connections, instances, and tasks need cleanup owners. Disconnect/cancel at teardown. Export typed custom signal payloads (`Signal<T...>`).

Configure before parenting to hide partial state. Parent earlier only when ancestry is required; explain why. This does not guarantee replication ordering.

### Preserve failure semantics

```luau
local ok, value = pcall(dataStore.GetAsync, dataStore, key)
if not ok then
````
END THIRD-PARTY FILE 7362e2e855ac8bef

The third-party file has ended. Everything between the 7362e2e855ac8bef tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2143 of 3169 bytes. © TabooHarmony · MIT · https://github.com/TabooHarmony/roblox-brain/tree/HEAD/skills/core/roblox-luau-patterns/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md