Skip to main content
skill CX Codex

roblox-rojo — Claude Code skill: what it does, how to install

roblox-rojo sets up Rojo 7 to sync local filesystem code with Roblox Studio, build place files, and export places back to disk.

MIT 519 installs ★ 36 updated 2026-10-22

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

What roblox-rojo does

This skill configures Rojo 7 projects so external code editors can sync files directly to Roblox Studio instances. It outlines file mapping rules for .lua and .luau scripts, helps construct default.project.json configurations, and provides CLI commands for place builds.

Sync sessions run on port 34872 by default and apply changes in one direction from disk to Studio. Converting an existing place file into source code on disk relies on rojo syncback.

Certain asset types cannot update via live sync due to Studio plugin constraints. Terrain and MeshPart.MeshId values require a full rebuild with rojo build.

What it helps with

  • map folder structures to Roblox instances inside default.project.json
  • export an existing place into local files using rojo syncback
  • generate place and model files with rojo build
  • create sourcemaps for external Luau editor tooling

Example prompts for the agent

  • Help me configure default.project.json for client and server scripts.
  • How do I extract instances from place.rbxl back to disk using rojo syncback?
  • Generate a command to watch and output sourcemap.json continuously.

How to install roblox-rojo

1Skills CLI (Vercel)

npx skills add nonlooped/roblox-suite --skill roblox-rojo -a claude-code

2Manually: put the files in place

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

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

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

Questions about roblox-rojo

How to install roblox-rojo in Claude Code?

Run npx skills add nonlooped/roblox-suite --skill roblox-rojo -a claude-code. The skill writes to ~/.claude/skills/roblox-rojo/SKILL.md.

What does roblox-rojo do?

It guides project layout, live-sync setup, builds, and CLI workflows for Rojo 7.

Why do some Roblox properties fail to live-sync?

Studio plugin limitations prevent real-time updates for binary data like Terrain or properties like MeshPart.MeshId. Those changes require recompiling the file via rojo build.

Source text

SKILL.md · MIT
---
name: roblox-rojo
description: "Set up or troubleshoot Rojo projects. Use for CLI and plugin installation, project files, live sync, builds, uploads, sourcemaps, and exporting existing places with syncback."
last_reviewed: 2026-07-09
---

# roblox-rojo

**Official sources:**
- https://rojo.space/docs/v7/ (docs index; current major is v7)
- https://rojo.space/docs/v7/getting-started/installation/
- https://rojo.space/docs/v7/getting-started/new-game/
- https://rojo.space/docs/v7/getting-started/existing-game/
- https://rojo.space/docs/v7/project-format/
- https://rojo.space/docs/v7/properties/
- https://rojo.space/docs/v7/sync-details/
- https://rojo.space/docs/v7/upgrade/
- https://github.com/rojo-rbx/rojo/releases (latest CLI/plugin releases; verify version before recommending install pins)
- https://github.com/rojo-rbx/rojo (source of truth for CLI flags and changelog when docs lag)

Rojo maps a filesystem project to Roblox instances so you can edit with external tools (VS Code, Git, linters, formatters) and live-sync or build into Studio/place files. This skill covers **Rojo 7** as documented at rojo.space and implemented in the current `rojo-rbx/rojo` release line.

## Mental model

| Piece | Role |
| --- | --- |
| **Rojo CLI** | Reads the project file + filesystem; serves live sync, builds place/model files, uploads, sourcemaps, syncback. |
| **Studio plugin** | Connects to the local serve session and applies patches into the open place. |
| **Project file** | `*.project.json` / `*.project.jsonc` describing the instance tree and options. |
| **Filesystem tree** | Scripts, models, JSON/TOML/YAML/CSV/text under `$path` nodes become Instances. |

Rojo is **filesystem → Studio** for live sync (one primary direction). Optional **two-way sync** in the plugin is experimental and incomplete. Do not design production workflows around it. For place → files, use **`rojo syncback`** (Rojo 7.7+) or external porting tools.

## Quick start

1. Install the **CLI** (Rokit recommended for projects; GitHub binaries or `cargo install rojo --version ^7` also supported).
2. Install the **Studio plugin** with `rojo plugin install` (or GitHub `rbxm` / Roblox.com plugin for the matching major).
3. `rojo init my-game` (or open folder + VS Code "Rojo: Open Menu").
4. `rojo serve` in the project folder.
5. In Studio: open the Rojo plugin panel → **Connect**.
6. Edit files on disk; watch them sync. Use `rojo build -o build.rbxlx` for a one-shot place file.

Full install matrix and CLI flags: [references/installation-and-cli.md](references/installation-and-cli.md).

## Script file → Instance mapping (defaults)

