roblox-performance · tabooharmony — Claude Code skill: what it does, how to install
Profiling rules and performance targets for Roblox projects. Helps coding agents track down frame drops, server lag, and memory leaks.
npx skills add TabooHarmony/roblox-brain --skill roblox-performance -a claude-codeWhat roblox-performance does
The skill guides coding agents through Roblox profiling workflows and performance budgets. It sets baseline targets: server heartbeat below 16ms, 60 desktop FPS, and 45 mobile FPS. Any server delay above 33ms or frame rate drop below 30 requires investigation. The guidelines prioritize hard measurements over folklore. They specify shortcuts for MicroProfiler, Developer Console, and Script Profiler, along with region marking via debug.profilebegin.
Specific rules govern Parallel Luau and CPU hot paths. Actors belong only in isolated compute tasks confirmed by profiling. Shared state between workers must rely on SharedTable because SendMessage duplicates data. Luau already optimizes global imports. Because of that, manual loop unrolling or function hoisting provides no real gain.
Memory and StreamingEnabled get explicit coverage. Streamed-out instances move to nil instead of being destroyed. Relying on FindFirstChild for distant parts will quietly break your scripts.
What it helps with
- profile script CPU and memory using Script Profiler
- distribute compute tasks across worker Actors with SharedTable
- prevent script errors caused by StreamingEnabled parenting parts to nil
- keep server heartbeat within the 16ms budget
Example prompts for the agent
- Server heartbeat is spiking past 33ms, help me inspect hot paths.
- How do I safely share state between Actors using SharedTable?
- Parts return nil after enabling StreamingEnabled, how should I fix FindFirstChild calls?
How to install roblox-performance
1Skills CLI (Vercel)
npx skills add TabooHarmony/roblox-brain --skill roblox-performance -a claude-code2Manually: put the files in place
~/.claude/skills/roblox-performance/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/roblox-performance/
1Skills CLI (Vercel)
npx skills add TabooHarmony/roblox-brain --skill roblox-performance -a codex2Manually: put the files in place
.agents/skills/roblox-performance/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add TabooHarmony/roblox-brain --skill roblox-performance -a cursor2Manually: put the files in place
.cursor/skills/roblox-performance/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install TabooHarmony/roblox-brain roblox-performance2Manually: put the files in place
.github/skills/roblox-performance/SKILL.md1Skills CLI (Vercel)
npx skills add TabooHarmony/roblox-brain --skill roblox-performance -a gemini-cli2Platform CLI
gemini skills install https://github.com/TabooHarmony/roblox-brain --path skills/core/roblox-performanceManually: put the files in place
.devin/skills/roblox-performance/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add TabooHarmony/roblox-brain --skill roblox-performance -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about roblox-performance
How do I install roblox-performance in Claude Code?
Run npx skills add TabooHarmony/roblox-brain --skill roblox-performance -a claude-code.
What is the purpose of roblox-performance?
It supplies coding assistants with Roblox performance budgets, profiler shortcuts, and Luau optimization guidelines.
Why does the skill caution against FindFirstChild with StreamingEnabled?
Streamed-out objects are temporarily parented to nil rather than destroyed. The skill directs agents to use WaitForChild with a timeout instead.
Source text
SKILL.md · MIT
---
name: roblox-performance
description: "Use when profiling or fixing Roblox performance: low FPS, lag, memory, network load, slow phones, hot paths."
when_to_use: "Also when the game stutters, phones overheat or crash, server heartbeat drops, before adding many parts/effects/UI, and when auditing performance before release."
last_reviewed: 2026-10-02
sources:
- https://create.roblox.com/docs/en-us/performance-optimization/microprofiler
- https://create.roblox.com/docs/en-us/reference/engine/libraries/debug
- https://devforum.roblox.com/t/huge-memory-leak-prevention-for-everyone-or-most-people-atleast/3099605
- https://devforum.roblox.com/t/full-release-of-parallel-luau-v1/1836187
- https://luau.org/performance
- https://create.roblox.com/docs/reference/engine/classes/Actor
- https://create.roblox.com/docs/reference/engine/datatypes/SharedTable
- https://create.roblox.com/docs/scripting/multithreading
---
# Roblox Performance
## When to Load
Use for profiling and performance budgets. Pooling and lifecycle patterns: `roblox-luau-patterns`.
## Quick Reference
### Profiling Tools
- **MicroProfiler (Ctrl+F6)**: Frame breakdown of scripts, physics, rendering.
- **Developer Console (F9)**: Memory, network, rendering, and server stats.
- **Script Profiler (Ctrl+Alt+F5)**: Per-script CPU and heap.
- **Labels**: `debug.profilebegin`/`debug.profileend` mark regions; `debug.setmemorycategory` labels memory. Gate instrumentation behind a flag.
### Performance Targets
| Metric | Starting target | Investigate at |
|--------|-----------------|----------------|
| Server heartbeat | < 16ms | > 33ms |
| Client FPS (desktop) | 60 | < 30 |
| Client FPS (mobile) | 45 | < 30 |
| Memory | device-specific | sustained growth |
Optimize measured hot paths, not folklore. Throttle from measurements; re-profile after shipping.
### Parallel Luau
- Use Actors only after profiling identifies isolatable CPU work.
- Workers compute; synchronize before restricted DataModel writes.
- Do not rely on shared module state across Actors. `SendMessage` copies data; SharedTable supports shared state and atomic updates.
### Hot-loop cost model
- Luau optimizes global imports; avoid folklore function hoisting/unrolling. Environment impurity can disable optimizations. Profile allocations as well as CPU; GC cost may occur later.
### Object Pooling
Pre-clone and reuse. Canonical pool code (token-lease ownership): `roblox-luau-patterns`.
### StreamingEnabled Essentials
- **On by default**. Container-scoped: only Workspace descendants stream. `ModelStreamingBehavior = Improved` streams non-BasePart descendants with their parent Model; Legacy streams only BaseParts.
- **Streamed-out = parented to nil**, not destroyed. Luau refs persist if it streams back.
- **Config (Studio)**: target defaults 1024, min 64; set `StreamingIntegrityMode`; tune from data.
- **Gotcha**: `FindFirstChild("DistantPart")` returns nil if streamed out. Use WaitForChild with timeout.
### Mobile
- Profile geometry, textures, particles, UI, shadows on low-end devices.
> Full reference with code examples and API tables: [references/full.md](references/full.md)
© TabooHarmony · MIT · TabooHarmony/roblox-brain
Similar skills
Everything for Game dev and 3D: Unity, Unreal, Godot, Blender →roblox-performance by other authors comes first.
