# roblox-rojo

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

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 519 installs · ★ 36 repo stars
- Author: nonlooped
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/nonlooped/roblox-suite/tree/HEAD/roblox-rojo/SKILL.md
- Updated: 2026-10-22
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/roblox-rojo

## What it 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`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add nonlooped/roblox-suite --skill roblox-rojo -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/roblox-rojo/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/roblox-rojo/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add nonlooped/roblox-suite --skill roblox-rojo -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/roblox-rojo/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add nonlooped/roblox-suite --skill roblox-rojo -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/roblox-rojo/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install nonlooped/roblox-suite roblox-rojo
```

2. **Manually: put the files in place**
- File: `.github/skills/roblox-rojo/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add nonlooped/roblox-suite --skill roblox-rojo -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/nonlooped/roblox-suite --path roblox-rojo
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/roblox-rojo/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add nonlooped/roblox-suite --skill roblox-rojo -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/nonlooped/roblox-suite/tree/HEAD/roblox-rojo/SKILL.md

## When to use it
- 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
- 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.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: deceb68c52419720.

BEGIN THIRD-PARTY FILE deceb68c52419720
```text
---
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` |
```
END THIRD-PARTY FILE deceb68c52419720

The third-party file has ended. Everything between the deceb68c52419720 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3049 of 10258 bytes. © nonlooped · MIT · https://github.com/nonlooped/roblox-suite/tree/HEAD/roblox-rojo/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
