Comprehensive React Native & Expo skills guide

.github/skills/react-native-skills/README.md

@@ -0,0 +1,132 @@
+# React Native & Expo Skills
+
+Best practices for React Native and Expo mobile applications targeting iOS and
+Android. Optimized for AI agents and LLMs working on this codebase.
+
+## Tech Stack
+
+- React Native 0.81+ with New Architecture
+- Expo SDK 54+
+- Expo Router 5.1 (file-based navigation)
+- NativeWind 4.1 (Tailwind CSS)
+- React Native Reanimated 4.1
+- TypeScript 5.9
+
+## Structure
+
+- `rules/` - Individual rule files (one per rule)
+  - `_sections.md` - Section metadata (titles, impacts, descriptions)
+  - `_template.md` - Template for creating new rules
+  - `{prefix}-{description}.md` - Individual rule files
+- `metadata.json` - Document metadata (version, organization, abstract)
+- `SKILL.md` - Skill overview and quick reference
+- **`AGENTS.md`** - Compiled output for agents (generated)
+
+## Rules by Category
+
+### Core Rendering (CRITICAL)
+
+- `rendering-text-in-text-component.md` - Wrap strings in Text components
+- `rendering-no-falsy-and.md` - Avoid falsy && operator in JSX
+
+### List Performance (HIGH)
+
+- `list-performance-virtualize.md` - Use FlashList for lists
+- `list-performance-function-references.md` - Keep stable object references
+- `list-performance-callbacks.md` - Hoist callbacks to list root
+- `list-performance-inline-objects.md` - Avoid inline objects in renderItem
+- `list-performance-item-memo.md` - Pass primitives for memoization
+- `list-performance-item-expensive.md` - Keep list items lightweight
+- `list-performance-images.md` - Use compressed images in lists
+- `list-performance-item-types.md` - Use item types for heterogeneous lists
+
+### Animation (HIGH)
+
+- `animation-gpu-properties.md` - Animate transform/opacity only
+- `animation-gesture-detector-press.md` - Use GestureDetector for press
+- `animation-derived-value.md` - Prefer useDerivedValue
+
+### Scroll Performance (HIGH)
+
+- `scroll-position-no-state.md` - Never track scroll in useState
+
+### Navigation (HIGH)
+
+- `navigation-native-navigators.md` - Use Expo Router
+
+### React State (MEDIUM)
+
+- `react-state-dispatcher.md` - Use functional setState updates
+- `react-state-fallback.md` - State represents user intent only
+- `react-state-minimize.md` - Minimize state, derive values
+
+### State Architecture (MEDIUM)
+
+- `state-ground-truth.md` - State must represent ground truth
+
+### React Compiler (MEDIUM)
+
+- `react-compiler-destructure-functions.md` - Destructure functions early
+- `react-compiler-reanimated-shared-values.md` - Use .get()/.set()
+
+### User Interface (MEDIUM)
+
+- `ui-expo-image.md` - Use expo-image for images
+- `ui-menus.md` - Native dropdown and context menus
+- `ui-native-modals.md` - Use native Modal with formSheet
+- `ui-pressable.md` - Use Pressable over TouchableOpacity
+- `ui-measure-views.md` - Measuring view dimensions
+- `ui-safe-area-scroll.md` - Use contentInsetAdjustmentBehavior
+- `ui-scrollview-content-inset.md` - Use contentInset for spacing
+- `ui-styling.md` - NativeWind styling patterns
+
+### JavaScript (LOW)
+
+- `js-hoist-intl.md` - Hoist Intl formatter creation
+
+### Fonts (LOW)
+
+- `fonts-config-plugin.md` - Load fonts natively at build time
+
+## Creating a New Rule
+
+1. Copy `rules/_template.md` to `rules/{prefix}-{description}.md`
+2. Choose the appropriate prefix from `_sections.md`
+3. Fill in the frontmatter and content
+4. Include clear incorrect/correct examples
+
+## Rule File Structure
+
+```markdown
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description
+tags: tag1, tag2, tag3
+---
+
+## Rule Title Here
+
+Brief explanation of the rule and why it matters.
+
+**Incorrect (description):**
+
+\`\`\`tsx
+// Bad code example
+\`\`\`
+
+**Correct (description):**
+
+\`\`\`tsx
+// Good code example
+\`\`\`
+
+Reference: [Link](https://example.com)
+```
+
+## Impact Levels
+
+- `CRITICAL` - Causes crashes or broken UI
+- `HIGH` - Significant performance improvements
+- `MEDIUM` - Moderate improvements
+- `LOW` - Incremental improvements

