# Roblox Best Practices

> Framework-agnostic Roblox/Luau coding standards. Use when writing, reviewing, or refactoring any Luau code (Script, LocalScript, ModuleScript) in a Roblox project, or when the user asks to keep best practices in mind as standing guidance — enforces the VARIABLES/FUNCTIONS/INITIALIZATION section layout, naming rules, performance, memory, networking, and security best practices regardless of the pr…

- **Type:** Skill
- **Install:** `agentstack add skill-andrian-syh-roblox-best-practices-skill-roblox-best-practices`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [andrian-syh](https://agentstack.voostack.com/s/andrian-syh)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [andrian-syh](https://github.com/andrian-syh)
- **Source:** https://github.com/andrian-syh/roblox-best-practices-skill/tree/main/roblox-best-practices

## Install

```sh
agentstack add skill-andrian-syh-roblox-best-practices-skill-roblox-best-practices
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Roblox Game Development Best Practices

Framework-agnostic standards for writing clean, efficient, lightweight, and resource-frugal Luau code. These rules fit any architecture (single-script, module-based, Knit, actor-based, ECS, etc.) — they govern *how each script is written*, not how the project is structured.

**Goals, in priority order:** correct → secure (server-authoritative) → efficient (CPU/memory/network) → readable → consistent.

## Reference Routing

Load only what the situation needs:

| Situation | Read |
|---|---|
| Writing a new Script/LocalScript/ModuleScript | [references/templates.md](references/templates.md) |
| Existing codebase with its own conventions (Adaptive mode) | [references/adaptive-mode.md](references/adaptive-mode.md) |
| Project uses community libraries (ProfileStore, Packet, Trove, Knit, Fusion, ...) | [references/community-libraries.md](references/community-libraries.md) |
| Hot loops, memory, network traffic, rendering, profiling | [references/performance.md](references/performance.md) |
| Data stores, remotes, cleanup, pooling, input, anti-patterns | [references/patterns.md](references/patterns.md) |
| Purchases, anti-exploit, remote validation depth | [references/security-monetization.md](references/security-monetization.md) |
| UI/UX, cross-platform, testing, debugging, telemetry | [references/ui-ux-testing.md](references/ui-ux-testing.md) |
| Genre is known (simulator, FPS, obby, RPG, racing, horror, social) | [references/genres.md](references/genres.md) |

## User Authority

This skill is guidance, not a mandate — **full control always stays with the user**:

- The user's explicit instructions override any convention in this skill. If an instruction conflicts with a Non-Negotiable Runtime Rule, state the risk once, briefly, then follow the user's decision.
- Never take actions the user didn't ask for on the strength of this skill alone: no unrequested refactors, restructuring, file creation, or "while I'm here" cleanups. Recommend; don't act.

### Advisory invocation (no specific task)

Users may invoke this skill purely as a standing reminder — "use best practices", "ikuti skill ini mulai sekarang" — without a concrete coding task. In that case:

- **Do not** start codebase analysis or ask the mode/library setup questions yet. Briefly acknowledge that the standards are now active, and stop.
- Hold these rules as active guidance for all subsequent Luau work in the session.
- Resolve Mode Selection and the community-library check **lazily** — at the first actual coding/review task, and only the parts that task needs.

## Supervision Level (how often to confirm)

The user controls how much the agent asks before acting. Three levels:

| Level | Token | Behavior |
|---|---|---|
| **Supervised** | `!ask` | Confirm before every meaningful decision: convention choices, the list of files to create/modify, any deviation from this skill, and before writing code. The user sees and approves everything. |
| **Balanced** (default) | `!bal` | Ask only when genuinely needed: real ambiguity, conflict with a Non-Negotiable Runtime Rule, or wide-impact/destructive changes. Otherwise proceed. |
| **Autonomous** | `!go` | Don't ask; make sensible best-practice decisions and record every assumption in the final summary. Stop only for destructive/irreversible actions. |

**How the level is set:**
1. **Session declaration** — the user states it in any words ("supervised mode", "awasi penuh", "jangan banyak tanya", "bebas saja") → holds for the whole session until changed.
2. **Inline token** — `!ask` / `!bal` / `!go` anywhere in a prompt → overrides the session level for that prompt only.

**Precedence:** inline token > session declaration > Balanced default. Never ask the user which level they want — absence of a declaration *is* the Balanced choice. Explicit user instructions (User Authority) outrank the level itself.

**Effect on this skill's confirmation points:**

| Confirmation point | Supervised | Balanced | Autonomous |
|---|---|---|---|
| Default/adaptive mode question | Always ask | Ask once if a codebase exists | Infer; report the assumption |
| Adaptive convention confirmation (Step 2) | Wait for approval | Wait for approval | Present as a report; proceed |
| Community-library check | Ask | Ask once / detect | Detect via `require()`s |
| Conflict with a non-negotiable | Ask | Ask | Warn in summary; choose the safe option |
| Review mode: stylistic restructuring | Propose, wait | Propose, wait | Still propose only (User Authority — unchanged) |

## Mode Selection (before the first coding task)

This skill runs in one of two modes. Determine the mode before writing any code:

- **Default mode** — apply this skill's conventions exactly as written below (section layout, naming, ordering). Use when: the user asked for it, the project is new/empty, or the existing code has no consistent conventions worth preserving.
- **Adaptive mode** — first study the project's existing coding structure and conventions, present what you found together with a proposed adapted convention, **get the user's confirmation**, then write code following the confirmed convention. The universal rules (Non-Negotiable Runtime Rules, Language & Style safety items, everything in the performance/patterns references) still apply in full — only *stylistic/structural* conventions adapt.

How to decide:
1. If the user explicitly stated a mode (e.g., "pakai default", "ikuti struktur project ini", "pelajari dulu kode kami") → obey it.
2. Otherwise, if there is an existing codebase with visible conventions → ask the user once: *"Use this skill's default conventions, or should I study your project's existing structure first and adapt to it (with your confirmation)?"*
3. If asking is impossible (autonomous run) → default mode for new files; for edits to existing files, match the file's existing style and note the assumption in your summary.

Adaptive-mode procedure (analysis checklist, confirmation format, precedence rules): see [references/adaptive-mode.md](references/adaptive-mode.md).

### Community-library check (part of mode selection)

Also determine, once, whether the project uses community libraries that replace built-in APIs — ask the user (*"Does this project use community libraries such as ProfileStore/ProfileService for data, Packet/ByteNet for networking, Trove/Maid for cleanup, Knit/Flamework, Fusion/React-lua, ...?"*) or, in autonomous runs, detect them by scanning `require()`s. If any are in use, read [references/community-libraries.md](references/community-libraries.md) and defer the overlapping built-in patterns to the library — library idioms win for the concern they own; the Non-Negotiable Runtime Rules still hold through them.

### Review/refactor mode

When asked to *review or tidy existing code* (rather than write new code):

- Violations of Non-Negotiable Runtime Rules and deprecated APIs → report as findings (and fix if asked). Apply the rules *as scoped* — the exceptions written into them (periodic loops, cold-path allocations, small state snapshots) are not violations.
- Section-layout/naming deviations and missing doc comments on trivial private functions → *propose* restructuring as minor suggestions, don't silently rewrite and don't report them as violations; the user decides.
- Never reformat code unrelated to the request; consistency within the file beats consistency with this skill.
- Before flagging an API as wrong/nonexistent, verify against the target environment (see Environment & Scale) — never flag from memory alone.

## Environment & Scale

- **Detect the project environment first:** Studio-native (work through Studio/MCP tools; paths are Instance paths) vs Rojo/filesystem (work through files; requires may use path aliases and `src/` layout maps to services). Match how you read, write, and reference scripts accordingly.
- **Verify newer APIs before use** (`BindToSimulation`, `UIShadow`, Input Action System, structured `LogService`, ...) — check they exist in the target environment rather than assuming; fall back to the stable equivalent if absent. **The official docs (create.roblox.com — Engine API Reference) are the primary authority**; the API dump/ReflectionService or a quick in-Studio test settle what the docs haven't caught up to. Roblox ships new APIs continuously — absence from your training knowledge is not evidence an API doesn't exist.
- **Scale the ceremony to the script.** Tiny scripts ( session declaration > Balanced); in Autonomous, all assumptions listed in the summary
- [ ] Mode determined (default vs adaptive); in adaptive mode, the convention was confirmed by the user before coding (or reported, in Autonomous)
- [ ] Community libraries identified (asked or detected); overlapping patterns deferred to them
- [ ] Three top-level sections present and correctly ordered (except exempt pure data/type modules); correct header syntax at each level (or the confirmed adapted equivalent); ceremony scaled to script size, no empty headers
- [ ] In review mode: non-negotiables reported as findings, stylistic changes proposed not forced, unrelated code untouched
- [ ] Services/Modules/Objects/Configuration/State ordered per spec; module requires ordered SSS → SS → RS → Workspace → script-relative (only reachable locations count)
- [ ] Every function has a `--[[ ... ]]` block doc comment in desc → params → returns order; the description is general/contract-level (no mention of the body's specific features or code) so it survives implementation changes
- [ ] `--!strict` (or justified `--!nonstrict`); no deprecated APIs
- [ ] All connections have an owner and a teardown path; no leaked Instances
- [ ] No allocation or Instance-tree lookup inside hot loops; nothing polled that could be event-driven
- [ ] All remote handlers validate arguments; all yielding external calls wrapped in `pcall` with retry
- [ ] Works regardless of the project's framework — no assumptions about folder layout beyond standard Roblox services

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [andrian-syh](https://github.com/andrian-syh)
- **Source:** [andrian-syh/roblox-best-practices-skill](https://github.com/andrian-syh/roblox-best-practices-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-andrian-syh-roblox-best-practices-skill-roblox-best-practices
- Seller: https://agentstack.voostack.com/s/andrian-syh
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.