roblox-dev-skill
Verified, current Roblox and Luau knowledge for writing, reviewing and debugging Roblox game code. Use it for ANY task that involves Roblox, Luau or Roblox Studio, even a quick question or a one-line snippet: scripts and modules, RemoteEvents, DataStores and ProfileStore, ProcessReceipt and monetization, UI, the Input Action System, Parallel Luau and Actors, performance, security and anti-exploit, deprecated APIs, Rojo, and the Roblox Studio MCP tools (execute_luau, multi_edit, script_read, open_cloud_invoke). It holds facts that general knowledge gets wrong (which properties a game Script may set, features that exist but are not enabled, Studio betas that cannot be published, engine changes up to 0.746 and Luau up to 0.745) and worked examples tested in Studio, so consult it before answering from memory. Not for Lua outside Roblox (Redis, OpenResty, WoW addons, LOVE) or for other game engines.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/msayib--roblox-dev-skill)HTML
<a href="/listings/msayib--roblox-dev-skill"><img src="/api/listings/msayib--roblox-dev-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
**macOS, Linux, WSL, Git Bash**
curl -fsSL https://raw.githubusercontent.com/MSayib/roblox-dev-skill/master/install.sh | bash
**Windows PowerShell**
irm https://raw.githubusercontent.com/MSayib/roblox-dev-skill/master/install.ps1 | iex
**Windows CMD**
curl -fsSL https://raw.githubusercontent.com/MSayib/roblox-dev-skill/master/install.cmd -o install.cmd && install.cmd
The installer asks which agents to set up (the ones it finds are pre-selected), stores the skill once, and links it into each agent, so one update reaches all of them. It can also set up [`~/RobloxDocs`](docs/robloxdocs.md), a local copy of the Roblox API for fast, offline lookups. It never deletes anything it did not create.
**Then restart your agent** and try:
> *Create a coin collection system for my Roblox game*
You should get server-authoritative `--!strict` Luau that validates what the client sends. Options, updating, uninstalling and manual install: **[docs/installation.md](docs/installation.md)**.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 514 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- ---
- name: roblox-dev-skill
- description: >
- Verified, current Roblox and Luau knowledge for writing, reviewing and debugging Roblox game code.
- Use it for ANY task that involves Roblox, Luau or Roblox Studio, even a quick question or a
- one-line snippet: scripts and modules, RemoteEvents, DataStores and ProfileStore, ProcessReceipt
- and monetization, UI, the Input Action System, Parallel Luau and Actors, performance, security
- and anti-exploit, deprecated APIs, Rojo, and the Roblox Studio MCP tools (execute_luau,
- multi_edit, script_read, open_cloud_invoke). It holds facts that general knowledge gets wrong (which properties a
- game Script may set, features that exist but are not enabled, Studio betas that cannot be
- published, engine changes up to 0.746 and Luau up to 0.745) and worked examples tested in Studio, so consult
- it before answering from memory. Not for Lua outside Roblox (Redis, OpenResty, WoW addons, LOVE)
- or for other game engines.
- ---
- # Roblox Game Development Skill
- Expert development companion for building Roblox experiences with Luau. Grounded in
- official Roblox documentation (https://create.roblox.com/docs), the Luau language spec
- (https://luau.org), and the Roblox Lua Style Guide (https://roblox.github.io/lua-style-guide/).
- > **Engine**: Roblox Studio **0.746.0.7461269** with **Luau 0.745** (released 2026-10-30) — dump
- > downloaded, re-split, and diffed against 0.745 on **2026-11-05**, with every developer-visible
- > change run in Studio 0.746. 950 classes / 656 enums; locally, 267 class files named `*Service`
- > (347 classes carry the `Service` tag) and 48 deprecated classes (577 members). The official docs
- > were checked through 2026-11-04. New and usable: `RaycastParams.Margin` / `SizeGradient`, the
- > `Color3` contrast methods, `GamepadService:EnableGamepadCursor()` with no argument.
- >
- > Roblox ships roughly weekly, so this line is stale by design — never quote it as today's version.
- > Re-derive it instead:
- >
- > ```bash
- > curl -s "https://clientsettings.roblox.com/v2/client-version/MacStudio" # or WindowsStudio64
- > curl -s "https://api.github.com/repos/luau-lang/luau/releases?per_page=1" | grep tag_name
- > ```
- >
- > The `WindowsStudio` (no `64`) endpoint returns a long-stale value — measured 2026-09-06 it still
- > answered `0.578.0.5780566`. Use `WindowsStudio64` or `MacStudio`.
- >
- > When in doubt about an API, look it up (see **API & Documentation Lookup** below) rather than
- > recalling it. If it is still unclear, ask the user before proceeding.
- ---
- ## MCP Detection
- On every invocation, detect available Roblox Studio MCP tools before proceeding:
- ### Official Roblox MCP (Roblox_Studio server)
- **This skill is a knowledge base, not an MCP server.** It ships no tools and no execution
- surface. The tools below belong to **Roblox's own MCP server, built into Studio** — this skill
- only tells you how to use them well. Official reference:
- https://create.roblox.com/docs/studio/mcp
- The docs page lists **26 tools**. The build observed 2026-11-07 (Studio 0.746.0.7461269) exposed
- **35**: those plus `open_cloud_invoke`, which has its own page (`studio/mcp-open-cloud`), and the
- undocumented `generate_texture`, `segment_mesh`, `generate_scene`, `generate_avatar`,
- `auto_setup_avatar` and three skill-authoring tools, `list_skills`, `create_skill` and `edit_skill`
- (34 on 2026-11-05; 31 on 2026-10-29, Studio 0.745; 28 on 2026-10-17 to 2026-10-22, Studio 0.743–0.744;
- `list_plugin_guis` and `capture_plugin_gui`, seen on 2026-10-11 in Studio 0.742, were gone by then). Detect what your host actually
- exposes rather than trusting this table.
- | Tool | Purpose |
- |------|---------|
- | `execute_luau` | Run Luau in Studio at plugin privilege — **returns the result or the error**. HTTP and data stores go through the MCP Permissions gates |
- | `open_cloud_invoke` | Call Open Cloud with no API key, limited to the scopes the user enabled; uploads create permanent assets, so ask first (`mcp-integration.md`) |
- | `multi_edit` | Apply several exact-match edits to **ONE** script (creates it if missing); `Edit` datamodel only |
- | `script_read` | Read script source, whole or by line range; output is `LINE→CONTENT` |
- | `script_search` / `script_grep` | Find scripts by name (fuzzy, ≤10) or by content (≤50 matches) |
- | `search_game_tree` | Explore the DataModel as flat JSON, filterable by path/type/keyword; requires `datamodel_type` |
- | `inspect_instance` | Properties, attributes, and child summary for one instance |
- | `subagent` | Launch a Roblox-side subagent for autonomous multi-step work (types vary by build) |
- | `get_studio_state` | Play state **and which datamodel types are available** |
- | `start_stop_play` | Start/stop playtesting |
- | `get_console_output` | Read Output/console logs |
- | `screen_capture` | Capture the viewport, optionally from a custom camera; requires a `capture_id` |
- | `character_navigation` | Move the character to a position or instance path |
- | `user_mouse_input` / `user_keyboard_input` | Simulate ordered mouse/keyboard actions |
- | `search_asset` / `insert_asset` | Search Creator Store + Inventory; insert by asset ID |
- | `store_image` | **Local** png/jpg ≤5 MB → `IMAGEID_` URI for other tools |
- | `upload_image` | Batch upload from **HTTP(S) URLs** → imagePath→assetId map |
- | `generate_mesh` / `generate_procedural_model` | Generate 3D content |
- | `generate_material` | Generate a `MaterialVariant`; returns the base material + variant name |
- | `generate_texture` | Re-texture an **existing** MeshPart/Model — **replaces the source in place** (duplicate it first) |
- | `segment_mesh` | Split an existing mesh into ≤5 named parts; inserts a new Model next to the source |
- | `generate_scene` | Generate models and parts from a prompt or images, in an optional bounding box; **runs the generated script in the DataModel** |
- | `generate_avatar` | Generate a rigged R15 avatar from a prompt, **upload it as a persistent asset** and insert it into Workspace; usually several minutes |
- | `auto_setup_avatar` | Rig an existing static Workspace Model as an R15 avatar and place the result beside it; usually 3-5 minutes |
- | `wait_job_finished` | Await a background `jobId` (from a tool's own `async: true`) |
- | `http_get` | Fetch Roblox docs **from an allowlist**; URL must end `.md` or be `llms.txt` |
- | `skill` | Roblox's first-party `rbx-*` references (debug, perf, scene analysis, configs, analytics, permissions, Open Cloud, model import, …) |
- | `list_skills` / `create_skill` / `edit_skill` | List every skill; **publish** a new user skill or edit one (persistent, not undoable here: ask first) |
- | `list_roblox_studios` | Enumerate connected Studio instances (name + place ID) |
- > **Every call takes a `studio_id`.** There is no "set active studio" tool — call
- > `list_roblox_studios` first and pass the id you want on each subsequent call. Several Studio
- > instances are commonly open at once, so picking the wrong id silently targets the wrong place.
- >
- > **`datamodel_type` is asymmetric.** `execute_luau` accepts `Edit` / `Client` / `Server`;
- > **`multi_edit` accepts `Edit` only**, so you cannot edit scripts mid-playtest — stop the
- > playtest first. `Client` and `Server` exist only during a playtest, and `Edit` is refused during
- > one (`Edit datamodel is not available in Play mode`); check `get_studio_state`.
- >
- > **`multi_edit` is one script per call**, taking `file_path` plus
- > `edits[{old_string, new_string, replace_all}]`. Replacements are sequential, exact-match, and
- > atomic within the call: one `old_string` that does not match fails the call and leaves the
- > script unchanged (tested 2026-10-11). It does not require a prior `script_read`, but read
- > first anyway, since `old_string` must match the source exactly, whitespace included.
- >
- > **Confirm `script_grep`'s line numbers with `script_read`.** On 2026-09-06 it reported a match
- > at line 171 that `script_read` showed was 15 lines further down; on 2026-10-11 (Studio 0.742)
- > two tests returned the exact line, so the cause is unknown. Use it to find *which* script
- > contains a string, then `script_read` for the real location.
- >
- > **There is no `run_as_job` tool.** Earlier versions of this file listed one; it does not exist
- > in the docs or in any observed build. Async is a per-tool argument returning a `jobId`.
- If MCP tools are available, prefer using them for:
- - Reading existing scripts before writing new ones (`script_read`, `script_search`)
- - Validating changes by running code (`execute_luau`)
- - Inspecting game tree to understand project structure (`search_game_tree`)
- - Testing changes with playtest (`start_stop_play`, `get_console_output`)
- - Roblox's own domain skills (`skill`) for debugging, MicroProfiler, scene analysis, permissions
- and Open Cloud — first-party and shipped with Studio, but not always current: some steps in them
- fail when run (`mcp-integration.md` lists the ones measured)
- **Before the first mutation of any session**, read `references/agent-safety.md`. Roblox's own
- warning: *"MCP clients can read and modify content in your open Roblox places."* There is no
- dry-run and no reliable undo. Confirm which place you are targeting before you write to it.
- If MCP tools are NOT available, provide copy-paste-ready Luau scripts with clear
- placement instructions (which service container to put them in).
- ---
- ## Routing Table
- Match user intent to the appropriate reference file. Read the file BEFORE generating code.
- | User Intent | Reference File |
- |---|---|
- | **How do I actually sequence this?** End-to-end worked patterns: build a server-authoritative feature, debug via MCP, migrate a deprecation, verify an API, refuse an unsafe request, grant a developer product, migrate saved data, open a menu from an Input Action | `references/worked-examples.md` |
- | Luau syntax, types, naming conventions, style | `references/luau-fundamentals.md` |
- | Project layout, architecture, patterns, values you tune without a restart (`ConfigService`) | `references/project-structure.md` |
- | Save/load player data, DataStore, ProfileStore | `references/datastore-persistence.md` |
- | Client-server communication, RemoteEvents, input, text chat (`TextChatService`, chat commands, platform-integrated chat) | `references/networking.md` |
- | Security, anti-exploit, server authority, bans | `references/security-hardening.md` |
- | Agent→Studio safety, destructive MCP ops, prompt injection from place content | `references/agent-safety.md` |
- | Performance, memory, optimization, Parallel Luau, live instance groups (`CreateCollection`) | `references/performance-optimization.md` |
- | Using Roblox Studio MCP tools effectively | `references/mcp-integration.md` |
- | Open Cloud from an MCP client (`open_cloud_invoke`), MCP Permissions, permission errors, uploads | `references/mcp-integration.md` + `references/agent-safety.md` |
- | UI, GUI, ScreenGui, menus, HUD, StyleQuery | `references/ui-systems.md` |
- | Migrating legacy code, deprecated APIs | `references/legacy-migration.md` |
- | Monetization, game passes, donations, transfers | `references/monetization.md` |
- | File formats, import/export, asset management | `references/file-formats-and-assets.md` |
- | Plugins, `Script.Source` limits, HttpService/engine limits | `references/studio-plugins-and-limits.md` |
- **Start with `worked-examples.md` when the task is a *doing* task** (build, debug, migrate, look up, sell, bind input)
- rather than a *knowing* task. It gives the call sequence and the verification step, and each example
- carries a **Not this** list so a near-miss request routes to the right place instead of the nearest
- familiar pattern. Where an example and a reference file disagree, the reference file wins.
- If the intent spans multiple domains, read all relevant files.
- If a reference file doesn't cover a topic sufficiently, use the Official
- Documentation Lookup workflow below.
- ---
- ## API & Documentation Lookup
- ### Priority 1: Local API Reference (`~/RobloxDocs/`)
- **Always check local files first** — they are pre-split, far cheaper to read than the full dump, and
- require no network. If `~/RobloxDocs/RobloxAPI/` exists, use it.
- **How much cheaper, re-measured 2026-11-05 on 0.746.0.7461264** (an earlier "845× smaller" figure
- was not reproducible from any measurement, so here are the real numbers and the command that
- produced them): the full dump is **8,721,015 bytes**; the 950 split class files run **101 B min,
- 2,074 B median, 4,897 B mean, 105,756 B max**. So a typical class lookup reads about **0.02%** of
- the dump, and even the largest class reads under **1.3%** of it. Re-measure with:
- ```bash
- # Portable (macOS, Linux, Windows). Do not use `stat -f %z`: on Linux `stat -f` reports the
- # *filesystem*, not the file, and prints a wrong number without any error. It also reads the
- # 75-byte latest.json symlink instead of the dump unless you remember -L.
- python3 -c "import os,glob,statistics as s; d=os.path.expanduser('~/RobloxDocs/RobloxAPI'); \
- z=sorted(os.path.getsize(f) for f in glob.glob(d+'/classes/*.json')); \
- print('dump', os.path.getsize(os.path.realpath(d+'/dumps/latest.json')), 'B | n', len(z), \
- 'min', z[0], 'median', int(s.median(z)), 'mean', int(s.mean(z)), 'max', z[-1])"
- ```
- ```bash
- # Look up a specific class (~2 KB median vs the 8.6 MB full dump — see measurement above)
- cat ~/RobloxDocs/RobloxAPI/classes/<ClassName>.json
- # Query a specific property/method (jq if installed; the python3 form works everywhere)
- jq '.Members[] | select(.Name == "<MemberName>")' ~/RobloxDocs/RobloxAPI/classes/<ClassName>.json
- python3 -c "import json,os; print([m for m in json.load(open(os.path.expanduser('~/RobloxDocs/RobloxAPI/classes/<ClassName>.json')))['Members'] if m['Name']=='<MemberName>'])"
- # Find all services
- cat ~/RobloxDocs/RobloxAPI/service-index.json
- # Check what's deprecated
- cat ~/RobloxDocs/RobloxAPI/deprecated-index.json
- # Search across classes by filename
- ls ~/RobloxDocs/RobloxAPI/classes/ | grep -i <keyword>
- # Search for a property across all classes
- grep -l '"<PropertyName>"' ~/RobloxDocs/RobloxAPI/classes/*.json
- ```
- **Obsolescence check:** Before using local data, verify freshness:
- ```bash
- # Check when local data was last updated
- cat ~/RobloxDocs/RobloxAPI/.current-version
- # → {"version": "0.746.0.7461264", "platform": "MacStudio", "platformVersion": "0.746.0.7461264",
- # "winHash": "version-fee454b8e2094ba9", "updatedAt": "2026-11-04T18:00:20Z", "checkedAt": "2026-11-04T18:00:20Z"}
- ```
- > **Read whichever timestamp is present: `updatedAt` OR `checkedAt`.** `updatedAt` is when a dump
- > was last downloaded; `checkedAt` is when the version was last checked. The current monitor
- > (skill 2.12.0+) always writes both, but the older zsh script wrote **only `updatedAt`** after a
- > download — so an install that has not refreshed its tools may lack `checkedAt` entirely. Earlier
- > versions of this file told the agent to read `checkedAt`, which silently found nothing there.
- If that timestamp is older than 7 days, or a class/member is not found locally, **proceed with the
- live web fallback below and tell the user the local dump looks stale.** Offer to refresh it:
- ```bash
- # Only after the user agrees — this downloads and re-splits the API dump
- ~/RobloxDocs/scripts/roblox-api-monitor.sh # macOS, Linux, WSL, Git Bash
- python "%USERPROFILE%\RobloxDocs\scripts\roblox-api-monitor.py" # Windows without bash
- ```
- If `~/RobloxDocs` does not exist at all, the user never set it up. Say so and point them at the
- installer's `--docs-only` option (`-DocsOnly` in PowerShell) rather than creating it yourself.
- > **Do not background this and do not run it unasked.** Earlier versions of this file told the
- > agent to fire `roblox-api-monitor.sh &` automatically, which contradicted both the
- > Knowledge Freshness Check below ("NEVER auto-update without user approval") and the README.
- > There is no scheduler and no background job in this skill; a human triggers the refresh.
- > Staleness never blocks the answer — fall through to the web sources and say so.
- ### Priority 2: Live Web Sources (Fallback)
- Use these when local data doesn't cover a topic, is obsolete, or you need prose docs:
- | Resource | URL | Use For |
- |----------|-----|--------|
- | **LLM docs index** | `https://create.roblox.com/docs/llms.txt` | Browse all available doc pages by topic |
- | **Full docs (single file)** | `https://create.roblox.com/docs/llms-full.txt` | Comprehensive single-file reference |
- | **Per-page markdown** | `https://create.roblox.com/docs/en-us/{path}.md` | Read specific doc pages in clean markdown |
- | **Engine API index** | `https://create.roblox.com/docs/reference/engine/llms.txt` | Luau API classes, methods, events |
- | **Open Cloud API index** | `https://create.roblox.com/docs/cloud/llms.txt` | **Primary discovery** for all Cloud REST API: features, domains, guides, auth |
- | **OpenAPI spec (raw)** | `https://create.roblox.com/docs/cloud/openapi.json` | Machine-readable OpenAPI spec for MCP/code-gen tools |
- | **Deprecated API check** | `https://robloxapi.github.io/ref/class/<Name>.html` | Check individual class/member status (deprecated items marked visually) |
- > **If you are fetching these through Studio's `http_get` tool, note its allowlist:** only
- > `create.roblox.com/docs` (incl. `/reference/engine`, `/cloud`, `/performance-optimization`) and
- > `github.com/Roblox/libmp`, and **the URL must end in `.md` or be `llms.txt`**. So
- > `llms-full.txt`, `openapi.json`, and `robloxapi.github.io` are **rejected** by `http_get` — use
- > the host's own fetch tool or `curl` for those. `http_get`'s `query` argument returns only
- > matching sections, which is much cheaper than pulling a whole page into context. A
- > `github.com/Roblox/libmp/blob/….md` URL is accepted but comes back as GitHub's HTML page
- > (measured 2026-10-21); read LibMP files from `raw.githubusercontent.com` with curl instead.
- ### Lookup Workflow
- 1. Check if a **reference file** covers the topic (Routing Table above)
- 2. Check **`~/RobloxDocs/RobloxAPI/classes/<Name>.json`** for Engine API details
- 3. If not found locally, fetch the per-page markdown URL with whatever web-fetch tool the host
- provides (`WebFetch` in Claude Code, `curl` in a shell — the URL is the portable part)
- - Example: `https://create.roblox.com/docs/en-us/studio/importer.md`
- 4. If unsure which page to read, browse `llms.txt` for the right URL
- 5. For **Open Cloud / REST API** topics, read `https://create.roblox.com/docs/cloud/llms.txt`
- - Search Features section first, then Domains
- - Prefer Open Cloud endpoints (API key / OAuth) over legacy cookie-auth endpoints
- - From an MCP client, call them with `open_cloud_invoke`: Studio supplies the token, so no key
- 6. **Fallback**: Context7. Its MCP tools are `resolve-library-id` then `query-docs` (the
- upstash/context7 README, checked 2026-10-11; an earlier version of this file called the second
- one `get-library-docs` and said `query-docs` did not exist). Where the
- MCP server is not connected, the CLI does the same job:
- `npx ctx7@latest library "Roblox"` then `npx ctx7@latest docs <libraryId> "<question>"`
- 7. If still unclear, ask the user before proceeding
- > **Important**: Engine APIs (Luau via `game:GetService()`) and Open Cloud APIs
- > (HTTP REST via `x-api-key`, or `open_cloud_invoke` from an MCP client) are **completely separate
- > systems**. Using the wrong index will produce non-functional code.
- > **Checking deprecated APIs**: Use these approaches (in priority order):
- > 1. `cat ~/RobloxDocs/RobloxAPI/deprecated-index.json` — instant local lookup
- > 2. `cat ~/RobloxDocs/RobloxAPI/deprecated/<ClassName>.json` — full deprecated class detail
- > 3. Check `robloxapi.github.io/ref/class/<Name>.html` — deprecated members marked visually
- > 4. Use Context7 (`resolve-library-id` → `get-library-docs`, or the `ctx7` CLI) to query specific APIs
- ---
- ## Core Coding Standards
- These rules apply to ALL generated Roblox/Luau code. They are non-negotiable.
- ### 1. Type Safety
- - Use `--!strict` at the top of every new script
- - Annotate function parameters and return types
- - Define custom types with `type` keyword for complex data structures
- ### 2. Naming Conventions (Official Roblox Style)
- - **PascalCase**: Classes, ModuleScripts, Constructors, Services — `CombatService`, `PlayerData`
- - **camelCase**: Variables, functions, parameters — `playerHealth`, `calculateDamage()`
- - **UPPER_SNAKE_CASE**: Constants — `MAX_HEALTH`, `DEFAULT_SPEED`
- - Spell out words fully — avoid abbreviations
- - Don't fully capitalize acronyms: `JsonTable` not `JSONTable`
- ### 3. Modern API Usage
- - Use `task.spawn()`, `task.delay()`, `task.wait()` — NOT legacy `spawn()`, `delay()`, `wait()`
- - Use `task.cancel()` to clean up deferred tasks
- - Always disconnect event connections in cleanup: `connection:Disconnect()`
- - Wrap fallible operations in `pcall()` or `xpcall()`
- ### 4. Architecture Rules
- - **Server authority**: All game state mutations happen on the server
- - **ModuleScripts** for shared logic — avoid monolithic scripts
- - **Service/Controller pattern**: Services (server), Controllers (client)
- - Scripts go in the correct container:
- - Server logic → `ServerScriptService`
- - Client logic → `StarterPlayerScripts` or `StarterCharacterScripts`
- - Shared modules → `ReplicatedStorage`
- - Server-only data → `ServerStorage`
- - UI → `StarterGui`
- ### 5. Error Handling
- <!-- skilltest: prelude datastore; expect call-succeeded -->
- ```lua
- local success, result = pcall(function()
- return DataStoreService:GetDataStore("PlayerData"):GetAsync(key)
- end)
- if not success then
- warn("[DataService] Failed to load data:", result)
- -- Handle gracefully: use defaults, retry, etc.
- end
- ```
- ### 6. Security (Always Apply)
- - NEVER trust client-sent data — validate types, ranges, and permissions on server
- - Keep sensitive logic in `ServerScriptService` (not visible to clients)
- - Validate RemoteEvent arguments: check `typeof()`, ranges, and player state
- - Rate-limit RemoteEvent calls from clients
- - Never expose admin commands or server keys to ReplicatedStorage
- ---
- ## Script Template
- When creating new scripts, use this template as a starting point:
- ```lua
- --!strict
- -- [ScriptName]
- -- [Brief description of what this script does]
- -- Container: [ServerScriptService/StarterPlayerScripts/ReplicatedStorage]
- ----- Services -----
- local Players = game:GetService("Players")
- local ReplicatedStorage = game:GetService("ReplicatedStorage")
- ----- Dependencies -----
- -- local SomeModule = require(ReplicatedStorage.Modules.SomeModule)
- ----- Constants -----
- local MAX_VALUE = 100
- ----- Types -----
- type PlayerData = {
- coins: number,
- level: number,
- inventory: { string },
- }
- ----- Variables -----
- local activeConnections: { [Player]: { RBXScriptConnection } } = {}
- ----- Private Functions -----
- local function cleanup(player: Player)
- local connections = activeConnections[player]
- if connections then
- for _, conn in connections do
- conn:Disconnect()
- end
- activeConnections[player] = nil
- end
- end
- ----- Public / Event Handlers -----
- local function onPlayerAdded(player: Player)
- activeConnections[player] = {}
- -- Setup logic here
- end
- ----- Initialization -----
- Players.PlayerAdded:Connect(onPlayerAdded)
- Players.PlayerRemoving:Connect(cleanup)
- -- Handle players already in game (Studio hot-reload)
- for _, player in Players:GetPlayers() do
- task.spawn(onPlayerAdded, player)
- end
- ```
- ---
- ## Response Guidelines
- 1. **Ask before building**: If the request is vague, ask clarifying questions about genre, scale, and target audience
- 2. **Read before writing**: If MCP is available, read existing scripts and game tree before modifying
- 3. **Small slices**: Generate 50-100 lines at a time for complex systems — easier to debug
- 4. **Explain the why**: Comment non-obvious code and explain architectural decisions
- 5. **Test path**: Suggest how to test the code (playtest steps, console checks)
- 6. **Migration-aware**: When touching existing code, check for legacy patterns and suggest migration if appropriate — but never force it. Incremental migration is acceptable.
- ---
- ## Common Workflows
- ### New Feature
- 1. Read existing project structure (MCP: `search_game_tree`)
- 2. Identify where the feature fits in the architecture
- 3. Create ModuleScript(s) in the appropriate container
- 4. Wire up server/client communication if needed
- 5. Test via playtest (MCP: `start_stop_play` + `get_console_output`)
- ### Debug Issue
- 1. Read the relevant script (MCP: `script_read`)
- 2. Check console output (MCP: `get_console_output`)
- 3. Identify the root cause — look for:
- - Missing `pcall` around DataStore/HTTP calls
- - Client-server boundary issues
- - Connection leaks (missing Disconnect)
- - Race conditions (script execution order)
- 4. Apply minimal fix
- 5. Verify fix via playtest
- ### Code Review
- 1. Read scripts in the project (MCP: `script_grep`)
- 2. Check against Core Coding Standards above
- 3. Flag security issues (client trust, exposed data)
- 4. Flag performance issues (expensive loops, part count)
- 5. Suggest improvements with before/after examples
- ---
- ## Knowledge Freshness Check
- Nothing about this is automatic — there is no scheduler, hook, or background job behind it. It is an
- instruction to *you*, the agent reading this file: **when this skill is invoked**, read
- `metadata.json` in this skill directory and compare `last_updated` to the current date.
- ### Logic:
- ```
- IF (current_date - last_updated) > update_interval_days (default: 7):
- TELL the user:
- "⏰ Roblox Dev Skill knowledge was last updated on {last_updated}, {days} days ago.
- Want me to run a knowledge update before we rely on it?"
- ...then WAIT. Do not update anything unless they say yes.
- ELSE:
- Proceed normally — knowledge is fresh.
- ```
- ### Decision Rules:
- - **NEVER auto-update** without user approval — always ask first
- - **Source of truth**: https://create.roblox.com/docs, https://devforum.roblox.com
- - **Decision maker**: Always the user (never the AI alone)
- - **Update process**: Deep research → fact-check → QnA with user → apply → audit
- - **After update**: Update `metadata.json` with new timestamp, version, and changes
- ---
- ## Manual Knowledge Update
- The user can trigger a full knowledge update at any time by asking for one in plain language —
- "update roblox skill knowledge", "refresh roblox dev skill", "roblox-update".
- > **`/roblox-update` is NOT a registered slash command.** Earlier versions of this file presented it
- > as one; it has never been installed in `~/.claude/commands/` or shipped by a plugin, so typing it
- > resolves to nothing. It is a phrase this skill listens for, and that is all it has ever been.
- ### Update Protocol:
- 1. **Research** — Search for latest Roblox changes since `last_updated` timestamp
- - DevForum release notes, API changelog, deprecation notices
- - Use web search for "Roblox developer updates {year}" and "Roblox API changes {month} {year}"
- - Visit https://devforum.roblox.com/c/updates/release-notes/58
- 2. **Compare** — Cross-check findings against existing reference files
- 3. **Report** — Present findings to user with clear "what changed" summary
- 4. **Discuss** — QnA with user on any decisions (add/remove/modify content)
- 5. **Apply** — Update reference files (keep what's correct, update what changed)
- 6. **Audit** — Full fact-check (same pattern as initial audit: file integrity + content verification)
- 7. **Stamp** — Update `metadata.json` with new timestamp and changelog entry
- > [!IMPORTANT]
- > All updates must be research-based. No improvisation. When in doubt, ask the user.
- > Fallback: consult official docs via context7 MCP or direct web search.
- ---
- ## Export / Publish
- This skill is designed to be export-ready for GitHub publishing. See `README.md`
- in the skill root directory for the complete structure and usage guide.
- Users install it with the one-line installers in the repository (`install.sh`, `install.ps1`,
- `install.cmd`), which link it into each agent's skills folder. When copying it by hand, the folder
- **must be named `roblox-dev-skill`** — the Agent Skills spec requires the folder name to match the
- `name` field above, and stricter agents skip a skill whose folder does not.
README.md · README · 114 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # 🎮 Roblox Dev Skill
- [](https://github.com/MSayib/roblox-dev-skill/actions/workflows/ci.yml)
- **An [Agent Skill](https://agentskills.io) that makes an AI coding agent write correct, current Roblox
- code.** When you mention Roblox, Luau or Roblox Studio, the agent loads this skill: a routing file
- ([`SKILL.md`](SKILL.md)) plus 14 reference guides on Luau, client-server architecture, security,
- DataStores, UI, performance, monetization, migration, and driving Roblox Studio through its MCP
- server. Works with Claude Code, Codex, Cursor, Gemini CLI, Antigravity, GitHub Copilot, and any
- agent that reads the Agent Skills format.
- > **Skill 2.22.0** · verified against Roblox Studio **0.746.0.7461269** and **Luau 0.745** on
- > 2026-11-07. Every code example was type-checked under `--!strict` and run in a real Studio place,
- > and every factual statement checked against an official source or a test.
- > Roblox ships weekly, so this is *when it was last verified*, not today's version.
- It is Markdown an agent reads. It is **not** an MCP server and ships no tools: for Studio access,
- enable [Studio's built-in MCP server](https://create.roblox.com/docs/studio/mcp).
- ## Quick install
- **macOS, Linux, WSL, Git Bash**
- ```bash
- curl -fsSL https://raw.githubusercontent.com/MSayib/roblox-dev-skill/master/install.sh | bash
- ```
- **Windows PowerShell**
- ```powershell
- irm https://raw.githubusercontent.com/MSayib/roblox-dev-skill/master/install.ps1 | iex
- ```
- **Windows CMD**
- ```bat
- curl -fsSL https://raw.githubusercontent.com/MSayib/roblox-dev-skill/master/install.cmd -o install.cmd && install.cmd
- ```
- The installer asks which agents to set up (the ones it finds are pre-selected), stores the skill
- once, and links it into each agent, so one update reaches all of them. It can also set up
- [`~/RobloxDocs`](docs/robloxdocs.md), a local copy of the Roblox API for fast, offline lookups.
- It never deletes anything it did not create.
- **Then restart your agent** and try:
- > *Create a coin collection system for my Roblox game*
- You should get server-authoritative `--!strict` Luau that validates what the client sends. Options,
- updating, uninstalling and manual install: **[docs/installation.md](docs/installation.md)**.
- ## What's inside
- | Reference | Covers |
- |---|---|
- | [worked-examples](references/worked-examples.md) | Eight end-to-end tasks for an agent (build, debug, migrate, look up, refuse, sell a product, migrate saved data, bind input), each ending in a tested verification |
- | [luau-fundamentals](references/luau-fundamentals.md) | Luau syntax, types and the New Type Solver, `coroutine.finally`, what each Luau release changed, beta and experimental features you cannot ship |
- | [project-structure](references/project-structure.md) | Services, Rojo, client/server layout, the Input Action System |
- | [networking](references/networking.md) | RemoteEvents, RemoteFunctions, unreliable remotes, bindables, text chat and platform-integrated chat, teleports to reserved and VIP servers |
- | [security-hardening](references/security-hardening.md) | Server authority, validating remote input, anti-exploit, bans, device trust, script capabilities |
- | [datastore-persistence](references/datastore-persistence.md) | DataStoreService, ProfileStore, MemoryStoreService |
- | [performance-optimization](references/performance-optimization.md) | Memory, Parallel Luau and Actors, streaming, the frame pipeline, thick casts with `RaycastParams.Margin` |
- | [ui-systems](references/ui-systems.md) | GUI layout, StyleSheets, BillboardGui / SurfaceGui, ProximityPrompt, `Color3` contrast methods |
- | [monetization](references/monetization.md) | Game passes, developer products, subscriptions, Robux transfers |
- | [legacy-migration](references/legacy-migration.md) | Deprecated APIs and replacements, what each engine release changed |
- | [mcp-integration](references/mcp-integration.md) | Studio MCP tools with their real signatures and limits, Open Cloud and MCP Permissions, what Roblox's own skills get wrong |
- | [agent-safety](references/agent-safety.md) | What an agent with Studio access can break, and the rules that prevent it |
- | [studio-plugins-and-limits](references/studio-plugins-and-limits.md) | Plugins, `Script.Source` limits, engine limits |
- | [file-formats-and-assets](references/file-formats-and-assets.md) | `.rbxl`/`.rbxm`, meshes, importing |
- How routing, lookup and the coverage dates work: **[docs/how-it-works.md](docs/how-it-works.md)**.
- ## How it stays correct
- - **Every example is tested.** Each Luau block is type-checked with luau-lsp under `--!strict`, then
- run in a real Studio place through Rojo, as a game Script (so security gates apply), a
- LocalScript, or inside an Actor. The 2.16.0 pass found and fixed a script that could not compile,
- a pool that leaked objects, player data shared between players, and a purchase handler that
- charged for items it did not give. Since 2.17.0 the fragments run too, with the names a reader's
- project would supply, and the important examples assert what they do (a pool returns to 10, a
- receipt is granted once). **[docs/testing.md](docs/testing.md)**
- - **Every claim is checked.** Each high-risk statement (limits, versions, "cannot", "not enabled")
- is in a register with its source or test; the 2.17.0 pass corrected 58, among them a
- delayed rollout the text dated, limits off by up to 1000×, and an event that does not exist.
- **[docs/claims.md](docs/claims.md)**
- - **Every engine release is diffed** member by member against the previous API dump, and the
- developer-visible changes are run in Studio before the skill describes them. "Not enabled"
- statements are re-run every cycle, because a server-side flag can change them with an empty diff.
- - **It says what it does not know.** Features that exist but are not enabled, betas you cannot
- publish, and anything not yet tested are labelled as such.
- History: **[CHANGELOG.md](CHANGELOG.md)** (machine-readable: [`metadata.json`](metadata.json)).
- ## For AI agents reading this
- Start at [`SKILL.md`](SKILL.md): it holds the standards (always `--!strict`, server authority,
- validate every remote argument) and a routing table that says which reference to open for which
- task. Where a reference and a worked example disagree, the reference wins. Treat the version line
- above as a date, and re-check the live engine version with the commands in `SKILL.md`.
- ## Contributing
- Ground every claim in official documentation, the API dump, or a test you ran, and pass the four
- test layers in [docs/testing.md](docs/testing.md) before opening a pull request.
- ## License and credits
- MIT, see [LICENSE](LICENSE). Created by [@MSayib](https://github.com/MSayib), built with AI and
- fact-checked against [Roblox Creator Docs](https://create.roblox.com/docs), [Luau](https://luau.org),
- the Roblox API dump, and Roblox Studio itself.
- If the skill helps you, a ⭐ helps other developers find it.
- [](https://star-history.com/#MSayib/roblox-dev-skill&Date)
install.ps1 · Bundled script · 641 lines · 3 findings marked
- <#
- roblox-dev-skill installer for Windows PowerShell 5.1+ and PowerShell 7+
- https://github.com/MSayib/roblox-dev-skill
- irm https://raw.githubusercontent.com/MSayib/roblox-dev-skill/master/install.ps1 | iex
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 5 on GitHub
- With options:
- & ([scriptblock]::Create((irm https://raw.githubusercontent.com/MSayib/roblox-dev-skill/master/install.ps1))) -Agents claude,universal -Yes
- Installs the skill once and links it into every agent you pick (symlink, else a junction, else a
- copy), then optionally sets up ~\RobloxDocs with a freshly downloaded Roblox API dump.
- No git needed. RobloxDocs needs Python 3.6+.
- This file is deliberately ASCII-only: Windows PowerShell 5.1 reads BOM-less UTF-8 as ANSI.
- #>
- param(
- [string[]]$Agents,
- [string[]]$Path,
- [switch]$Yes,
- [switch]$DryRun,
- [switch]$Force,
- [switch]$Copy,
- [switch]$Docs,
- [switch]$NoDocs,
- [switch]$DocsOnly,
- [string]$Ref = $(if ($env:ROBLOX_SKILL_REF) { $env:ROBLOX_SKILL_REF } else { 'master' }),
- [string]$Source,
- [switch]$NoDedupe,
- [switch]$Update,
- [switch]$Uninstall,
- [switch]$PurgeDocs,
- [switch]$List,
- [switch]$Help
- )
- # Everything runs in a child scope: when piped into `iex` this script executes inside the user's
- # own session, so nothing -- preferences, functions, variables -- may leak into it, and nothing may
- # call `exit`, which would close their window.
- & {
- $ErrorActionPreference = 'Stop'
- $ProgressPreference = 'SilentlyContinue' # the 5.1 progress bar slows downloads dramatically
- $RepoOwner = 'MSayib'
- $RepoName = 'roblox-dev-skill'
- $SkillName = 'roblox-dev-skill' # must equal SKILL.md `name` and the folder name (agentskills.io)
- $Marker = '.roblox-dev-skill-install'
- $OnWindows = ($PSVersionTable.PSVersion.Major -lt 6) -or $IsWindows
- # ROBLOX_SKILL_HOME lets tests run against a throwaway profile ($HOME cannot be redirected in pwsh on Windows)
- if ($env:ROBLOX_SKILL_HOME) { $HomeDir = $env:ROBLOX_SKILL_HOME } else { $HomeDir = $HOME }
- $Stamp = Get-Date -Format 'yyyyMMdd-HHmmss'
- if ($env:ROBLOX_SKILL_STORE) { $Store = $env:ROBLOX_SKILL_STORE }
- elseif ($OnWindows) { $Store = Join-Path $env:LOCALAPPDATA $RepoName }
- elseif ($env:XDG_DATA_HOME) { $Store = Join-Path $env:XDG_DATA_HOME $RepoName }
- else { $Store = Join-Path (Join-Path (Join-Path $HomeDir '.local') 'share') $RepoName }
- $Payload = Join-Path $Store $SkillName
- $Manifest = Join-Path $Store 'manifest.tsv'
- if ($env:ROBLOX_DOCS_HOME) { $DocsHome = $env:ROBLOX_DOCS_HOME } else { $DocsHome = Join-Path $HomeDir 'RobloxDocs' }
- # ======================================================================
- # Output
- # ======================================================================
- function Say([string]$m) { Write-Host " $m" }
- function Ok([string]$m) { Write-Host ' [ok] ' -ForegroundColor Green -NoNewline; Write-Host $m }
- function Warn([string]$m) { Write-Host ' [!] ' -ForegroundColor Yellow -NoNewline; Write-Host $m }
- function Step([string]$m) { Write-Host ''; Write-Host "> $m" -ForegroundColor Cyan }
- function Dry([string]$m) { Write-Host ' [dry-run] ' -ForegroundColor Yellow -NoNewline; Write-Host $m }
- function Fail([string]$m) { throw "roblox-dev-skill installer: $m" }
- function P([string]$p) {
- if ($p -and $p.StartsWith($HomeDir, [StringComparison]::OrdinalIgnoreCase)) { return '~' + $p.Substring($HomeDir.Length) }
- return $p
- }
- function J { param([Parameter(ValueFromRemainingArguments = $true)][string[]]$parts)
- $r = $parts[0]; for ($i = 1; $i -lt $parts.Count; $i++) { $r = Join-Path $r $parts[$i] }; return $r }
- # ======================================================================
- # Agent registry -- every path verified against the agent's own docs on 2026-09-25.
- # ReadsUniversal: the agent documents ~/.agents/skills as a discovery path, so the one universal
- # link already covers it (a second link would list the skill twice).
- # ======================================================================
- function Under-Home([string]$rel) { Join-Path $HomeDir ($rel -replace '/', [IO.Path]::DirectorySeparatorChar) }
- function New-Agent($Id, $Label, $Rel, $ReadsUniversal, $Docs, $Cmd, $DetectRel) {
- [pscustomobject]@{ Id = $Id; Label = $Label; Dir = (Under-Home $Rel); ReadsUniversal = $ReadsUniversal
- Docs = $Docs; Cmd = $Cmd; DetectRel = $DetectRel }
- }
- $Registry = @(
- (New-Agent 'universal' 'Universal ~/.agents/skills' '.agents/skills' $false 'https://agentskills.io/client-implementation/adding-skills-support' $null '.agents'),
- (New-Agent 'claude' 'Claude Code' '.claude/skills' $false 'https://code.claude.com/docs/en/skills' 'claude' '.claude'),
- (New-Agent 'antigravity' 'Antigravity (2.0 / IDE)' '.gemini/config/skills' $false 'https://antigravity.google/docs/skills/' 'antigravity' '.gemini/config'),
- (New-Agent 'antigravity-cli' 'Antigravity CLI' '.gemini/antigravity-cli/skills' $false 'https://antigravity.google/docs/skills/' $null '.gemini/antigravity-cli'),
- (New-Agent 'kiro' 'Kiro' '.kiro/skills' $false 'https://kiro.dev/docs/skills/' 'kiro' '.kiro'),
- (New-Agent 'codex' 'Codex (OpenAI)' '.agents/skills' $true 'https://developers.openai.com/codex/skills/' 'codex' '.codex'),
- (New-Agent 'gemini' 'Gemini CLI' '.gemini/skills' $true 'https://geminicli.com/docs/cli/skills/' 'gemini' '.gemini/settings.json'),
- (New-Agent 'cursor' 'Cursor' '.cursor/skills' $true 'https://cursor.com/docs/context/skills' 'cursor' '.cursor'),
- (New-Agent 'copilot' 'GitHub Copilot (CLI / VS Code)' '.copilot/skills' $true 'https://docs.github.com/en/copilot/concepts/agents/about-agent-skills' 'copilot' '.copilot'),
- (New-Agent 'opencode' 'OpenCode' '.config/opencode/skills' $true 'https://opencode.ai/docs/skills/' 'opencode' '.config/opencode'),
- (New-Agent 'roo' 'Roo Code' '.roo/skills' $true 'https://docs.roocode.com/features/skills' $null '.roo'),
- (New-Agent 'goose' 'Goose' '.agents/skills' $true 'https://block.github.io/goose/docs/guides/context-engineering/using-skills/' 'goose' '.config/goose'),
- (New-Agent 'junie' 'Junie (JetBrains)' '.junie/skills' $true 'https://junie.jetbrains.com/docs/agent-skills.html' 'junie' '.junie'),
- (New-Agent 'amp' 'Amp' '.config/amp/skills' $true 'https://ampcode.com/docs/customize/skills' 'amp' '.config/amp')
- )
- $UniversalReaders = 'Codex, Gemini CLI, Cursor, GitHub Copilot, OpenCode, Roo Code, Goose, Junie, Amp'
- function Get-Agent([string]$id) { $Registry | Where-Object { $_.Id -eq $id } | Select-Object -First 1 }
- function Test-Detected($a) {
- if ($a.Cmd -and (Get-Command $a.Cmd -ErrorAction SilentlyContinue)) { return $true }
- return (Test-Path -LiteralPath (Under-Home $a.DetectRel))
- }
- function Get-DefaultSelection {
- $sel = @('universal')
- foreach ($id in 'claude', 'antigravity', 'antigravity-cli', 'kiro') {
- if (Test-Detected (Get-Agent $id)) { $sel += $id }
- }
- return $sel
- }
- function Resolve-Selection([string[]]$raw) {
- $out = @()
- foreach ($tok in (($raw -join ',') -split '[,\s]+')) {
- $t = $tok.Trim().ToLowerInvariant()
- if (-not $t) { continue }
- if ($t -eq 'all') { return @($Registry | ForEach-Object { $_.Id }) }
- if ($t -eq 'detected') { $out += Get-DefaultSelection; continue }
- if (-not (Get-Agent $t)) { Fail "unknown agent '$t'. Known: $(($Registry | ForEach-Object { $_.Id }) -join ', ') (or all, detected)" }
- $out += $t
- }
- return $out
- }
- function Resolve-Targets([string[]]$sel, [string[]]$custom) {
- $targets = New-Object System.Collections.ArrayList
- $seen = @{}
- $universalOn = ($sel -contains 'universal') -or ($sel -contains 'codex') -or ($sel -contains 'goose')
- foreach ($a in $Registry) {
- if ($sel -notcontains $a.Id) { continue }
- if ($universalOn -and -not $NoDedupe -and $a.ReadsUniversal -and ($a.Id -ne 'codex') -and ($a.Id -ne 'goose')) { continue }
- $k = $a.Dir.ToLowerInvariant()
- if ($seen.ContainsKey($k)) { continue }
- $seen[$k] = $true
- [void]$targets.Add([pscustomobject]@{ Label = $a.Label; Dir = $a.Dir })
- }
- foreach ($c in $custom) {
- if (-not $c) { continue }
- $d = Expand-UserPath $c
- $k = $d.ToLowerInvariant()
- if ($seen.ContainsKey($k)) { continue }
- $seen[$k] = $true
- [void]$targets.Add([pscustomobject]@{ Label = 'Custom'; Dir = $d })
- }
- return ,$targets.ToArray()
- }
- function Expand-UserPath([string]$p) {
- $p = $p.Trim().Trim('"')
- if ($p -eq '~') { $p = $HomeDir }
- elseif ($p.StartsWith('~/') -or $p.StartsWith('~\')) { $p = Join-Path $HomeDir $p.Substring(2) }
- $p = [IO.Path]::GetFullPath($p).TrimEnd('\', '/')
- # a path that already ends in the skill folder means "put it here", not "nest it again"
- if ((Split-Path $p -Leaf) -eq $SkillName) { $p = Split-Path $p -Parent }
- return $p
- }
- # ======================================================================
- # Wizard
- # ======================================================================
- function Test-Interactive {
- if ($Yes) { return $false }
- try { return [Environment]::UserInteractive -and -not [Console]::IsInputRedirected } catch { return $false }
- }
- function Invoke-Wizard {
- $sel = New-Object System.Collections.ArrayList
- foreach ($id in (Get-DefaultSelection)) { [void]$sel.Add($id) }
- $custom = ''
- while ($true) {
- Write-Host ''
- Write-Host 'Which agents should get the skill?' -ForegroundColor White -NoNewline
- Write-Host ' (* = found on this machine)' -ForegroundColor DarkGray
- Write-Host ''
- $i = 0
- foreach ($a in $Registry) {
- $i++
- if ($sel -contains $a.Id) { $box = '[x]'; $col = 'Green' } else { $box = '[ ]'; $col = 'Gray' }
- if (Test-Detected $a) { $det = ' *' } else { $det = '' }
- Write-Host (' {0} {1,2}) ' -f $box, $i) -ForegroundColor $col -NoNewline
- Write-Host ('{0,-32} ' -f $a.Label) -NoNewline
- Write-Host (P $a.Dir) -ForegroundColor DarkGray -NoNewline
- Write-Host $det -ForegroundColor Green
- if ($a.Id -eq 'universal') {
- Write-Host " read by $UniversalReaders" -ForegroundColor DarkGray
- Write-Host ''
- }
- }
- $i++
- if ($custom) { $box = '[x]'; $col = 'Green' } else { $box = '[ ]'; $col = 'Gray' }
- Write-Host (' {0} {1,2}) ' -f $box, $i) -ForegroundColor $col -NoNewline
- Write-Host ('{0,-32} {1}' -f 'Custom path...', $custom)
- Write-Host ''
- Write-Host ' Toggle by number (e.g. 2 3), a = all, n = none, Enter to continue.'
- $answer = Read-Host ' >' # not $input: that is PowerShell's automatic pipeline variable
- if (-not $answer) { break }
- foreach ($tok in ($answer -split '\s+')) {
- if (-not $tok) { continue }
- if ($tok -eq 'a') { $sel.Clear(); foreach ($a in $Registry) { [void]$sel.Add($a.Id) }; continue }
- if ($tok -eq 'n') { $sel.Clear(); $custom = ''; continue }
- $n = 0
- if (-not [int]::TryParse($tok, [ref]$n) -or $n -lt 1 -or $n -gt $i) { Warn "no option '$tok'"; continue }
- if ($n -eq $i) {
- if ($custom) { $custom = '' } else { $custom = Read-Host ' Skills directory (the folder that CONTAINS skill folders)' }
- continue
- }
- $id = $Registry[$n - 1].Id
- if ($sel -contains $id) { $sel.Remove($id) } else { [void]$sel.Add($id) }
- }
- }
- return [pscustomobject]@{ Selection = @($sel); Custom = $custom }
- }
- function Confirm-Choice([string]$q, [bool]$default = $true) {
- if (-not (Test-Interactive)) { return $default }
- if ($default) { $hint = '[Y/n]' } else { $hint = '[y/N]' }
- $ans = Read-Host "$q $hint"
- if (-not $ans) { return $default }
- return @('y', 'yes') -contains $ans.Trim().ToLowerInvariant()
- }
- # ======================================================================
- # Source
- # ======================================================================
- function Enable-Tls12 {
- try { [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12 } catch { }
- }
- function Get-Source([string]$work) {
- if ($Source) {
- if (-not (Test-Path -LiteralPath $Source -PathType Container)) { Fail "-Source: not a directory: $Source" }
- return (Resolve-Path -LiteralPath $Source).ProviderPath
- }
- Enable-Tls12
- $url = "https://codeload.github.com/$RepoOwner/$RepoName/zip/$Ref"
- $zip = Join-Path $work 'src.zip'
- Say "Downloading $RepoOwner/$RepoName@$Ref..."
- try { Invoke-WebRequest -Uri $url -OutFile $zip -UseBasicParsing }
- catch { Fail "download failed: $url (is -Ref '$Ref' a real branch or tag?) $($_.Exception.Message)" }
- $dest = Join-Path $work 'src'
- Expand-Archive -LiteralPath $zip -DestinationPath $dest -Force
- $top = @(Get-ChildItem -LiteralPath $dest -Directory)
- if ($top.Count -lt 1) { Fail 'the archive was empty' }
- return $top[0].FullName
- }
- function Test-Source([string]$src) {
- $skill = Join-Path $src 'SKILL.md'
- if (-not (Test-Path -LiteralPath $skill)) { Fail "no SKILL.md in $src -- not a $RepoName checkout" }
- if (-not (Test-Path -LiteralPath (Join-Path $src 'references'))) { Fail "no references\ in $src" }
- $line = Get-Content -LiteralPath $skill -TotalCount 15 | Where-Object { $_ -match '^name:\s*' } | Select-Object -First 1
- $name = ($line -replace '^name:\s*', '').Trim().Trim('"', "'")
- if ($name -ne $SkillName) { Fail "SKILL.md name is '$name', expected '$SkillName'" }
- }
- function Get-SkillVersion([string]$src) {
- try { return (Get-Content -LiteralPath (Join-Path $src 'metadata.json') -Raw | ConvertFrom-Json).version } catch { return 'unknown' }
- }
- # ======================================================================
- # Links -- never Remove-Item -Recurse a link: on 5.1 that can delete the TARGET's contents.
- # ======================================================================
- function Get-Entry([string]$p) {
- $item = Get-Item -LiteralPath $p -Force -ErrorAction SilentlyContinue
- if ($item) { return $item }
- return $null
- }
- function Get-LinkTarget($item) {
- if (-not $item -or -not $item.LinkType) { return $null }
- $t = @($item.Target)[0]
- if ($t) { $t = $t -replace '^\\\\\?\\', '' }
- return $t
- }
- function Test-SamePath([string]$a, [string]$b) {
- if (-not $a -or -not $b) { return $false }
- $a = $a.TrimEnd('\', '/'); $b = $b.TrimEnd('\', '/')
- if ($OnWindows) { return [string]::Equals($a, $b, [StringComparison]::OrdinalIgnoreCase) }
- return $a -ceq $b
- }
- function Remove-Link([string]$p) {
- if ($OnWindows) { [IO.Directory]::Delete($p, $false) } # removes the reparse point only
- else { [IO.File]::Delete($p) } # unlink(2): removes the symlink only
- }
- function Backup-Entry([string]$dest) {
- $rel = (Split-Path $dest -Parent) -replace '[:\\/]+', '_'
- $bdir = J $Store 'backups' $Stamp $rel
- if ($DryRun) { Dry "back up existing $dest -> $bdir"; return }
- New-Item -ItemType Directory -Force -Path $bdir | Out-Null
- $item = Get-Entry $dest
- if ($item.LinkType) {
- # record where the link pointed, then remove only the link
- Set-Content -LiteralPath (Join-Path $bdir "$(Split-Path $dest -Leaf).link.txt") -Value (Get-LinkTarget $item)
- Remove-Link $dest
- } else {
- Move-Item -LiteralPath $dest -Destination $bdir
- }
- Warn "existing $(P $dest) moved to $(P $bdir)"
- }
- function Add-Manifest([string]$mode, [string]$p) {
- if ($DryRun) { return }
- New-Item -ItemType Directory -Force -Path $Store | Out-Null
- $lines = @()
- if (Test-Path -LiteralPath $Manifest) { $lines = @(Get-Content -LiteralPath $Manifest | Where-Object { $_ -and ($_ -ne "$mode`t$p") }) }
- $lines += "$mode`t$p"
- Set-Content -LiteralPath $Manifest -Value $lines
- }
- function Install-Link([string]$dir) {
- $dest = Join-Path $dir $SkillName
- $item = Get-Entry $dest
- if ($item -and $item.LinkType) {
- $target = Get-LinkTarget $item
- if (Test-SamePath $target $Payload) { Ok "$(P $dest) (already linked)"; Add-Manifest 'link' $dest; return }
- if (-not $Force) { Warn "$(P $dest) is a link to $target -- left untouched (use -Force to replace)"; return }
- Backup-Entry $dest
- } elseif ($item) {
- if (Test-Path -LiteralPath (Join-Path $dest $Marker)) {
- if ($DryRun) { Dry "refresh managed copy $dest"; return }
- Remove-Item -LiteralPath $dest -Recurse -Force # a real directory we made, not a link
- } else {
- Backup-Entry $dest
- }
- }
- if ($DryRun) { Dry "link $dest -> $Payload"; return }
- New-Item -ItemType Directory -Force -Path $dir | Out-Null
- # ROBLOX_SKILL_LINK = symlink | junction | copy pins the method (default: try them in that order)
- $mode = "$env:ROBLOX_SKILL_LINK".ToLowerInvariant()
- if ($Copy) { $mode = 'copy' }
- if ($mode -ne 'copy') {
- if ($mode -ne 'junction') {
- try {
- New-Item -ItemType SymbolicLink -Path $dest -Target $Payload | Out-Null
- Ok "$(P $dest) -> store (symlink)"; Add-Manifest 'link' $dest; return
- } catch { }
- }
- if ($OnWindows) {
- # junctions need no admin rights or Developer Mode
- try {
- New-Item -ItemType Junction -Path $dest -Target $Payload | Out-Null
- Ok "$(P $dest) -> store (junction)"; Add-Manifest 'link' $dest; return
- } catch { }
- }
- }
- Copy-Item -LiteralPath $Payload -Destination $dest -Recurse
- Ok "$(P $dest) (copy -- re-run with -Update after upgrades)"
- Add-Manifest 'copy' $dest
- }
- function Install-Payload([string]$src, [string]$version) {
- Step "Installing skill into $(P $Payload)"
- if ($DryRun) { Dry "copy SKILL.md, metadata.json, references\ ... -> $Payload"; return }
- New-Item -ItemType Directory -Force -Path $Store | Out-Null
- $new = Join-Path $Store ".new.$PID"; $old = Join-Path $Store ".old.$PID"
- if (Test-Path -LiteralPath $new) { Remove-Item -LiteralPath $new -Recurse -Force }
- New-Item -ItemType Directory -Path $new | Out-Null
- foreach ($f in 'SKILL.md', 'metadata.json', 'LICENSE', 'README.md', 'CHANGELOG.md') {
- $p = Join-Path $src $f
- if (Test-Path -LiteralPath $p) { Copy-Item -LiteralPath $p -Destination $new }
- }
- Copy-Item -LiteralPath (Join-Path $src 'references') -Destination (Join-Path $new 'references') -Recurse
- # docs\ holds the pages README.md links to (absent in versions before 2.16.0)
- $docs = Join-Path $src 'docs'
- if (Test-Path -LiteralPath $docs) { Copy-Item -LiteralPath $docs -Destination (Join-Path $new 'docs') -Recurse }
- Set-Content -LiteralPath (Join-Path $new $Marker) -Value @("managed-by=$RepoName install.ps1", "version=$version", "installed=$Stamp")
- # swap in place: links point at $Payload, so they follow the new content automatically
- try {
- if (Test-Path -LiteralPath $Payload) { Rename-Item -LiteralPath $Payload -NewName (Split-Path $old -Leaf) }
- Rename-Item -LiteralPath $new -NewName $SkillName
- } catch {
- Fail "could not replace $Payload -- is an agent holding a file open? Close it and retry. ($($_.Exception.Message))"
- }
- if (Test-Path -LiteralPath $old) { Remove-Item -LiteralPath $old -Recurse -Force }
- $me = Join-Path $src 'install.ps1'
- if (Test-Path -LiteralPath $me) { Copy-Item -LiteralPath $me -Destination (Join-Path $Store 'install.ps1') -Force }
- Ok "Skill v$version stored"
- }
- function Warn-Legacy($targets) {
- $claudeDir = (Get-Agent 'claude').Dir
- if (-not ($targets | Where-Object { Test-SamePath $_.Dir $claudeDir })) { return }
- $legacy = Join-Path $claudeDir 'roblox-dev'
- $item = Get-Entry $legacy
- if (-not $item) { return }
- $skill = Join-Path $legacy 'SKILL.md'
- if (-not ((Test-Path -LiteralPath $skill) -and (Select-String -LiteralPath $skill -Pattern "^name: $SkillName" -Quiet))) { return }
- if ($item.LinkType) {
- Warn "$(P $legacy) also points to this skill (old folder name) -- Claude Code will list it twice."
- } else {
- Backup-Entry $legacy
- Say "that was an old install under the non-standard name 'roblox-dev'; the spec requires the folder to match the skill name"
- }
- }
- # ======================================================================
- # RobloxDocs
- # ======================================================================
- function Find-Python {
- foreach ($cand in @(@('py', '-3'), @('python'), @('python3'))) {
- if (-not (Get-Command $cand[0] -ErrorAction SilentlyContinue)) { continue }
- $pyArgs = @($cand | Select-Object -Skip 1)
- try {
- $oldEap = $ErrorActionPreference; $ErrorActionPreference = 'Continue'
- try { & $cand[0] @pyArgs -c 'import sys; sys.exit(0 if sys.version_info >= (3, 6) else 1)' 2>$null | Out-Null }
- finally { $ErrorActionPreference = $oldEap }
- if ($LASTEXITCODE -eq 0) { return , $cand } # `python3` on Windows is often a Store stub that fails here
- } catch { }
- }
- return $null
- }
- function Install-Docs([string]$src) {
- Step "Setting up $(P $DocsHome)"
- $py = Find-Python
- if (-not $py) {
- Warn 'Python 3 not found -- skipping RobloxDocs. The skill works without it, using web docs.'
- Say "Install Python 3 (https://www.python.org/downloads/), then run: & `"$(Join-Path $Store 'install.ps1')`" -DocsOnly"
- return
- }
- $tools = J $src 'tools' 'robloxdocs'
- if (-not (Test-Path -LiteralPath $tools)) { Warn 'this version has no tools\robloxdocs -- skipping'; return }
- if ($DryRun) { Dry "install scripts -> $DocsHome\scripts and run roblox-api-monitor.py"; return }
- $scripts = Join-Path $DocsHome 'scripts'
- New-Item -ItemType Directory -Force -Path $scripts | Out-Null
- $bdir = $null
- foreach ($f in @(Get-ChildItem -LiteralPath $tools -File | Where-Object { $_.Extension -in '.py', '.sh' })) {
- $dest = Join-Path $scripts $f.Name
- if ((Test-Path -LiteralPath $dest) -and ((Get-FileHash -LiteralPath $dest).Hash -ne (Get-FileHash -LiteralPath $f.FullName).Hash)) {
- if (-not $bdir) { $bdir = Join-Path $scripts ".backup-$Stamp"; New-Item -ItemType Directory -Force -Path $bdir | Out-Null }
- Copy-Item -LiteralPath $dest -Destination $bdir
- }
- Copy-Item -LiteralPath $f.FullName -Destination $dest -Force
- }
- if ($bdir) { Say "your previous scripts were different -- kept a copy in $(P $bdir)" }
- $readme = Join-Path $DocsHome 'README.md'
- if (-not (Test-Path -LiteralPath $readme)) { Copy-Item -LiteralPath (Join-Path $tools 'README.md') -Destination $readme }
- $cfg = Join-Path $DocsHome 'config'
- if (-not (Test-Path -LiteralPath $cfg)) {
- Set-Content -LiteralPath $cfg -Value @('# RobloxDocs configuration -- KEY=VALUE, parsed (never executed)',
- "SKILL_REFS=$(Join-Path $Payload 'references')", 'AUDIT_MODE=warn')
- } else { Say "kept your existing $(P $cfg)" }
- Ok 'Scripts installed'
- Step 'Downloading and splitting the Roblox API dump (one-time, ~8 MB)'
- $oldHome = $env:ROBLOX_DOCS_HOME; $oldEnc = $env:PYTHONIOENCODING
- $env:ROBLOX_DOCS_HOME = $DocsHome; $env:PYTHONIOENCODING = 'utf-8'
- # Windows PowerShell 5.1 turns a native program's stderr into error records when output is
- # redirected, and under 'Stop' the first Python warning would abort the whole installer.
- $oldEap = $ErrorActionPreference; $ErrorActionPreference = 'Continue'
- try {
- $pyArgs = @($py | Select-Object -Skip 1)
- & $py[0] @pyArgs (Join-Path $scripts 'roblox-api-monitor.py')
- $code = $LASTEXITCODE
- } finally { $env:ROBLOX_DOCS_HOME = $oldHome; $env:PYTHONIOENCODING = $oldEnc; $ErrorActionPreference = $oldEap }
- if ($code -eq 0) { Ok 'RobloxDocs ready' }
- else {
- Warn 'the API dump step did not finish -- the skill is installed and works without it.'
- Say "Retry any time: python `"$(Join-Path $scripts 'roblox-api-monitor.py')`""
- }
- }
- # ======================================================================
- # Uninstall
- # ======================================================================
- function Invoke-Uninstall {
- Step "Uninstalling $SkillName"
- $removed = 0
- if (Test-Path -LiteralPath $Manifest) {
- foreach ($line in @(Get-Content -LiteralPath $Manifest)) {
- if (-not $line) { continue }
- $mode, $p = $line -split "`t", 2
- $item = Get-Entry $p
- if (-not $item) { continue }
- if ($item.LinkType -and (Test-SamePath (Get-LinkTarget $item) $Payload)) {
- if ($DryRun) { Dry "remove link $p" } else { Remove-Link $p; Ok "removed $(P $p)" }; $removed++
- } elseif (-not $item.LinkType -and (Test-Path -LiteralPath (Join-Path $p $Marker))) {
- if ($DryRun) { Dry "remove copy $p" } else { Remove-Item -LiteralPath $p -Recurse -Force; Ok "removed $(P $p)" }; $removed++
- } else {
- Warn "$(P $p) is no longer ours -- left untouched"
- }
- }
- } else { Say "no manifest at $(P $Manifest)" }
- foreach ($p in $Payload, $Manifest, (Join-Path $Store 'install.ps1')) {
- if (Test-Path -LiteralPath $p) { if ($DryRun) { Dry "remove $p" } else { Remove-Item -LiteralPath $p -Recurse -Force } }
- }
- Ok "removed $removed agent link(s) and the stored skill"
- if (Test-Path -LiteralPath (Join-Path $Store 'backups')) { Say "backups of anything replaced during install are kept in $(P (Join-Path $Store 'backups'))" }
- if ($PurgeDocs -and (Test-Path -LiteralPath $DocsHome)) {
- if ((Test-Interactive) -and (Confirm-Choice "Delete $(P $DocsHome) including every downloaded API dump?" $false)) {
- foreach ($sub in 'RobloxAPI', 'scripts', 'config') {
- $p = Join-Path $DocsHome $sub
- if (Test-Path -LiteralPath $p) { if ($DryRun) { Dry "remove $p" } else { Remove-Item -LiteralPath $p -Recurse -Force } }
- }
- Ok "removed RobloxAPI\, scripts\ and config from $(P $DocsHome)"
- } else { Say "nothing deleted from $(P $DocsHome) (purging always asks first)" }
- } elseif (Test-Path -LiteralPath $DocsHome) { Say "$(P $DocsHome) was kept. Add -PurgeDocs to remove it too." }
- }
- # ======================================================================
- # Main
- # ======================================================================
- function Show-Help {
- @"
- roblox-dev-skill installer (PowerShell)
- irm https://raw.githubusercontent.com/$RepoOwner/$RepoName/master/install.ps1 | iex
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 520 on GitHub
- & ([scriptblock]::Create((irm https://raw.githubusercontent.com/$RepoOwner/$RepoName/master/install.ps1))) [options]
- -Agents a,b agent ids, 'detected' or 'all':
- $(($Registry | ForEach-Object { $_.Id }) -join ', ')
- -Path DIR also install into DIR (a folder that CONTAINS skill folders)
- -List show every supported agent and its skills folder
- -Yes no questions; use -Agents or the detected defaults
- -DryRun show what would change, change nothing
- -Copy copy instead of symlink/junction
- -Force replace an existing link that points elsewhere (it is backed up)
- -Ref REF branch or tag (default master) -Source DIR install from a local checkout
- -Docs/-NoDocs set up ~\RobloxDocs or skip it -DocsOnly only (re)install RobloxDocs
- -NoDedupe also link agents that already read ~/.agents/skills
- -Update fetch the latest skill; links follow automatically
- -Uninstall remove what this installer made -PurgeDocs also delete RobloxDocs data (asks)
- Environment (useful with `irm | iex`, which cannot take options):
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 537 on GitHub
- ROBLOX_SKILL_REF=TAG install that branch or tag instead of master
- ROBLOX_SKILL_LINK=MODE symlink, junction or copy
- "@ | Write-Host
- }
- function Show-List {
- Write-Host ''
- Write-Host ('{0,-16} {1,-32} {2,-38} {3}' -f 'ID', 'AGENT', 'USER SKILLS DIR', 'DETECTED')
- foreach ($a in $Registry) {
- if (Test-Detected $a) { $d = 'yes' } else { $d = '-' }
- Write-Host ('{0,-16} {1,-32} {2,-38} {3}' -f $a.Id, $a.Label, (P $a.Dir), $d)
- }
- Write-Host ''
- Write-Host "Paths verified against each agent's documentation (2026-09-25):"
- foreach ($a in $Registry) { Write-Host (' {0,-16} {1}' -f $a.Id, $a.Docs) }
- Write-Host ''
- }
- function Invoke-Main {
- if ($Help) { Show-Help; return }
- if ($List) { Show-List; return }
- Write-Host ''
- Write-Host ' roblox-dev-skill installer ' -ForegroundColor White
- Write-Host " Roblox & Luau knowledge for AI coding agents -- https://github.com/$RepoOwner/$RepoName" -ForegroundColor DarkGray
- if ($DryRun) { Write-Host ''; Write-Host ' DRY RUN -- nothing will be changed' -ForegroundColor Yellow }
- Say ("PowerShell {0} on {1}" -f $PSVersionTable.PSVersion, $(if ($OnWindows) { 'Windows' } else { [Environment]::OSVersion.Platform }))
- if ($Uninstall) { Invoke-Uninstall; return }
- $work = Join-Path ([IO.Path]::GetTempPath()) ("rds-install-" + [guid]::NewGuid().ToString('N'))
- New-Item -ItemType Directory -Path $work | Out-Null
- try {
- $src = Get-Source $work
- Test-Source $src
- $version = Get-SkillVersion $src
- if ($Source) { $from = 'local source' } else { $from = "ref $Ref" }
- Ok "Skill $SkillName v$version ($from)"
- if ($DocsOnly) { Install-Docs $src; return }
- $custom = @($Path)
- if ($Update) {
- $targets = @()
- if (Test-Path -LiteralPath $Manifest) {
- $targets = @(Get-Content -LiteralPath $Manifest | Where-Object { $_ } | ForEach-Object {
- [pscustomobject]@{ Label = 'Previous'; Dir = (Split-Path (($_ -split "`t", 2)[1]) -Parent) } })
- }
- if ($targets.Count -eq 0) { Fail "nothing to update: no previous install found in $Manifest" }
- $wantDocs = Test-Path -LiteralPath (J $DocsHome 'scripts' 'roblox-api-monitor.py')
- } else {
- if ($Agents) { $sel = Resolve-Selection $Agents }
- elseif (Test-Interactive) {
- $w = Invoke-Wizard
- $sel = $w.Selection
- if ($w.Custom) { $custom += $w.Custom }
- } else {
- $sel = Get-DefaultSelection
- Say "Non-interactive run: using detected defaults ($($sel -join ','))."
- }
- $targets = Resolve-Targets $sel $custom
- if ($targets.Count -eq 0) { Fail 'no agents selected -- nothing to install' }
- if ($Docs) { $wantDocs = $true }
- elseif ($NoDocs) { $wantDocs = $false }
- elseif (Test-Interactive) { $wantDocs = Confirm-Choice 'Also set up ~\RobloxDocs (downloads the ~8 MB Roblox API dump; needs Python 3)?' $true }
- else { $wantDocs = $true }
- }
- Step 'Plan'
- Say "Skill store: $(P $Payload)"
- foreach ($t in $targets) { Write-Host (' -> {0,-26} {1}' -f $t.Label, (P (Join-Path $t.Dir $SkillName))) }
- if ($targets | Where-Object { $_.Dir -like '*.agents*skills' }) { Say "~/.agents/skills is read by $UniversalReaders" }
- if ($wantDocs) { Say "RobloxDocs: $(P $DocsHome)" } else { Say 'RobloxDocs: skipped' }
- if (-not $Update -and (Test-Interactive)) {
- if (-not (Confirm-Choice 'Proceed?' $true)) { Say 'Cancelled -- nothing was changed.'; return }
- }
- Install-Payload $src $version
- foreach ($t in $targets) { Install-Link $t.Dir }
- Warn-Legacy $targets
- if ($wantDocs) { Install-Docs $src }
- Step 'Done'
- Say "Installed $SkillName v$version."
- Say 'Restart your agent(s) so they rescan their skills folders.'
- Write-Host ''
- Say "Update & ([scriptblock]::Create((irm https://raw.githubusercontent.com/$RepoOwner/$RepoName/master/install.ps1))) -Update"
- Say "Uninstall & `"$(Join-Path $Store 'install.ps1')`" -Uninstall" # absolute: a pasted ~ is not reliably expanded
- Write-Host ''
- } finally {
- Remove-Item -LiteralPath $work -Recurse -Force -ErrorAction SilentlyContinue
- }
- }
- try {
- Invoke-Main
- } catch {
- Write-Host ''
- Write-Host " [x] $($_.Exception.Message)" -ForegroundColor Red
- Write-Host ''
- # Only a dedicated process (install.cmd) may set an exit code; `iex` must never close the window.
- if ($env:ROBLOX_SKILL_EXIT_ON_ERROR -eq '1') { exit 1 }
- }
- }
install.sh · Bundled script · 745 lines · 3 findings marked
- #!/usr/bin/env bash
- # roblox-dev-skill installer — https://github.com/MSayib/roblox-dev-skill
- #
- # curl -fsSL https://raw.githubusercontent.com/MSayib/roblox-dev-skill/master/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 4 on GitHub
- #
- # Installs the skill once and links it into every agent you pick, then (optionally) sets up
- # ~/RobloxDocs with a freshly downloaded and split Roblox API dump. No git clone needed.
- #
- # Works with bash 3.2+ (macOS default), on macOS, Linux, WSL and Git Bash for Windows.
- # Needs: curl or wget, tar. RobloxDocs additionally needs python3.
- #
- # Run with --help for every option.
- # Everything lives inside main(), which is only called on the very last line. If the download is
- # cut off halfway, bash sees an unterminated function and runs nothing.
- REPO_OWNER="MSayib"
- REPO_NAME="roblox-dev-skill"
- SKILL_NAME="roblox-dev-skill" # must equal the SKILL.md `name` and the folder name (agentskills.io spec)
- DEFAULT_REF="master"
- MARKER=".roblox-dev-skill-install" # present in every copy this installer makes; nothing else is ever removed
- TAB="$(printf '\t')"
- main() {
- set -Eeuo pipefail
- # Never die silently: any unexpected failure names the line and the command.
- trap 'die "unexpected failure at line $LINENO: $BASH_COMMAND"' ERR
- # ─── Options ────────────────────────────────────────────────────────────
- local REF="${ROBLOX_SKILL_REF:-$DEFAULT_REF}" SOURCE_DIR="" AGENTS_ARG="" CUSTOM_PATHS="" YES=false DRY=false
- local FORCE=false FORCE_COPY=false DOCS_MODE=ask ACTION=install PURGE_DOCS=false NO_DEDUPE=false
- if [ "${ROBLOX_SKILL_LINK:-}" = copy ]; then FORCE_COPY=true; fi
- while [ $# -gt 0 ]; do
- case "$1" in
- --agents) AGENTS_ARG="$2"; shift 2 ;;
- --agents=*) AGENTS_ARG="${1#*=}"; shift ;;
- --path) CUSTOM_PATHS="$CUSTOM_PATHS$2"$'\n'; shift 2 ;;
- --path=*) CUSTOM_PATHS="$CUSTOM_PATHS${1#*=}"$'\n'; shift ;;
- -y|--yes) YES=true; shift ;;
- --dry-run) DRY=true; shift ;;
- --force) FORCE=true; shift ;;
- --copy) FORCE_COPY=true; shift ;;
- --docs) DOCS_MODE=yes; shift ;;
- --no-docs) DOCS_MODE=no; shift ;;
- --docs-only) ACTION=docs-only; DOCS_MODE=yes; shift ;;
- --ref) REF="$2"; shift 2 ;;
- --ref=*) REF="${1#*=}"; shift ;;
- --source) SOURCE_DIR="$2"; shift 2 ;;
- --source=*) SOURCE_DIR="${1#*=}"; shift ;;
- --no-dedupe) NO_DEDUPE=true; shift ;;
- --update) ACTION=update; shift ;;
- --uninstall) ACTION=uninstall; shift ;;
- --purge-docs) PURGE_DOCS=true; shift ;;
- --list) ACTION=list; shift ;;
- -h|--help) usage; return 0 ;;
- *) die "unknown option: $1 (try --help)" ;;
- esac
- done
- # ─── Paths ──────────────────────────────────────────────────────────────
- STORE="${ROBLOX_SKILL_STORE:-${XDG_DATA_HOME:-$HOME/.local/share}/$REPO_NAME}"
- PAYLOAD="$STORE/$SKILL_NAME"
- MANIFEST="$STORE/manifest.tsv"
- DOCS_HOME="${ROBLOX_DOCS_HOME:-$HOME/RobloxDocs}"
- STAMP="$(date +%Y%m%d-%H%M%S)"
- TTY_OK=false
- if [ "$YES" = false ] && { : </dev/tty; } 2>/dev/null; then TTY_OK=true; fi
- setup_colors
- case "$ACTION" in
- list) list_agents; return 0 ;;
- uninstall) do_uninstall; return 0 ;;
- esac
- banner
- preflight
- local SRC
- WORK="$(mktemp -d "${TMPDIR:-/tmp}/rds-install.XXXXXX")"
- trap 'rm -rf "${WORK:-}"' EXIT
- SRC="$(obtain_source "$WORK")"
- validate_source "$SRC"
- local VERSION; VERSION="$(skill_version "$SRC")"
- ok "Skill $SKILL_NAME v$VERSION ($( [ -n "$SOURCE_DIR" ] && echo "local source" || echo "ref $REF"))"
- if [ "$ACTION" = docs-only ]; then
- install_docs "$SRC"
- return 0
- fi
- # ─── Choose targets ─────────────────────────────────────────────────────
- local SELECTED
- if [ "$ACTION" = update ]; then
- SELECTED="" # update re-uses the manifest; no agent selection
- elif [ -n "$AGENTS_ARG" ]; then
- SELECTED="$(parse_agents_arg "$AGENTS_ARG")"
- elif [ "$TTY_OK" = true ]; then
- SELECTED="$(wizard)"
- case "$SELECTED" in *"@custom:"*)
- CUSTOM_PATHS="$CUSTOM_PATHS${SELECTED#*@custom:}"$'\n'
- SELECTED="${SELECTED%%@custom:*}" ;;
- esac
- else
- SELECTED="$(default_selection)"
- if [ -n "$SELECTED" ]; then
- info "Non-interactive run: using detected defaults ($(echo $SELECTED | tr ' ' ','))."
- fi
- fi
- if [ "$DOCS_MODE" = ask ] && [ "$ACTION" = update ]; then
- # an update refreshes RobloxDocs only if it was set up before
- if [ -f "$DOCS_HOME/scripts/roblox-api-monitor.sh" ]; then DOCS_MODE=yes; else DOCS_MODE=no; fi
- fi
- if [ "$DOCS_MODE" = ask ]; then
- if [ "$TTY_OK" = true ]; then
- if confirm "Also set up ~/RobloxDocs (downloads the ~8 MB Roblox API dump; needs python3)?" y; then
- DOCS_MODE=yes; else DOCS_MODE=no; fi
- else
- DOCS_MODE=yes
- fi
- fi
- local TARGETS
- if [ "$ACTION" = update ]; then
- TARGETS="$(manifest_targets)"
- [ -n "$TARGETS" ] || die "nothing to update: no previous install found in $MANIFEST"
- else
- TARGETS="$(resolve_targets "$SELECTED" "$CUSTOM_PATHS")"
- [ -n "$TARGETS" ] || die "no agents selected — nothing to install"
- fi
- plan_summary "$TARGETS"
- if [ "$TTY_OK" = true ] && [ "$ACTION" != update ]; then
- confirm "Proceed?" y || { info "Cancelled — nothing was changed."; return 0; }
- fi
- # ─── Install ────────────────────────────────────────────────────────────
- install_payload "$SRC" "$VERSION"
- local line dir
- while IFS= read -r line; do
- [ -n "$line" ] || continue
- dir="${line#*$TAB}"
- link_into "$dir"
- done <<EOF
- $TARGETS
- EOF
- warn_legacy_installs "$TARGETS"
- if [ "$DOCS_MODE" = yes ]; then install_docs "$SRC"; fi
- finish "$TARGETS" "$VERSION"
- }
- # ════════════════════════════════════════════════════════════════════════
- # Agent registry. Every path below was checked against that agent's own documentation on
- # 2026-09-25 — see the URL in agent_docs. "Reads ~/.agents/skills" is what lets one install cover
- # many agents; agents that do NOT read it need their own link.
- # ════════════════════════════════════════════════════════════════════════
- AGENT_IDS="universal claude antigravity antigravity-cli kiro codex gemini cursor copilot opencode roo goose junie amp"
- agent_label() {
- case "$1" in
- universal) echo "Universal ~/.agents/skills" ;;
- claude) echo "Claude Code" ;;
- antigravity) echo "Antigravity (2.0 / IDE)" ;;
- antigravity-cli) echo "Antigravity CLI" ;;
- kiro) echo "Kiro" ;;
- codex) echo "Codex (OpenAI)" ;;
- gemini) echo "Gemini CLI" ;;
- cursor) echo "Cursor" ;;
- copilot) echo "GitHub Copilot (CLI / VS Code)" ;;
- opencode) echo "OpenCode" ;;
- roo) echo "Roo Code" ;;
- goose) echo "Goose" ;;
- junie) echo "Junie (JetBrains)" ;;
- amp) echo "Amp" ;;
- esac
- }
- agent_dir() {
- case "$1" in
- universal|codex|goose) echo "$HOME/.agents/skills" ;;
- claude) echo "$HOME/.claude/skills" ;;
- antigravity) echo "$HOME/.gemini/config/skills" ;;
- antigravity-cli) echo "$HOME/.gemini/antigravity-cli/skills" ;;
- kiro) echo "$HOME/.kiro/skills" ;;
- gemini) echo "$HOME/.gemini/skills" ;;
- cursor) echo "$HOME/.cursor/skills" ;;
- copilot) echo "$HOME/.copilot/skills" ;;
- opencode) echo "$HOME/.config/opencode/skills" ;;
- roo) echo "$HOME/.roo/skills" ;;
- junie) echo "$HOME/.junie/skills" ;;
- amp) echo "$HOME/.config/amp/skills" ;;
- esac
- }
- agent_docs() {
- case "$1" in
- universal) echo "https://agentskills.io/client-implementation/adding-skills-support" ;;
- claude) echo "https://code.claude.com/docs/en/skills" ;;
- antigravity|antigravity-cli) echo "https://antigravity.google/docs/skills/" ;;
- kiro) echo "https://kiro.dev/docs/skills/" ;;
- codex) echo "https://developers.openai.com/codex/skills/" ;;
- gemini) echo "https://geminicli.com/docs/cli/skills/" ;;
- cursor) echo "https://cursor.com/docs/context/skills" ;;
- copilot) echo "https://docs.github.com/en/copilot/concepts/agents/about-agent-skills" ;;
- opencode) echo "https://opencode.ai/docs/skills/" ;;
- roo) echo "https://docs.roocode.com/features/skills" ;;
- goose) echo "https://block.github.io/goose/docs/guides/context-engineering/using-skills/" ;;
- junie) echo "https://junie.jetbrains.com/docs/agent-skills.html" ;;
- amp) echo "https://ampcode.com/docs/customize/skills" ;;
- esac
- }
- # Agents whose documented discovery path includes ~/.agents/skills.
- agent_reads_universal() {
- case "$1" in codex|gemini|cursor|copilot|opencode|roo|goose|junie|amp) return 0 ;; *) return 1 ;; esac
- }
- UNIVERSAL_READERS="Codex, Gemini CLI, Cursor, GitHub Copilot, OpenCode, Roo Code, Goose, Junie, Amp"
- have() { command -v "$1" >/dev/null 2>&1; }
- # Detection only drives the default selection. Being wrong costs a checkbox, nothing else.
- agent_detected() {
- case "$1" in
- universal) [ -d "$HOME/.agents" ] ;;
- claude) have claude || [ -d "$HOME/.claude" ] ;;
- antigravity) [ -d "$HOME/.gemini/config" ] || [ -d "/Applications/Antigravity.app" ] || have antigravity ;;
- antigravity-cli) [ -d "$HOME/.gemini/antigravity-cli" ] ;;
- kiro) have kiro || [ -d "$HOME/.kiro" ] ;;
- codex) have codex || [ -d "$HOME/.codex" ] ;;
- gemini) have gemini || [ -f "$HOME/.gemini/settings.json" ] ;;
- cursor) have cursor || [ -d "$HOME/.cursor" ] ;;
- copilot) have copilot || [ -d "$HOME/.copilot" ] ;;
- opencode) have opencode || [ -d "$HOME/.config/opencode" ] ;;
- roo) [ -d "$HOME/.roo" ] ;;
- goose) have goose || [ -d "$HOME/.config/goose" ] ;;
- junie) have junie || [ -d "$HOME/.junie" ] ;;
- amp) have amp || [ -d "$HOME/.config/amp" ] ;;
- *) return 1 ;;
- esac
- }
- is_agent_id() { case " $AGENT_IDS " in *" $1 "*) return 0 ;; *) return 1 ;; esac; }
- in_list() { case " $2 " in *" $1 "*) return 0 ;; *) return 1 ;; esac; }
- # Universal covers nine agents in one link; add a native link only for detected agents that
- # do not read it.
- default_selection() {
- local sel="universal" id
- for id in claude antigravity antigravity-cli kiro; do
- if agent_detected "$id"; then sel="$sel $id"; fi
- done
- echo "$sel"
- }
- parse_agents_arg() {
- local raw id out=""
- raw="$(echo "$1" | tr ',' ' ' | tr 'A-Z' 'a-z')"
- for id in $raw; do
- case "$id" in
- all) out="$AGENT_IDS"; break ;;
- detected) out="$out $(default_selection)" ;;
- *) is_agent_id "$id" || die "unknown agent '$id'. Known: $AGENT_IDS (or all, detected)"
- out="$out $id" ;;
- esac
- done
- echo $out
- }
- # Turn a selection into "label<TAB>dir" lines: deduplicated by directory, and — unless
- # --no-dedupe — dropping agents already covered by ~/.agents/skills (otherwise they list the
- # skill twice).
- resolve_targets() {
- local sel="$1" custom="$2" id dir out="" seen=" " p
- local universal_on=false
- if in_list universal "$sel" || in_list codex "$sel" || in_list goose "$sel"; then universal_on=true; fi
- for id in $AGENT_IDS; do
- in_list "$id" "$sel" || continue
- if [ "$universal_on" = true ] && [ "$NO_DEDUPE" = false ] && [ "$id" != universal ] \
- && [ "$id" != codex ] && [ "$id" != goose ] && agent_reads_universal "$id"; then
- continue
- fi
- dir="$(agent_dir "$id")"
- case "$seen" in *" $dir "*) continue ;; esac
- seen="$seen$dir "
- out="$out$(agent_label "$id")$TAB$dir"$'\n'
- done
- while IFS= read -r p; do
- [ -n "$p" ] || continue
- p="$(expand_path "$p")"
- case "$seen" in *" $p "*) continue ;; esac
- seen="$seen$p "
- out="${out}Custom$TAB$p"$'\n'
- done <<EOF
- $custom
- EOF
- printf '%s' "$out"
- }
- expand_path() {
- local p="$1"
- # a literal "~" typed by the user (quoted, so the shell did not expand it) — matched on purpose
- # shellcheck disable=SC2088
- case "$p" in "~") p="$HOME" ;; "~/"*) p="$HOME/${p#\~/}" ;; esac
- case "$p" in /*|[A-Za-z]:*) ;; *) p="$PWD/$p" ;; esac
- # a path that already ends in the skill folder means "put it here", not "nest it again"
- case "$p" in */"$SKILL_NAME") p="${p%/$SKILL_NAME}" ;; esac
- echo "${p%/}"
- }
- # ════════════════════════════════════════════════════════════════════════
- # Wizard
- # ════════════════════════════════════════════════════════════════════════
- wizard() {
- local sel custom="" input tok i id mark det
- sel=" $(default_selection) "
- while true; do
- {
- echo ""
- echo "${B}Which agents should get the skill?${R} ${D}(✓ = found on this machine)${R}"
- echo ""
- i=0
- for id in $AGENT_IDS; do
- i=$((i + 1))
- mark="[ ]"; in_list "$id" "$sel" && mark="${G}[x]${R}"
- det=""; agent_detected "$id" && det=" ${G}✓${R}"
- printf " %s %2d) %-32s %s%s\n" "$mark" "$i" "$(agent_label "$id")" \
- "${D}$(pretty "$(agent_dir "$id")")${R}" "$det"
- if [ "$id" = universal ]; then
- printf " ${D}read by %s${R}\n" "$UNIVERSAL_READERS"
- echo ""
- fi
- done
- i=$((i + 1))
- mark="[ ]"; [ -n "$custom" ] && mark="${G}[x]${R}"
- printf " %s %2d) %-32s %s\n" "$mark" "$i" "Custom path…" "${D}$(echo "$custom" | tr '\n' ' ')${R}"
- echo ""
- echo " Toggle by number (e.g. ${B}2 3${R}), ${B}a${R} all, ${B}n${R} none, ${B}Enter${R} to continue."
- } >/dev/tty
- printf " > " >/dev/tty
- IFS= read -r input </dev/tty || input=""
- [ -z "$input" ] && break
- for tok in $input; do
- case "$tok" in
- a|A) sel=" $AGENT_IDS " ;;
- n|N) sel=" "; custom="" ;;
- *[!0-9]*) echo " ${Y}ignored '$tok'${R}" >/dev/tty ;;
- *)
- if [ "$tok" -ge 1 ] && [ "$tok" -le "$i" ]; then
- if [ "$tok" -eq "$i" ]; then
- if [ -n "$custom" ]; then custom=""; else
- printf " Skills directory (the folder that CONTAINS skill folders): " >/dev/tty
- IFS= read -r input </dev/tty || input=""
- [ -n "$input" ] && custom="$input"
- fi
- else
- id="$(echo $AGENT_IDS | cut -d' ' -f"$tok")"
- if in_list "$id" "$sel"; then sel="$(echo "$sel" | sed "s/ $id / /")"; else sel="$sel$id "; fi
- fi
- else echo " ${Y}no option $tok${R}" >/dev/tty; fi ;;
- esac
- done
- done
- # the wizard runs in a subshell, so custom paths travel back inside the selection string
- echo $sel "${custom:+@custom:$custom}"
- }
- confirm() {
- local q="$1" def="${2:-y}" ans hint="[Y/n]"
- [ "$def" = n ] && hint="[y/N]"
- [ "$TTY_OK" = true ] || { [ "$def" = y ]; return; }
- printf "\n%s %s " "$q" "$hint" >/dev/tty
- IFS= read -r ans </dev/tty || ans=""
- ans="$(echo "${ans:-$def}" | tr 'A-Z' 'a-z')"
- [ "$ans" = y ] || [ "$ans" = yes ]
- }
- # ════════════════════════════════════════════════════════════════════════
- # Source: GitHub tarball (default) or a local checkout (--source)
- # ════════════════════════════════════════════════════════════════════════
- obtain_source() {
- local work="$1" url tarball top
- if [ -n "$SOURCE_DIR" ]; then
- [ -d "$SOURCE_DIR" ] || die "--source: not a directory: $SOURCE_DIR"
- (cd "$SOURCE_DIR" && pwd)
- return
- fi
- url="https://codeload.github.com/$REPO_OWNER/$REPO_NAME/tar.gz/$REF"
- tarball="$work/src.tar.gz"
- # ${REF} braced: bash 3.2 in a UTF-8 locale reads a non-ASCII byte right after a name as part
- # of the name, so an unbraced REF followed by an ellipsis looked up a variable called
- # REF\xe2... and died under set -u. tests/lint/check_sources.py now rejects that pattern.
- info "Downloading ${REPO_OWNER}/${REPO_NAME}@${REF}…" >&2
- download "$url" "$tarball" || die "download failed: $url (is --ref '$REF' a real branch or tag?)"
- mkdir -p "$work/src"
- tar -xzf "$tarball" -C "$work/src" || die "could not extract the downloaded archive"
- for top in "$work/src"/*/; do echo "${top%/}"; return; done
- die "the archive was empty"
- }
- download() {
- if have curl; then curl -fsSL --retry 2 --max-time 120 -o "$2" "$1"
- elif have wget; then wget -q --timeout=120 -O "$2" "$1"
- else return 1; fi
- }
- validate_source() {
- local src="$1" name
- [ -f "$src/SKILL.md" ] || die "no SKILL.md in $src — not a $REPO_NAME checkout"
- [ -d "$src/references" ] || die "no references/ in $src"
- name="$(sed -n '1,15p' "$src/SKILL.md" | sed -n 's/^name:[[:space:]]*//p' | head -1 | tr -d '\r"'"'"' ')"
- [ "$name" = "$SKILL_NAME" ] || die "SKILL.md name is '$name', expected '$SKILL_NAME'"
- }
- skill_version() {
- sed -n 's/^[[:space:]]*"version":[[:space:]]*"\([^"]*\)".*/\1/p' "$1/metadata.json" 2>/dev/null | head -1
- }
- # ════════════════════════════════════════════════════════════════════════
- # Install
- # ════════════════════════════════════════════════════════════════════════
- # The payload is what an agent reads. Repo-only material (evals, tools, installer) stays out.
- install_payload() {
- local src="$1" version="$2" new="$STORE/.new.$$" old="$STORE/.old.$$" f
- step "Installing skill into $(pretty "$PAYLOAD")"
- if [ "$DRY" = true ]; then dry "copy SKILL.md, metadata.json, references/ … → $PAYLOAD"; return; fi
- mkdir -p "$STORE"
- rm -rf "$new"; mkdir -p "$new"
- for f in SKILL.md metadata.json LICENSE README.md CHANGELOG.md; do
- [ -f "$src/$f" ] && cp "$src/$f" "$new/"
- done
- cp -R "$src/references" "$new/references"
- # docs/ holds the pages README.md links to (absent in versions before 2.16.0)
- [ -d "$src/docs" ] && cp -R "$src/docs" "$new/docs"
- printf 'managed-by=%s install.sh\nversion=%s\ninstalled=%s\n' "$REPO_NAME" "$version" "$STAMP" > "$new/$MARKER"
- # swap in place: links point at $PAYLOAD, so they follow the new content automatically
- [ -e "$PAYLOAD" ] && mv "$PAYLOAD" "$old"
- mv "$new" "$PAYLOAD"
- rm -rf "$old"
- [ -f "$src/install.sh" ] && cp "$src/install.sh" "$STORE/install.sh" && chmod +x "$STORE/install.sh"
- ok "Skill v$version stored"
- }
- # Place $SKILL_NAME inside a skills directory: a symlink when possible, a marked copy otherwise.
- link_into() {
- local dir="$1" dest="$1/$SKILL_NAME" target
- if [ -L "$dest" ]; then
- target="$(readlink "$dest")"
- if [ "$target" = "$PAYLOAD" ]; then
- ok "$(pretty "$dest") ${D}(already linked)${R}"; manifest_add link "$dest"; return
- fi
- if [ "$FORCE" = false ]; then
- warn "$(pretty "$dest") is a symlink to $(pretty "$target") — left untouched (use --force to replace)"
- return
- fi
- backup_entry "$dest"
- elif [ -e "$dest" ]; then
- if [ -f "$dest/$MARKER" ]; then
- [ "$DRY" = true ] && { dry "refresh managed copy $dest"; return; }
- rm -rf "$dest"
- else
- backup_entry "$dest"
- fi
- fi
- if [ "$DRY" = true ]; then dry "link $dest → $PAYLOAD"; return; fi
- mkdir -p "$dir"
- if [ "$FORCE_COPY" = false ] && ln -s "$PAYLOAD" "$dest" 2>/dev/null && [ -L "$dest" ]; then
- ok "$(pretty "$dest") → store"
- manifest_add link "$dest"
- else
- # Git Bash without Developer Mode silently turns `ln -s` into a copy; handle both cases.
- [ -e "$dest" ] && [ ! -L "$dest" ] && rm -rf "$dest"
- cp -R "$PAYLOAD" "$dest"
- ok "$(pretty "$dest") ${D}(copy — re-run with --update after upgrades)${R}"
- manifest_add copy "$dest"
- fi
- }
- # Anything that is not ours is moved aside, never deleted. Backups live OUTSIDE every skills
- # directory: a backup containing SKILL.md inside a scanned folder would load as a duplicate skill.
- backup_entry() {
- local dest="$1" bdir
- bdir="$STORE/backups/$STAMP$(dirname "$dest" | sed 's#[:\\]#_#g')"
- if [ "$DRY" = true ]; then dry "back up existing $dest → $bdir/"; return; fi
- mkdir -p "$bdir"
- mv "$dest" "$bdir/"
- warn "existing $(pretty "$dest") moved to $(pretty "$bdir")/"
- }
- manifest_add() {
- [ "$DRY" = true ] && return
- mkdir -p "$STORE"; touch "$MANIFEST"
- grep -vxF "$1$TAB$2" "$MANIFEST" > "$MANIFEST.tmp" 2>/dev/null || true
- printf '%s\t%s\n' "$1" "$2" >> "$MANIFEST.tmp"
- mv "$MANIFEST.tmp" "$MANIFEST"
- }
- manifest_targets() {
- [ -f "$MANIFEST" ] || return 0
- local mode path
- while IFS="$TAB" read -r mode path; do
- [ -n "$path" ] && printf 'Previous\t%s\n' "$(dirname "$path")"
- done < "$MANIFEST"
- }
- # Older README instructions installed under names or paths that now cause duplicates.
- warn_legacy_installs() {
- local legacy="$HOME/.claude/skills/roblox-dev"
- if echo "$1" | grep -q "/.claude/skills\$" && [ -e "$legacy" ] && grep -q "^name: $SKILL_NAME" "$legacy/SKILL.md" 2>/dev/null; then
- if [ -L "$legacy" ]; then
- warn "$(pretty "$legacy") also points to this skill (old folder name) — Claude Code will list it twice. Remove it when ready: rm \"$legacy\""
- else
- backup_entry "$legacy"
- info "that was an old install under the non-standard name 'roblox-dev'; the spec requires the folder to match the skill name"
- fi
- fi
- local plugin="$HOME/.gemini/config/plugins/roblox-dev-suite/skills/$SKILL_NAME"
- if [ -e "$plugin" ] && echo "$1" | grep -q "/.gemini/config/skills"; then
- warn "Antigravity also loads this skill through your roblox-dev-suite plugin — it may appear twice."
- fi
- }
- # ════════════════════════════════════════════════════════════════════════
- # RobloxDocs
- # ════════════════════════════════════════════════════════════════════════
- find_python() {
- local c
- for c in python3 python; do
- if have "$c" && "$c" -c 'import sys; sys.exit(0 if sys.version_info >= (3, 6) else 1)' >/dev/null 2>&1; then
- echo "$c"; return 0
- fi
- done
- return 1
- }
- install_docs() {
- local src="$1" tools="$1/tools/robloxdocs" py f bdir="" cfg
- step "Setting up $(pretty "$DOCS_HOME")"
- if ! py="$(find_python)"; then
- warn "python3 not found — skipping RobloxDocs. The skill works without it, using web docs."
- info "Install Python 3, then run: bash \"$STORE/install.sh\" --docs-only"
- return 0
- fi
- [ -d "$tools" ] || { warn "this version has no tools/robloxdocs — skipping"; return 0; }
- if [ "$DRY" = true ]; then
- dry "install scripts → $DOCS_HOME/scripts/ and run roblox-api-monitor.sh"; return 0
- fi
- mkdir -p "$DOCS_HOME/scripts"
- for f in "$tools"/*; do
- local name; name="$(basename "$f")"
- # only the tools themselves — never caches or other stray files from a local checkout
- [ -f "$f" ] || continue
- case "$name" in *.py|*.sh) ;; *) continue ;; esac
- if [ -f "$DOCS_HOME/scripts/$name" ] && ! cmp -s "$f" "$DOCS_HOME/scripts/$name"; then
- [ -n "$bdir" ] || { bdir="$DOCS_HOME/scripts/.backup-$STAMP"; mkdir -p "$bdir"; }
- cp "$DOCS_HOME/scripts/$name" "$bdir/"
- fi
- cp "$f" "$DOCS_HOME/scripts/$name"
- case "$name" in *.sh|*.py) chmod +x "$DOCS_HOME/scripts/$name" ;; esac
- done
- [ -n "$bdir" ] && info "your previous scripts were different — kept a copy in $(pretty "$bdir")"
- [ -f "$DOCS_HOME/README.md" ] || cp "$tools/README.md" "$DOCS_HOME/README.md"
- cfg="$DOCS_HOME/config"
- if [ ! -f "$cfg" ]; then
- # Under Git Bash / Cygwin the Python that reads this file is a native Windows program: it cannot
- # resolve "/c/Users/…" or "/tmp/…". MSYS converts paths in arguments and environment variables,
- # never in file contents — so write a native path ourselves.
- local refs="$PAYLOAD/references"
- if have cygpath; then refs="$(cygpath -m "$refs")"; fi
- printf '# RobloxDocs configuration — KEY=VALUE, parsed (never sourced)\nSKILL_REFS=%s\nAUDIT_MODE=warn\n' \
- "$refs" > "$cfg"
- else
- info "kept your existing $(pretty "$cfg")"
- fi
- ok "Scripts installed"
- step "Downloading and splitting the Roblox API dump (one-time, ~8 MB)"
- if ROBLOX_DOCS_HOME="$DOCS_HOME" "$py" "$DOCS_HOME/scripts/roblox-api-monitor.py"; then
- ok "RobloxDocs ready"
- else
- warn "the API dump step did not finish — the skill is installed and works without it."
- info "Retry any time: ~/RobloxDocs/scripts/roblox-api-monitor.sh"
- fi
- }
- # ════════════════════════════════════════════════════════════════════════
- # Uninstall
- # ════════════════════════════════════════════════════════════════════════
- do_uninstall() {
- banner
- step "Uninstalling $SKILL_NAME"
- local mode path removed=0
- if [ -f "$MANIFEST" ]; then
- while IFS="$TAB" read -r mode path; do
- [ -n "$path" ] || continue
- if [ "$mode" = link ] && [ -L "$path" ] && [ "$(readlink "$path")" = "$PAYLOAD" ]; then
- run rm "$path"; [ "$DRY" = true ] || ok "removed $(pretty "$path")"; removed=$((removed + 1))
- elif [ -d "$path" ] && [ -f "$path/$MARKER" ]; then
- run rm -rf "$path"; [ "$DRY" = true ] || ok "removed $(pretty "$path")"; removed=$((removed + 1))
- elif [ -e "$path" ] || [ -L "$path" ]; then
- warn "$(pretty "$path") is no longer ours — left untouched"
- fi
- done < "$MANIFEST"
- else
- info "no manifest at $(pretty "$MANIFEST")"
- fi
- run rm -rf "$PAYLOAD" "$MANIFEST" "$STORE/install.sh"
- ok "removed $removed agent link(s) and the stored skill"
- [ -d "$STORE/backups" ] && info "backups of anything replaced during install are kept in $(pretty "$STORE/backups")"
- if [ "$PURGE_DOCS" = true ]; then
- if [ -d "$DOCS_HOME" ] && confirm "Delete $(pretty "$DOCS_HOME") including every downloaded API dump?" n; then
- run rm -rf "$DOCS_HOME/RobloxAPI" "$DOCS_HOME/scripts" "$DOCS_HOME/config"
- ok "removed RobloxAPI/, scripts/ and config from $(pretty "$DOCS_HOME")"
- elif [ "$YES" = true ] && [ -d "$DOCS_HOME" ]; then
- info "--purge-docs with --yes still asks for confirmation; nothing deleted from $(pretty "$DOCS_HOME")"
- fi
- elif [ -d "$DOCS_HOME" ]; then
- info "$(pretty "$DOCS_HOME") was kept. Add --purge-docs to remove it too."
- fi
- }
- # ════════════════════════════════════════════════════════════════════════
- # Output
- # ════════════════════════════════════════════════════════════════════════
- setup_colors() {
- if [ -t 1 ] && [ -z "${NO_COLOR:-}" ] && [ "${TERM:-dumb}" != dumb ]; then
- B=$'\033[1m'; D=$'\033[2m'; G=$'\033[32m'; Y=$'\033[33m'; RD=$'\033[31m'; C=$'\033[36m'; R=$'\033[0m'
- else B=""; D=""; G=""; Y=""; RD=""; C=""; R=""; fi
- }
- B=""; D=""; G=""; Y=""; RD=""; C=""; R=""
- info() { printf ' %s\n' "$*"; }
- ok() { printf ' %s✓%s %s\n' "$G" "$R" "$*"; }
- warn() { printf ' %s!%s %s\n' "$Y" "$R" "$*"; }
- step() { printf '\n%s▸ %s%s\n' "$C$B" "$*" "$R"; }
- dry() { printf ' %s[dry-run]%s %s\n' "$Y" "$R" "$*"; }
- die() { printf '\n %s✗ %s%s\n\n' "$RD" "$*" "$R" >&2; exit 1; }
- run() { if [ "$DRY" = true ]; then dry "$*"; else "$@"; fi; }
- pretty() { case "$1" in "$HOME"|"$HOME"/*) echo "~${1#"$HOME"}" ;; *) echo "$1" ;; esac; }
- banner() {
- printf '\n%s roblox-dev-skill installer %s\n' "$B" "$R"
- printf '%s Roblox & Luau knowledge for AI coding agents — %s%s\n' "$D" "https://github.com/$REPO_OWNER/$REPO_NAME" "$R"
- [ "$DRY" = true ] && printf '\n %sDRY RUN — nothing will be changed%s\n' "$Y" "$R"
- return 0
- }
- preflight() {
- local os
- os="$(uname -s 2>/dev/null || echo unknown)"
- case "$os" in
- Darwin) os="macOS" ;;
- Linux) grep -qi microsoft /proc/version 2>/dev/null && os="Linux (WSL)" || os="Linux" ;;
- MINGW*|MSYS*|CYGWIN*) os="Windows ($os)" ;;
- esac
- have curl || have wget || die "curl or wget is required"
- have tar || [ -n "$SOURCE_DIR" ] || die "tar is required"
- info "${D}$os · bash ${BASH_VERSION%%(*}${R}"
- }
- plan_summary() {
- local label dir
- step "Plan"
- info "Skill store: $(pretty "$PAYLOAD")"
- while IFS="$TAB" read -r label dir; do
- [ -n "$dir" ] || continue
- printf ' %s→%s %-26s %s\n' "$G" "$R" "$label" "$(pretty "$dir")/$SKILL_NAME"
- done <<EOF
- $1
- EOF
- if echo "$1" | grep -q "/.agents/skills"; then
- info "${D}~/.agents/skills is read by $UNIVERSAL_READERS${R}"
- fi
- info "RobloxDocs: $( [ "$DOCS_MODE" = yes ] && pretty "$DOCS_HOME" || echo "skipped")"
- }
- list_agents() {
- printf '\n%-16s %-32s %-40s %s\n' "ID" "AGENT" "USER SKILLS DIR" "DETECTED"
- local id
- for id in $AGENT_IDS; do
- printf '%-16s %-32s %-40s %s\n' "$id" "$(agent_label "$id")" "$(pretty "$(agent_dir "$id")")" \
- "$(agent_detected "$id" && echo yes || echo -)"
- done
- printf '\nPaths verified against each agent'"'"'s documentation (2026-09-25). Sources:\n'
- for id in $AGENT_IDS; do printf ' %-16s %s\n' "$id" "$(agent_docs "$id")"; done
- echo
- }
- finish() {
- step "Done"
- info "Installed $SKILL_NAME v$2."
- info "Restart your agent(s) so they rescan their skills folders."
- echo ""
- info "${B}Update${R} curl -fsSL https://raw.githubusercontent.com/$REPO_OWNER/$REPO_NAME/master/install.sh | bash -s -- --update"
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 697 on GitHub
- # absolute path: a quoted "~/…" is not expanded by the shell, so a pasted command would fail
- info "${B}Uninstall${R} bash \"$STORE/install.sh\" --uninstall"
- [ "$DOCS_MODE" = yes ] && info "${B}Refresh API${R} ~/RobloxDocs/scripts/roblox-api-monitor.sh"
- echo ""
- }
- usage() {
- cat <<USAGE
- roblox-dev-skill installer
- curl -fsSL https://raw.githubusercontent.com/$REPO_OWNER/$REPO_NAME/master/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 708 on GitHub
- curl -fsSL …/install.sh | bash -s -- [options]
- Interactive by default: pick agents from a list. Without a terminal it installs to the
- detected defaults.
- Choosing agents
- --agents LIST comma-separated ids, 'detected', or 'all'. Ids:
- $(echo $AGENT_IDS | fold -s -w 60 | sed '2,$s/^/ /')
- --path DIR also install into DIR (a folder that contains skill folders); repeatable
- --list show every supported agent, its skills folder, and whether it was detected
- --no-dedupe also link agents that already read ~/.agents/skills (they will list it twice)
- Behaviour
- -y, --yes no questions; use --agents or the detected defaults
- --dry-run show what would change, change nothing
- --copy copy instead of symlink (default: symlink, falling back to copy)
- --force replace an existing symlink that points somewhere else (it is backed up)
- --ref REF install a branch or tag (default: $DEFAULT_REF)
- --source DIR install from a local checkout instead of GitHub
- RobloxDocs (local Roblox API reference, needs python3)
- --docs / --no-docs set up ~/RobloxDocs or skip it (default: ask; yes when non-interactive)
- --docs-only only (re)install ~/RobloxDocs
- Maintenance
- --update fetch the latest skill; existing links follow automatically
- --uninstall remove every link/copy this installer made (nothing else)
- --purge-docs with --uninstall: also delete ~/RobloxDocs data (asks first)
- Environment
- ROBLOX_SKILL_REF default for --ref (e.g. a tag) — handy when options cannot be passed
- ROBLOX_SKILL_LINK copy = same as --copy
- ROBLOX_SKILL_STORE, ROBLOX_DOCS_HOME, XDG_DATA_HOME, NO_COLOR
- USAGE
- }
- main "$@"
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.