AmazonAppDev · Neha · May 19, 2026 · May 19, 2026
diff --git a/README.md b/README.md
@@ -9,6 +9,7 @@ This repository contains skills that work across open-source frameworks, tools a
 | Skill | Description |
 |-------|-------------|
 | [vega-multi-tv-migration](vega-multi-tv-migration/SKILL.md) | Migrate Vega OS (Fire TV) apps to multi-platform React Native monorepo supporting Android TV, Apple TV, and more |
+| [rn-tv-performance](rn-tv-performance/SKILL.md) | Measure, diagnose, and optimize performance for React Native TV apps, including React Native for Vega and Vega WebView |
 
 ## Installation
 
@@ -28,6 +29,10 @@ Install a specific skill:
 npx skills add AmazonAppDev/devices-agent-skills --skill vega-multi-tv-migration
 ```
 
+```bash
+npx skills add AmazonAppDev/devices-agent-skills --skill rn-tv-performance
+```
+
 For more options, see the [skills CLI documentation](https://skills.sh/docs/cli).
 
 ### 2. Manual Installation

diff --git a/rn-tv-performance/LICENSE b/rn-tv-performance/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vega Skills
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/rn-tv-performance/SKILL.md b/rn-tv-performance/SKILL.md
@@ -0,0 +1,176 @@
+---
+name: rn-tv-performance
+description: Audit, measure, and optimize performance for React Native TV applications, with Vega-specific guidance for React Native for Vega and Vega WebView apps. Use when investigating app launch latency, UI fluidity, video fluidity, memory, CPU usage, overdraw, jank, slow lists, re-renders, WebView performance, Web Workers, WebGL, profiling, Vega KPI Visualizer results, TTFF, TTFD, or TTFVF.
+---
+
+# RN TV Performance
+
+## Overview
+
+Measure before optimizing. Help agents diagnose and improve React Native TV app performance across native TV surfaces, with Vega-specific guidance for React Native for Vega, Vega WebView, official Vega KPIs, and Vega Studio profiling tools.
+
+Always identify the app surface first because generic React Native TV, React Native for Vega, and Vega WebView apps use different APIs, tools, and performance tactics.
+
+## When to Apply
+
+Use this skill when user mentions:
+- React Native TV app performance, slow startup, launch latency, responsiveness, or release-readiness
+- UI jank, poor fluidity, slow D-pad navigation, frame drops, or unresponsive screens
+- Video startup, Time-to-First Video Frame, buffering, dropped frames, or video fluidity
+- High CPU usage, memory growth, crashes, background memory, or profiling
+- React Native re-renders, FlatList, FlashList, memoization, concurrent rendering, or image/list performance
+- Vega app performance, React Native for Vega, Vega WebView, TTFF, TTFD, TTFVF, or report fully drawn
+- Vega KPI Visualizer, Activity Monitor, Recording View, Perfetto, Chrome DevTools, overdraw, or flamegraphs
+
+## Phase Priority Guide
+
+| Priority | Phase | Impact | When to Use |
+|----------|-------|--------|-------------|
+| 1 | App Surface Detection | CRITICAL | Before recommending platform-specific fixes |
+| 2 | Baseline Measurement | CRITICAL | Before optimizing launch, fluidity, memory, or video |
+| 3 | Tool Selection | HIGH | Choose KPI Visualizer, Activity Monitor, CDT, Perfetto, or overdraw |
+| 4 | Root Cause Analysis | HIGH | Map symptoms to CPU, memory, rendering, network, list, video, or WebView causes |
+| 5 | Targeted Fix | HIGH | Apply the smallest source-aligned fix and re-measure |
+
+## Quick Decision Tree
+
+```
+What is slow?
++-- Launch or resume?
+|   +-- Measure platform launch metrics; for Vega, measure TTFF/TTFD and verify reportFullyDrawn/useReportFullyDrawn
++-- UI interaction, scrolling, D-pad, or animation?
+|   +-- Measure ui-fluidity; inspect re-renders, overdraw, render thread, and JS thread
++-- Video startup or playback?
+|   +-- Measure video-fluidity and TTFVF; check hardware decode and media setup
++-- Memory or crash?
+|   +-- Measure foreground/background memory; inspect Activity Monitor recordings
++-- Native React Native TV screen?
+|   +-- Use RN TV guidance for memoization, lists, images, render work, and navigation responsiveness
++-- WebView page or HTML app?
+|   +-- Use WebView guidance for network, JS, cache, Web Workers, WebGL, video
++-- Vega app?
+|   +-- Use Vega KPI and profiling guidance for official metrics and tooling
++-- Unknown?
+    +-- Inspect manifest.toml, package.json, app entry points, WebView usage, and rendered flows
+```
+
+## Quick Reference
+
+### Detect App Surface
+
+```bash
+# Generic React Native TV indicators
+rg "react-native|react-native-tvos|@react-native|FlatList|FlashList|TVEventHandler|hasTVPreferredFocus"
+
+# Vega package marker
+find . -name manifest.toml -maxdepth 5
+
+# WebView indicators
+rg "@amazon-devices/webview|<WebView|webview.html|ReactNativeWebView|postMessage"
+
+# React Native for Vega indicators
+rg "@amazon-devices/react-native-kepler|react-native-vega|build:app|vega project|FlatList|FlashList"
+```
+
+### Vega Measurement Commands
+
+```bash
+# Check host and target readiness
+vega exec perf doctor
+
+# Default cool-start TTFF and TTFD
+vega exec perf kpi-visualizer --app-name=<interactive-component-id>
+
+# Explicit iteration count
+vega exec perf kpi-visualizer --app-name=<interactive-component-id> --iterations <count>
+
+# UI fluidity with a test scenario
+vega exec perf kpi-visualizer --app-name=<interactive-component-id> --kpi ui-fluidity --test-scenario <scenario.py>
+
+# Activity Monitor with CPU profiling
+vega exec perf activity-monitor --record-cpu-profiling --app-name=<interactive-component-id> --sourcemap-file-path=<source-map>
+```
+
+### Vega KPI Targets
+
+- Cool start TTFF: less than 1.5 s
+- Warm start TTFF: less than 0.5 s
+- Cool start TTFD: less than 8.0 s
+- Warm start TTFD: less than 1.5 s
+- Foreground memory: less than 400 MiB
+- Background memory: less than 150 MiB
+- Video fluidity: greater than 99%
+- Time-to-First Video Frame: less than 2500 ms
+- UI fluidity: target 99% or higher
+- Iterations: default 3; certification mode uses 30 with 90th percentile aggregation
+
+### Vega-Specific Path
+
+Use the Vega-specific references when the app is React Native for Vega, uses Vega WebView, exposes `manifest.toml`, or needs official Vega KPI evidence. For non-Vega React Native TV apps, use the RN TV reference and the project's available platform profilers, then adapt the same measure-before-fix workflow.
+
+## References
+
+| File | Impact | Description |
+|------|--------|-------------|
+| [REACT_NATIVE_TV_PERFORMANCE.md](references/REACT_NATIVE_TV_PERFORMANCE.md) | CRITICAL | React Native TV optimization for renders, lists, images, concurrent rendering, and TV navigation responsiveness |
+| [KPI_MEASUREMENT.md](references/KPI_MEASUREMENT.md) | CRITICAL | Vega-specific KPI Visualizer metrics, targets, commands, and report fully drawn APIs |
+| [WEBVIEW_PERFORMANCE.md](references/WEBVIEW_PERFORMANCE.md) | CRITICAL | Vega WebView launch, network, rendering, cache, Web Worker, WebGL, and video guidance |
+| [PROFILING_AND_RENDERING.md](references/PROFILING_AND_RENDERING.md) | HIGH | Vega Activity Monitor, Recording View, CPU profiler, Chrome DevTools, Perfetto, overdraw |
+
+### Templates
+
+Use [PERFORMANCE_CHECKLIST.md](assets/templates/PERFORMANCE_CHECKLIST.md) to track measurement, fixes, and verification.
+
+### Evals
+
+Use [evals/README.md](evals/README.md) to test trigger quality, task quality, and with-skill vs without-skill behavior.
+
+## Problem -> Skill Mapping
+
+| Problem | Start With |
+|---------|------------|
+| Slow React Native TV screen or interaction | REACT_NATIVE_TV_PERFORMANCE.md |
+| Slow Vega launch or resume | KPI_MEASUREMENT.md |
+| Vega TTFD is missing or `-1` | KPI_MEASUREMENT.md |
+| UI jank or D-pad lag | PROFILING_AND_RENDERING.md, then platform reference |
+| Slow FlatList/rails | REACT_NATIVE_TV_PERFORMANCE.md |
+| Too many React renders | REACT_NATIVE_TV_PERFORMANCE.md |
+| Slow WebView load | WEBVIEW_PERFORMANCE.md |
+| Heavy WebView JavaScript | WEBVIEW_PERFORMANCE.md |
+| High CPU or memory | PROFILING_AND_RENDERING.md |
+| Rendering overdraw | PROFILING_AND_RENDERING.md |
+| Video startup/playback issues | KPI_MEASUREMENT.md, then WEBVIEW_PERFORMANCE.md if WebView video |
+
+## Workflow
+
+1. Detect app surface: generic React Native TV, React Native for Vega, Vega WebView, mixed, or unknown.
+2. Identify the symptom and target KPI: launch, UI fluidity, video fluidity, memory, CPU, or rendering.
+3. Run the appropriate measurement tool on a release build when possible. For Vega, use KPI Visualizer, Activity Monitor, Recording View, and related Vega tools.
+4. Inspect evidence: profiler output, KPI Visualizer output, Activity Monitor recording, flamegraph, Perfetto trace, Chrome DevTools profile, overdraw colors, or re-render logs.
+5. Apply targeted fixes from the correct reference path.
+6. Re-run the same measurement and compare before/after values.
+7. Report symptom, baseline, root cause, fix, after-measurement, remaining risk, and official source used.
+
+## Guardrails
+
+- Do not optimize before establishing a baseline measurement.
+- Do not compare debug-build numbers against release-build numbers.
+- Do not compare before/after results from different devices, app states, scenarios, or iteration counts.
+- Do not treat Vega TTFD as valid unless the app reports fully drawn when it is actually ready for user interaction.
+- Do not apply WebView fixes to native React Native surfaces, or native-only fixes to WebView content, without checking app surface first.
+
+## Official Sources
+
+- App Performance Best Practices: https://developer.amazon.com/docs/vega/0.21/best_practices.html
+- Measure App KPIs: https://developer.amazon.com/docs/vega/0.21/measure-app-kpis.html
+- Performance Best Practices for Web Apps: https://developer.amazon.com/docs/vega/0.21/webview-app-performance-best-practices.html
+- Improve App Performance with Concurrent Rendering: https://developer.amazon.com/docs/vega/0.21/concurrent-rendering.html
+- Optimizing Flatlist Configuration: https://developer.amazon.com/docs/react-native-vega/0.72/optimizing-flatlist-configuration.html
+- Monitor CPU Usage: https://developer.amazon.com/docs/vega/0.21/monitor-cpu-usage.html
+- Use Chrome DevTools for App Profiling: https://developer.amazon.com/docs/vega/0.21/chrome-devtools.html
+- Identify UI Rendering Issues: https://developer.amazon.com/docs/vega/0.21/ui-rendering.html
+- Detect Overdraw: https://developer.amazon.com/docs/vega/0.21/detect-overdraw.html
+
+## Attribution
+
+Based on official React Native performance patterns plus official Vega, React Native for Vega, Vega WebView, and Vega Studio performance documentation.
diff --git a/rn-tv-performance/assets/templates/PERFORMANCE_CHECKLIST.md b/rn-tv-performance/assets/templates/PERFORMANCE_CHECKLIST.md
@@ -0,0 +1,62 @@
+# Performance Checklist
+
+Use this checklist during React Native TV performance investigations. Use Vega-specific KPI and profiling checks when the app targets Vega.
+
+## Scope
+
+- [ ] Identified app surface: generic React Native TV, React Native for Vega, Vega WebView, mixed, or unknown.
+- [ ] Identified symptom: launch, UI fluidity, video, CPU, memory, rendering, network, list, or WebGL.
+- [ ] Identified target device and build variant.
+- [ ] Confirmed measurements are from a repeatable scenario.
+- [ ] Recorded KPI iteration count, using default 3 iterations for quick checks or 30 iterations for certification-mode evidence.
+
+## KPI Baseline
+
+- [ ] Recorded cool start TTFF.
+- [ ] Recorded warm start TTFF if relevant.
+- [ ] Recorded cool start TTFD and verified report fully drawn marker.
+- [ ] Recorded warm start TTFD if relevant.
+- [ ] Recorded UI fluidity for navigation or scrolling.
+- [ ] Recorded video fluidity and TTFVF for playback.
+- [ ] Recorded foreground memory.
+- [ ] Recorded background memory.
+- [ ] Compared P90 values from the same iteration count before and after the fix.
+
+## Native React Native TV
+
+- [ ] Checked unnecessary re-renders with React DevTools or why-did-you-render in development.
+- [ ] Memoized expensive stable children where evidence supports it.
+- [ ] Stabilized callbacks, objects, arrays, and render functions passed to list items.
+- [ ] Tuned FlatList props: `initialNumToRender`, `maxToRenderPerBatch`, `windowSize`, `getItemLayout`, and `keyExtractor`.
+- [ ] Considered FlashList when list performance remains poor.
+- [ ] Used thumbnail/cropped images in lists and rails.
+- [ ] Applied concurrent rendering for heavy non-urgent updates.
+
+## Vega WebView
+
+- [ ] Used native SplashScreen API where applicable.
+- [ ] Implemented TTFD marker only after real readiness.
+- [ ] Minimized startup JavaScript and render-blocking scripts.
+- [ ] Optimized network requests, redirects, cache headers, and server response time.
+- [ ] Deferred noncritical data and code.
+- [ ] Avoided forced reflows and heavy scroll handlers.
+- [ ] Used Web Workers only for suitable heavy work and bounded worker count.
+- [ ] Optimized WebGL draw calls, texture sizes, shaders, object reuse, and blocking calls.
+- [ ] Used hardware-supported video codecs and avoided multiple simultaneous video elements.
+
+## Profiling and Rendering
+
+- [ ] Used KPI Visualizer for the target KPI.
+- [ ] Used Activity Monitor or Recording View for CPU/memory spikes.
+- [ ] Inspected flamegraphs or call trees for hot functions.
+- [ ] Inspected Perfetto traces for render thread jank.
+- [ ] Checked overdraw with `SHOW_OVERDRAWN=true` where rendering cost is suspected.
+- [ ] Used Chrome DevTools for debug/web profiling where appropriate.
+
+## Verification
+
+- [ ] Re-ran the same KPI command and scenario after fixes.
+- [ ] Compared before/after numbers.
+- [ ] Confirmed no regression in adjacent flows.
+- [ ] Confirmed UI remains responsive with D-pad navigation.
+- [ ] Documented source, fix, measurement, and remaining risk.
diff --git a/rn-tv-performance/evals/README.md b/rn-tv-performance/evals/README.md
@@ -0,0 +1,28 @@
+# RN TV Performance Evals
+
+Use these evals to measure whether `rn-tv-performance` improves performance investigations compared with a baseline run without the skill.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| [TRIGGER_PROMPTS.md](TRIGGER_PROMPTS.md) | Trigger and non-trigger prompts for description quality |
+| [TASK_SCENARIOS.md](TASK_SCENARIOS.md) | Realistic performance diagnosis and fix scenarios |
+| [SCORING_RUBRIC.md](SCORING_RUBRIC.md) | Quantitative and qualitative scoring criteria |
+| [RUNBOOK.md](RUNBOOK.md) | Step-by-step instructions for running and comparing evals |
+
+## Success Targets
+
+- Trigger precision: at least 9/10 trigger prompts should use the skill.
+- Non-trigger specificity: at least 8/10 non-trigger prompts should avoid the skill.
+- Task pass rate: at least 80% of task scenarios score 4 or 5.
+- Safety: zero outputs should recommend optimizations without measurement or mix WebView and native RN guidance incorrectly.
+
+## Required Behaviors
+
+High-quality outputs should:
+- Detect app surface first: generic React Native TV, React Native for Vega, Vega WebView, mixed, or unknown.
+- Choose a KPI and establish a baseline before recommending fixes.
+- Use official Vega tools and targets: KPI Visualizer, Activity Monitor, Recording View, Chrome DevTools, Perfetto, overdraw, and report fully drawn APIs.
+- Apply platform-specific fixes for native RN or WebView.
+- Re-measure the same scenario after changes.
diff --git a/rn-tv-performance/evals/RUNBOOK.md b/rn-tv-performance/evals/RUNBOOK.md
@@ -0,0 +1,68 @@
+# Eval Runbook
+
+Use this runbook to compare baseline agent behavior with behavior after installing or enabling `rn-tv-performance`.
+
+## Preparation
+
+1. Use the same model and environment for baseline and skill-enabled runs.
+2. Use the same prompt text in both runs.
+3. Record whether the skill was available, explicitly invoked, or automatically selected.
+4. Capture response text, timing, and token usage if the runner exposes those metrics.
+
+## Trigger Eval
+
+1. Run each prompt in [TRIGGER_PROMPTS.md](TRIGGER_PROMPTS.md).
+2. Mark expected trigger prompts as pass when the agent uses or clearly follows the skill.
+3. Mark expected non-trigger prompts as pass when the agent avoids the skill and uses a more relevant workflow.
+4. Calculate:
+   - Trigger precision: trigger passes / 10
+   - Non-trigger specificity: non-trigger passes / 10
+
+## Task Eval
+
+1. Run each prompt in [TASK_SCENARIOS.md](TASK_SCENARIOS.md) without the skill.
+2. Run the same prompt with the skill available.
+3. Score both outputs with [SCORING_RUBRIC.md](SCORING_RUBRIC.md).
+4. Mark scenarios scoring 4 or 5 as pass.
+5. Compare:
+   - Overall score delta
+   - Pass/fail delta
+   - Automatic failures
+   - Missing guidance patterns
+
+## Review Template
+
+Use this template for each scenario:
+
+```markdown
+Prompt ID:
+Skill available: yes/no
+Skill selected: yes/no/unknown
+Overall score:
+App surface detection:
+Measurement discipline:
+Official tool usage:
+Fix quality:
+Verification:
+Automatic failure: yes/no
+Key strengths:
+Key gaps:
+Recommended skill change:
+```
+
+## Iteration Rules
+
+Update the skill when:
+- Two or more scenarios miss the same required behavior.
+- Any scenario recommends optimization before measurement.
+- Any scenario mixes WebView and native React Native TV guidance incorrectly.
+- Trigger precision is below 9/10.
+- Non-trigger specificity is below 8/10.
+- Task pass rate is below 80%.
+
+Update the description when:
+- Trigger prompts are missed despite good skill content.
+- Non-trigger prompts activate because the description is too broad.
+
+Update references or checklist when:
+- The agent uses the skill but still misses official Vega KPI targets, iteration count, release-build guidance, or validation steps.