/roblox-studio-workflow

name: roblox-studio-workflow
description: >
  Safely edits an existing Roblox place or Rojo project: finds the source of truth and proves
  changes with the right test mode or Studio MCP (execute_luau). Use when an agent edits a .rbxl
  or Rojo project, works through Studio MCP tools, or must report what was tested. Not for
  installing Studio MCP (`roblox-get-started`) or the feature code (`roblox-luau`, `roblox-ui`).

Roblox Studio workflow

Work as a collaborator inside an existing place, not as if it were a blank text repository. This skill owns how changes are made and proven; the domain skills own what the code does.

Workflow

1. **Establish the source of truth.** Decide whether Studio, Rojo files, Script Sync, a package, or a generated build owns each subtree (`*.project.json` mappings, `PackageLink` objects). Edit only the owner; a Studio edit to a Rojo-mapped script is overwritten by the next sync. 2. **Inventory before proposing structure.** Search scripts, modules, remotes, tags and Attributes for the feature's current owner (`rg` over the Rojo tree, or `script_grep` and `search_game_tree` over Studio MCP). Run once and record existing warnings, so new ones are yours. 3. **Plan the smallest compatible edit.** Name the Instances and execution locations you will change. Reuse existing remotes, components, cleanup utilities, tags, folders, and config patterns. State any ownership question you could not resolve. 4. **Create real, meaningful objects.** Authored UI, folders, attachments, constraints, remotes and configuration stay inspectable in Explorer. Scripts add behavior and genuinely dynamic repetition; they do not hide the whole feature in runtime construction. 5. **Respect execution and replication.** Authoritative logic in server containers, persistent client logic in `StarterPlayerScripts`, per-character logic in `StarterCharacterScripts`, UI templates in `StarterGui`, shared modules and remotes in `ReplicatedStorage`, secrets and server assets in server-only containers. Check each `Script`'s `RunContext`. 6. **Test the actual risk** with the smallest rung of the verification ladder that covers it. 7. **Clean the experiment.** Remove temporary parts, test remotes, Command Bar fixtures, debug UI, prints, disabled duplicate scripts, placeholder assets, and diagnostic tags or Attributes. Stop the session and confirm the edit-mode hierarchy is clean (`search_game_tree` or Explorer). 8. **Report evidence precisely.** Changed Instances and files; modes and client counts; cases run; observed Output; failures and fixes; and what was not run. Label each claim executed, statically checked, prepared but not run, or unverified. "Looks right" and static inspection are never "tested in Studio".

When Studio MCP is connected

If tools such as `list_roblox_studios` and `execute_luau` are available, drive the same ladder through them instead of asking the user to click: pick the place with `list_roblox_studios`, inventory, edit with `multi_edit`, run with `start_stop_play` and `execute_luau`, and collect evidence with `get_console_output` and `screen_capture` from both server and client. For live debugging, unit tests, device capture and profiling, call Studio's built-in skills (`rbx-debug`, `rbx-unit-test`, `rbx-device-simulator-lua`, `rbx-perf-profiling`) through the `skill` tool. Read `references/studio-mcp.md` for the tool map, limits, and safety rules.

When the tools are absent, the manual Studio and Rojo path is the full default; nothing here requires MCP. If the user wants it connected, Roblox's official `roblox-get-started` skill handles installation and connection.

Execution-location map

| Location | Typical role | Key constraint | |---|---|---| | `ServerScriptService` | authoritative Scripts and modules | not replicated to clients | | `ServerStorage` | server-only assets and data | clients cannot access it | | `ReplicatedStorage` | shared modules, assets, remotes | visible to clients; no secrets | | `StarterPlayerScripts` | client systems across respawns | cloned into `PlayerScripts` | | `StarterCharacterScripts` | per-character client behavior | recreated each character | | `StarterGui` | authored UI templates | cloned into `PlayerGui`; lifecycle follows `ResetOnSpawn` | | `Workspace` | replicated world and live characters | streaming and ownership change what clients see |

Reuse before adding

Before creating a RemoteEvent, search by purpose and read both endpoints. Before adding a "manager" module, find the current feature owner. Before adding folders or tags, read the existing naming and lookup patterns. Duplicate systems that both run double-bind input, save twice, create two UI clones, or apply gameplay twice.

Attributes hold small typed designer-editable values on an Instance; `CollectionService` tags find sets of Instances across the hierarchy; folders express ownership and navigation. Validate Attributes at the system boundary:

local CollectionService = game:GetService("CollectionService")

local function setupDoor(instance: Instance)
    if not instance:IsA("Model") then return end
    local accessLevel = instance:GetAttribute("AccessLevel")
    if type(accessLevel) ~= "number" then
        warn(`Door {instance:GetFullName()} needs numeric AccessLevel`)
        return
    end
    attachDoorBehavior(instance, accessLevel)
end

for _, door in CollectionService:GetTagged("Door") do setupDoor(door) end
CollectionService:GetInstanceAddedSignal("Door"):Connect(setupDoor)

The owning system also tears behavior down when a tagged Instance is removed.

Verification ladder

1. **Static:** project JSON and models build (`rojo build default.project.json -o check.rbxlx`), links resolve, selene and luau-lsp pass where the project uses them. 2. **Single session:** right execution context and hierarchy, no new Output errors or warnings, happy path and cleanup. 3. **Lifecycle:** respawn,