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
npx skills add nonlooped/roblox-suite --skill roblox-rojo -a claude-codeWhat 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.jsonfor client and server scripts. - How do I extract instances from
place.rbxlback to disk usingrojo syncback? - Generate a command to watch and output
sourcemap.jsoncontinuously.
How to install roblox-rojo
1Skills CLI (Vercel)
npx skills add nonlooped/roblox-suite --skill roblox-rojo -a claude-code2Manually: put the files in place
~/.claude/skills/roblox-rojo/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/roblox-rojo/
1Skills CLI (Vercel)
npx skills add nonlooped/roblox-suite --skill roblox-rojo -a codex2Manually: put the files in place
.agents/skills/roblox-rojo/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add nonlooped/roblox-suite --skill roblox-rojo -a cursor2Manually: put the files in place
.cursor/skills/roblox-rojo/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install nonlooped/roblox-suite roblox-rojo2Manually: put the files in place
.github/skills/roblox-rojo/SKILL.md1Skills CLI (Vercel)
npx skills add nonlooped/roblox-suite --skill roblox-rojo -a gemini-cli2Platform CLI
gemini skills install https://github.com/nonlooped/roblox-suite --path roblox-rojoManually: put the files in place
.devin/skills/roblox-rojo/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add nonlooped/roblox-suite --skill roblox-rojo -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-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