Both `.lua` and `.luau` are supported. Default rules (from Rojo source / sync docs):

| File pattern | Instance (when `emitLegacyScripts` is **true**, the default) | Instance (when `emitLegacyScripts` is **false**) |
| --- | --- | --- |
| `*.server.lua(u)` | `Script` (legacy RunContext) | `Script` with `RunContext = Server` |
| `*.client.lua(u)` | `LocalScript` | `Script` with `RunContext = Client` |
| `*.plugin.lua(u)` | `Script` with `RunContext = Plugin` | same |
| other `*.lua(u)` | `ModuleScript` | same |

**Init usurpers** (replace the parent folder with a script): `init.server.lua(u)`, `init.client.lua(u)`, `init.plugin.lua(u)`, `init.lua(u)`. Only one init script type per folder. A directory with `default.project.json` / `default.project.jsonc` is treated as a nested project instead of a plain folder.

Other defaults: `.rbxm`/`.rbxmx` models, `.model.json(c)`, plain `.json(c)` → ModuleScript returning a table, `.toml` / `.yml`/`.yaml` similarly, `.csv` → `LocalizationTable`, `.txt` → `StringValue`.

Details, meta files, limitations: [references/sync-details.md](references/sync-details.md).

## Project file essentials

Minimal place-shaped tree (services inferred without `$className` for known services):

```json
{
  "name": "MyGame",
  "tree": {
    "$className": "DataModel",
    "ReplicatedStorage": {
      "$path": "src/ReplicatedStorage"
    },
    "ServerScriptService": {
      "$path": "src/ServerScriptService"
    },
    "StarterPlayer": {
      "StarterPlayerScripts": {
        "$path": "src/StarterPlayerScripts"
      }
    }
  }
}
```

Important top-level fields (docs + current CLI):

| Field | Purpose |
| --- | --- |
| `name` | Project/instance name (optional for `default.project.json`; folder name used). |
| `tree` | Root instance description (required). |
| `servePort` | Default port for `rojo serve` (default **34872**). |
| `serveAddress` | Default bind address when CLI `--address` omitted. |
| `servePlaceIds` / `blockedPlaceIds` | Allow/deny live-sync targets by place ID. |
| `placeId` / `gameId` | Set Studio place/universe IDs on connect. |
| `serveAllowedHosts` | Extra Host/Origin values for serve (hostname access); CLI `--allowed-hosts` overrides. |
| `globIgnorePaths` | Globs to ignore (gitignore-style negation supported in recent releases). |
| `emitLegacyScripts` | Default **true** = Script/LocalScript; **false** = RunContext Scripts for server/client files. |
| `syncRules` | Custom file→middleware patterns. |
| `syncbackRules` | Controls `rojo syncback` behavior. |

Instance nodes use `$className`, `$path`, `$properties`, `$attributes`, `$ignoreUnknownInstances`, plus child keys. Prefer **implicit** property syntax. Full format: [references/project-format.md](references/project-format.md).

## Daily commands

```bash
# New project (place | model | plugin)
rojo init my-game
rojo init --kind model
rojo init --kind plugin --skip-git

# Live sync (default localhost:34872)
rojo serve
rojo serve --port 34872 --address 127.0.0.1

# Build place/model
rojo build -o build.rbxlx
rojo build -o build.rbxl
rojo build --plugin MyPlugin.rbxm
rojo build -o out.rbxlx --watch

# Sourcemap for editor tooling
rojo sourcemap --output sourcemap.json
rojo sourcemap --watch --absolute

# Upload (prefer dedicated deploy account; never commit cookies/keys)
rojo upload --asset_id PLACE_ID --cookie "..."
rojo upload --asset_id PLACE_ID --api_key "..." --universe_id UNIVERSE_ID

# Place file → filesystem into an existing project tree
rojo syncback . --input place.rbxl
rojo syncback . --input place.rbxlx --dry-run --list

# Plugin management / docs / format
rojo plugin install
rojo plugin uninstall
rojo doc
rojo fmt-project
```

## Live-sync limitations

Not all property types apply in real time (Studio plugin API limits). Common cases that may need a full **build + open** instead of live sync:

- Binary data (Terrain, CSG)
- `MeshPart.MeshId`
- `HttpService.HttpEnabled`

Property type coverage for build vs live sync is documented on the Properties page and rbx-dom's coverage chart. When live sync fails for a class/property, rebuild with `rojo build` and open the place.

`rojo serve` binds to loopback by default. Binding to a network-reachable address exposes the session: recent Rojo versions validate Host/Origin, gate some APIs to local clients, and warn on non-local binds. Prefer localhost; if you must expose, use `serveAllowedHosts` / `--allowed-hosts` deliberately.

## Porting existing games