.github/skills/react-native-skills/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: react-native-expo-skills
+description:
+  React Native and Expo best practices for building performant iOS and Android
+  mobile apps. Use when building components, optimizing list performance,
+  implementing animations with Reanimated, or styling with NativeWind. Triggers
+  on tasks involving React Native, Expo, Expo Router navigation, or mobile
+  performance optimization.
+license: MIT
+metadata:
+  author: BitSleuth
+  version: '2.0.0'
+---
+
+# React Native & Expo Skills
+
+Best practices for React Native and Expo mobile applications targeting iOS and
+Android. Contains rules covering performance, animations, navigation, styling,
+and platform-specific optimizations.
+
+## Tech Stack
+
+- React Native 0.81+
+- Expo SDK 54+
+- Expo Router (file-based navigation)
+- NativeWind (Tailwind CSS)
+- React Native Reanimated
+- TypeScript
+
+## When to Apply
+
+Reference these guidelines when:
+
+- Building React Native or Expo apps for iOS/Android
+- Optimizing list and scroll performance
+- Implementing animations with Reanimated
+- Configuring navigation with Expo Router
+- Styling components with NativeWind
+- Working with images using expo-image
+
+## Rule Categories by Priority
+
+| Priority | Category         | Impact   | Prefix              |
+| -------- | ---------------- | -------- | ------------------- |
+| 1        | Core Rendering   | CRITICAL | `rendering-`        |
+| 2        | List Performance | HIGH     | `list-performance-` |
+| 3        | Animation        | HIGH     | `animation-`        |
+| 4        | Scroll           | HIGH     | `scroll-`           |
+| 5        | Navigation       | HIGH     | `navigation-`       |
+| 6        | React State      | MEDIUM   | `react-state-`      |
+| 7        | State Arch       | MEDIUM   | `state-`            |
+| 8        | React Compiler   | MEDIUM   | `react-compiler-`   |
+| 9        | User Interface   | MEDIUM   | `ui-`               |
+| 10       | JavaScript       | LOW      | `js-`               |
+| 11       | Fonts            | LOW      | `fonts-`            |
+
+## Quick Reference
+
+### 1. Core Rendering (CRITICAL)
+
+- `rendering-text-in-text-component` - Wrap strings in Text components
+- `rendering-no-falsy-and` - Avoid falsy && for conditional rendering
+
+### 2. List Performance (HIGH)
+
+- `list-performance-virtualize` - Use FlashList for large lists
+- `list-performance-item-memo` - Pass primitives for memoization
+- `list-performance-callbacks` - Hoist callbacks to list root
+- `list-performance-inline-objects` - Avoid inline style objects
+- `list-performance-function-references` - Keep stable object references
+- `list-performance-images` - Use compressed images in lists
+- `list-performance-item-expensive` - Keep list items lightweight
+- `list-performance-item-types` - Use item types for heterogeneous lists
+
+### 3. Animation (HIGH)
+
+- `animation-gpu-properties` - Animate transform and opacity only
+- `animation-derived-value` - Use useDerivedValue for computed animations
+- `animation-gesture-detector-press` - Use Gesture.Tap for press animations
+
+### 4. Scroll Performance (HIGH)
+
+- `scroll-position-no-state` - Never track scroll position in useState
+
+### 5. Navigation (HIGH)
+
+- `navigation-native-navigators` - Use Expo Router for file-based navigation
+
+### 6. React State (MEDIUM)
+
+- `react-state-minimize` - Minimize state variables, derive values
+- `react-state-dispatcher` - Use functional setState updates
+- `react-state-fallback` - Use fallback state instead of initialState
+
+### 7. State Architecture (MEDIUM)
+
+- `state-ground-truth` - State must represent ground truth
+
+### 8. React Compiler (MEDIUM)
+
+- `react-compiler-destructure-functions` - Destructure functions early
+- `react-compiler-reanimated-shared-values` - Use .get()/.set() for shared values
+
+### 9. User Interface (MEDIUM)
+
+- `ui-expo-image` - Use expo-image for all images
+- `ui-pressable` - Use Pressable over TouchableOpacity
+- `ui-safe-area-scroll` - Use contentInsetAdjustmentBehavior
+- `ui-scrollview-content-inset` - Use contentInset for dynamic spacing
+- `ui-menus` - Use native context menus
+- `ui-native-modals` - Use native modals when possible
+- `ui-measure-views` - Use onLayout for measuring views
+- `ui-styling` - Use NativeWind for styling
+
+### 10. JavaScript (LOW)
+
+- `js-hoist-intl` - Hoist Intl object creation
+
+### 11. Fonts (LOW)
+
+- `fonts-config-plugin` - Use config plugins for custom fonts
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/list-performance-virtualize.md
+rules/animation-gpu-properties.md
+rules/ui-styling.md
+```
+
+Each rule file contains:
+
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`

