@roku-sdk/ai 0.0.0-stage → 2.19.0

package/skills-manifest.json

@@ -0,0 +1,316 @@
+{
+  "version": 1,
+  "skills": [
+    {
+      "name": "focus-management",
+      "description": "Use when D-pad focus in an RSG SDK TypeScript app has to be wired or is not behaving \u2014 reaching for FocusBoundary or useFocusable, deciding where an OK press on the focused item is handled, showing focus state on a row or list and dimming the items that are not focused, handing focus between regions built out of FocusBoundary, holding focus inside a dialog, or focus that lands on the wrong node. Not for a region a FlexGrid owns: that grid claims the movement keys itself, so its edges and its focus belong to the flex-grid skill.",
+      "triggers": [
+        "focus",
+        "FocusBoundary",
+        "useFocusable",
+        "D-pad navigation"
+      ],
+      "path": "skills/focus-management/SKILL.md",
+      "references": [
+        "skills/focus-management/references/focus-recipes.md"
+      ]
+    },
+    {
+      "name": "flex-grid",
+      "description": "Use when the request names a FlexGrid, or asks for the virtualized shelf and poster-grid renderer @roku-sdk/flex-grid provides \u2014 creating one with defineFlexGrid or createFlexGrid, the config it requires, filling its rows in as they load, a FlexGrid that renders but receives no key press or whose initialFocus never resolves, a grid nested inside another grid's cell, moving focus from a grid edge to a nav bar or sibling region, and its focus-highlight, zoom and row-title plugins. Everything a grid owns is here, including its focus and its edges. Not for a list, menu or row built by hand out of FocusBoundary and useFocusable \u2014 including dimming the items of one that are not focused.",
+      "triggers": [
+        "FlexGrid",
+        "createFlexGrid",
+        "defineFlexGrid",
+        "shelf"
+      ],
+      "path": "skills/flex-grid/SKILL.md",
+      "references": [
+        "skills/flex-grid/references/focus-integration.md",
+        "skills/flex-grid/references/plugins.md"
+      ]
+    },
+    {
+      "name": "testing",
+      "description": "Use when a test for an RSG SDK TypeScript component has to be written, read or fixed \u2014 what app authors usually call a unit test, though children render for real \u2014 rendering a component with render and TestAnchorNode, finding what it built by tag or by prop value, driving a key press through it, snapshotting the rendered tree, or a test whose assertion reads a value from before the update it is asserting on. Not for proving anything on real hardware, and not for a web component test: this renders into an in-process node tree, so its queries are over SceneGraph tags and props rather than a DOM.",
+      "triggers": [
+        "testing-library",
+        "TestAnchorNode",
+        "getByProp",
+        "fireEvent"
+      ],
+      "path": "skills/testing/SKILL.md",
+      "references": [
+        "skills/testing/references/async-and-timing.md"
+      ]
+    },
+    {
+      "name": "sdk-components",
+      "description": "Use when the question is which @roku-sdk/components component draws a thing on screen in an RSG SDK TypeScript app, or how one is composed \u2014 a block of text, an image, a row of buttons, a busy indicator, a confirmation or alert dialog built from a StandardDialog and the named StdDlg area nodes that go inside it, layout with Group, LayoutGroup or MaskGroup, and which props a component needs before it renders anything at all. Not for a virtualized shelf or poster grid, not for focus, movement or the state that dims an unfocused item, and not for a Dynamic Component Library loaded at runtime, which the app-packaging skill routes.",
+      "triggers": [
+        "@roku-sdk/components",
+        "Poster",
+        "StandardDialog",
+        "LayoutGroup"
+      ],
+      "path": "skills/sdk-components/SKILL.md",
+      "references": [
+        "skills/sdk-components/references/dialogs.md",
+        "skills/sdk-components/references/scenegraph-node-spelling.md"
+      ]
+    },
+    {
+      "name": "mcp-ai-dev-loop",
+      "description": "Use when an RSG SDK TypeScript app has to be built, deployed, driven or diagnosed on a real Roku through the SDK's MCP server \u2014 sideloading a build and knowing which directory it came from, a device still running older code than the source after a tool built and installed it, capturing what is on screen, reading the rendered node tree, sending remote keys, collecting device logs, turning a crash stack back into TypeScript source, asking from inside a working session whether the server those tools depend on is up, a tool call that answered from the wrong Roku because of the target it was given, or starting and stopping a billed Roku Cloud Emulator device with device_start and device_stop. Not for the Roku developer web interface, not for debugging a web or mobile app, and not for a shell script or CI job with no agent in it, which is the cli-dev-loop skill.",
+      "triggers": [
+        "MCP",
+        "capture_screen",
+        "get_server_health",
+        "decode_stack_trace"
+      ],
+      "path": "skills/mcp-ai-dev-loop/SKILL.md",
+      "references": [
+        "skills/mcp-ai-dev-loop/references/crash-and-console.md",
+        "skills/mcp-ai-dev-loop/references/live-debugging.md"
+      ]
+    },
+    {
+      "name": "app-performance",
+      "description": "Use when an RSG SDK TypeScript app janks, drops frames, responds late, or its memory climbs the longer it runs on a real Roku, and the question is how to measure it \u2014 recording a Perfetto trace and the order the calls have to happen in, reading which thread and which interval actually blocks, attributing the inside of a slow window to the TypeScript that ran there, and reading how much JS heap the running app holds with cdp_heap_usage, including why the debug build that read needs makes its timings incomparable with a normal run. What retains that heap is cpu-and-heap-profiling. Not for the everyday deploy-and-inspect loop, not for a slow build, not for making a test reliable whether or not it runs on hardware, and not for a component's own API once a trace has named it.",
+      "triggers": [
+        "perfetto",
+        "perfetto_start",
+        "jank",
+        "cdp_heap_usage"
+      ],
+      "path": "skills/app-performance/SKILL.md"
+    },
+    {
+      "name": "cpu-and-heap-profiling",
+      "description": "Use when an RSG SDK TypeScript app's CPU time or heap has to be attributed \u2014 which JavaScript function is hot, or which objects and call sites hold the heap \u2014 recording a CPU profile, heap snapshot or allocation sample through the server's CDP session, making frames readable rather than minified, driving the app between start and stop, reading the .cpuprofile, .heapprofile or .heapsnapshot that lands on disk, and profiling while also evaluating expressions in the same session, which a debugger tool having run on that session makes impossible. Not the heap's size alone, which app-performance reads with cdp_heap_usage; not frame drops, jank or a render-thread question, which is app-performance; not a crash stack, which is mcp-ai-dev-loop; and not missing MCP tools, which is mcp-setup.",
+      "triggers": [
+        "cdp_profile_start",
+        "cdp_heap_snapshot",
+        "cpuprofile",
+        "heapsnapshot",
+        "cdp_heap_sampling_start",
+        "heapprofile"
+      ],
+      "path": "skills/cpu-and-heap-profiling/SKILL.md",
+      "references": [
+        "skills/cpu-and-heap-profiling/references/reading-profiles.md"
+      ]
+    },
+    {
+      "name": "mcp-setup",
+      "description": "Use when the SDK's MCP tools are missing from an agent session, will not connect, or have to be configured for the first time \u2014 choosing between the editor spawning the server and running it persistently, the config entry that does either, starting a server and finding the port it chose, and reading the failure when no tools appear at all. Not for a session whose tools already answer: one call failing over targeting, a device or the app, asking from inside that session whether the backing server is up, and everything after that \u2014 deploying, capturing the screen, driving the app, reading logs \u2014 belongs to the mcp-ai-dev-loop skill.",
+      "triggers": [
+        "mcp.json",
+        "rk mcp",
+        "mcpServers",
+        "rk server"
+      ],
+      "path": "skills/mcp-setup/SKILL.md"
+    },
+    {
+      "name": "sdk-installation",
+      "description": "Use when @roku-sdk packages must be installed from npmjs.com or their versions have to move \u2014 public pnpm installs that need no token, an install that succeeds locally but fails in CI, a package publishing major lines under separate dist-tags, a peer dependency an SDK package requires the app to declare, and checking registry configuration and the lockfile to prove where packages resolve. Not for a package the app lists because its own code imports it, or how a scaffolded app is configured, which is the project-setup skill's subject.",
+      "triggers": [
+        "npmjs.com",
+        "registry",
+        "dist-tag",
+        "pnpm add"
+      ],
+      "path": "skills/sdk-installation/SKILL.md"
+    },
+    {
+      "name": "project-setup",
+      "description": "Use when an RSG SDK TypeScript app has to be created or its project-level configuration is wrong \u2014 scaffolding a new app, what roku-config.ts owns (title, version, splash, manifest entries, and dtsOptions such as includeDefaults when declaration generation does not recognise an XML base), the app's tsconfig.json, which @roku-sdk packages the app must list because its own code imports them, what the scaffold's .gitignore covers after rk create, or where a file such as an image has to live before it can be imported in code. Not for resolving SDK packages from npmjs.com, which version line installs, or a peer an SDK package requires the app to declare, which is the sdk-installation skill's subject.",
+      "triggers": [
+        "roku-config",
+        "scaffold",
+        "tsconfig",
+        "rk create"
+      ],
+      "path": "skills/project-setup/SKILL.md",
+      "references": [
+        "skills/project-setup/references/roku-config.md"
+      ]
+    },
+    {
+      "name": "app-packaging",
+      "description": "Use when a built RSG SDK TypeScript app has to be signed, published, or cleared off a device \u2014 producing a signed .pkg and the password tiers a CI job with no terminal is left with, rekeying a box to a different signing key, getting a new version onto a channel for review or live (publishing to a channel is done in the Roku Developer Dashboard; the SDK has no command for it), listing or removing the dev channel and the Dynamic Component Libraries a device holds, and where setting a library up and referencing a node from it is documented once a partner ships that library separately and the app loads it from a URL at runtime. Not for installing @roku-sdk packages from npmjs.com, which is the sdk-installation skill's subject; not for producing the build that then gets signed, which is the cli-dev-loop skill; and not for what roku-config.ts declares about the app, which project-setup owns.",
+      "triggers": [
+        "rk package",
+        "rk dcl",
+        "squashfs"
+      ],
+      "path": "skills/app-packaging/SKILL.md"
+    },
+    {
+      "name": "device-management",
+      "description": "Use when the rk CLI's own list of Rokus is wrong, or a shell command has to be pointed at a different one \u2014 registering a device, storing its developer password and keeping the file that holds it out of a shared repository, choosing which registered device is active, overriding the target for a single command and why --device and --host cannot be combined, where roku-dev-config.json is looked up and which copy of it wins, rk device ls listing a device that no config file seems to mention, and registering, starting or stopping a Roku Cloud Emulator device named rce:<name>. Not for an agent session whose MCP tools already answer: a tool call that reached the wrong box carries its own target argument, and that is the mcp-ai-dev-loop skill. Not for what gets run against the device once it answers \u2014 building, sideloading, driving it or reading its logs is the cli-dev-loop skill \u2014 and not for leasing a device out of a shared pool, which needs internal tooling the partner CLI does not ship.",
+      "triggers": [
+        "rk device",
+        "roku-dev-config",
+        "set-active",
+        "--device"
+      ],
+      "path": "skills/device-management/SKILL.md"
+    },
+    {
+      "name": "cli-dev-loop",
+      "description": "Use when an RSG SDK TypeScript app has to be built, installed, driven and observed from a shell script or a CI job, with no agent session in it \u2014 rk build and rk dev writing to different directories while rk dev --no-build reads only one of them, rk start-dev and top-level rk sideload surviving as deprecated aliases, there being no rk deploy, a dev build with no Roku on hand, which commands refuse to run without rk server, a flag one build command accepts and the other rejects, flags rejected as the wrong half of --no-build or --no-sideload, sending remote keys or capturing the screen from a script, and collecting device logs or decoding a crash stack once the run is over. Not for an agent session whose MCP tools already answer \u2014 that is the mcp-ai-dev-loop skill, which reaches the same operations through tool calls; not for what the running app costs in frames, memory or startup time, which is app-performance; and not for registering a Roku or choosing which one commands reach, which is device-management.",
+      "triggers": [
+        "rk build",
+        "rk dev",
+        "rk start-dev",
+        "rk sideload",
+        "rk ecp"
+      ],
+      "path": "skills/cli-dev-loop/SKILL.md",
+      "references": [
+        "skills/cli-dev-loop/references/logs-and-crashes.md"
+      ]
+    },
+    {
+      "name": "solid-on-roku",
+      "description": "Use when SolidJS code in an RSG SDK TypeScript app has to match what this platform ships rather than what the framework documents \u2014 an import of createDeferred, lazy or SuspenseList that @roku-sdk/solid deliberately does not re-export because the Roku runtime cannot support it, why reading the anchor node's inputs whole subscribes an effect to every field and what the untrack there is for, a let or const inside a loop behaving as if it were var, a generator function the build will not transform, a development build whose createSignal is not the one the release build runs, and whether Show needs a fallback. Not for handling something that threw, which is the logging-and-errors skill; not for a stale read in a test assertion, which is testing; and not for which component draws a thing or how focus and keys are wired, which are sdk-components and focus-management.",
+      "triggers": [
+        "@roku-sdk/solid",
+        "createSignal",
+        "createEffect",
+        "untrack"
+      ],
+      "path": "skills/solid-on-roku/SKILL.md",
+      "references": [
+        "skills/solid-on-roku/references/hermes-and-exports.md"
+      ]
+    },
+    {
+      "name": "logging-and-errors",
+      "description": "Use when an RSG SDK TypeScript app has to report what it is doing, or has to survive something throwing \u2014 the logger the SDK exports and the thunk its methods take, a level raised at runtime that recovers nothing because the build already deleted the call sites, log levels set through buildVariables that silently change nothing, console calls present in development and gone from a production build, a screen that comes up blank with no crash and no stack because a root component threw, containing that with ErrorBoundary and recovering with catchError or resetErrorBoundaries, registering an uncaught-exception handler and what it never sees, and calling enableExceptionTagging in main() so the running app marks its own traces.",
+      "triggers": [
+        "logger",
+        "baseLogLevel",
+        "enableExceptionTagging",
+        "setUncaughtExceptionHandler"
+      ],
+      "path": "skills/logging-and-errors/SKILL.md",
+      "references": [
+        "skills/logging-and-errors/references/uncaught-exceptions.md"
+      ]
+    },
+    {
+      "name": "fonts-and-glyphs",
+      "description": "Use when text in an RSG SDK TypeScript app needs a typeface or a symbol and the wrong thing renders \u2014 an arrow, chevron, star or check mark taken from the RokuFont01 constants instead of a Unicode character the firmware may not have, text coming out as empty boxes, symbols that disappeared once the app shipped a font of its own, whether fallbackGlyph does anything about that, importing a .ttf or .otf and the build refusing two files that share a name, a typeface that renders unreadably small because its size was left at the default, and a SimpleLabel whose fontSize is ignored because the built-in font name it was given is a fixed-size one.",
+      "triggers": [
+        "RokuFont01",
+        "glyphs",
+        "@roku-sdk/components/glyphs",
+        "fallbackGlyph"
+      ],
+      "path": "skills/fonts-and-glyphs/SKILL.md",
+      "references": [
+        "skills/fonts-and-glyphs/references/glyph-tables.md"
+      ]
+    },
+    {
+      "name": "dialogs-and-modals",
+      "description": "Use when a dialog in an RSG SDK TypeScript app has to be opened, closed and sequenced rather than assembled \u2014 an app-level provider that owns which dialog is showing, carrying a close reason back so the caller can branch on how it was dismissed, chaining a multi-step flow such as terms then entry then confirmation, a loading dialog that has to come down when the request it covers resolves, and a determinate progress dialog driven from app state. Not which component draws it, or which StdDlg area and item types go inside one, which is the sdk-components skill; and not holding D-pad focus inside a self-drawn overlay or deciding which keys close it, which is focus-management.",
+      "triggers": [
+        "DialogContext",
+        "StdDlgProgressItem",
+        "dialog lifecycle",
+        "StandardProgressDialog"
+      ],
+      "path": "skills/dialogs-and-modals/SKILL.md"
+    },
+    {
+      "name": "screen-navigation",
+      "description": "Use when an RSG SDK TypeScript app has to move between whole screens \u2014 mounting ScreenControllerProvider with the fallback it requires, pushing and popping a stack whose lower entries stay mounted, replacing the current screen instead of stacking it, releasing work when a screen is covered and restoring it when it is uncovered, passing data into a screen, and a pushed screen that shows the one underneath through it because the controller paints no background of its own. Not focus or D-pad movement once a screen is up, which is focus-management; and not the app's layout or which packages it declares, which is project-setup.",
+      "triggers": [
+        "pushScreen",
+        "popScreen",
+        "ScreenControllerProvider",
+        "onScreenCovered"
+      ],
+      "path": "skills/screen-navigation/SKILL.md"
+    },
+    {
+      "name": "user-accounts-and-purchases",
+      "description": "Use when an RSG SDK TypeScript app has to sign a viewer in, remember them across devices, or sell them something through ChannelStore \u2014 setting a data field, registering the result handler and only then setting command, reading the viewer's Roku account details, storing and retrieving channel credentials so a second device signs in without typing, fetching the product catalog, placing an order, listing what the viewer already owns, and requesting a device attestation token. Not signing a build, publishing it, or the beta channel, which is app-packaging; not SDK package installation, which is sdk-installation; and not a Roku's developer password, which is device-management.",
+      "triggers": [
+        "ChannelStore",
+        "getChannelCred",
+        "storeChannelCredData",
+        "getDeviceAttestationToken"
+      ],
+      "path": "skills/user-accounts-and-purchases/SKILL.md"
+    },
+    {
+      "name": "fetch-and-data-loading",
+      "description": "Use when an RSG SDK TypeScript app has to load data over the network \u2014 calling fetch with the single argument this runtime accepts rather than the two-argument form the web uses and which still compiles here, checking ok because a 4xx or 5xx resolves instead of rejecting, reading a typed body out of json, building a Request when a method or headers are needed, pointing HttpsAgent at a custom certificate file, and asking isFeatureSupported before relying on an optional capability. Not when the rows of a FlexGrid fill in, which that grid owns; and not scaffolding or which packages an app declares, which is project-setup.",
+      "triggers": [
+        "fetch",
+        "HttpsAgent",
+        "ResponseInstance",
+        "setGlobalAgent"
+      ],
+      "path": "skills/fetch-and-data-loading/SKILL.md",
+      "references": [
+        "skills/fetch-and-data-loading/references/https-and-certificates.md"
+      ]
+    },
+    {
+      "name": "data-entry-keyboards",
+      "description": "Use when a viewer has to type something into an RSG SDK TypeScript app \u2014 wiring CustomKeyboard, DynamicKeyboard, DynamicKeyGrid, DynamicMiniKeyboard or DynamicPinPad, reading what was entered as it changes, authoring a .keyboard.json definition with several modes for another language or a caps state, masking a PIN as it is typed, and a search field that filters while the viewer types. Not which pre-assembled dialog wraps one, or how a StandardDialog is composed from areas and items, which is sdk-components; and not remote key routing or where focus sits, which is focus-management.",
+      "triggers": [
+        "CustomKeyboard",
+        "DynamicPinPad",
+        "DynamicKeyGrid",
+        "keyboard.json"
+      ],
+      "path": "skills/data-entry-keyboards/SKILL.md"
+    },
+    {
+      "name": "slideshow",
+      "description": "Use when an RSG SDK TypeScript app shows one thing at a time and transitions between them \u2014 a hero banner, a full-screen image carousel, an onboarding or promo pager \u2014 built with @roku-sdk/slideshow: choosing among createSlideshow, createVirtualSlideshow and createPooledSlideshow, the JSX defineSlideshow wrapper that only wraps the eager one, slideFocusId and making a slide focusable, a pooled slideshow whose recycled templates can never take focus and how one entry in it is made reachable with the remote anyway, handing focus back to a sibling region at the first or last slide, and the DefaultChevrons and DefaultDotIndicator chrome. Not a row, shelf, poster grid or any screen that scrolls through many items at once, which is flex-grid; not which node draws the picture or the text inside a slide, which is sdk-components; and never video playback or the handoff from one video to the next, which this package has no part in.",
+      "triggers": [
+        "createSlideshow",
+        "createVirtualSlideshow",
+        "createPooledSlideshow",
+        "slideFocusId"
+      ],
+      "path": "skills/slideshow/SKILL.md",
+      "references": [
+        "skills/slideshow/references/focus-and-handoff.md"
+      ]
+    },
+    {
+      "name": "ads-and-raf",
+      "description": "Use when an RSG SDK TypeScript app has to play ads through the Roku Advertising Framework with @roku-sdk/ads \u2014 waiting for the Ads task to report ready before issuing anything, setting the data fields first and command last, and reading each result off its own callback; choosing between CSAI, SSAI and CSAS and the command sequence each needs; the roku_ads_lib manifest entry without which RAF never initialises; a command re-issued with the same value writing nothing because the field never changed; a result handler firing with a none sentinel before the real value; why almost every ad-pod field is optional and lowercase; and the audience-measurement fields that must precede getAds. Not which node plays the content video or anything else on screen, which is sdk-components; not making the network request yourself, which is fetch-and-data-loading, since RAF fetches the ads; and not ChannelStore's set-data-then-set-command sequence for sign-in and purchases, which is user-accounts-and-purchases.",
+      "triggers": [
+        "getAds",
+        "showAds",
+        "stitchedAdsInit",
+        "roku_ads_lib"
+      ],
+      "path": "skills/ads-and-raf/SKILL.md",
+      "references": [
+        "skills/ads-and-raf/references/integration-flows.md"
+      ]
+    },
+    {
+      "name": "effects",
+      "description": "Use when a Rectangle or Poster in an RSG SDK TypeScript app needs rounded corners, a border or a gradient fill through the Effect node \u2014 where to create the Effect and when one is rebuilt instead of updated, one Effect shared by several consumers, animating its fields with an interpolator that otherwise does nothing, shaderCompatible on a Poster whose corners stay square for some images, a gradient that never draws, corners that do not appear on some devices and how to detect that at runtime, and a child that still paints over the rounded corners. Not clipping or fading a group of children through an image mask, which is MaskGroup in sdk-components; and not createEffect or any other reactive primitive, which is solid-on-roku.",
+      "triggers": [
+        "borderRadius",
+        "shaderCompatible",
+        "gradientStyle",
+        "IEffectProps"
+      ],
+      "path": "skills/effects/SKILL.md"
+    }
+  ]
+}

