Roblox Best Practices Skill

An Agent Skill that gives AI coding assistants a working standard for Roblox and Luau development. It covers how each script is written, how systems are assembled, and where the platform's real limits sit, without assuming anything about your framework, folder layout, or game genre.

Works with Claude Code, Cursor, Codex, Gemini, Windsurf, Cline, Zed, and any other tool that reads the Agent Skills standard.

What it gives your agent

Implementation blueprints, not just rules. Twenty-two recipes for the systems Roblox developers actually build: player data, currency, inventory, trading, developer products, gacha, leaderboards, damage validation, abilities, projectiles, NPC AI at scale, round lifecycles, matchmaking, placement systems, pets, HUD sync, rate limiting, and more. Each one carries its assembly order, the failure modes specific to that case, the budget it has to fit inside, and how to prove it works.

A review that does not cry wolf. A severity taxonomy (Blocker, Correctness, Advisory) and a catalog of what not to flag: which allocations are actually hot, what does not leak, what is not a trust boundary, and where a discouraged API is simply not a deprecated one. Findings must clear a four step confidence gate before they are reported.

Current to the July 2026 engine. Server Authority, the Character Controller Library, the new Luau type solver, InstanceHandle attributes, unified data store limits, and the 2026 Luau standard library. Every capability is tagged for maturity, and anything the skill could not confirm is marked as unverified rather than asserted.

Platform ceilings in one place. Data store size and request budgets, memory store quotas, message size caps, attribute windows, animation track limits. The agent checks them while designing, instead of discovering them in production.

Safe hands on the Studio MCP. When the agent drives Studio directly, it identifies which MCP variant it is connected to from the tools actually present, runs a preflight before the first write, and knows which operations cannot be undone: play mode discarding work, a mistyped path silently creating a new script, inserted assets carrying backdoor scripts. It also knows which calls quietly burn your budget, and avoids them.

Context that stays cheap. The skill is 22 files, but only the entry point loads on activation. Everything else is routed on demand, so a task pulls the one reference it needs and nothing more.

Installation

Windows (PowerShell)

irm https://raw.githubusercontent.com/andrian-syh/roblox-best-practices-skill/main/install.ps1 | iex

macOS and Linux

curl -fsSL https://raw.githubusercontent.com/andrian-syh/roblox-best-practices-skill/main/install.sh | bash

Both scripts launch the Node installer when Node is available and fall back to a native menu when it is not.

Direct npx

npx --allow-git=all github:andrian-syh/roblox-best-practices-skill

The --allow-git=all flag is required on npm v12 and later, which block Git fetches by default. The one liners above handle this for you.

Flags

How installation works

Version selection. The installer fetches published tags from GitHub and offers the bundled version plus the five most recent releases. Older versions stay installable through the manual entry option or the --tag flag.

Universal destination. The skill always installs to ./.agents/skills/roblox-best-practices/, which makes it available to any tool reading the standard workspace path.

Additional agents. The installer scans your home directory for known agent configuration folders, pre-selects the ones it finds, and lets you filter the list as you type. Folders that do not exist are skipped.

Supported agents

How the skill behaves

Two modes

Default. Applies this skill's conventions as written. Suited to new or greenfield work.

Adaptive. Studies the project's existing conventions first, presents what it found alongside a proposed standard, and waits for your approval before writing code. Safety rules still apply in full; only stylistic and structural conventions adapt.

Three supervision levels

Confirmation gates

The agent resolves these once per session rather than assuming: which community libraries own a concern (ProfileStore, Packet, Trove, Knit, Fusion), and whether the place actually runs Server Authority. Roblox does not enable Server Authority by default, and assuming the wrong mode inverts the correct answer for input, camera, simulation stepping, and movement validation.

Reference map

Only the entry point loads by default. Everything below is read on demand.

Authoring

Implementation blueprints

Depth and guardrails

Full entry point: SKILL.md.

Script layout

Every script is divided into three top level sections, with a five level header hierarchy for subdivision.

-- // VARIABLES // --
-- | Services | --
-- | Modules | --
-- | Objects | --
-- | Configuration | --
-- | State Management | --

-- // FUNCTIONS // --
-- | Private | --
-- | Public | --

-- // INITIALIZATION // --

Ceremony scales to the script. Small files use the three headers alone, and pure data or type modules are exempt entirely.

Non negotiable runtime rules

1. Server is authoritative. Validate every remote argument for type, range, ownership, and rate.
2. Clean up everything you create. Every connection has an owner and a teardown path.
3. No avoidable per frame garbage. Hoist what can be hoisted out of genuinely hot paths.
4. React, do not poll. Use signals rather than loops that watch a condition.
5. Save data safely. UpdateAsync with backoff, saved on leave, flushed on shutdown.
6. Budget the network. Batch, send deltas, and use unreliable events for loss tolerant data.
7. Re-validate after every yield. The player may have left and the instance may be gone.

Each rule carries scoped exceptions, documented so that legitimate code is not reported as a violation.

Maintenance

Roblox ships changes continuously, and guidance that is a year old quietly becomes wrong. This skill is maintained against that.

The aim is an update at the end of each month, tracking what Roblox actually shipped that month across both fronts:

• Luau, the language itself: new syntax and standard library additions, type solver behavior, compiler and runtime changes.
• Roblox Studio and the engine: new and deprecated APIs, systems moving between beta and general release, changed platform limits, and Studio tooling that affects how an agent works.

Each cycle also carries improvements beyond the refresh: sharper guardrails, new implementation blueprints, and corrections where reality has moved past what the skill says. Anything that cannot be confirmed against the official documentation is marked unverified rather than asserted, so the skill stays honest about its own edges.

Released versions are tagged and documented in CHANGELOG.md.

Contributing

Issues and pull requests are welcome at the repository. Corrections are especially valuable: if the skill states something the engine no longer does, that is a bug worth reporting.

License

MIT.