Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/msayib--roblox-dev-skill/badge.svg)](/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

i

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.

  1. ---
  2. name: roblox-dev-skill
  3. description: >
  4. Verified, current Roblox and Luau knowledge for writing, reviewing and debugging Roblox game code.
  5. Use it for ANY task that involves Roblox, Luau or Roblox Studio, even a quick question or a
  6. one-line snippet: scripts and modules, RemoteEvents, DataStores and ProfileStore, ProcessReceipt
  7. and monetization, UI, the Input Action System, Parallel Luau and Actors, performance, security
  8. and anti-exploit, deprecated APIs, Rojo, and the Roblox Studio MCP tools (execute_luau,
  9. multi_edit, script_read, open_cloud_invoke). It holds facts that general knowledge gets wrong (which properties a
  10. game Script may set, features that exist but are not enabled, Studio betas that cannot be
  11. published, engine changes up to 0.746 and Luau up to 0.745) and worked examples tested in Studio, so consult
  12. it before answering from memory. Not for Lua outside Roblox (Redis, OpenResty, WoW addons, LOVE)
  13. or for other game engines.
  14. ---
  15. # Roblox Game Development Skill
  16. Expert development companion for building Roblox experiences with Luau. Grounded in
  17. official Roblox documentation (https://create.roblox.com/docs), the Luau language spec
  18. (https://luau.org), and the Roblox Lua Style Guide (https://roblox.github.io/lua-style-guide/).
  19. > **Engine**: Roblox Studio **0.746.0.7461269** with **Luau 0.745** (released 2026-10-30) — dump
  20. > downloaded, re-split, and diffed against 0.745 on **2026-11-05**, with every developer-visible
  21. > change run in Studio 0.746. 950 classes / 656 enums; locally, 267 class files named `*Service`
  22. > (347 classes carry the `Service` tag) and 48 deprecated classes (577 members). The official docs
  23. > were checked through 2026-11-04. New and usable: `RaycastParams.Margin` / `SizeGradient`, the
  24. > `Color3` contrast methods, `GamepadService:EnableGamepadCursor()` with no argument.
  25. >
  26. > Roblox ships roughly weekly, so this line is stale by design — never quote it as today's version.
  27. > Re-derive it instead:
  28. >
  29. > ```bash
  30. > curl -s "https://clientsettings.roblox.com/v2/client-version/MacStudio" # or WindowsStudio64
  31. > curl -s "https://api.github.com/repos/luau-lang/luau/releases?per_page=1" | grep tag_name
  32. > ```
  33. >
  34. > The `WindowsStudio` (no `64`) endpoint returns a long-stale value — measured 2026-09-06 it still
  35. > answered `0.578.0.5780566`. Use `WindowsStudio64` or `MacStudio`.
  36. >
  37. > When in doubt about an API, look it up (see **API & Documentation Lookup** below) rather than
  38. > recalling it. If it is still unclear, ask the user before proceeding.
  39. ---
  40. ## MCP Detection
  41. On every invocation, detect available Roblox Studio MCP tools before proceeding:
  42. ### Official Roblox MCP (Roblox_Studio server)
  43. **This skill is a knowledge base, not an MCP server.** It ships no tools and no execution
  44. surface. The tools below belong to **Roblox's own MCP server, built into Studio** — this skill
  45. only tells you how to use them well. Official reference:
  46. https://create.roblox.com/docs/studio/mcp
  47. The docs page lists **26 tools**. The build observed 2026-11-07 (Studio 0.746.0.7461269) exposed
  48. **35**: those plus `open_cloud_invoke`, which has its own page (`studio/mcp-open-cloud`), and the
  49. undocumented `generate_texture`, `segment_mesh`, `generate_scene`, `generate_avatar`,
  50. `auto_setup_avatar` and three skill-authoring tools, `list_skills`, `create_skill` and `edit_skill`
  51. (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;
  52. `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
  53. exposes rather than trusting this table.
  54. | Tool | Purpose |
  55. |------|---------|
  56. | `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 |
  57. | `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`) |
  58. | `multi_edit` | Apply several exact-match edits to **ONE** script (creates it if missing); `Edit` datamodel only |
  59. | `script_read` | Read script source, whole or by line range; output is `LINE→CONTENT` |
  60. | `script_search` / `script_grep` | Find scripts by name (fuzzy, ≤10) or by content (≤50 matches) |
  61. | `search_game_tree` | Explore the DataModel as flat JSON, filterable by path/type/keyword; requires `datamodel_type` |
  62. | `inspect_instance` | Properties, attributes, and child summary for one instance |
  63. | `subagent` | Launch a Roblox-side subagent for autonomous multi-step work (types vary by build) |
  64. | `get_studio_state` | Play state **and which datamodel types are available** |
  65. | `start_stop_play` | Start/stop playtesting |
  66. | `get_console_output` | Read Output/console logs |
  67. | `screen_capture` | Capture the viewport, optionally from a custom camera; requires a `capture_id` |
  68. | `character_navigation` | Move the character to a position or instance path |
  69. | `user_mouse_input` / `user_keyboard_input` | Simulate ordered mouse/keyboard actions |
  70. | `search_asset` / `insert_asset` | Search Creator Store + Inventory; insert by asset ID |
  71. | `store_image` | **Local** png/jpg ≤5 MB → `IMAGEID_` URI for other tools |
  72. | `upload_image` | Batch upload from **HTTP(S) URLs** → imagePath→assetId map |
  73. | `generate_mesh` / `generate_procedural_model` | Generate 3D content |
  74. | `generate_material` | Generate a `MaterialVariant`; returns the base material + variant name |
  75. | `generate_texture` | Re-texture an **existing** MeshPart/Model — **replaces the source in place** (duplicate it first) |
  76. | `segment_mesh` | Split an existing mesh into ≤5 named parts; inserts a new Model next to the source |
  77. | `generate_scene` | Generate models and parts from a prompt or images, in an optional bounding box; **runs the generated script in the DataModel** |
  78. | `generate_avatar` | Generate a rigged R15 avatar from a prompt, **upload it as a persistent asset** and insert it into Workspace; usually several minutes |
  79. | `auto_setup_avatar` | Rig an existing static Workspace Model as an R15 avatar and place the result beside it; usually 3-5 minutes |
  80. | `wait_job_finished` | Await a background `jobId` (from a tool's own `async: true`) |
  81. | `http_get` | Fetch Roblox docs **from an allowlist**; URL must end `.md` or be `llms.txt` |
  82. | `skill` | Roblox's first-party `rbx-*` references (debug, perf, scene analysis, configs, analytics, permissions, Open Cloud, model import, …) |
  83. | `list_skills` / `create_skill` / `edit_skill` | List every skill; **publish** a new user skill or edit one (persistent, not undoable here: ask first) |
  84. | `list_roblox_studios` | Enumerate connected Studio instances (name + place ID) |
  85. > **Every call takes a `studio_id`.** There is no "set active studio" tool — call
  86. > `list_roblox_studios` first and pass the id you want on each subsequent call. Several Studio
  87. > instances are commonly open at once, so picking the wrong id silently targets the wrong place.
  88. >
  89. > **`datamodel_type` is asymmetric.** `execute_luau` accepts `Edit` / `Client` / `Server`;
  90. > **`multi_edit` accepts `Edit` only**, so you cannot edit scripts mid-playtest — stop the
  91. > playtest first. `Client` and `Server` exist only during a playtest, and `Edit` is refused during
  92. > one (`Edit datamodel is not available in Play mode`); check `get_studio_state`.
  93. >
  94. > **`multi_edit` is one script per call**, taking `file_path` plus
  95. > `edits[{old_string, new_string, replace_all}]`. Replacements are sequential, exact-match, and
  96. > atomic within the call: one `old_string` that does not match fails the call and leaves the
  97. > script unchanged (tested 2026-10-11). It does not require a prior `script_read`, but read
  98. > first anyway, since `old_string` must match the source exactly, whitespace included.
  99. >
  100. > **Confirm `script_grep`'s line numbers with `script_read`.** On 2026-09-06 it reported a match
  101. > at line 171 that `script_read` showed was 15 lines further down; on 2026-10-11 (Studio 0.742)
  102. > two tests returned the exact line, so the cause is unknown. Use it to find *which* script
  103. > contains a string, then `script_read` for the real location.
  104. >
  105. > **There is no `run_as_job` tool.** Earlier versions of this file listed one; it does not exist
  106. > in the docs or in any observed build. Async is a per-tool argument returning a `jobId`.
  107. If MCP tools are available, prefer using them for:
  108. - Reading existing scripts before writing new ones (`script_read`, `script_search`)
  109. - Validating changes by running code (`execute_luau`)
  110. - Inspecting game tree to understand project structure (`search_game_tree`)
  111. - Testing changes with playtest (`start_stop_play`, `get_console_output`)
  112. - Roblox's own domain skills (`skill`) for debugging, MicroProfiler, scene analysis, permissions
  113. and Open Cloud — first-party and shipped with Studio, but not always current: some steps in them
  114. fail when run (`mcp-integration.md` lists the ones measured)
  115. **Before the first mutation of any session**, read `references/agent-safety.md`. Roblox's own
  116. warning: *"MCP clients can read and modify content in your open Roblox places."* There is no
  117. dry-run and no reliable undo. Confirm which place you are targeting before you write to it.
  118. If MCP tools are NOT available, provide copy-paste-ready Luau scripts with clear
  119. placement instructions (which service container to put them in).
  120. ---
  121. ## Routing Table
  122. Match user intent to the appropriate reference file. Read the file BEFORE generating code.
  123. | User Intent | Reference File |
  124. |---|---|
  125. | **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` |
  126. | Luau syntax, types, naming conventions, style | `references/luau-fundamentals.md` |
  127. | Project layout, architecture, patterns, values you tune without a restart (`ConfigService`) | `references/project-structure.md` |
  128. | Save/load player data, DataStore, ProfileStore | `references/datastore-persistence.md` |
  129. | Client-server communication, RemoteEvents, input, text chat (`TextChatService`, chat commands, platform-integrated chat) | `references/networking.md` |
  130. | Security, anti-exploit, server authority, bans | `references/security-hardening.md` |
  131. | Agent→Studio safety, destructive MCP ops, prompt injection from place content | `references/agent-safety.md` |
  132. | Performance, memory, optimization, Parallel Luau, live instance groups (`CreateCollection`) | `references/performance-optimization.md` |
  133. | Using Roblox Studio MCP tools effectively | `references/mcp-integration.md` |
  134. | Open Cloud from an MCP client (`open_cloud_invoke`), MCP Permissions, permission errors, uploads | `references/mcp-integration.md` + `references/agent-safety.md` |
  135. | UI, GUI, ScreenGui, menus, HUD, StyleQuery | `references/ui-systems.md` |
  136. | Migrating legacy code, deprecated APIs | `references/legacy-migration.md` |
  137. | Monetization, game passes, donations, transfers | `references/monetization.md` |
  138. | File formats, import/export, asset management | `references/file-formats-and-assets.md` |
  139. | Plugins, `Script.Source` limits, HttpService/engine limits | `references/studio-plugins-and-limits.md` |
  140. **Start with `worked-examples.md` when the task is a *doing* task** (build, debug, migrate, look up, sell, bind input)
  141. rather than a *knowing* task. It gives the call sequence and the verification step, and each example
  142. carries a **Not this** list so a near-miss request routes to the right place instead of the nearest
  143. familiar pattern. Where an example and a reference file disagree, the reference file wins.
  144. If the intent spans multiple domains, read all relevant files.
  145. If a reference file doesn't cover a topic sufficiently, use the Official
  146. Documentation Lookup workflow below.
  147. ---
  148. ## API & Documentation Lookup
  149. ### Priority 1: Local API Reference (`~/RobloxDocs/`)
  150. **Always check local files first** — they are pre-split, far cheaper to read than the full dump, and
  151. require no network. If `~/RobloxDocs/RobloxAPI/` exists, use it.
  152. **How much cheaper, re-measured 2026-11-05 on 0.746.0.7461264** (an earlier "845× smaller" figure
  153. was not reproducible from any measurement, so here are the real numbers and the command that
  154. produced them): the full dump is **8,721,015 bytes**; the 950 split class files run **101 B min,
  155. 2,074 B median, 4,897 B mean, 105,756 B max**. So a typical class lookup reads about **0.02%** of
  156. the dump, and even the largest class reads under **1.3%** of it. Re-measure with:
  157. ```bash
  158. # Portable (macOS, Linux, Windows). Do not use `stat -f %z`: on Linux `stat -f` reports the
  159. # *filesystem*, not the file, and prints a wrong number without any error. It also reads the
  160. # 75-byte latest.json symlink instead of the dump unless you remember -L.
  161. python3 -c "import os,glob,statistics as s; d=os.path.expanduser('~/RobloxDocs/RobloxAPI'); \
  162. z=sorted(os.path.getsize(f) for f in glob.glob(d+'/classes/*.json')); \
  163. print('dump', os.path.getsize(os.path.realpath(d+'/dumps/latest.json')), 'B | n', len(z), \
  164. 'min', z[0], 'median', int(s.median(z)), 'mean', int(s.mean(z)), 'max', z[-1])"
  165. ```
  166. ```bash
  167. # Look up a specific class (~2 KB median vs the 8.6 MB full dump — see measurement above)
  168. cat ~/RobloxDocs/RobloxAPI/classes/<ClassName>.json
  169. # Query a specific property/method (jq if installed; the python3 form works everywhere)
  170. jq '.Members[] | select(.Name == "<MemberName>")' ~/RobloxDocs/RobloxAPI/classes/<ClassName>.json
  171. 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>'])"
  172. # Find all services
  173. cat ~/RobloxDocs/RobloxAPI/service-index.json
  174. # Check what's deprecated
  175. cat ~/RobloxDocs/RobloxAPI/deprecated-index.json
  176. # Search across classes by filename
  177. ls ~/RobloxDocs/RobloxAPI/classes/ | grep -i <keyword>
  178. # Search for a property across all classes
  179. grep -l '"<PropertyName>"' ~/RobloxDocs/RobloxAPI/classes/*.json
  180. ```
  181. **Obsolescence check:** Before using local data, verify freshness:
  182. ```bash
  183. # Check when local data was last updated
  184. cat ~/RobloxDocs/RobloxAPI/.current-version
  185. # → {"version": "0.746.0.7461264", "platform": "MacStudio", "platformVersion": "0.746.0.7461264",
  186. # "winHash": "version-fee454b8e2094ba9", "updatedAt": "2026-11-04T18:00:20Z", "checkedAt": "2026-11-04T18:00:20Z"}
  187. ```
  188. > **Read whichever timestamp is present: `updatedAt` OR `checkedAt`.** `updatedAt` is when a dump
  189. > was last downloaded; `checkedAt` is when the version was last checked. The current monitor
  190. > (skill 2.12.0+) always writes both, but the older zsh script wrote **only `updatedAt`** after a
  191. > download — so an install that has not refreshed its tools may lack `checkedAt` entirely. Earlier
  192. > versions of this file told the agent to read `checkedAt`, which silently found nothing there.
  193. If that timestamp is older than 7 days, or a class/member is not found locally, **proceed with the
  194. live web fallback below and tell the user the local dump looks stale.** Offer to refresh it:
  195. ```bash
  196. # Only after the user agrees — this downloads and re-splits the API dump
  197. ~/RobloxDocs/scripts/roblox-api-monitor.sh # macOS, Linux, WSL, Git Bash
  198. python "%USERPROFILE%\RobloxDocs\scripts\roblox-api-monitor.py" # Windows without bash
  199. ```
  200. If `~/RobloxDocs` does not exist at all, the user never set it up. Say so and point them at the
  201. installer's `--docs-only` option (`-DocsOnly` in PowerShell) rather than creating it yourself.
  202. > **Do not background this and do not run it unasked.** Earlier versions of this file told the
  203. > agent to fire `roblox-api-monitor.sh &` automatically, which contradicted both the
  204. > Knowledge Freshness Check below ("NEVER auto-update without user approval") and the README.
  205. > There is no scheduler and no background job in this skill; a human triggers the refresh.
  206. > Staleness never blocks the answer — fall through to the web sources and say so.
  207. ### Priority 2: Live Web Sources (Fallback)
  208. Use these when local data doesn't cover a topic, is obsolete, or you need prose docs:
  209. | Resource | URL | Use For |
  210. |----------|-----|--------|
  211. | **LLM docs index** | `https://create.roblox.com/docs/llms.txt` | Browse all available doc pages by topic |
  212. | **Full docs (single file)** | `https://create.roblox.com/docs/llms-full.txt` | Comprehensive single-file reference |
  213. | **Per-page markdown** | `https://create.roblox.com/docs/en-us/{path}.md` | Read specific doc pages in clean markdown |
  214. | **Engine API index** | `https://create.roblox.com/docs/reference/engine/llms.txt` | Luau API classes, methods, events |
  215. | **Open Cloud API index** | `https://create.roblox.com/docs/cloud/llms.txt` | **Primary discovery** for all Cloud REST API: features, domains, guides, auth |
  216. | **OpenAPI spec (raw)** | `https://create.roblox.com/docs/cloud/openapi.json` | Machine-readable OpenAPI spec for MCP/code-gen tools |
  217. | **Deprecated API check** | `https://robloxapi.github.io/ref/class/<Name>.html` | Check individual class/member status (deprecated items marked visually) |
  218. > **If you are fetching these through Studio's `http_get` tool, note its allowlist:** only
  219. > `create.roblox.com/docs` (incl. `/reference/engine`, `/cloud`, `/performance-optimization`) and
  220. > `github.com/Roblox/libmp`, and **the URL must end in `.md` or be `llms.txt`**. So
  221. > `llms-full.txt`, `openapi.json`, and `robloxapi.github.io` are **rejected** by `http_get` — use
  222. > the host's own fetch tool or `curl` for those. `http_get`'s `query` argument returns only
  223. > matching sections, which is much cheaper than pulling a whole page into context. A
  224. > `github.com/Roblox/libmp/blob/….md` URL is accepted but comes back as GitHub's HTML page
  225. > (measured 2026-10-21); read LibMP files from `raw.githubusercontent.com` with curl instead.
  226. ### Lookup Workflow
  227. 1. Check if a **reference file** covers the topic (Routing Table above)
  228. 2. Check **`~/RobloxDocs/RobloxAPI/classes/<Name>.json`** for Engine API details
  229. 3. If not found locally, fetch the per-page markdown URL with whatever web-fetch tool the host
  230. provides (`WebFetch` in Claude Code, `curl` in a shell — the URL is the portable part)
  231. - Example: `https://create.roblox.com/docs/en-us/studio/importer.md`
  232. 4. If unsure which page to read, browse `llms.txt` for the right URL
  233. 5. For **Open Cloud / REST API** topics, read `https://create.roblox.com/docs/cloud/llms.txt`
  234. - Search Features section first, then Domains
  235. - Prefer Open Cloud endpoints (API key / OAuth) over legacy cookie-auth endpoints
  236. - From an MCP client, call them with `open_cloud_invoke`: Studio supplies the token, so no key
  237. 6. **Fallback**: Context7. Its MCP tools are `resolve-library-id` then `query-docs` (the
  238. upstash/context7 README, checked 2026-10-11; an earlier version of this file called the second
  239. one `get-library-docs` and said `query-docs` did not exist). Where the
  240. MCP server is not connected, the CLI does the same job:
  241. `npx ctx7@latest library "Roblox"` then `npx ctx7@latest docs <libraryId> "<question>"`
  242. 7. If still unclear, ask the user before proceeding
  243. > **Important**: Engine APIs (Luau via `game:GetService()`) and Open Cloud APIs
  244. > (HTTP REST via `x-api-key`, or `open_cloud_invoke` from an MCP client) are **completely separate
  245. > systems**. Using the wrong index will produce non-functional code.
  246. > **Checking deprecated APIs**: Use these approaches (in priority order):
  247. > 1. `cat ~/RobloxDocs/RobloxAPI/deprecated-index.json` — instant local lookup
  248. > 2. `cat ~/RobloxDocs/RobloxAPI/deprecated/<ClassName>.json` — full deprecated class detail
  249. > 3. Check `robloxapi.github.io/ref/class/<Name>.html` — deprecated members marked visually
  250. > 4. Use Context7 (`resolve-library-id` → `get-library-docs`, or the `ctx7` CLI) to query specific APIs
  251. ---
  252. ## Core Coding Standards
  253. These rules apply to ALL generated Roblox/Luau code. They are non-negotiable.
  254. ### 1. Type Safety
  255. - Use `--!strict` at the top of every new script
  256. - Annotate function parameters and return types
  257. - Define custom types with `type` keyword for complex data structures
  258. ### 2. Naming Conventions (Official Roblox Style)
  259. - **PascalCase**: Classes, ModuleScripts, Constructors, Services — `CombatService`, `PlayerData`
  260. - **camelCase**: Variables, functions, parameters — `playerHealth`, `calculateDamage()`
  261. - **UPPER_SNAKE_CASE**: Constants — `MAX_HEALTH`, `DEFAULT_SPEED`
  262. - Spell out words fully — avoid abbreviations
  263. - Don't fully capitalize acronyms: `JsonTable` not `JSONTable`
  264. ### 3. Modern API Usage
  265. - Use `task.spawn()`, `task.delay()`, `task.wait()` — NOT legacy `spawn()`, `delay()`, `wait()`
  266. - Use `task.cancel()` to clean up deferred tasks
  267. - Always disconnect event connections in cleanup: `connection:Disconnect()`
  268. - Wrap fallible operations in `pcall()` or `xpcall()`
  269. ### 4. Architecture Rules
  270. - **Server authority**: All game state mutations happen on the server
  271. - **ModuleScripts** for shared logic — avoid monolithic scripts
  272. - **Service/Controller pattern**: Services (server), Controllers (client)
  273. - Scripts go in the correct container:
  274. - Server logic → `ServerScriptService`
  275. - Client logic → `StarterPlayerScripts` or `StarterCharacterScripts`
  276. - Shared modules → `ReplicatedStorage`
  277. - Server-only data → `ServerStorage`
  278. - UI → `StarterGui`
  279. ### 5. Error Handling
  280. <!-- skilltest: prelude datastore; expect call-succeeded -->
  281. ```lua
  282. local success, result = pcall(function()
  283. return DataStoreService:GetDataStore("PlayerData"):GetAsync(key)
  284. end)
  285. if not success then
  286. warn("[DataService] Failed to load data:", result)
  287. -- Handle gracefully: use defaults, retry, etc.
  288. end
  289. ```
  290. ### 6. Security (Always Apply)
  291. - NEVER trust client-sent data — validate types, ranges, and permissions on server
  292. - Keep sensitive logic in `ServerScriptService` (not visible to clients)
  293. - Validate RemoteEvent arguments: check `typeof()`, ranges, and player state
  294. - Rate-limit RemoteEvent calls from clients
  295. - Never expose admin commands or server keys to ReplicatedStorage
  296. ---
  297. ## Script Template
  298. When creating new scripts, use this template as a starting point:
  299. ```lua
  300. --!strict
  301. -- [ScriptName]
  302. -- [Brief description of what this script does]
  303. -- Container: [ServerScriptService/StarterPlayerScripts/ReplicatedStorage]
  304. ----- Services -----
  305. local Players = game:GetService("Players")
  306. local ReplicatedStorage = game:GetService("ReplicatedStorage")
  307. ----- Dependencies -----
  308. -- local SomeModule = require(ReplicatedStorage.Modules.SomeModule)
  309. ----- Constants -----
  310. local MAX_VALUE = 100
  311. ----- Types -----
  312. type PlayerData = {
  313. coins: number,
  314. level: number,
  315. inventory: { string },
  316. }
  317. ----- Variables -----
  318. local activeConnections: { [Player]: { RBXScriptConnection } } = {}
  319. ----- Private Functions -----
  320. local function cleanup(player: Player)
  321. local connections = activeConnections[player]
  322. if connections then
  323. for _, conn in connections do
  324. conn:Disconnect()
  325. end
  326. activeConnections[player] = nil
  327. end
  328. end
  329. ----- Public / Event Handlers -----
  330. local function onPlayerAdded(player: Player)
  331. activeConnections[player] = {}
  332. -- Setup logic here
  333. end
  334. ----- Initialization -----
  335. Players.PlayerAdded:Connect(onPlayerAdded)
  336. Players.PlayerRemoving:Connect(cleanup)
  337. -- Handle players already in game (Studio hot-reload)
  338. for _, player in Players:GetPlayers() do
  339. task.spawn(onPlayerAdded, player)
  340. end
  341. ```
  342. ---
  343. ## Response Guidelines
  344. 1. **Ask before building**: If the request is vague, ask clarifying questions about genre, scale, and target audience
  345. 2. **Read before writing**: If MCP is available, read existing scripts and game tree before modifying
  346. 3. **Small slices**: Generate 50-100 lines at a time for complex systems — easier to debug
  347. 4. **Explain the why**: Comment non-obvious code and explain architectural decisions
  348. 5. **Test path**: Suggest how to test the code (playtest steps, console checks)
  349. 6. **Migration-aware**: When touching existing code, check for legacy patterns and suggest migration if appropriate — but never force it. Incremental migration is acceptable.
  350. ---
  351. ## Common Workflows
  352. ### New Feature
  353. 1. Read existing project structure (MCP: `search_game_tree`)
  354. 2. Identify where the feature fits in the architecture
  355. 3. Create ModuleScript(s) in the appropriate container
  356. 4. Wire up server/client communication if needed
  357. 5. Test via playtest (MCP: `start_stop_play` + `get_console_output`)
  358. ### Debug Issue
  359. 1. Read the relevant script (MCP: `script_read`)
  360. 2. Check console output (MCP: `get_console_output`)
  361. 3. Identify the root cause — look for:
  362. - Missing `pcall` around DataStore/HTTP calls
  363. - Client-server boundary issues
  364. - Connection leaks (missing Disconnect)
  365. - Race conditions (script execution order)
  366. 4. Apply minimal fix
  367. 5. Verify fix via playtest
  368. ### Code Review
  369. 1. Read scripts in the project (MCP: `script_grep`)
  370. 2. Check against Core Coding Standards above
  371. 3. Flag security issues (client trust, exposed data)
  372. 4. Flag performance issues (expensive loops, part count)
  373. 5. Suggest improvements with before/after examples
  374. ---
  375. ## Knowledge Freshness Check
  376. Nothing about this is automatic — there is no scheduler, hook, or background job behind it. It is an
  377. instruction to *you*, the agent reading this file: **when this skill is invoked**, read
  378. `metadata.json` in this skill directory and compare `last_updated` to the current date.
  379. ### Logic:
  380. ```
  381. IF (current_date - last_updated) > update_interval_days (default: 7):
  382. TELL the user:
  383. "⏰ Roblox Dev Skill knowledge was last updated on {last_updated}, {days} days ago.
  384. Want me to run a knowledge update before we rely on it?"
  385. ...then WAIT. Do not update anything unless they say yes.
  386. ELSE:
  387. Proceed normally — knowledge is fresh.
  388. ```
  389. ### Decision Rules:
  390. - **NEVER auto-update** without user approval — always ask first
  391. - **Source of truth**: https://create.roblox.com/docs, https://devforum.roblox.com
  392. - **Decision maker**: Always the user (never the AI alone)
  393. - **Update process**: Deep research → fact-check → QnA with user → apply → audit
  394. - **After update**: Update `metadata.json` with new timestamp, version, and changes
  395. ---
  396. ## Manual Knowledge Update
  397. The user can trigger a full knowledge update at any time by asking for one in plain language —
  398. "update roblox skill knowledge", "refresh roblox dev skill", "roblox-update".
  399. > **`/roblox-update` is NOT a registered slash command.** Earlier versions of this file presented it
  400. > as one; it has never been installed in `~/.claude/commands/` or shipped by a plugin, so typing it
  401. > resolves to nothing. It is a phrase this skill listens for, and that is all it has ever been.
  402. ### Update Protocol:
  403. 1. **Research** — Search for latest Roblox changes since `last_updated` timestamp
  404. - DevForum release notes, API changelog, deprecation notices
  405. - Use web search for "Roblox developer updates {year}" and "Roblox API changes {month} {year}"
  406. - Visit https://devforum.roblox.com/c/updates/release-notes/58
  407. 2. **Compare** — Cross-check findings against existing reference files
  408. 3. **Report** — Present findings to user with clear "what changed" summary
  409. 4. **Discuss** — QnA with user on any decisions (add/remove/modify content)
  410. 5. **Apply** — Update reference files (keep what's correct, update what changed)
  411. 6. **Audit** — Full fact-check (same pattern as initial audit: file integrity + content verification)
  412. 7. **Stamp** — Update `metadata.json` with new timestamp and changelog entry
  413. > [!IMPORTANT]
  414. > All updates must be research-based. No improvisation. When in doubt, ask the user.
  415. > Fallback: consult official docs via context7 MCP or direct web search.
  416. ---
  417. ## Export / Publish
  418. This skill is designed to be export-ready for GitHub publishing. See `README.md`
  419. in the skill root directory for the complete structure and usage guide.
  420. Users install it with the one-line installers in the repository (`install.sh`, `install.ps1`,
  421. `install.cmd`), which link it into each agent's skills folder. When copying it by hand, the folder
  422. **must be named `roblox-dev-skill`** — the Agent Skills spec requires the folder name to match the
  423. `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.

  1. # 🎮 Roblox Dev Skill
  2. [![CI](https://github.com/MSayib/roblox-dev-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/MSayib/roblox-dev-skill/actions/workflows/ci.yml)
  3. **An [Agent Skill](https://agentskills.io) that makes an AI coding agent write correct, current Roblox
  4. code.** When you mention Roblox, Luau or Roblox Studio, the agent loads this skill: a routing file
  5. ([`SKILL.md`](SKILL.md)) plus 14 reference guides on Luau, client-server architecture, security,
  6. DataStores, UI, performance, monetization, migration, and driving Roblox Studio through its MCP
  7. server. Works with Claude Code, Codex, Cursor, Gemini CLI, Antigravity, GitHub Copilot, and any
  8. agent that reads the Agent Skills format.
  9. > **Skill 2.22.0** · verified against Roblox Studio **0.746.0.7461269** and **Luau 0.745** on
  10. > 2026-11-07. Every code example was type-checked under `--!strict` and run in a real Studio place,
  11. > and every factual statement checked against an official source or a test.
  12. > Roblox ships weekly, so this is *when it was last verified*, not today's version.
  13. It is Markdown an agent reads. It is **not** an MCP server and ships no tools: for Studio access,
  14. enable [Studio's built-in MCP server](https://create.roblox.com/docs/studio/mcp).
  15. ## Quick install
  16. **macOS, Linux, WSL, Git Bash**
  17. ```bash
  18. curl -fsSL https://raw.githubusercontent.com/MSayib/roblox-dev-skill/master/install.sh | bash
  19. ```
  20. **Windows PowerShell**
  21. ```powershell
  22. irm https://raw.githubusercontent.com/MSayib/roblox-dev-skill/master/install.ps1 | iex
  23. ```
  24. **Windows CMD**
  25. ```bat
  26. curl -fsSL https://raw.githubusercontent.com/MSayib/roblox-dev-skill/master/install.cmd -o install.cmd && install.cmd
  27. ```
  28. The installer asks which agents to set up (the ones it finds are pre-selected), stores the skill
  29. once, and links it into each agent, so one update reaches all of them. It can also set up
  30. [`~/RobloxDocs`](docs/robloxdocs.md), a local copy of the Roblox API for fast, offline lookups.
  31. It never deletes anything it did not create.
  32. **Then restart your agent** and try:
  33. > *Create a coin collection system for my Roblox game*
  34. You should get server-authoritative `--!strict` Luau that validates what the client sends. Options,
  35. updating, uninstalling and manual install: **[docs/installation.md](docs/installation.md)**.
  36. ## What's inside
  37. | Reference | Covers |
  38. |---|---|
  39. | [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 |
  40. | [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 |
  41. | [project-structure](references/project-structure.md) | Services, Rojo, client/server layout, the Input Action System |
  42. | [networking](references/networking.md) | RemoteEvents, RemoteFunctions, unreliable remotes, bindables, text chat and platform-integrated chat, teleports to reserved and VIP servers |
  43. | [security-hardening](references/security-hardening.md) | Server authority, validating remote input, anti-exploit, bans, device trust, script capabilities |
  44. | [datastore-persistence](references/datastore-persistence.md) | DataStoreService, ProfileStore, MemoryStoreService |
  45. | [performance-optimization](references/performance-optimization.md) | Memory, Parallel Luau and Actors, streaming, the frame pipeline, thick casts with `RaycastParams.Margin` |
  46. | [ui-systems](references/ui-systems.md) | GUI layout, StyleSheets, BillboardGui / SurfaceGui, ProximityPrompt, `Color3` contrast methods |
  47. | [monetization](references/monetization.md) | Game passes, developer products, subscriptions, Robux transfers |
  48. | [legacy-migration](references/legacy-migration.md) | Deprecated APIs and replacements, what each engine release changed |
  49. | [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 |
  50. | [agent-safety](references/agent-safety.md) | What an agent with Studio access can break, and the rules that prevent it |
  51. | [studio-plugins-and-limits](references/studio-plugins-and-limits.md) | Plugins, `Script.Source` limits, engine limits |
  52. | [file-formats-and-assets](references/file-formats-and-assets.md) | `.rbxl`/`.rbxm`, meshes, importing |
  53. How routing, lookup and the coverage dates work: **[docs/how-it-works.md](docs/how-it-works.md)**.
  54. ## How it stays correct
  55. - **Every example is tested.** Each Luau block is type-checked with luau-lsp under `--!strict`, then
  56. run in a real Studio place through Rojo, as a game Script (so security gates apply), a
  57. LocalScript, or inside an Actor. The 2.16.0 pass found and fixed a script that could not compile,
  58. a pool that leaked objects, player data shared between players, and a purchase handler that
  59. charged for items it did not give. Since 2.17.0 the fragments run too, with the names a reader's
  60. project would supply, and the important examples assert what they do (a pool returns to 10, a
  61. receipt is granted once). **[docs/testing.md](docs/testing.md)**
  62. - **Every claim is checked.** Each high-risk statement (limits, versions, "cannot", "not enabled")
  63. is in a register with its source or test; the 2.17.0 pass corrected 58, among them a
  64. delayed rollout the text dated, limits off by up to 1000×, and an event that does not exist.
  65. **[docs/claims.md](docs/claims.md)**
  66. - **Every engine release is diffed** member by member against the previous API dump, and the
  67. developer-visible changes are run in Studio before the skill describes them. "Not enabled"
  68. statements are re-run every cycle, because a server-side flag can change them with an empty diff.
  69. - **It says what it does not know.** Features that exist but are not enabled, betas you cannot
  70. publish, and anything not yet tested are labelled as such.
  71. History: **[CHANGELOG.md](CHANGELOG.md)** (machine-readable: [`metadata.json`](metadata.json)).
  72. ## For AI agents reading this
  73. Start at [`SKILL.md`](SKILL.md): it holds the standards (always `--!strict`, server authority,
  74. validate every remote argument) and a routing table that says which reference to open for which
  75. task. Where a reference and a worked example disagree, the reference wins. Treat the version line
  76. above as a date, and re-check the live engine version with the commands in `SKILL.md`.
  77. ## Contributing
  78. Ground every claim in official documentation, the API dump, or a test you ran, and pass the four
  79. test layers in [docs/testing.md](docs/testing.md) before opening a pull request.
  80. ## License and credits
  81. MIT, see [LICENSE](LICENSE). Created by [@MSayib](https://github.com/MSayib), built with AI and
  82. fact-checked against [Roblox Creator Docs](https://create.roblox.com/docs), [Luau](https://luau.org),
  83. the Roblox API dump, and Roblox Studio itself.
  84. If the skill helps you, a ⭐ helps other developers find it.
  85. [![Star History Chart](https://api.star-history.com/svg?repos=MSayib/roblox-dev-skill&type=Date)](https://star-history.com/#MSayib/roblox-dev-skill&Date)
install.ps1 · Bundled script · 641 lines · 3 findings marked
  1. <#
  2. roblox-dev-skill installer for Windows PowerShell 5.1+ and PowerShell 7+
  3. https://github.com/MSayib/roblox-dev-skill
  4. 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
  5. With options:
  6. & ([scriptblock]::Create((irm https://raw.githubusercontent.com/MSayib/roblox-dev-skill/master/install.ps1))) -Agents claude,universal -Yes
  7. Installs the skill once and links it into every agent you pick (symlink, else a junction, else a
  8. copy), then optionally sets up ~\RobloxDocs with a freshly downloaded Roblox API dump.
  9. No git needed. RobloxDocs needs Python 3.6+.
  10. This file is deliberately ASCII-only: Windows PowerShell 5.1 reads BOM-less UTF-8 as ANSI.
  11. #>
  12. param(
  13. [string[]]$Agents,
  14. [string[]]$Path,
  15. [switch]$Yes,
  16. [switch]$DryRun,
  17. [switch]$Force,
  18. [switch]$Copy,
  19. [switch]$Docs,
  20. [switch]$NoDocs,
  21. [switch]$DocsOnly,
  22. [string]$Ref = $(if ($env:ROBLOX_SKILL_REF) { $env:ROBLOX_SKILL_REF } else { 'master' }),
  23. [string]$Source,
  24. [switch]$NoDedupe,
  25. [switch]$Update,
  26. [switch]$Uninstall,
  27. [switch]$PurgeDocs,
  28. [switch]$List,
  29. [switch]$Help
  30. )
  31. # Everything runs in a child scope: when piped into `iex` this script executes inside the user's
  32. # own session, so nothing -- preferences, functions, variables -- may leak into it, and nothing may
  33. # call `exit`, which would close their window.
  34. & {
  35. $ErrorActionPreference = 'Stop'
  36. $ProgressPreference = 'SilentlyContinue' # the 5.1 progress bar slows downloads dramatically
  37. $RepoOwner = 'MSayib'
  38. $RepoName = 'roblox-dev-skill'
  39. $SkillName = 'roblox-dev-skill' # must equal SKILL.md `name` and the folder name (agentskills.io)
  40. $Marker = '.roblox-dev-skill-install'
  41. $OnWindows = ($PSVersionTable.PSVersion.Major -lt 6) -or $IsWindows
  42. # ROBLOX_SKILL_HOME lets tests run against a throwaway profile ($HOME cannot be redirected in pwsh on Windows)
  43. if ($env:ROBLOX_SKILL_HOME) { $HomeDir = $env:ROBLOX_SKILL_HOME } else { $HomeDir = $HOME }
  44. $Stamp = Get-Date -Format 'yyyyMMdd-HHmmss'
  45. if ($env:ROBLOX_SKILL_STORE) { $Store = $env:ROBLOX_SKILL_STORE }
  46. elseif ($OnWindows) { $Store = Join-Path $env:LOCALAPPDATA $RepoName }
  47. elseif ($env:XDG_DATA_HOME) { $Store = Join-Path $env:XDG_DATA_HOME $RepoName }
  48. else { $Store = Join-Path (Join-Path (Join-Path $HomeDir '.local') 'share') $RepoName }
  49. $Payload = Join-Path $Store $SkillName
  50. $Manifest = Join-Path $Store 'manifest.tsv'
  51. if ($env:ROBLOX_DOCS_HOME) { $DocsHome = $env:ROBLOX_DOCS_HOME } else { $DocsHome = Join-Path $HomeDir 'RobloxDocs' }
  52. # ======================================================================
  53. # Output
  54. # ======================================================================
  55. function Say([string]$m) { Write-Host " $m" }
  56. function Ok([string]$m) { Write-Host ' [ok] ' -ForegroundColor Green -NoNewline; Write-Host $m }
  57. function Warn([string]$m) { Write-Host ' [!] ' -ForegroundColor Yellow -NoNewline; Write-Host $m }
  58. function Step([string]$m) { Write-Host ''; Write-Host "> $m" -ForegroundColor Cyan }
  59. function Dry([string]$m) { Write-Host ' [dry-run] ' -ForegroundColor Yellow -NoNewline; Write-Host $m }
  60. function Fail([string]$m) { throw "roblox-dev-skill installer: $m" }
  61. function P([string]$p) {
  62. if ($p -and $p.StartsWith($HomeDir, [StringComparison]::OrdinalIgnoreCase)) { return '~' + $p.Substring($HomeDir.Length) }
  63. return $p
  64. }
  65. function J { param([Parameter(ValueFromRemainingArguments = $true)][string[]]$parts)
  66. $r = $parts[0]; for ($i = 1; $i -lt $parts.Count; $i++) { $r = Join-Path $r $parts[$i] }; return $r }
  67. # ======================================================================
  68. # Agent registry -- every path verified against the agent's own docs on 2026-09-25.
  69. # ReadsUniversal: the agent documents ~/.agents/skills as a discovery path, so the one universal
  70. # link already covers it (a second link would list the skill twice).
  71. # ======================================================================
  72. function Under-Home([string]$rel) { Join-Path $HomeDir ($rel -replace '/', [IO.Path]::DirectorySeparatorChar) }
  73. function New-Agent($Id, $Label, $Rel, $ReadsUniversal, $Docs, $Cmd, $DetectRel) {
  74. [pscustomobject]@{ Id = $Id; Label = $Label; Dir = (Under-Home $Rel); ReadsUniversal = $ReadsUniversal
  75. Docs = $Docs; Cmd = $Cmd; DetectRel = $DetectRel }
  76. }
  77. $Registry = @(
  78. (New-Agent 'universal' 'Universal ~/.agents/skills' '.agents/skills' $false 'https://agentskills.io/client-implementation/adding-skills-support' $null '.agents'),
  79. (New-Agent 'claude' 'Claude Code' '.claude/skills' $false 'https://code.claude.com/docs/en/skills' 'claude' '.claude'),
  80. (New-Agent 'antigravity' 'Antigravity (2.0 / IDE)' '.gemini/config/skills' $false 'https://antigravity.google/docs/skills/' 'antigravity' '.gemini/config'),
  81. (New-Agent 'antigravity-cli' 'Antigravity CLI' '.gemini/antigravity-cli/skills' $false 'https://antigravity.google/docs/skills/' $null '.gemini/antigravity-cli'),
  82. (New-Agent 'kiro' 'Kiro' '.kiro/skills' $false 'https://kiro.dev/docs/skills/' 'kiro' '.kiro'),
  83. (New-Agent 'codex' 'Codex (OpenAI)' '.agents/skills' $true 'https://developers.openai.com/codex/skills/' 'codex' '.codex'),
  84. (New-Agent 'gemini' 'Gemini CLI' '.gemini/skills' $true 'https://geminicli.com/docs/cli/skills/' 'gemini' '.gemini/settings.json'),
  85. (New-Agent 'cursor' 'Cursor' '.cursor/skills' $true 'https://cursor.com/docs/context/skills' 'cursor' '.cursor'),
  86. (New-Agent 'copilot' 'GitHub Copilot (CLI / VS Code)' '.copilot/skills' $true 'https://docs.github.com/en/copilot/concepts/agents/about-agent-skills' 'copilot' '.copilot'),
  87. (New-Agent 'opencode' 'OpenCode' '.config/opencode/skills' $true 'https://opencode.ai/docs/skills/' 'opencode' '.config/opencode'),
  88. (New-Agent 'roo' 'Roo Code' '.roo/skills' $true 'https://docs.roocode.com/features/skills' $null '.roo'),
  89. (New-Agent 'goose' 'Goose' '.agents/skills' $true 'https://block.github.io/goose/docs/guides/context-engineering/using-skills/' 'goose' '.config/goose'),
  90. (New-Agent 'junie' 'Junie (JetBrains)' '.junie/skills' $true 'https://junie.jetbrains.com/docs/agent-skills.html' 'junie' '.junie'),
  91. (New-Agent 'amp' 'Amp' '.config/amp/skills' $true 'https://ampcode.com/docs/customize/skills' 'amp' '.config/amp')
  92. )
  93. $UniversalReaders = 'Codex, Gemini CLI, Cursor, GitHub Copilot, OpenCode, Roo Code, Goose, Junie, Amp'
  94. function Get-Agent([string]$id) { $Registry | Where-Object { $_.Id -eq $id } | Select-Object -First 1 }
  95. function Test-Detected($a) {
  96. if ($a.Cmd -and (Get-Command $a.Cmd -ErrorAction SilentlyContinue)) { return $true }
  97. return (Test-Path -LiteralPath (Under-Home $a.DetectRel))
  98. }
  99. function Get-DefaultSelection {
  100. $sel = @('universal')
  101. foreach ($id in 'claude', 'antigravity', 'antigravity-cli', 'kiro') {
  102. if (Test-Detected (Get-Agent $id)) { $sel += $id }
  103. }
  104. return $sel
  105. }
  106. function Resolve-Selection([string[]]$raw) {
  107. $out = @()
  108. foreach ($tok in (($raw -join ',') -split '[,\s]+')) {
  109. $t = $tok.Trim().ToLowerInvariant()
  110. if (-not $t) { continue }
  111. if ($t -eq 'all') { return @($Registry | ForEach-Object { $_.Id }) }
  112. if ($t -eq 'detected') { $out += Get-DefaultSelection; continue }
  113. if (-not (Get-Agent $t)) { Fail "unknown agent '$t'. Known: $(($Registry | ForEach-Object { $_.Id }) -join ', ') (or all, detected)" }
  114. $out += $t
  115. }
  116. return $out
  117. }
  118. function Resolve-Targets([string[]]$sel, [string[]]$custom) {
  119. $targets = New-Object System.Collections.ArrayList
  120. $seen = @{}
  121. $universalOn = ($sel -contains 'universal') -or ($sel -contains 'codex') -or ($sel -contains 'goose')
  122. foreach ($a in $Registry) {
  123. if ($sel -notcontains $a.Id) { continue }
  124. if ($universalOn -and -not $NoDedupe -and $a.ReadsUniversal -and ($a.Id -ne 'codex') -and ($a.Id -ne 'goose')) { continue }
  125. $k = $a.Dir.ToLowerInvariant()
  126. if ($seen.ContainsKey($k)) { continue }
  127. $seen[$k] = $true
  128. [void]$targets.Add([pscustomobject]@{ Label = $a.Label; Dir = $a.Dir })
  129. }
  130. foreach ($c in $custom) {
  131. if (-not $c) { continue }
  132. $d = Expand-UserPath $c
  133. $k = $d.ToLowerInvariant()
  134. if ($seen.ContainsKey($k)) { continue }
  135. $seen[$k] = $true
  136. [void]$targets.Add([pscustomobject]@{ Label = 'Custom'; Dir = $d })
  137. }
  138. return ,$targets.ToArray()
  139. }
  140. function Expand-UserPath([string]$p) {
  141. $p = $p.Trim().Trim('"')
  142. if ($p -eq '~') { $p = $HomeDir }
  143. elseif ($p.StartsWith('~/') -or $p.StartsWith('~\')) { $p = Join-Path $HomeDir $p.Substring(2) }
  144. $p = [IO.Path]::GetFullPath($p).TrimEnd('\', '/')
  145. # a path that already ends in the skill folder means "put it here", not "nest it again"
  146. if ((Split-Path $p -Leaf) -eq $SkillName) { $p = Split-Path $p -Parent }
  147. return $p
  148. }
  149. # ======================================================================
  150. # Wizard
  151. # ======================================================================
  152. function Test-Interactive {
  153. if ($Yes) { return $false }
  154. try { return [Environment]::UserInteractive -and -not [Console]::IsInputRedirected } catch { return $false }
  155. }
  156. function Invoke-Wizard {
  157. $sel = New-Object System.Collections.ArrayList
  158. foreach ($id in (Get-DefaultSelection)) { [void]$sel.Add($id) }
  159. $custom = ''
  160. while ($true) {
  161. Write-Host ''
  162. Write-Host 'Which agents should get the skill?' -ForegroundColor White -NoNewline
  163. Write-Host ' (* = found on this machine)' -ForegroundColor DarkGray
  164. Write-Host ''
  165. $i = 0
  166. foreach ($a in $Registry) {
  167. $i++
  168. if ($sel -contains $a.Id) { $box = '[x]'; $col = 'Green' } else { $box = '[ ]'; $col = 'Gray' }
  169. if (Test-Detected $a) { $det = ' *' } else { $det = '' }
  170. Write-Host (' {0} {1,2}) ' -f $box, $i) -ForegroundColor $col -NoNewline
  171. Write-Host ('{0,-32} ' -f $a.Label) -NoNewline
  172. Write-Host (P $a.Dir) -ForegroundColor DarkGray -NoNewline
  173. Write-Host $det -ForegroundColor Green
  174. if ($a.Id -eq 'universal') {
  175. Write-Host " read by $UniversalReaders" -ForegroundColor DarkGray
  176. Write-Host ''
  177. }
  178. }
  179. $i++
  180. if ($custom) { $box = '[x]'; $col = 'Green' } else { $box = '[ ]'; $col = 'Gray' }
  181. Write-Host (' {0} {1,2}) ' -f $box, $i) -ForegroundColor $col -NoNewline
  182. Write-Host ('{0,-32} {1}' -f 'Custom path...', $custom)
  183. Write-Host ''
  184. Write-Host ' Toggle by number (e.g. 2 3), a = all, n = none, Enter to continue.'
  185. $answer = Read-Host ' >' # not $input: that is PowerShell's automatic pipeline variable
  186. if (-not $answer) { break }
  187. foreach ($tok in ($answer -split '\s+')) {
  188. if (-not $tok) { continue }
  189. if ($tok -eq 'a') { $sel.Clear(); foreach ($a in $Registry) { [void]$sel.Add($a.Id) }; continue }
  190. if ($tok -eq 'n') { $sel.Clear(); $custom = ''; continue }
  191. $n = 0
  192. if (-not [int]::TryParse($tok, [ref]$n) -or $n -lt 1 -or $n -gt $i) { Warn "no option '$tok'"; continue }
  193. if ($n -eq $i) {
  194. if ($custom) { $custom = '' } else { $custom = Read-Host ' Skills directory (the folder that CONTAINS skill folders)' }
  195. continue
  196. }
  197. $id = $Registry[$n - 1].Id
  198. if ($sel -contains $id) { $sel.Remove($id) } else { [void]$sel.Add($id) }
  199. }
  200. }
  201. return [pscustomobject]@{ Selection = @($sel); Custom = $custom }
  202. }
  203. function Confirm-Choice([string]$q, [bool]$default = $true) {
  204. if (-not (Test-Interactive)) { return $default }
  205. if ($default) { $hint = '[Y/n]' } else { $hint = '[y/N]' }
  206. $ans = Read-Host "$q $hint"
  207. if (-not $ans) { return $default }
  208. return @('y', 'yes') -contains $ans.Trim().ToLowerInvariant()
  209. }
  210. # ======================================================================
  211. # Source
  212. # ======================================================================
  213. function Enable-Tls12 {
  214. try { [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12 } catch { }
  215. }
  216. function Get-Source([string]$work) {
  217. if ($Source) {
  218. if (-not (Test-Path -LiteralPath $Source -PathType Container)) { Fail "-Source: not a directory: $Source" }
  219. return (Resolve-Path -LiteralPath $Source).ProviderPath
  220. }
  221. Enable-Tls12
  222. $url = "https://codeload.github.com/$RepoOwner/$RepoName/zip/$Ref"
  223. $zip = Join-Path $work 'src.zip'
  224. Say "Downloading $RepoOwner/$RepoName@$Ref..."
  225. try { Invoke-WebRequest -Uri $url -OutFile $zip -UseBasicParsing }
  226. catch { Fail "download failed: $url (is -Ref '$Ref' a real branch or tag?) $($_.Exception.Message)" }
  227. $dest = Join-Path $work 'src'
  228. Expand-Archive -LiteralPath $zip -DestinationPath $dest -Force
  229. $top = @(Get-ChildItem -LiteralPath $dest -Directory)
  230. if ($top.Count -lt 1) { Fail 'the archive was empty' }
  231. return $top[0].FullName
  232. }
  233. function Test-Source([string]$src) {
  234. $skill = Join-Path $src 'SKILL.md'
  235. if (-not (Test-Path -LiteralPath $skill)) { Fail "no SKILL.md in $src -- not a $RepoName checkout" }
  236. if (-not (Test-Path -LiteralPath (Join-Path $src 'references'))) { Fail "no references\ in $src" }
  237. $line = Get-Content -LiteralPath $skill -TotalCount 15 | Where-Object { $_ -match '^name:\s*' } | Select-Object -First 1
  238. $name = ($line -replace '^name:\s*', '').Trim().Trim('"', "'")
  239. if ($name -ne $SkillName) { Fail "SKILL.md name is '$name', expected '$SkillName'" }
  240. }
  241. function Get-SkillVersion([string]$src) {
  242. try { return (Get-Content -LiteralPath (Join-Path $src 'metadata.json') -Raw | ConvertFrom-Json).version } catch { return 'unknown' }
  243. }
  244. # ======================================================================
  245. # Links -- never Remove-Item -Recurse a link: on 5.1 that can delete the TARGET's contents.
  246. # ======================================================================
  247. function Get-Entry([string]$p) {
  248. $item = Get-Item -LiteralPath $p -Force -ErrorAction SilentlyContinue
  249. if ($item) { return $item }
  250. return $null
  251. }
  252. function Get-LinkTarget($item) {
  253. if (-not $item -or -not $item.LinkType) { return $null }
  254. $t = @($item.Target)[0]
  255. if ($t) { $t = $t -replace '^\\\\\?\\', '' }
  256. return $t
  257. }
  258. function Test-SamePath([string]$a, [string]$b) {
  259. if (-not $a -or -not $b) { return $false }
  260. $a = $a.TrimEnd('\', '/'); $b = $b.TrimEnd('\', '/')
  261. if ($OnWindows) { return [string]::Equals($a, $b, [StringComparison]::OrdinalIgnoreCase) }
  262. return $a -ceq $b
  263. }
  264. function Remove-Link([string]$p) {
  265. if ($OnWindows) { [IO.Directory]::Delete($p, $false) } # removes the reparse point only
  266. else { [IO.File]::Delete($p) } # unlink(2): removes the symlink only
  267. }
  268. function Backup-Entry([string]$dest) {
  269. $rel = (Split-Path $dest -Parent) -replace '[:\\/]+', '_'
  270. $bdir = J $Store 'backups' $Stamp $rel
  271. if ($DryRun) { Dry "back up existing $dest -> $bdir"; return }
  272. New-Item -ItemType Directory -Force -Path $bdir | Out-Null
  273. $item = Get-Entry $dest
  274. if ($item.LinkType) {
  275. # record where the link pointed, then remove only the link
  276. Set-Content -LiteralPath (Join-Path $bdir "$(Split-Path $dest -Leaf).link.txt") -Value (Get-LinkTarget $item)
  277. Remove-Link $dest
  278. } else {
  279. Move-Item -LiteralPath $dest -Destination $bdir
  280. }
  281. Warn "existing $(P $dest) moved to $(P $bdir)"
  282. }
  283. function Add-Manifest([string]$mode, [string]$p) {
  284. if ($DryRun) { return }
  285. New-Item -ItemType Directory -Force -Path $Store | Out-Null
  286. $lines = @()
  287. if (Test-Path -LiteralPath $Manifest) { $lines = @(Get-Content -LiteralPath $Manifest | Where-Object { $_ -and ($_ -ne "$mode`t$p") }) }
  288. $lines += "$mode`t$p"
  289. Set-Content -LiteralPath $Manifest -Value $lines
  290. }
  291. function Install-Link([string]$dir) {
  292. $dest = Join-Path $dir $SkillName
  293. $item = Get-Entry $dest
  294. if ($item -and $item.LinkType) {
  295. $target = Get-LinkTarget $item
  296. if (Test-SamePath $target $Payload) { Ok "$(P $dest) (already linked)"; Add-Manifest 'link' $dest; return }
  297. if (-not $Force) { Warn "$(P $dest) is a link to $target -- left untouched (use -Force to replace)"; return }
  298. Backup-Entry $dest
  299. } elseif ($item) {
  300. if (Test-Path -LiteralPath (Join-Path $dest $Marker)) {
  301. if ($DryRun) { Dry "refresh managed copy $dest"; return }
  302. Remove-Item -LiteralPath $dest -Recurse -Force # a real directory we made, not a link
  303. } else {
  304. Backup-Entry $dest
  305. }
  306. }
  307. if ($DryRun) { Dry "link $dest -> $Payload"; return }
  308. New-Item -ItemType Directory -Force -Path $dir | Out-Null
  309. # ROBLOX_SKILL_LINK = symlink | junction | copy pins the method (default: try them in that order)
  310. $mode = "$env:ROBLOX_SKILL_LINK".ToLowerInvariant()
  311. if ($Copy) { $mode = 'copy' }
  312. if ($mode -ne 'copy') {
  313. if ($mode -ne 'junction') {
  314. try {
  315. New-Item -ItemType SymbolicLink -Path $dest -Target $Payload | Out-Null
  316. Ok "$(P $dest) -> store (symlink)"; Add-Manifest 'link' $dest; return
  317. } catch { }
  318. }
  319. if ($OnWindows) {
  320. # junctions need no admin rights or Developer Mode
  321. try {
  322. New-Item -ItemType Junction -Path $dest -Target $Payload | Out-Null
  323. Ok "$(P $dest) -> store (junction)"; Add-Manifest 'link' $dest; return
  324. } catch { }
  325. }
  326. }
  327. Copy-Item -LiteralPath $Payload -Destination $dest -Recurse
  328. Ok "$(P $dest) (copy -- re-run with -Update after upgrades)"
  329. Add-Manifest 'copy' $dest
  330. }
  331. function Install-Payload([string]$src, [string]$version) {
  332. Step "Installing skill into $(P $Payload)"
  333. if ($DryRun) { Dry "copy SKILL.md, metadata.json, references\ ... -> $Payload"; return }
  334. New-Item -ItemType Directory -Force -Path $Store | Out-Null
  335. $new = Join-Path $Store ".new.$PID"; $old = Join-Path $Store ".old.$PID"
  336. if (Test-Path -LiteralPath $new) { Remove-Item -LiteralPath $new -Recurse -Force }
  337. New-Item -ItemType Directory -Path $new | Out-Null
  338. foreach ($f in 'SKILL.md', 'metadata.json', 'LICENSE', 'README.md', 'CHANGELOG.md') {
  339. $p = Join-Path $src $f
  340. if (Test-Path -LiteralPath $p) { Copy-Item -LiteralPath $p -Destination $new }
  341. }
  342. Copy-Item -LiteralPath (Join-Path $src 'references') -Destination (Join-Path $new 'references') -Recurse
  343. # docs\ holds the pages README.md links to (absent in versions before 2.16.0)
  344. $docs = Join-Path $src 'docs'
  345. if (Test-Path -LiteralPath $docs) { Copy-Item -LiteralPath $docs -Destination (Join-Path $new 'docs') -Recurse }
  346. Set-Content -LiteralPath (Join-Path $new $Marker) -Value @("managed-by=$RepoName install.ps1", "version=$version", "installed=$Stamp")
  347. # swap in place: links point at $Payload, so they follow the new content automatically
  348. try {
  349. if (Test-Path -LiteralPath $Payload) { Rename-Item -LiteralPath $Payload -NewName (Split-Path $old -Leaf) }
  350. Rename-Item -LiteralPath $new -NewName $SkillName
  351. } catch {
  352. Fail "could not replace $Payload -- is an agent holding a file open? Close it and retry. ($($_.Exception.Message))"
  353. }
  354. if (Test-Path -LiteralPath $old) { Remove-Item -LiteralPath $old -Recurse -Force }
  355. $me = Join-Path $src 'install.ps1'
  356. if (Test-Path -LiteralPath $me) { Copy-Item -LiteralPath $me -Destination (Join-Path $Store 'install.ps1') -Force }
  357. Ok "Skill v$version stored"
  358. }
  359. function Warn-Legacy($targets) {
  360. $claudeDir = (Get-Agent 'claude').Dir
  361. if (-not ($targets | Where-Object { Test-SamePath $_.Dir $claudeDir })) { return }
  362. $legacy = Join-Path $claudeDir 'roblox-dev'
  363. $item = Get-Entry $legacy
  364. if (-not $item) { return }
  365. $skill = Join-Path $legacy 'SKILL.md'
  366. if (-not ((Test-Path -LiteralPath $skill) -and (Select-String -LiteralPath $skill -Pattern "^name: $SkillName" -Quiet))) { return }
  367. if ($item.LinkType) {
  368. Warn "$(P $legacy) also points to this skill (old folder name) -- Claude Code will list it twice."
  369. } else {
  370. Backup-Entry $legacy
  371. Say "that was an old install under the non-standard name 'roblox-dev'; the spec requires the folder to match the skill name"
  372. }
  373. }
  374. # ======================================================================
  375. # RobloxDocs
  376. # ======================================================================
  377. function Find-Python {
  378. foreach ($cand in @(@('py', '-3'), @('python'), @('python3'))) {
  379. if (-not (Get-Command $cand[0] -ErrorAction SilentlyContinue)) { continue }
  380. $pyArgs = @($cand | Select-Object -Skip 1)
  381. try {
  382. $oldEap = $ErrorActionPreference; $ErrorActionPreference = 'Continue'
  383. try { & $cand[0] @pyArgs -c 'import sys; sys.exit(0 if sys.version_info >= (3, 6) else 1)' 2>$null | Out-Null }
  384. finally { $ErrorActionPreference = $oldEap }
  385. if ($LASTEXITCODE -eq 0) { return , $cand } # `python3` on Windows is often a Store stub that fails here
  386. } catch { }
  387. }
  388. return $null
  389. }
  390. function Install-Docs([string]$src) {
  391. Step "Setting up $(P $DocsHome)"
  392. $py = Find-Python
  393. if (-not $py) {
  394. Warn 'Python 3 not found -- skipping RobloxDocs. The skill works without it, using web docs.'
  395. Say "Install Python 3 (https://www.python.org/downloads/), then run: & `"$(Join-Path $Store 'install.ps1')`" -DocsOnly"
  396. return
  397. }
  398. $tools = J $src 'tools' 'robloxdocs'
  399. if (-not (Test-Path -LiteralPath $tools)) { Warn 'this version has no tools\robloxdocs -- skipping'; return }
  400. if ($DryRun) { Dry "install scripts -> $DocsHome\scripts and run roblox-api-monitor.py"; return }
  401. $scripts = Join-Path $DocsHome 'scripts'
  402. New-Item -ItemType Directory -Force -Path $scripts | Out-Null
  403. $bdir = $null
  404. foreach ($f in @(Get-ChildItem -LiteralPath $tools -File | Where-Object { $_.Extension -in '.py', '.sh' })) {
  405. $dest = Join-Path $scripts $f.Name
  406. if ((Test-Path -LiteralPath $dest) -and ((Get-FileHash -LiteralPath $dest).Hash -ne (Get-FileHash -LiteralPath $f.FullName).Hash)) {
  407. if (-not $bdir) { $bdir = Join-Path $scripts ".backup-$Stamp"; New-Item -ItemType Directory -Force -Path $bdir | Out-Null }
  408. Copy-Item -LiteralPath $dest -Destination $bdir
  409. }
  410. Copy-Item -LiteralPath $f.FullName -Destination $dest -Force
  411. }
  412. if ($bdir) { Say "your previous scripts were different -- kept a copy in $(P $bdir)" }
  413. $readme = Join-Path $DocsHome 'README.md'
  414. if (-not (Test-Path -LiteralPath $readme)) { Copy-Item -LiteralPath (Join-Path $tools 'README.md') -Destination $readme }
  415. $cfg = Join-Path $DocsHome 'config'
  416. if (-not (Test-Path -LiteralPath $cfg)) {
  417. Set-Content -LiteralPath $cfg -Value @('# RobloxDocs configuration -- KEY=VALUE, parsed (never executed)',
  418. "SKILL_REFS=$(Join-Path $Payload 'references')", 'AUDIT_MODE=warn')
  419. } else { Say "kept your existing $(P $cfg)" }
  420. Ok 'Scripts installed'
  421. Step 'Downloading and splitting the Roblox API dump (one-time, ~8 MB)'
  422. $oldHome = $env:ROBLOX_DOCS_HOME; $oldEnc = $env:PYTHONIOENCODING
  423. $env:ROBLOX_DOCS_HOME = $DocsHome; $env:PYTHONIOENCODING = 'utf-8'
  424. # Windows PowerShell 5.1 turns a native program's stderr into error records when output is
  425. # redirected, and under 'Stop' the first Python warning would abort the whole installer.
  426. $oldEap = $ErrorActionPreference; $ErrorActionPreference = 'Continue'
  427. try {
  428. $pyArgs = @($py | Select-Object -Skip 1)
  429. & $py[0] @pyArgs (Join-Path $scripts 'roblox-api-monitor.py')
  430. $code = $LASTEXITCODE
  431. } finally { $env:ROBLOX_DOCS_HOME = $oldHome; $env:PYTHONIOENCODING = $oldEnc; $ErrorActionPreference = $oldEap }
  432. if ($code -eq 0) { Ok 'RobloxDocs ready' }
  433. else {
  434. Warn 'the API dump step did not finish -- the skill is installed and works without it.'
  435. Say "Retry any time: python `"$(Join-Path $scripts 'roblox-api-monitor.py')`""
  436. }
  437. }
  438. # ======================================================================
  439. # Uninstall
  440. # ======================================================================
  441. function Invoke-Uninstall {
  442. Step "Uninstalling $SkillName"
  443. $removed = 0
  444. if (Test-Path -LiteralPath $Manifest) {
  445. foreach ($line in @(Get-Content -LiteralPath $Manifest)) {
  446. if (-not $line) { continue }
  447. $mode, $p = $line -split "`t", 2
  448. $item = Get-Entry $p
  449. if (-not $item) { continue }
  450. if ($item.LinkType -and (Test-SamePath (Get-LinkTarget $item) $Payload)) {
  451. if ($DryRun) { Dry "remove link $p" } else { Remove-Link $p; Ok "removed $(P $p)" }; $removed++
  452. } elseif (-not $item.LinkType -and (Test-Path -LiteralPath (Join-Path $p $Marker))) {
  453. if ($DryRun) { Dry "remove copy $p" } else { Remove-Item -LiteralPath $p -Recurse -Force; Ok "removed $(P $p)" }; $removed++
  454. } else {
  455. Warn "$(P $p) is no longer ours -- left untouched"
  456. }
  457. }
  458. } else { Say "no manifest at $(P $Manifest)" }
  459. foreach ($p in $Payload, $Manifest, (Join-Path $Store 'install.ps1')) {
  460. if (Test-Path -LiteralPath $p) { if ($DryRun) { Dry "remove $p" } else { Remove-Item -LiteralPath $p -Recurse -Force } }
  461. }
  462. Ok "removed $removed agent link(s) and the stored skill"
  463. if (Test-Path -LiteralPath (Join-Path $Store 'backups')) { Say "backups of anything replaced during install are kept in $(P (Join-Path $Store 'backups'))" }
  464. if ($PurgeDocs -and (Test-Path -LiteralPath $DocsHome)) {
  465. if ((Test-Interactive) -and (Confirm-Choice "Delete $(P $DocsHome) including every downloaded API dump?" $false)) {
  466. foreach ($sub in 'RobloxAPI', 'scripts', 'config') {
  467. $p = Join-Path $DocsHome $sub
  468. if (Test-Path -LiteralPath $p) { if ($DryRun) { Dry "remove $p" } else { Remove-Item -LiteralPath $p -Recurse -Force } }
  469. }
  470. Ok "removed RobloxAPI\, scripts\ and config from $(P $DocsHome)"
  471. } else { Say "nothing deleted from $(P $DocsHome) (purging always asks first)" }
  472. } elseif (Test-Path -LiteralPath $DocsHome) { Say "$(P $DocsHome) was kept. Add -PurgeDocs to remove it too." }
  473. }
  474. # ======================================================================
  475. # Main
  476. # ======================================================================
  477. function Show-Help {
  478. @"
  479. roblox-dev-skill installer (PowerShell)
  480. irm https://raw.githubusercontent.com/$RepoOwner/$RepoName/master/install.ps1 | iex
  481. & ([scriptblock]::Create((irm https://raw.githubusercontent.com/$RepoOwner/$RepoName/master/install.ps1))) [options]
  482. -Agents a,b agent ids, 'detected' or 'all':
  483. $(($Registry | ForEach-Object { $_.Id }) -join ', ')
  484. -Path DIR also install into DIR (a folder that CONTAINS skill folders)
  485. -List show every supported agent and its skills folder
  486. -Yes no questions; use -Agents or the detected defaults
  487. -DryRun show what would change, change nothing
  488. -Copy copy instead of symlink/junction
  489. -Force replace an existing link that points elsewhere (it is backed up)
  490. -Ref REF branch or tag (default master) -Source DIR install from a local checkout
  491. -Docs/-NoDocs set up ~\RobloxDocs or skip it -DocsOnly only (re)install RobloxDocs
  492. -NoDedupe also link agents that already read ~/.agents/skills
  493. -Update fetch the latest skill; links follow automatically
  494. -Uninstall remove what this installer made -PurgeDocs also delete RobloxDocs data (asks)
  495. Environment (useful with `irm | iex`, which cannot take options):
  496. ROBLOX_SKILL_REF=TAG install that branch or tag instead of master
  497. ROBLOX_SKILL_LINK=MODE symlink, junction or copy
  498. "@ | Write-Host
  499. }
  500. function Show-List {
  501. Write-Host ''
  502. Write-Host ('{0,-16} {1,-32} {2,-38} {3}' -f 'ID', 'AGENT', 'USER SKILLS DIR', 'DETECTED')
  503. foreach ($a in $Registry) {
  504. if (Test-Detected $a) { $d = 'yes' } else { $d = '-' }
  505. Write-Host ('{0,-16} {1,-32} {2,-38} {3}' -f $a.Id, $a.Label, (P $a.Dir), $d)
  506. }
  507. Write-Host ''
  508. Write-Host "Paths verified against each agent's documentation (2026-09-25):"
  509. foreach ($a in $Registry) { Write-Host (' {0,-16} {1}' -f $a.Id, $a.Docs) }
  510. Write-Host ''
  511. }
  512. function Invoke-Main {
  513. if ($Help) { Show-Help; return }
  514. if ($List) { Show-List; return }
  515. Write-Host ''
  516. Write-Host ' roblox-dev-skill installer ' -ForegroundColor White
  517. Write-Host " Roblox & Luau knowledge for AI coding agents -- https://github.com/$RepoOwner/$RepoName" -ForegroundColor DarkGray
  518. if ($DryRun) { Write-Host ''; Write-Host ' DRY RUN -- nothing will be changed' -ForegroundColor Yellow }
  519. Say ("PowerShell {0} on {1}" -f $PSVersionTable.PSVersion, $(if ($OnWindows) { 'Windows' } else { [Environment]::OSVersion.Platform }))
  520. if ($Uninstall) { Invoke-Uninstall; return }
  521. $work = Join-Path ([IO.Path]::GetTempPath()) ("rds-install-" + [guid]::NewGuid().ToString('N'))
  522. New-Item -ItemType Directory -Path $work | Out-Null
  523. try {
  524. $src = Get-Source $work
  525. Test-Source $src
  526. $version = Get-SkillVersion $src
  527. if ($Source) { $from = 'local source' } else { $from = "ref $Ref" }
  528. Ok "Skill $SkillName v$version ($from)"
  529. if ($DocsOnly) { Install-Docs $src; return }
  530. $custom = @($Path)
  531. if ($Update) {
  532. $targets = @()
  533. if (Test-Path -LiteralPath $Manifest) {
  534. $targets = @(Get-Content -LiteralPath $Manifest | Where-Object { $_ } | ForEach-Object {
  535. [pscustomobject]@{ Label = 'Previous'; Dir = (Split-Path (($_ -split "`t", 2)[1]) -Parent) } })
  536. }
  537. if ($targets.Count -eq 0) { Fail "nothing to update: no previous install found in $Manifest" }
  538. $wantDocs = Test-Path -LiteralPath (J $DocsHome 'scripts' 'roblox-api-monitor.py')
  539. } else {
  540. if ($Agents) { $sel = Resolve-Selection $Agents }
  541. elseif (Test-Interactive) {
  542. $w = Invoke-Wizard
  543. $sel = $w.Selection
  544. if ($w.Custom) { $custom += $w.Custom }
  545. } else {
  546. $sel = Get-DefaultSelection
  547. Say "Non-interactive run: using detected defaults ($($sel -join ','))."
  548. }
  549. $targets = Resolve-Targets $sel $custom
  550. if ($targets.Count -eq 0) { Fail 'no agents selected -- nothing to install' }
  551. if ($Docs) { $wantDocs = $true }
  552. elseif ($NoDocs) { $wantDocs = $false }
  553. elseif (Test-Interactive) { $wantDocs = Confirm-Choice 'Also set up ~\RobloxDocs (downloads the ~8 MB Roblox API dump; needs Python 3)?' $true }
  554. else { $wantDocs = $true }
  555. }
  556. Step 'Plan'
  557. Say "Skill store: $(P $Payload)"
  558. foreach ($t in $targets) { Write-Host (' -> {0,-26} {1}' -f $t.Label, (P (Join-Path $t.Dir $SkillName))) }
  559. if ($targets | Where-Object { $_.Dir -like '*.agents*skills' }) { Say "~/.agents/skills is read by $UniversalReaders" }
  560. if ($wantDocs) { Say "RobloxDocs: $(P $DocsHome)" } else { Say 'RobloxDocs: skipped' }
  561. if (-not $Update -and (Test-Interactive)) {
  562. if (-not (Confirm-Choice 'Proceed?' $true)) { Say 'Cancelled -- nothing was changed.'; return }
  563. }
  564. Install-Payload $src $version
  565. foreach ($t in $targets) { Install-Link $t.Dir }
  566. Warn-Legacy $targets
  567. if ($wantDocs) { Install-Docs $src }
  568. Step 'Done'
  569. Say "Installed $SkillName v$version."
  570. Say 'Restart your agent(s) so they rescan their skills folders.'
  571. Write-Host ''
  572. Say "Update & ([scriptblock]::Create((irm https://raw.githubusercontent.com/$RepoOwner/$RepoName/master/install.ps1))) -Update"
  573. Say "Uninstall & `"$(Join-Path $Store 'install.ps1')`" -Uninstall" # absolute: a pasted ~ is not reliably expanded
  574. Write-Host ''
  575. } finally {
  576. Remove-Item -LiteralPath $work -Recurse -Force -ErrorAction SilentlyContinue
  577. }
  578. }
  579. try {
  580. Invoke-Main
  581. } catch {
  582. Write-Host ''
  583. Write-Host " [x] $($_.Exception.Message)" -ForegroundColor Red
  584. Write-Host ''
  585. # Only a dedicated process (install.cmd) may set an exit code; `iex` must never close the window.
  586. if ($env:ROBLOX_SKILL_EXIT_ON_ERROR -eq '1') { exit 1 }
  587. }
  588. }
install.sh · Bundled script · 745 lines · 3 findings marked
  1. #!/usr/bin/env bash
  2. # roblox-dev-skill installer — https://github.com/MSayib/roblox-dev-skill
  3. #
  4. # 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
  5. #
  6. # Installs the skill once and links it into every agent you pick, then (optionally) sets up
  7. # ~/RobloxDocs with a freshly downloaded and split Roblox API dump. No git clone needed.
  8. #
  9. # Works with bash 3.2+ (macOS default), on macOS, Linux, WSL and Git Bash for Windows.
  10. # Needs: curl or wget, tar. RobloxDocs additionally needs python3.
  11. #
  12. # Run with --help for every option.
  13. # Everything lives inside main(), which is only called on the very last line. If the download is
  14. # cut off halfway, bash sees an unterminated function and runs nothing.
  15. REPO_OWNER="MSayib"
  16. REPO_NAME="roblox-dev-skill"
  17. SKILL_NAME="roblox-dev-skill" # must equal the SKILL.md `name` and the folder name (agentskills.io spec)
  18. DEFAULT_REF="master"
  19. MARKER=".roblox-dev-skill-install" # present in every copy this installer makes; nothing else is ever removed
  20. TAB="$(printf '\t')"
  21. main() {
  22. set -Eeuo pipefail
  23. # Never die silently: any unexpected failure names the line and the command.
  24. trap 'die "unexpected failure at line $LINENO: $BASH_COMMAND"' ERR
  25. # ─── Options ────────────────────────────────────────────────────────────
  26. local REF="${ROBLOX_SKILL_REF:-$DEFAULT_REF}" SOURCE_DIR="" AGENTS_ARG="" CUSTOM_PATHS="" YES=false DRY=false
  27. local FORCE=false FORCE_COPY=false DOCS_MODE=ask ACTION=install PURGE_DOCS=false NO_DEDUPE=false
  28. if [ "${ROBLOX_SKILL_LINK:-}" = copy ]; then FORCE_COPY=true; fi
  29. while [ $# -gt 0 ]; do
  30. case "$1" in
  31. --agents) AGENTS_ARG="$2"; shift 2 ;;
  32. --agents=*) AGENTS_ARG="${1#*=}"; shift ;;
  33. --path) CUSTOM_PATHS="$CUSTOM_PATHS$2"$'\n'; shift 2 ;;
  34. --path=*) CUSTOM_PATHS="$CUSTOM_PATHS${1#*=}"$'\n'; shift ;;
  35. -y|--yes) YES=true; shift ;;
  36. --dry-run) DRY=true; shift ;;
  37. --force) FORCE=true; shift ;;
  38. --copy) FORCE_COPY=true; shift ;;
  39. --docs) DOCS_MODE=yes; shift ;;
  40. --no-docs) DOCS_MODE=no; shift ;;
  41. --docs-only) ACTION=docs-only; DOCS_MODE=yes; shift ;;
  42. --ref) REF="$2"; shift 2 ;;
  43. --ref=*) REF="${1#*=}"; shift ;;
  44. --source) SOURCE_DIR="$2"; shift 2 ;;
  45. --source=*) SOURCE_DIR="${1#*=}"; shift ;;
  46. --no-dedupe) NO_DEDUPE=true; shift ;;
  47. --update) ACTION=update; shift ;;
  48. --uninstall) ACTION=uninstall; shift ;;
  49. --purge-docs) PURGE_DOCS=true; shift ;;
  50. --list) ACTION=list; shift ;;
  51. -h|--help) usage; return 0 ;;
  52. *) die "unknown option: $1 (try --help)" ;;
  53. esac
  54. done
  55. # ─── Paths ──────────────────────────────────────────────────────────────
  56. STORE="${ROBLOX_SKILL_STORE:-${XDG_DATA_HOME:-$HOME/.local/share}/$REPO_NAME}"
  57. PAYLOAD="$STORE/$SKILL_NAME"
  58. MANIFEST="$STORE/manifest.tsv"
  59. DOCS_HOME="${ROBLOX_DOCS_HOME:-$HOME/RobloxDocs}"
  60. STAMP="$(date +%Y%m%d-%H%M%S)"
  61. TTY_OK=false
  62. if [ "$YES" = false ] && { : </dev/tty; } 2>/dev/null; then TTY_OK=true; fi
  63. setup_colors
  64. case "$ACTION" in
  65. list) list_agents; return 0 ;;
  66. uninstall) do_uninstall; return 0 ;;
  67. esac
  68. banner
  69. preflight
  70. local SRC
  71. WORK="$(mktemp -d "${TMPDIR:-/tmp}/rds-install.XXXXXX")"
  72. trap 'rm -rf "${WORK:-}"' EXIT
  73. SRC="$(obtain_source "$WORK")"
  74. validate_source "$SRC"
  75. local VERSION; VERSION="$(skill_version "$SRC")"
  76. ok "Skill $SKILL_NAME v$VERSION ($( [ -n "$SOURCE_DIR" ] && echo "local source" || echo "ref $REF"))"
  77. if [ "$ACTION" = docs-only ]; then
  78. install_docs "$SRC"
  79. return 0
  80. fi
  81. # ─── Choose targets ─────────────────────────────────────────────────────
  82. local SELECTED
  83. if [ "$ACTION" = update ]; then
  84. SELECTED="" # update re-uses the manifest; no agent selection
  85. elif [ -n "$AGENTS_ARG" ]; then
  86. SELECTED="$(parse_agents_arg "$AGENTS_ARG")"
  87. elif [ "$TTY_OK" = true ]; then
  88. SELECTED="$(wizard)"
  89. case "$SELECTED" in *"@custom:"*)
  90. CUSTOM_PATHS="$CUSTOM_PATHS${SELECTED#*@custom:}"$'\n'
  91. SELECTED="${SELECTED%%@custom:*}" ;;
  92. esac
  93. else
  94. SELECTED="$(default_selection)"
  95. if [ -n "$SELECTED" ]; then
  96. info "Non-interactive run: using detected defaults ($(echo $SELECTED | tr ' ' ','))."
  97. fi
  98. fi
  99. if [ "$DOCS_MODE" = ask ] && [ "$ACTION" = update ]; then
  100. # an update refreshes RobloxDocs only if it was set up before
  101. if [ -f "$DOCS_HOME/scripts/roblox-api-monitor.sh" ]; then DOCS_MODE=yes; else DOCS_MODE=no; fi
  102. fi
  103. if [ "$DOCS_MODE" = ask ]; then
  104. if [ "$TTY_OK" = true ]; then
  105. if confirm "Also set up ~/RobloxDocs (downloads the ~8 MB Roblox API dump; needs python3)?" y; then
  106. DOCS_MODE=yes; else DOCS_MODE=no; fi
  107. else
  108. DOCS_MODE=yes
  109. fi
  110. fi
  111. local TARGETS
  112. if [ "$ACTION" = update ]; then
  113. TARGETS="$(manifest_targets)"
  114. [ -n "$TARGETS" ] || die "nothing to update: no previous install found in $MANIFEST"
  115. else
  116. TARGETS="$(resolve_targets "$SELECTED" "$CUSTOM_PATHS")"
  117. [ -n "$TARGETS" ] || die "no agents selected — nothing to install"
  118. fi
  119. plan_summary "$TARGETS"
  120. if [ "$TTY_OK" = true ] && [ "$ACTION" != update ]; then
  121. confirm "Proceed?" y || { info "Cancelled — nothing was changed."; return 0; }
  122. fi
  123. # ─── Install ────────────────────────────────────────────────────────────
  124. install_payload "$SRC" "$VERSION"
  125. local line dir
  126. while IFS= read -r line; do
  127. [ -n "$line" ] || continue
  128. dir="${line#*$TAB}"
  129. link_into "$dir"
  130. done <<EOF
  131. $TARGETS
  132. EOF
  133. warn_legacy_installs "$TARGETS"
  134. if [ "$DOCS_MODE" = yes ]; then install_docs "$SRC"; fi
  135. finish "$TARGETS" "$VERSION"
  136. }
  137. # ════════════════════════════════════════════════════════════════════════
  138. # Agent registry. Every path below was checked against that agent's own documentation on
  139. # 2026-09-25 — see the URL in agent_docs. "Reads ~/.agents/skills" is what lets one install cover
  140. # many agents; agents that do NOT read it need their own link.
  141. # ════════════════════════════════════════════════════════════════════════
  142. AGENT_IDS="universal claude antigravity antigravity-cli kiro codex gemini cursor copilot opencode roo goose junie amp"
  143. agent_label() {
  144. case "$1" in
  145. universal) echo "Universal ~/.agents/skills" ;;
  146. claude) echo "Claude Code" ;;
  147. antigravity) echo "Antigravity (2.0 / IDE)" ;;
  148. antigravity-cli) echo "Antigravity CLI" ;;
  149. kiro) echo "Kiro" ;;
  150. codex) echo "Codex (OpenAI)" ;;
  151. gemini) echo "Gemini CLI" ;;
  152. cursor) echo "Cursor" ;;
  153. copilot) echo "GitHub Copilot (CLI / VS Code)" ;;
  154. opencode) echo "OpenCode" ;;
  155. roo) echo "Roo Code" ;;
  156. goose) echo "Goose" ;;
  157. junie) echo "Junie (JetBrains)" ;;
  158. amp) echo "Amp" ;;
  159. esac
  160. }
  161. agent_dir() {
  162. case "$1" in
  163. universal|codex|goose) echo "$HOME/.agents/skills" ;;
  164. claude) echo "$HOME/.claude/skills" ;;
  165. antigravity) echo "$HOME/.gemini/config/skills" ;;
  166. antigravity-cli) echo "$HOME/.gemini/antigravity-cli/skills" ;;
  167. kiro) echo "$HOME/.kiro/skills" ;;
  168. gemini) echo "$HOME/.gemini/skills" ;;
  169. cursor) echo "$HOME/.cursor/skills" ;;
  170. copilot) echo "$HOME/.copilot/skills" ;;
  171. opencode) echo "$HOME/.config/opencode/skills" ;;
  172. roo) echo "$HOME/.roo/skills" ;;
  173. junie) echo "$HOME/.junie/skills" ;;
  174. amp) echo "$HOME/.config/amp/skills" ;;
  175. esac
  176. }
  177. agent_docs() {
  178. case "$1" in
  179. universal) echo "https://agentskills.io/client-implementation/adding-skills-support" ;;
  180. claude) echo "https://code.claude.com/docs/en/skills" ;;
  181. antigravity|antigravity-cli) echo "https://antigravity.google/docs/skills/" ;;
  182. kiro) echo "https://kiro.dev/docs/skills/" ;;
  183. codex) echo "https://developers.openai.com/codex/skills/" ;;
  184. gemini) echo "https://geminicli.com/docs/cli/skills/" ;;
  185. cursor) echo "https://cursor.com/docs/context/skills" ;;
  186. copilot) echo "https://docs.github.com/en/copilot/concepts/agents/about-agent-skills" ;;
  187. opencode) echo "https://opencode.ai/docs/skills/" ;;
  188. roo) echo "https://docs.roocode.com/features/skills" ;;
  189. goose) echo "https://block.github.io/goose/docs/guides/context-engineering/using-skills/" ;;
  190. junie) echo "https://junie.jetbrains.com/docs/agent-skills.html" ;;
  191. amp) echo "https://ampcode.com/docs/customize/skills" ;;
  192. esac
  193. }
  194. # Agents whose documented discovery path includes ~/.agents/skills.
  195. agent_reads_universal() {
  196. case "$1" in codex|gemini|cursor|copilot|opencode|roo|goose|junie|amp) return 0 ;; *) return 1 ;; esac
  197. }
  198. UNIVERSAL_READERS="Codex, Gemini CLI, Cursor, GitHub Copilot, OpenCode, Roo Code, Goose, Junie, Amp"
  199. have() { command -v "$1" >/dev/null 2>&1; }
  200. # Detection only drives the default selection. Being wrong costs a checkbox, nothing else.
  201. agent_detected() {
  202. case "$1" in
  203. universal) [ -d "$HOME/.agents" ] ;;
  204. claude) have claude || [ -d "$HOME/.claude" ] ;;
  205. antigravity) [ -d "$HOME/.gemini/config" ] || [ -d "/Applications/Antigravity.app" ] || have antigravity ;;
  206. antigravity-cli) [ -d "$HOME/.gemini/antigravity-cli" ] ;;
  207. kiro) have kiro || [ -d "$HOME/.kiro" ] ;;
  208. codex) have codex || [ -d "$HOME/.codex" ] ;;
  209. gemini) have gemini || [ -f "$HOME/.gemini/settings.json" ] ;;
  210. cursor) have cursor || [ -d "$HOME/.cursor" ] ;;
  211. copilot) have copilot || [ -d "$HOME/.copilot" ] ;;
  212. opencode) have opencode || [ -d "$HOME/.config/opencode" ] ;;
  213. roo) [ -d "$HOME/.roo" ] ;;
  214. goose) have goose || [ -d "$HOME/.config/goose" ] ;;
  215. junie) have junie || [ -d "$HOME/.junie" ] ;;
  216. amp) have amp || [ -d "$HOME/.config/amp" ] ;;
  217. *) return 1 ;;
  218. esac
  219. }
  220. is_agent_id() { case " $AGENT_IDS " in *" $1 "*) return 0 ;; *) return 1 ;; esac; }
  221. in_list() { case " $2 " in *" $1 "*) return 0 ;; *) return 1 ;; esac; }
  222. # Universal covers nine agents in one link; add a native link only for detected agents that
  223. # do not read it.
  224. default_selection() {
  225. local sel="universal" id
  226. for id in claude antigravity antigravity-cli kiro; do
  227. if agent_detected "$id"; then sel="$sel $id"; fi
  228. done
  229. echo "$sel"
  230. }
  231. parse_agents_arg() {
  232. local raw id out=""
  233. raw="$(echo "$1" | tr ',' ' ' | tr 'A-Z' 'a-z')"
  234. for id in $raw; do
  235. case "$id" in
  236. all) out="$AGENT_IDS"; break ;;
  237. detected) out="$out $(default_selection)" ;;
  238. *) is_agent_id "$id" || die "unknown agent '$id'. Known: $AGENT_IDS (or all, detected)"
  239. out="$out $id" ;;
  240. esac
  241. done
  242. echo $out
  243. }
  244. # Turn a selection into "label<TAB>dir" lines: deduplicated by directory, and — unless
  245. # --no-dedupe — dropping agents already covered by ~/.agents/skills (otherwise they list the
  246. # skill twice).
  247. resolve_targets() {
  248. local sel="$1" custom="$2" id dir out="" seen=" " p
  249. local universal_on=false
  250. if in_list universal "$sel" || in_list codex "$sel" || in_list goose "$sel"; then universal_on=true; fi
  251. for id in $AGENT_IDS; do
  252. in_list "$id" "$sel" || continue
  253. if [ "$universal_on" = true ] && [ "$NO_DEDUPE" = false ] && [ "$id" != universal ] \
  254. && [ "$id" != codex ] && [ "$id" != goose ] && agent_reads_universal "$id"; then
  255. continue
  256. fi
  257. dir="$(agent_dir "$id")"
  258. case "$seen" in *" $dir "*) continue ;; esac
  259. seen="$seen$dir "
  260. out="$out$(agent_label "$id")$TAB$dir"$'\n'
  261. done
  262. while IFS= read -r p; do
  263. [ -n "$p" ] || continue
  264. p="$(expand_path "$p")"
  265. case "$seen" in *" $p "*) continue ;; esac
  266. seen="$seen$p "
  267. out="${out}Custom$TAB$p"$'\n'
  268. done <<EOF
  269. $custom
  270. EOF
  271. printf '%s' "$out"
  272. }
  273. expand_path() {
  274. local p="$1"
  275. # a literal "~" typed by the user (quoted, so the shell did not expand it) — matched on purpose
  276. # shellcheck disable=SC2088
  277. case "$p" in "~") p="$HOME" ;; "~/"*) p="$HOME/${p#\~/}" ;; esac
  278. case "$p" in /*|[A-Za-z]:*) ;; *) p="$PWD/$p" ;; esac
  279. # a path that already ends in the skill folder means "put it here", not "nest it again"
  280. case "$p" in */"$SKILL_NAME") p="${p%/$SKILL_NAME}" ;; esac
  281. echo "${p%/}"
  282. }
  283. # ════════════════════════════════════════════════════════════════════════
  284. # Wizard
  285. # ════════════════════════════════════════════════════════════════════════
  286. wizard() {
  287. local sel custom="" input tok i id mark det
  288. sel=" $(default_selection) "
  289. while true; do
  290. {
  291. echo ""
  292. echo "${B}Which agents should get the skill?${R} ${D}(✓ = found on this machine)${R}"
  293. echo ""
  294. i=0
  295. for id in $AGENT_IDS; do
  296. i=$((i + 1))
  297. mark="[ ]"; in_list "$id" "$sel" && mark="${G}[x]${R}"
  298. det=""; agent_detected "$id" && det=" ${G}✓${R}"
  299. printf " %s %2d) %-32s %s%s\n" "$mark" "$i" "$(agent_label "$id")" \
  300. "${D}$(pretty "$(agent_dir "$id")")${R}" "$det"
  301. if [ "$id" = universal ]; then
  302. printf " ${D}read by %s${R}\n" "$UNIVERSAL_READERS"
  303. echo ""
  304. fi
  305. done
  306. i=$((i + 1))
  307. mark="[ ]"; [ -n "$custom" ] && mark="${G}[x]${R}"
  308. printf " %s %2d) %-32s %s\n" "$mark" "$i" "Custom path…" "${D}$(echo "$custom" | tr '\n' ' ')${R}"
  309. echo ""
  310. echo " Toggle by number (e.g. ${B}2 3${R}), ${B}a${R} all, ${B}n${R} none, ${B}Enter${R} to continue."
  311. } >/dev/tty
  312. printf " > " >/dev/tty
  313. IFS= read -r input </dev/tty || input=""
  314. [ -z "$input" ] && break
  315. for tok in $input; do
  316. case "$tok" in
  317. a|A) sel=" $AGENT_IDS " ;;
  318. n|N) sel=" "; custom="" ;;
  319. *[!0-9]*) echo " ${Y}ignored '$tok'${R}" >/dev/tty ;;
  320. *)
  321. if [ "$tok" -ge 1 ] && [ "$tok" -le "$i" ]; then
  322. if [ "$tok" -eq "$i" ]; then
  323. if [ -n "$custom" ]; then custom=""; else
  324. printf " Skills directory (the folder that CONTAINS skill folders): " >/dev/tty
  325. IFS= read -r input </dev/tty || input=""
  326. [ -n "$input" ] && custom="$input"
  327. fi
  328. else
  329. id="$(echo $AGENT_IDS | cut -d' ' -f"$tok")"
  330. if in_list "$id" "$sel"; then sel="$(echo "$sel" | sed "s/ $id / /")"; else sel="$sel$id "; fi
  331. fi
  332. else echo " ${Y}no option $tok${R}" >/dev/tty; fi ;;
  333. esac
  334. done
  335. done
  336. # the wizard runs in a subshell, so custom paths travel back inside the selection string
  337. echo $sel "${custom:+@custom:$custom}"
  338. }
  339. confirm() {
  340. local q="$1" def="${2:-y}" ans hint="[Y/n]"
  341. [ "$def" = n ] && hint="[y/N]"
  342. [ "$TTY_OK" = true ] || { [ "$def" = y ]; return; }
  343. printf "\n%s %s " "$q" "$hint" >/dev/tty
  344. IFS= read -r ans </dev/tty || ans=""
  345. ans="$(echo "${ans:-$def}" | tr 'A-Z' 'a-z')"
  346. [ "$ans" = y ] || [ "$ans" = yes ]
  347. }
  348. # ════════════════════════════════════════════════════════════════════════
  349. # Source: GitHub tarball (default) or a local checkout (--source)
  350. # ════════════════════════════════════════════════════════════════════════
  351. obtain_source() {
  352. local work="$1" url tarball top
  353. if [ -n "$SOURCE_DIR" ]; then
  354. [ -d "$SOURCE_DIR" ] || die "--source: not a directory: $SOURCE_DIR"
  355. (cd "$SOURCE_DIR" && pwd)
  356. return
  357. fi
  358. url="https://codeload.github.com/$REPO_OWNER/$REPO_NAME/tar.gz/$REF"
  359. tarball="$work/src.tar.gz"
  360. # ${REF} braced: bash 3.2 in a UTF-8 locale reads a non-ASCII byte right after a name as part
  361. # of the name, so an unbraced REF followed by an ellipsis looked up a variable called
  362. # REF\xe2... and died under set -u. tests/lint/check_sources.py now rejects that pattern.
  363. info "Downloading ${REPO_OWNER}/${REPO_NAME}@${REF}…" >&2
  364. download "$url" "$tarball" || die "download failed: $url (is --ref '$REF' a real branch or tag?)"
  365. mkdir -p "$work/src"
  366. tar -xzf "$tarball" -C "$work/src" || die "could not extract the downloaded archive"
  367. for top in "$work/src"/*/; do echo "${top%/}"; return; done
  368. die "the archive was empty"
  369. }
  370. download() {
  371. if have curl; then curl -fsSL --retry 2 --max-time 120 -o "$2" "$1"
  372. elif have wget; then wget -q --timeout=120 -O "$2" "$1"
  373. else return 1; fi
  374. }
  375. validate_source() {
  376. local src="$1" name
  377. [ -f "$src/SKILL.md" ] || die "no SKILL.md in $src — not a $REPO_NAME checkout"
  378. [ -d "$src/references" ] || die "no references/ in $src"
  379. name="$(sed -n '1,15p' "$src/SKILL.md" | sed -n 's/^name:[[:space:]]*//p' | head -1 | tr -d '\r"'"'"' ')"
  380. [ "$name" = "$SKILL_NAME" ] || die "SKILL.md name is '$name', expected '$SKILL_NAME'"
  381. }
  382. skill_version() {
  383. sed -n 's/^[[:space:]]*"version":[[:space:]]*"\([^"]*\)".*/\1/p' "$1/metadata.json" 2>/dev/null | head -1
  384. }
  385. # ════════════════════════════════════════════════════════════════════════
  386. # Install
  387. # ════════════════════════════════════════════════════════════════════════
  388. # The payload is what an agent reads. Repo-only material (evals, tools, installer) stays out.
  389. install_payload() {
  390. local src="$1" version="$2" new="$STORE/.new.$$" old="$STORE/.old.$$" f
  391. step "Installing skill into $(pretty "$PAYLOAD")"
  392. if [ "$DRY" = true ]; then dry "copy SKILL.md, metadata.json, references/ … → $PAYLOAD"; return; fi
  393. mkdir -p "$STORE"
  394. rm -rf "$new"; mkdir -p "$new"
  395. for f in SKILL.md metadata.json LICENSE README.md CHANGELOG.md; do
  396. [ -f "$src/$f" ] && cp "$src/$f" "$new/"
  397. done
  398. cp -R "$src/references" "$new/references"
  399. # docs/ holds the pages README.md links to (absent in versions before 2.16.0)
  400. [ -d "$src/docs" ] && cp -R "$src/docs" "$new/docs"
  401. printf 'managed-by=%s install.sh\nversion=%s\ninstalled=%s\n' "$REPO_NAME" "$version" "$STAMP" > "$new/$MARKER"
  402. # swap in place: links point at $PAYLOAD, so they follow the new content automatically
  403. [ -e "$PAYLOAD" ] && mv "$PAYLOAD" "$old"
  404. mv "$new" "$PAYLOAD"
  405. rm -rf "$old"
  406. [ -f "$src/install.sh" ] && cp "$src/install.sh" "$STORE/install.sh" && chmod +x "$STORE/install.sh"
  407. ok "Skill v$version stored"
  408. }
  409. # Place $SKILL_NAME inside a skills directory: a symlink when possible, a marked copy otherwise.
  410. link_into() {
  411. local dir="$1" dest="$1/$SKILL_NAME" target
  412. if [ -L "$dest" ]; then
  413. target="$(readlink "$dest")"
  414. if [ "$target" = "$PAYLOAD" ]; then
  415. ok "$(pretty "$dest") ${D}(already linked)${R}"; manifest_add link "$dest"; return
  416. fi
  417. if [ "$FORCE" = false ]; then
  418. warn "$(pretty "$dest") is a symlink to $(pretty "$target") — left untouched (use --force to replace)"
  419. return
  420. fi
  421. backup_entry "$dest"
  422. elif [ -e "$dest" ]; then
  423. if [ -f "$dest/$MARKER" ]; then
  424. [ "$DRY" = true ] && { dry "refresh managed copy $dest"; return; }
  425. rm -rf "$dest"
  426. else
  427. backup_entry "$dest"
  428. fi
  429. fi
  430. if [ "$DRY" = true ]; then dry "link $dest → $PAYLOAD"; return; fi
  431. mkdir -p "$dir"
  432. if [ "$FORCE_COPY" = false ] && ln -s "$PAYLOAD" "$dest" 2>/dev/null && [ -L "$dest" ]; then
  433. ok "$(pretty "$dest") → store"
  434. manifest_add link "$dest"
  435. else
  436. # Git Bash without Developer Mode silently turns `ln -s` into a copy; handle both cases.
  437. [ -e "$dest" ] && [ ! -L "$dest" ] && rm -rf "$dest"
  438. cp -R "$PAYLOAD" "$dest"
  439. ok "$(pretty "$dest") ${D}(copy — re-run with --update after upgrades)${R}"
  440. manifest_add copy "$dest"
  441. fi
  442. }
  443. # Anything that is not ours is moved aside, never deleted. Backups live OUTSIDE every skills
  444. # directory: a backup containing SKILL.md inside a scanned folder would load as a duplicate skill.
  445. backup_entry() {
  446. local dest="$1" bdir
  447. bdir="$STORE/backups/$STAMP$(dirname "$dest" | sed 's#[:\\]#_#g')"
  448. if [ "$DRY" = true ]; then dry "back up existing $dest → $bdir/"; return; fi
  449. mkdir -p "$bdir"
  450. mv "$dest" "$bdir/"
  451. warn "existing $(pretty "$dest") moved to $(pretty "$bdir")/"
  452. }
  453. manifest_add() {
  454. [ "$DRY" = true ] && return
  455. mkdir -p "$STORE"; touch "$MANIFEST"
  456. grep -vxF "$1$TAB$2" "$MANIFEST" > "$MANIFEST.tmp" 2>/dev/null || true
  457. printf '%s\t%s\n' "$1" "$2" >> "$MANIFEST.tmp"
  458. mv "$MANIFEST.tmp" "$MANIFEST"
  459. }
  460. manifest_targets() {
  461. [ -f "$MANIFEST" ] || return 0
  462. local mode path
  463. while IFS="$TAB" read -r mode path; do
  464. [ -n "$path" ] && printf 'Previous\t%s\n' "$(dirname "$path")"
  465. done < "$MANIFEST"
  466. }
  467. # Older README instructions installed under names or paths that now cause duplicates.
  468. warn_legacy_installs() {
  469. local legacy="$HOME/.claude/skills/roblox-dev"
  470. if echo "$1" | grep -q "/.claude/skills\$" && [ -e "$legacy" ] && grep -q "^name: $SKILL_NAME" "$legacy/SKILL.md" 2>/dev/null; then
  471. if [ -L "$legacy" ]; then
  472. warn "$(pretty "$legacy") also points to this skill (old folder name) — Claude Code will list it twice. Remove it when ready: rm \"$legacy\""
  473. else
  474. backup_entry "$legacy"
  475. info "that was an old install under the non-standard name 'roblox-dev'; the spec requires the folder to match the skill name"
  476. fi
  477. fi
  478. local plugin="$HOME/.gemini/config/plugins/roblox-dev-suite/skills/$SKILL_NAME"
  479. if [ -e "$plugin" ] && echo "$1" | grep -q "/.gemini/config/skills"; then
  480. warn "Antigravity also loads this skill through your roblox-dev-suite plugin — it may appear twice."
  481. fi
  482. }
  483. # ════════════════════════════════════════════════════════════════════════
  484. # RobloxDocs
  485. # ════════════════════════════════════════════════════════════════════════
  486. find_python() {
  487. local c
  488. for c in python3 python; do
  489. if have "$c" && "$c" -c 'import sys; sys.exit(0 if sys.version_info >= (3, 6) else 1)' >/dev/null 2>&1; then
  490. echo "$c"; return 0
  491. fi
  492. done
  493. return 1
  494. }
  495. install_docs() {
  496. local src="$1" tools="$1/tools/robloxdocs" py f bdir="" cfg
  497. step "Setting up $(pretty "$DOCS_HOME")"
  498. if ! py="$(find_python)"; then
  499. warn "python3 not found — skipping RobloxDocs. The skill works without it, using web docs."
  500. info "Install Python 3, then run: bash \"$STORE/install.sh\" --docs-only"
  501. return 0
  502. fi
  503. [ -d "$tools" ] || { warn "this version has no tools/robloxdocs — skipping"; return 0; }
  504. if [ "$DRY" = true ]; then
  505. dry "install scripts → $DOCS_HOME/scripts/ and run roblox-api-monitor.sh"; return 0
  506. fi
  507. mkdir -p "$DOCS_HOME/scripts"
  508. for f in "$tools"/*; do
  509. local name; name="$(basename "$f")"
  510. # only the tools themselves — never caches or other stray files from a local checkout
  511. [ -f "$f" ] || continue
  512. case "$name" in *.py|*.sh) ;; *) continue ;; esac
  513. if [ -f "$DOCS_HOME/scripts/$name" ] && ! cmp -s "$f" "$DOCS_HOME/scripts/$name"; then
  514. [ -n "$bdir" ] || { bdir="$DOCS_HOME/scripts/.backup-$STAMP"; mkdir -p "$bdir"; }
  515. cp "$DOCS_HOME/scripts/$name" "$bdir/"
  516. fi
  517. cp "$f" "$DOCS_HOME/scripts/$name"
  518. case "$name" in *.sh|*.py) chmod +x "$DOCS_HOME/scripts/$name" ;; esac
  519. done
  520. [ -n "$bdir" ] && info "your previous scripts were different — kept a copy in $(pretty "$bdir")"
  521. [ -f "$DOCS_HOME/README.md" ] || cp "$tools/README.md" "$DOCS_HOME/README.md"
  522. cfg="$DOCS_HOME/config"
  523. if [ ! -f "$cfg" ]; then
  524. # Under Git Bash / Cygwin the Python that reads this file is a native Windows program: it cannot
  525. # resolve "/c/Users/…" or "/tmp/…". MSYS converts paths in arguments and environment variables,
  526. # never in file contents — so write a native path ourselves.
  527. local refs="$PAYLOAD/references"
  528. if have cygpath; then refs="$(cygpath -m "$refs")"; fi
  529. printf '# RobloxDocs configuration — KEY=VALUE, parsed (never sourced)\nSKILL_REFS=%s\nAUDIT_MODE=warn\n' \
  530. "$refs" > "$cfg"
  531. else
  532. info "kept your existing $(pretty "$cfg")"
  533. fi
  534. ok "Scripts installed"
  535. step "Downloading and splitting the Roblox API dump (one-time, ~8 MB)"
  536. if ROBLOX_DOCS_HOME="$DOCS_HOME" "$py" "$DOCS_HOME/scripts/roblox-api-monitor.py"; then
  537. ok "RobloxDocs ready"
  538. else
  539. warn "the API dump step did not finish — the skill is installed and works without it."
  540. info "Retry any time: ~/RobloxDocs/scripts/roblox-api-monitor.sh"
  541. fi
  542. }
  543. # ════════════════════════════════════════════════════════════════════════
  544. # Uninstall
  545. # ════════════════════════════════════════════════════════════════════════
  546. do_uninstall() {
  547. banner
  548. step "Uninstalling $SKILL_NAME"
  549. local mode path removed=0
  550. if [ -f "$MANIFEST" ]; then
  551. while IFS="$TAB" read -r mode path; do
  552. [ -n "$path" ] || continue
  553. if [ "$mode" = link ] && [ -L "$path" ] && [ "$(readlink "$path")" = "$PAYLOAD" ]; then
  554. run rm "$path"; [ "$DRY" = true ] || ok "removed $(pretty "$path")"; removed=$((removed + 1))
  555. elif [ -d "$path" ] && [ -f "$path/$MARKER" ]; then
  556. run rm -rf "$path"; [ "$DRY" = true ] || ok "removed $(pretty "$path")"; removed=$((removed + 1))
  557. elif [ -e "$path" ] || [ -L "$path" ]; then
  558. warn "$(pretty "$path") is no longer ours — left untouched"
  559. fi
  560. done < "$MANIFEST"
  561. else
  562. info "no manifest at $(pretty "$MANIFEST")"
  563. fi
  564. run rm -rf "$PAYLOAD" "$MANIFEST" "$STORE/install.sh"
  565. ok "removed $removed agent link(s) and the stored skill"
  566. [ -d "$STORE/backups" ] && info "backups of anything replaced during install are kept in $(pretty "$STORE/backups")"
  567. if [ "$PURGE_DOCS" = true ]; then
  568. if [ -d "$DOCS_HOME" ] && confirm "Delete $(pretty "$DOCS_HOME") including every downloaded API dump?" n; then
  569. run rm -rf "$DOCS_HOME/RobloxAPI" "$DOCS_HOME/scripts" "$DOCS_HOME/config"
  570. ok "removed RobloxAPI/, scripts/ and config from $(pretty "$DOCS_HOME")"
  571. elif [ "$YES" = true ] && [ -d "$DOCS_HOME" ]; then
  572. info "--purge-docs with --yes still asks for confirmation; nothing deleted from $(pretty "$DOCS_HOME")"
  573. fi
  574. elif [ -d "$DOCS_HOME" ]; then
  575. info "$(pretty "$DOCS_HOME") was kept. Add --purge-docs to remove it too."
  576. fi
  577. }
  578. # ════════════════════════════════════════════════════════════════════════
  579. # Output
  580. # ════════════════════════════════════════════════════════════════════════
  581. setup_colors() {
  582. if [ -t 1 ] && [ -z "${NO_COLOR:-}" ] && [ "${TERM:-dumb}" != dumb ]; then
  583. B=$'\033[1m'; D=$'\033[2m'; G=$'\033[32m'; Y=$'\033[33m'; RD=$'\033[31m'; C=$'\033[36m'; R=$'\033[0m'
  584. else B=""; D=""; G=""; Y=""; RD=""; C=""; R=""; fi
  585. }
  586. B=""; D=""; G=""; Y=""; RD=""; C=""; R=""
  587. info() { printf ' %s\n' "$*"; }
  588. ok() { printf ' %s✓%s %s\n' "$G" "$R" "$*"; }
  589. warn() { printf ' %s!%s %s\n' "$Y" "$R" "$*"; }
  590. step() { printf '\n%s▸ %s%s\n' "$C$B" "$*" "$R"; }
  591. dry() { printf ' %s[dry-run]%s %s\n' "$Y" "$R" "$*"; }
  592. die() { printf '\n %s✗ %s%s\n\n' "$RD" "$*" "$R" >&2; exit 1; }
  593. run() { if [ "$DRY" = true ]; then dry "$*"; else "$@"; fi; }
  594. pretty() { case "$1" in "$HOME"|"$HOME"/*) echo "~${1#"$HOME"}" ;; *) echo "$1" ;; esac; }
  595. banner() {
  596. printf '\n%s roblox-dev-skill installer %s\n' "$B" "$R"
  597. printf '%s Roblox & Luau knowledge for AI coding agents — %s%s\n' "$D" "https://github.com/$REPO_OWNER/$REPO_NAME" "$R"
  598. [ "$DRY" = true ] && printf '\n %sDRY RUN — nothing will be changed%s\n' "$Y" "$R"
  599. return 0
  600. }
  601. preflight() {
  602. local os
  603. os="$(uname -s 2>/dev/null || echo unknown)"
  604. case "$os" in
  605. Darwin) os="macOS" ;;
  606. Linux) grep -qi microsoft /proc/version 2>/dev/null && os="Linux (WSL)" || os="Linux" ;;
  607. MINGW*|MSYS*|CYGWIN*) os="Windows ($os)" ;;
  608. esac
  609. have curl || have wget || die "curl or wget is required"
  610. have tar || [ -n "$SOURCE_DIR" ] || die "tar is required"
  611. info "${D}$os · bash ${BASH_VERSION%%(*}${R}"
  612. }
  613. plan_summary() {
  614. local label dir
  615. step "Plan"
  616. info "Skill store: $(pretty "$PAYLOAD")"
  617. while IFS="$TAB" read -r label dir; do
  618. [ -n "$dir" ] || continue
  619. printf ' %s→%s %-26s %s\n' "$G" "$R" "$label" "$(pretty "$dir")/$SKILL_NAME"
  620. done <<EOF
  621. $1
  622. EOF
  623. if echo "$1" | grep -q "/.agents/skills"; then
  624. info "${D}~/.agents/skills is read by $UNIVERSAL_READERS${R}"
  625. fi
  626. info "RobloxDocs: $( [ "$DOCS_MODE" = yes ] && pretty "$DOCS_HOME" || echo "skipped")"
  627. }
  628. list_agents() {
  629. printf '\n%-16s %-32s %-40s %s\n' "ID" "AGENT" "USER SKILLS DIR" "DETECTED"
  630. local id
  631. for id in $AGENT_IDS; do
  632. printf '%-16s %-32s %-40s %s\n' "$id" "$(agent_label "$id")" "$(pretty "$(agent_dir "$id")")" \
  633. "$(agent_detected "$id" && echo yes || echo -)"
  634. done
  635. printf '\nPaths verified against each agent'"'"'s documentation (2026-09-25). Sources:\n'
  636. for id in $AGENT_IDS; do printf ' %-16s %s\n' "$id" "$(agent_docs "$id")"; done
  637. echo
  638. }
  639. finish() {
  640. step "Done"
  641. info "Installed $SKILL_NAME v$2."
  642. info "Restart your agent(s) so they rescan their skills folders."
  643. echo ""
  644. 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
  645. # absolute path: a quoted "~/…" is not expanded by the shell, so a pasted command would fail
  646. info "${B}Uninstall${R} bash \"$STORE/install.sh\" --uninstall"
  647. [ "$DOCS_MODE" = yes ] && info "${B}Refresh API${R} ~/RobloxDocs/scripts/roblox-api-monitor.sh"
  648. echo ""
  649. }
  650. usage() {
  651. cat <<USAGE
  652. roblox-dev-skill installer
  653. 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
  654. curl -fsSL …/install.sh | bash -s -- [options]
  655. Interactive by default: pick agents from a list. Without a terminal it installs to the
  656. detected defaults.
  657. Choosing agents
  658. --agents LIST comma-separated ids, 'detected', or 'all'. Ids:
  659. $(echo $AGENT_IDS | fold -s -w 60 | sed '2,$s/^/ /')
  660. --path DIR also install into DIR (a folder that contains skill folders); repeatable
  661. --list show every supported agent, its skills folder, and whether it was detected
  662. --no-dedupe also link agents that already read ~/.agents/skills (they will list it twice)
  663. Behaviour
  664. -y, --yes no questions; use --agents or the detected defaults
  665. --dry-run show what would change, change nothing
  666. --copy copy instead of symlink (default: symlink, falling back to copy)
  667. --force replace an existing symlink that points somewhere else (it is backed up)
  668. --ref REF install a branch or tag (default: $DEFAULT_REF)
  669. --source DIR install from a local checkout instead of GitHub
  670. RobloxDocs (local Roblox API reference, needs python3)
  671. --docs / --no-docs set up ~/RobloxDocs or skip it (default: ask; yes when non-interactive)
  672. --docs-only only (re)install ~/RobloxDocs
  673. Maintenance
  674. --update fetch the latest skill; existing links follow automatically
  675. --uninstall remove every link/copy this installer made (nothing else)
  676. --purge-docs with --uninstall: also delete ~/RobloxDocs data (asks first)
  677. Environment
  678. ROBLOX_SKILL_REF default for --ref (e.g. a tag) — handy when options cannot be passed
  679. ROBLOX_SKILL_LINK copy = same as --copy
  680. ROBLOX_SKILL_STORE, ROBLOX_DOCS_HOME, XDG_DATA_HOME, NO_COLOR
  681. USAGE
  682. }
  683. main "$@"

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.