package/skills-manifest.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://roku.com/schemas/rsg-sdk/skills-manifest.schema.json",
+  "title": "RSG SDK Skills Manifest",
+  "description": "Standalone manifest mapping AI skill triggers to skill paths, shipped by @roku-sdk/ai. The zod schema in src/manifest.ts is the runtime authority; this file mirrors it for editors and CI. It is stricter about unknown keys on purpose: `additionalProperties: false` tells an author while editing that a key does nothing, whereas the loader ignores unknown keys so that a manifest from a newer @roku-sdk/* package still loads in an older one.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "skills"],
+  "properties": {
+    "version": {
+      "description": "Schema/format version of the manifest itself. Stays 1 even though `description` became required: this is a strict const, so a bump would reject v1 documents rather than accept them, and manifests are only ever read from installed @roku-sdk/* packages that ship alongside the loader.",
+      "const": 1
+    },
+    "skills": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/definitions/skillEntry" }
+    }
+  },
+  "definitions": {
+    "skillEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "description", "triggers", "path"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "kebab-case; MUST equal the skill's directory name; unique within a manifest.",
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+        },
+        "description": {
+          "type": "string",
+          "description": "Single-line activation prose, emitted verbatim as the generated skill's `description` frontmatter. Authored, not derived from triggers.",
+          "minLength": 1,
+          "maxLength": 1024,
+          "pattern": "^[^\\r\\n]+$"
+        },
+        "triggers": {
+          "type": "array",
+          "description": "Non-empty; each trigger should be unique across all discovered manifests.",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "path": {
+          "type": "string",
+          "description": "POSIX path relative to the package root; MUST resolve to an existing SKILL.md.",
+          "pattern": "^skills/[^/]+/SKILL\\.md$"
+        },
+        "references": {
+          "type": "array",
+          "description": "Documents delivered alongside the body and loaded on demand, for depth the body should not carry. Each MUST resolve on disk and sit under the same skills/<name>/ directory as `path` — the zod schema enforces that pairing, which this mirror cannot express.",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^skills/[^/]+/references/[^/]+\\.md$"
+          }
+        }
+      }
+    }
+  }
+}