1. Refactor Studio code into fewer service-rooted locations (`ReplicatedStorage`, `ServerScriptService`, `StarterPlayer`, tags via `CollectionService`) before porting.
2. Prefer **`rojo syncback`** with a project that already lists the services/paths you want filled (`rojo syncback path/to/project --input place.rbxl`). Only descendants of nodes present in the project tree are written.
3. Alternatives called out in official docs: [rbxlx-to-rojo](https://github.com/rojo-rbx/rbxlx-to-rojo), [Lune](https://github.com/lune-org/lune) for custom pipelines.
4. Leaving Rojo is always possible: Rojo builds normal place/model files; you can stop using the filesystem tree and edit in Studio only.

Workflows and syncback rules: [references/workflows-and-syncback.md](references/workflows-and-syncback.md).

## Agent checklist

- **Do** pin CLI + plugin to the **same major** (Rojo 7 plugin with Rojo 7 CLI).
- **Do** run `rojo plugin install` after upgrading the CLI.
- **Do** put shared modules under `ReplicatedStorage` paths and server authority under `ServerScriptService`.
- **Do** use `.luau` (Rojo's `init` templates use `.luau` since 7.4).
- **Do** set `emitLegacyScripts: false` only when the team understands modern `RunContext` scripts (and that client files become `Script`+Client, not `LocalScript`).
- **Do not** invent CLI flags or project keys. If unsure, run `rojo --help` / `rojo <cmd> --help` or re-check docs/changelog.
- **Do not** commit `.ROBLOSECURITY` cookies or Open Cloud API keys used with `rojo upload`.
- **Do not** treat experimental two-way sync as reliable source control.
- **Do not** confuse Rojo with Roblox **Script Sync** or **Studio MCP**. Different tools; they can coexist (see roblox-mcp).

## Verification

- [ ] `rojo --version` reports a 7.x release matching the intended pin.
- [ ] Studio shows the Rojo 7 plugin; connect succeeds against `rojo serve`.
- [ ] Editing a `.server.luau` under a mapped `$path` updates the correct service in Studio.
- [ ] `rojo build -o build.rbxlx` opens cleanly in Studio.
- [ ] `sourcemap.json` is gitignored if generated (Rojo's default gitignore template includes it in recent releases).

## How to proceed

1. Confirm install path: [references/installation-and-cli.md](references/installation-and-cli.md).
2. Shape the tree: [references/project-format.md](references/project-format.md).
3. Name files correctly: [references/sync-details.md](references/sync-details.md).
4. For teams / porting / deploy: [references/workflows-and-syncback.md](references/workflows-and-syncback.md).

<!-- catalog:references:start -->
## Reference index

- [installation-and-cli.md](references/installation-and-cli.md): Install Rojo or choose CLI commands and flags.
- [project-format.md](references/project-format.md): Write project trees, properties, paths, or nested projects.
- [sync-details.md](references/sync-details.md): Map files to instances or diagnose changes that live sync cannot apply.
- [workflows-and-syncback.md](references/workflows-and-syncback.md): Port an existing place, export Studio changes, or build in CI.
<!-- catalog:references:end -->

© nonlooped · MIT · nonlooped/roblox-suite

Similar skills

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

From the same set16

The whole set →
roblox-gamepasses roblox-gamepasses walks your agent through Roblox monetization: game passes, developer products, subscriptions and Robux transfers, with every benefit granted on the server. CX Codex +1 547installs roblox-core roblox-core is a Claude Code skill for choosing Roblox services, script locations, and execution contexts. It handles questions about Luau types, serialization, module loading, streaming, and client-server data. CX Codex +1 546installs roblox-datastores roblox-datastores is a Claude Code skill that implements and debugs persistent player data in Roblox, including concurrent writes, leaderboards, migrations, and storage choices. CX Codex +1 544installs roblox-audio This skill helps build and debug Roblox audio graphs, spatial sound, effects, and speech features. Use it when setting up playback or deciding whether to move from Sound to the audio graph. CX Codex +1 522installs roblox-physics roblox-physics guides agents on building and debugging Roblox assemblies, vehicles, mover constraints, and network ownership. CX Codex +1 521installs roblox-teleport roblox-teleport moves Roblox players between places, public servers, and reserved servers using TeleportAsync. Shows how to pass data, handle failures, and set up lobby flows. CX Codex +1 519installs roblox-npcs roblox-npcs — a skill for building and debugging NPC navigation in Roblox using PathfindingService. Use when you need patrol, chase, or obstacle avoidance logic. CX Codex +1 518installs roblox-open-cloud Reference skill for Roblox Open Cloud REST API to handle external automation, CI/CD deployments, and Data Store operations. CX Codex +1 497installs

Project sponsors

Companies that keep this analytics open