.github/skills/react-native-skills/metadata.json

@@ -0,0 +1,14 @@
+{
+  "version": "2.0.0",
+  "organization": "BitSleuth",
+  "date": "January 2026",
+  "abstract": "Performance and best practices guide for React Native and Expo mobile applications targeting iOS and Android. Contains 25+ rules across 11 categories covering core rendering, list performance, animations with Reanimated, navigation with Expo Router, styling with NativeWind, and platform-specific optimizations. Each rule includes detailed explanations, incorrect vs. correct code examples, and impact assessments.",
+  "references": [
+    "https://react.dev",
+    "https://reactnative.dev",
+    "https://docs.expo.dev",
+    "https://docs.swmansion.com/react-native-reanimated",
+    "https://docs.swmansion.com/react-native-gesture-handler",
+    "https://www.nativewind.dev"
+  ]
+}

.github/skills/react-native-skills/rules/_sections.md

@@ -0,0 +1,68 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Core Rendering (rendering)
+
+**Impact:** CRITICAL
+**Description:** Fundamental React Native rendering rules. Violations cause
+runtime crashes or broken UI.
+
+## 2. List Performance (list-performance)
+
+**Impact:** HIGH
+**Description:** Optimizing virtualized lists (FlatList, FlashList) for smooth
+scrolling and fast updates.
+
+## 3. Animation (animation)
+
+**Impact:** HIGH
+**Description:** GPU-accelerated animations, Reanimated patterns, and avoiding
+render thrashing during gestures.
+
+## 4. Scroll Performance (scroll)
+
+**Impact:** HIGH
+**Description:** Tracking scroll position without causing render thrashing.
+
+## 5. Navigation (navigation)
+
+**Impact:** HIGH
+**Description:** Using Expo Router and native navigators for file-based routing
+on iOS and Android.
+
+## 6. React State (react-state)
+
+**Impact:** MEDIUM
+**Description:** Patterns for managing React state to avoid stale closures and
+unnecessary re-renders.
+
+## 7. State Architecture (state)
+
+**Impact:** MEDIUM
+**Description:** Ground truth principles for state variables and derived values.
+
+## 8. React Compiler (react-compiler)
+
+**Impact:** MEDIUM
+**Description:** Compatibility patterns for React Compiler with React Native and
+Reanimated.
+
+## 9. User Interface (ui)
+
+**Impact:** MEDIUM
+**Description:** Native UI patterns for images, menus, modals, styling with
+NativeWind, and platform-consistent interfaces.
+
+## 10. JavaScript (js)
+
+**Impact:** LOW
+**Description:** Micro-optimizations like hoisting expensive object creation.
+
+## 11. Fonts (fonts)
+
+**Impact:** LOW
+**Description:** Native font loading for improved performance.

.github/skills/react-native-skills/rules/_template.md

@@ -0,0 +1,28 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)