package/src/__tests__/manifest.test.ts

@@ -0,0 +1,267 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "@jest/globals";
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { resolve } from "path";
+
+import { loadManifest, ManifestValidationError, type SkillManifest, zSkillEntry } from "../manifest";
+
+const PACKAGE_ROOT = resolve(__dirname, "..", "..");
+
+const VALID_DESCRIPTION = "Use when wiring D-pad focus in an RSG SDK TypeScript app.";
+
+/**
+ * A schema-valid entry. Tests override only the field under test, so adding a
+ * required field does not have to be mirrored into every case.
+ */
+function skillEntry(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+    return {
+        name: "focus-management",
+        description: VALID_DESCRIPTION,
+        triggers: ["focus"],
+        path: "skills/focus-management/SKILL.md",
+        ...overrides
+    };
+}
+
+function readManifestJson(): unknown {
+    return JSON.parse(readFileSync(resolve(PACKAGE_ROOT, "skills-manifest.json"), "utf8"));
+}
+
+describe("manifest — loadManifest", () => {
+    it("parses a valid manifest into a typed object", () => {
+        const manifest = loadManifest({
+            version: 1,
+            skills: [skillEntry({ triggers: ["focus", "FocusBoundary"] })]
+        });
+
+        expect(manifest.version).toBe(1);
+        expect(manifest.skills).toHaveLength(1);
+        expect(manifest.skills[0]).toMatchObject({
+            name: "focus-management",
+            description: VALID_DESCRIPTION,
+            path: "skills/focus-management/SKILL.md"
+        });
+    });
+
+    // `golden` was removed once it turned out to have no consumer. This zod
+    // schema is not strict, so a manifest written before the removal still
+    // loads. The shipped JSON Schema is stricter — `additionalProperties: false`
+    // rejects the same input — so the two disagree here, as they do for any
+    // unknown key. Loading is what runs, and it accepts the older shape.
+    it("ignores a field it no longer knows, such as the removed golden flag", () => {
+        const manifest = loadManifest({
+            version: 1,
+            skills: [skillEntry({ name: "project-setup", path: "skills/project-setup/SKILL.md", golden: true })]
+        });
+
+        expect(manifest.skills[0]).not.toHaveProperty("golden");
+        expect(manifest.skills[0].name).toBe("project-setup");
+    });
+
+    it("throws a descriptive ManifestValidationError for a bad skill name", () => {
+        const bad = { version: 1, skills: [skillEntry({ name: "Focus_Management" })] };
+
+        expect(() => loadManifest(bad)).toThrow(ManifestValidationError);
+
+        try {
+            loadManifest(bad);
+        } catch (error) {
+            expect(error).toBeInstanceOf(ManifestValidationError);
+            const message = (error as ManifestValidationError).message;
+            expect(message).toContain("skills.0.name");
+            expect(message).toContain("kebab-case");
+        }
+    });
+
+    it("rejects an empty triggers array", () => {
+        expect(() => loadManifest({ version: 1, skills: [skillEntry({ triggers: [] })] })).toThrow(
+            ManifestValidationError
+        );
+    });
+
+    it("rejects a malformed path", () => {
+        expect(() => loadManifest({ version: 1, skills: [skillEntry({ path: "focus-management/SKILL.md" })] })).toThrow(
+            ManifestValidationError
+        );
+    });
+
+    it("rejects an unsupported top-level version", () => {
+        expect(() => loadManifest({ version: 2, skills: [skillEntry()] })).toThrow(ManifestValidationError);
+    });
+
+    it("rejects a manifest with no skills", () => {
+        expect(() => loadManifest({ version: 1, skills: [] })).toThrow(ManifestValidationError);
+    });
+
+    // The description is what an agent runtime matches on to load the skill at
+    // all, and the runtimes we generate for reject these three shapes outright —
+    // so they fail here, where the diagnostic names the offending entry.
+    it.each([
+        ["absent", undefined],
+        ["empty", ""],
+        ["multi-line", "Use when wiring focus.\nSecond line."],
+        ["over 1024 characters", "x".repeat(1025)]
+    ])("rejects a description that is %s", (_label, description) => {
+        const entry = skillEntry({ description });
+        if (description === undefined) {
+            delete entry.description;
+        }
+
+        expect(() => loadManifest({ version: 1, skills: [entry] })).toThrow(ManifestValidationError);
+    });
+
+    it("accepts a description at the 1024-character ceiling", () => {
+        const description = "x".repeat(1024);
+        const manifest = loadManifest({ version: 1, skills: [skillEntry({ description })] });
+
+        expect(manifest.skills[0].description).toBe(description);
+    });
+});
+
+describe("manifest — references", () => {
+    it("loads an entry with no references", () => {
+        const manifest = loadManifest({ version: 1, skills: [skillEntry()] });
+
+        expect(manifest.skills[0].references).toBeUndefined();
+    });
+
+    it("loads references in the order declared", () => {
+        const references = [
+            "skills/focus-management/references/focus-recipes.md",
+            "skills/focus-management/references/plugins.md"
+        ];
+        const manifest = loadManifest({ version: 1, skills: [skillEntry({ references })] });
+
+        expect(manifest.skills[0].references).toEqual(references);
+    });
+
+    it.each([
+        ["outside a references/ directory", "skills/focus-management/focus-recipes.md"],
+        ["nested below references/", "skills/focus-management/references/deep/focus-recipes.md"],
+        ["not a markdown file", "skills/focus-management/references/focus-recipes.txt"],
+        ["absolute", "/skills/focus-management/references/focus-recipes.md"]
+    ])("rejects a reference path that is %s", (_label, reference) => {
+        expect(() => loadManifest({ version: 1, skills: [skillEntry({ references: [reference] })] })).toThrow(
+            ManifestValidationError
+        );
+    });
+
+    it("rejects an empty references array, so the key always means something", () => {
+        expect(() => loadManifest({ version: 1, skills: [skillEntry({ references: [] })] })).toThrow(
+            ManifestValidationError
+        );
+    });
+
+    // The pattern alone cannot catch this: the path is well-formed, it just
+    // belongs to another skill. The generator names its output from the owning
+    // entry, so the file would land in a directory whose own entry never
+    // declared it — and pruning works by directory.
+    it("rejects a reference under another skill's directory", () => {
+        const bad = {
+            version: 1,
+            skills: [skillEntry({ references: ["skills/project-setup/references/scaffold.md"] })]
+        };
+
+        expect(() => loadManifest(bad)).toThrow(ManifestValidationError);
+
+        try {
+            loadManifest(bad);
+        } catch (error) {
+            const message = (error as ManifestValidationError).message;
+            expect(message).toContain("skills.0.references.0");
+            expect(message).toContain("skills/focus-management/references/");
+        }
+    });
+
+    it("rejects a repeated reference, which would plan the same write twice", () => {
+        const reference = "skills/focus-management/references/focus-recipes.md";
+        const bad = { version: 1, skills: [skillEntry({ references: [reference, reference] })] };
+
+        expect(() => loadManifest(bad)).toThrow(ManifestValidationError);
+
+        try {
+            loadManifest(bad);
+        } catch (error) {
+            expect((error as ManifestValidationError).message).toContain("duplicate reference");
+        }
+    });
+});
+
+describe("manifest — shipped skills-manifest.json", () => {
+    it("validates against the schema", () => {
+        const manifest: SkillManifest = loadManifest(readManifestJson());
+        expect(manifest.skills.length).toBeGreaterThan(0);
+    });
+
+    // `skills-manifest.schema.json` is a hand-written mirror of `zSkillEntry`, read
+    // by editors and CI rather than by this loader, so nothing at runtime notices
+    // when a field lands on one side only. The two are deliberately not identical —
+    // the mirror is strict about unknown keys and cannot express the co-location
+    // rule — but a field the mirror has never heard of is drift, and the mirror
+    // rejects it under `additionalProperties: false` in the one place the author is
+    // still editing.
+    it("mirrors every zod entry field in the JSON Schema", () => {
+        const schema = JSON.parse(readFileSync(resolve(PACKAGE_ROOT, "skills-manifest.schema.json"), "utf8")) as {
+            definitions: { skillEntry: { properties: Record<string, unknown> } };
+        };
+
+        expect(Object.keys(schema.definitions.skillEntry.properties).sort()).toEqual(
+            Object.keys(zSkillEntry.shape).sort()
+        );
+    });
+
+    it("resolves every skill path on disk", () => {
+        const manifest = loadManifest(readManifestJson());
+        for (const skill of manifest.skills) {
+            expect(existsSync(resolve(PACKAGE_ROOT, skill.path))).toBe(true);
+        }
+    });
+
+    // The manifest is the only index of the library: discovery, the generated
+    // tree, the packaging check and the behavioral eval all enumerate skills
+    // from it, never from the directory. A skill directory with no entry is
+    // therefore invisible to every one of them while still being published by
+    // the `skills/**` files allow-list — so it ships to partners as prose no
+    // agent will ever load. Asserted as set equality rather than one-way
+    // containment, because the opposite direction (an entry whose directory is
+    // missing) is what the path test above covers.
+    it("resolves every declared reference on disk", () => {
+        const manifest = loadManifest(readManifestJson());
+        for (const skill of manifest.skills) {
+            for (const reference of skill.references ?? []) {
+                expect(existsSync(resolve(PACKAGE_ROOT, reference))).toBe(true);
+            }
+        }
+    });
+
+    // The mirror of the directory test below, one level down: `skills/**` publishes
+    // the whole tree, so a reference file nobody declared ships to partners while
+    // the generator never writes it and no body can point at it.
+    it("declares every file under a skill's references/ directory", () => {
+        const manifest = loadManifest(readManifestJson());
+        const declared = new Set(manifest.skills.flatMap(skill => skill.references ?? []));
+
+        for (const skill of manifest.skills) {
+            const dir = resolve(PACKAGE_ROOT, "skills", skill.name, "references");
+            if (!existsSync(dir)) {
+                continue;
+            }
+            for (const entry of readdirSync(dir, { withFileTypes: true })) {
+                expect(declared).toContain(`skills/${skill.name}/references/${entry.name}`);
+            }
+        }
+    });
+
+    it("has an entry for every skill directory, and no others", () => {
+        const manifest = loadManifest(readManifestJson());
+        const declared = manifest.skills.map(skill => skill.name).sort();
+        const onDisk = readdirSync(resolve(PACKAGE_ROOT, "skills"), { withFileTypes: true })
+            .filter(entry => entry.isDirectory())
+            .map(entry => entry.name)
+            .sort();
+
+        expect(onDisk).toEqual(declared);
+    });
+});