mobile-ai-agents 1.0.23

package/skills/react-native/new-arch-migrate.md

@@ -0,0 +1,53 @@
+# Skill — /new-arch-migrate
+
+**Platform:** React Native
+**Slash Command:** `/new-arch-migrate`
+
+---
+
+## Purpose
+
+Step-by-step React Native New Architecture (JSI / Fabric / TurboModules) migration guide for an existing module or component.
+
+---
+
+## Skill Prompt
+
+```
+Migrate the provided React Native module or component to the New Architecture:
+
+DETECT WHAT NEEDS MIGRATION:
+1. NativeModule (RCTBridgeModule) → TurboModule
+2. Native UI Component (RCTViewManager) → Fabric Component
+3. Animated bridge calls → Reanimated 2 / useNativeDriver
+
+TURBOMODULE MIGRATION:
+Old Architecture:
+- JS side: NativeModules.MyModule.doSomething()
+- Native side: @ReactMethod doSomething() in Java/Kotlin/ObjC/Swift
+
+New Architecture (TurboModule):
+1. Create TypeScript spec file (NativeMyModule.ts):
+   import type { TurboModule } from 'react-native';
+   import { TurboModuleRegistry } from 'react-native';
+   export interface Spec extends TurboModule {
+     doSomething(param: string): Promise<string>;
+   }
+   export default TurboModuleRegistry.getEnforcing<Spec>('MyModule');
+
+2. Android: implement ReactPackageTurboModuleManagerDelegate
+3. iOS: implement RCTTurboModule protocol
+
+FABRIC COMPONENT MIGRATION:
+1. Create ComponentSpec.js with codegenNativeComponent
+2. Register with RCTFabricComponentsPlugins
+3. Update native implementation to use Fabric API
+
+REANIMATED 2 MIGRATION:
+- Replace Animated.Value with useSharedValue
+- Replace Animated.timing/spring with withTiming/withSpring
+- Replace Animated.event with useAnimatedScrollHandler/useAnimatedGestureHandler
+
+Provide the complete before/after code for each migration step.
+Flag any migration blocker (3rd party library not yet New Architecture compatible).
+```

package/skills/react-native/performance.md

@@ -0,0 +1,124 @@
+# Skill — React Native Performance
+
+**Platform:** React Native (TypeScript)  
+**Category:** Performance & Optimization  
+**Composable With:** agents/react-native/performance-optimizer/agent.md
+
+---
+
+## Purpose
+
+A focused skill module covering the most common React Native performance pitfalls. Use as a quick primer before reviewing any RN component for re-render issues, FlatList problems, and animation overhead.
+
+## When to Use
+
+- Before reviewing any React Native component file
+- When a screen feels janky or sluggish and you need a checklist
+- When composing into a larger multi-file performance review
+
+---
+
+## Skill Prompt
+
+```
+When reviewing React Native TypeScript components for performance, check for:
+
+RE-RENDER PREVENTION
+- useCallback: every function passed as a prop to a child component (especially list items)
+  must be wrapped in useCallback. Inline () => fn(id) creates a new reference every render.
+- useMemo: every object or array created in the component body and passed as a prop must be
+  wrapped in useMemo. Inline style={{ backgroundColor: color }} creates a new object every render.
+- React.memo: components that receive stable props and render frequently (e.g., list cells)
+  should be wrapped in React.memo to skip re-renders when props haven't changed.
+- Context: components consuming a large Context object re-render on ANY context value change.
+  Split Context into smaller focused contexts or use a state manager (Zustand, Jotai, Redux).
+
+FLATLIST / FLASHLIST
+- keyExtractor must return a stable, unique string per item. Using index as the key causes
+  full re-renders on list changes.
+- getItemLayout: provide this if list items have a fixed height. Without it, FlatList cannot
+  pre-calculate positions, causing extra layout work on every scroll.
+- removeClippedSubviews: set to true for long lists to unmount off-screen items.
+- windowSize: default is 21 (viewports). For complex items, reduce to 7–11 to lower memory.
+- initialNumToRender: set to the count visible above the fold to avoid over-rendering on mount.
+- Consider migrating large lists (50+ items) to FlashList (Shopify) — better recycling,
+  significantly lower memory on New Architecture.
+
+ANIMATIONS
+- Every Animated.Value animation must use useNativeDriver: true where possible.
+  Animations without useNativeDriver run on the JS thread and drop frames under load.
+- useNativeDriver: true is compatible with: opacity, transform (scale, translate, rotate).
+  It is NOT compatible with: layout properties (width, height, margin, padding).
+- For layout animations, use Reanimated v3 with useAnimatedStyle — runs on the UI thread.
+- Avoid animating properties inside a FlatList renderItem — each frame update causes item re-renders.
+
+INLINE OBJECTS AND FUNCTIONS IN JSX
+- <Component style={{ flex: 1 }} /> — new object every render.
+  Fix: extract to StyleSheet.create or useMemo.
+- <Component onPress={() => doSomething(item.id)} /> — new function every render.
+  Fix: extract with useCallback or pass item.id as a prop and let the component call a stable handler.
+- <Component data={items.filter(i => i.active)} /> — new array every render.
+  Fix: memoize with useMemo.
+
+BRIDGE OVERHEAD (Old Architecture)
+- NativeModules calls in the render path or in a tight loop are expensive — they cross the bridge synchronously.
+- Prefer batch native calls or migrate to JSI (New Architecture) where native calls are synchronous and cheap.
+- AsyncStorage, FileSystem, and similar modules in hot render paths should use caching.
+
+For each issue found: state the component/line, what is wrong (with an impact estimate), and provide the corrected code snippet.
+```
+
+---
+
+## Example
+
+**Input:**
+```
+const CartItem = ({ item, onRemove }) => (
+  <TouchableOpacity
+    onPress={() => onRemove(item.id)}
+    style={{ padding: 12, backgroundColor: '#fff' }}
+  >
+    <Text>{item.name}</Text>
+  </TouchableOpacity>
+);
+```
+
+**Output:**
+```
+Inline onPress function — HIGH impact in lists
+  Problem: () => onRemove(item.id) is a new function reference every render. If CartItem
+           is inside a FlatList and the parent re-renders, every visible CartItem re-renders.
+  Fix:
+  const CartItem = React.memo(({ item, onRemoveId }) => (
+    <TouchableOpacity onPress={onRemoveId} style={styles.item}>
+      <Text>{item.name}</Text>
+    </TouchableOpacity>
+  ));
+  // In parent: const handleRemove = useCallback((id) => { ... }, []);
+  // Pass: onRemoveId={() => handleRemove(item.id)} is still inline — instead:
+  // Pass: item.id as a prop and call handleRemove(item.id) inside CartItem
+
+Inline style object — MEDIUM impact
+  Problem: { padding: 12, backgroundColor: '#fff' } is a new object every render.
+  Fix: const styles = StyleSheet.create({ item: { padding: 12, backgroundColor: '#fff' } });
+```
+
+---
+
+## Composition Example
+
+```
+Use before the RN Performance Optimizer agent for a quick triage:
+paste this skill → paste component → get a ranked list of issues.
+
+For the full structured report with ESTIMATED IMPROVEMENT and PROFILING STEPS,
+run agents/react-native/performance-optimizer/agent.md instead.
+```
+
+---
+
+## Notes
+
+- New Architecture (JSI/Fabric, RN 0.74+) eliminates bridge overhead. Bridge-specific checks still apply to Old Architecture apps.
+- React DevTools Profiler and Flipper are the ground-truth tools — use this skill for pre-profiling code review, not as a replacement for measuring.

package/skills/react-native/rn-review.md

@@ -0,0 +1,53 @@
+# Skill — /rn-review
+
+**Platform:** React Native
+**Slash Command:** `/rn-review`
+**Composable With:** agents/react-native/bridge/agent.md
+
+---
+
+## Purpose
+
+React Native component audit covering bridge calls, re-renders, New Architecture readiness, and FlatList performance.
+
+---
+
+## Skill Prompt
+
+```
+Review the provided React Native component for these issues:
+
+BRIDGE PERFORMANCE
+- NativeModule calls in render or event handlers that fire frequently.
+  Fix: move to useEffect, debounce, or replace with JSI-based alternatives.
+- AsyncStorage for synchronous-feeling reads: replace with MMKV.
+- Animated.Value without useNativeDriver: true — runs on JS thread, causes jank.
+  Fix: add useNativeDriver: true (only for transform and opacity properties).
+
+RE-RENDERS
+- Missing React.memo on child components that receive stable props.
+- Missing useCallback on functions passed as props.
+- Missing useMemo on expensive computations or derived arrays.
+- useSelector without equality function (Redux) — re-renders on any store change.
+  Fix: use shallowEqual or select specific slice.
+- Context consumers re-rendering on every context value change.
+  Fix: split context or use useMemo on context value.
+
+FLATLIST OPTIMIZATION
+- Missing keyExtractor → React can't diff efficiently.
+- Missing getItemLayout for fixed-height rows → scrollToIndex doesn't work.
+- Missing removeClippedSubviews (Android) for long lists.
+- initialNumToRender not set — defaults to 10, adjust for screen height.
+- renderItem not memoized with useCallback.
+
+NEW ARCHITECTURE
+- NativeModule using RCTBridgeModule → migrate to TurboModule.
+- ViewManager using RCTViewManager → migrate to Fabric component.
+- Animated.event bridge calls → useNativeDriver or Reanimated 2.
+
+TYPESCRIPT
+- any type on props or return values.
+- Missing null checks on optional props.
+
+For each issue: component name, line/hook, what causes it, and the fix.
+```

package/skills/react-native/rn-tdd.md

@@ -0,0 +1,76 @@
+# Skill — /rn-tdd
+
+**Platform:** React Native
+**Slash Command:** `/rn-tdd`
+**Composable With:** agents/react-native/bridge/agent.md
+
+---
+
+## Purpose
+
+Runs the red-green-refactor TDD loop for React Native using Jest and React Native Testing Library. Generates failing tests first, then the minimal implementation.
+
+---
+
+## Skill Prompt
+
+```
+Run the React Native TDD loop for the described component or function:
+
+STEP 1 — RED: Write a failing test using Jest + @testing-library/react-native.
+- Render the component with renderHook() or render().
+- Use userEvent for interactions (preferred over fireEvent for accuracy).
+- For custom hooks: use renderHook() with act() for state updates.
+- For Redux/Zustand: wrap in provider or use store.dispatch in test.
+- Test must fail for the right reason (expect failure, not crash).
+
+STEP 2 — GREEN: Minimal implementation to pass the test.
+STEP 3 — REFACTOR: Apply hooks, memoization, proper types.
+
+Format:
+--- RED ---
+<Jest test>
+
+--- GREEN ---
+<minimal component/function>
+
+--- REFACTOR ---
+<final implementation>
+```
+
+---
+
+## Example
+
+**Input:** "TDD a useDebounce hook that delays a value by N ms"
+
+**Output:**
+```typescript
+--- RED ---
+import { renderHook, act } from '@testing-library/react-native';
+import { useDebounce } from './useDebounce';
+
+jest.useFakeTimers();
+
+test('returns debounced value after delay', () => {
+  const { result, rerender } = renderHook(
+    ({ value }) => useDebounce(value, 300),
+    { initialProps: { value: 'a' } }
+  );
+  expect(result.current).toBe('a');
+  rerender({ value: 'ab' });
+  expect(result.current).toBe('a'); // still old value
+  act(() => jest.advanceTimersByTime(300));
+  expect(result.current).toBe('ab');
+});
+
+--- GREEN ---
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debounced, setDebounced] = React.useState(value);
+  React.useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+  return debounced;
+}
+```

package/skills/shared/README.md

@@ -0,0 +1,46 @@
+# Shared / Cross-Platform Skills
+
+Reusable skill prompt modules that apply across Android, iOS, Flutter, and React Native. These are platform-agnostic and can be composed with any agent or used standalone.
+
+## Index
+
+| Skill | File | Platforms | When to Use |
+|---|---|---|---|
+| Crash Log Analysis | [crash-analysis.md](crash-analysis.md) | Android, iOS | Quick crash triage — identify crash type, first app frame, root cause pattern |
+| Accessibility Audit | [accessibility-audit.md](accessibility-audit.md) | All | WCAG 2.2 mobile checklist — labels, touch targets, roles, focus order, announcements |
+| Security Scan | [security-scan.md](security-scan.md) | All | OWASP Mobile Top 10 — secrets, insecure storage, WebView, permissions, cryptography |
+
+## Usage
+
+```
+# Quick security gate before code review
+[paste skill prompt from security-scan.md]
+
+Scan this file for security issues: [paste code]
+```
+
+## Composable Pattern — Full Pre-Release Audit
+
+```
+# Run all three shared skills in one session for a comprehensive pre-release check
+[paste security-scan.md skill]
+[paste accessibility-audit.md skill]
+
+Review this screen for both security and accessibility issues: [paste code]
+```
+
+## Composable With
+
+- [`agents/cross-platform/security-scanner`](../../agents/cross-platform/security-scanner/) — full OWASP report with exploitability analysis
+- [`agents/cross-platform/accessibility-auditor`](../../agents/cross-platform/accessibility-auditor/) — full WCAG report with platform-specific fixes
+- [`agents/android/android-crash-analyzer`](../../agents/android/android-crash-analyzer/) — 9-section crash analysis
+- [`agents/ios/crash-analyzer`](../../agents/ios/crash-analyzer/) — iOS crash analysis
+
+## Contributing
+
+Ideas for new shared skills:
+- `api-contract-review.md` — REST API design patterns, versioning, error response shapes
+- `localization-audit.md` — flag hardcoded strings, RTL layout issues, date/number formatting
+- `code-documentation.md` — generate KDoc, DocC, or DartDoc comments
+
+Copy `templates/skill-template.md` and open a PR.

package/skills/shared/accessibility-audit.md

@@ -0,0 +1,132 @@
+# Skill — Mobile Accessibility Audit
+
+**Platform:** Cross-Platform (Android / iOS / Flutter / React Native)  
+**Category:** Code Quality / Accessibility  
+**Composable With:** agents/cross-platform/accessibility-auditor/agent.md
+
+---
+
+## Purpose
+
+Reviews mobile UI code against WCAG 2.2 mobile guidelines and platform-specific accessibility APIs. Covers content descriptions, touch targets, screen reader behavior, focus order, and contrast. Use as a pre-release accessibility gate.
+
+## When to Use
+
+- Before releasing any screen that has new interactive elements
+- When QA or a user reports a TalkBack/VoiceOver issue
+- As a composable check inside a larger UI review
+
+---
+
+## Skill Prompt
+
+```
+When auditing mobile UI code for accessibility, check for:
+
+CONTENT DESCRIPTIONS & LABELS
+Android (Compose/XML):
+- Every Image, Icon, or decorative element needs contentDescription.
+  If purely decorative: contentDescription = null (Compose) or android:contentDescription=""
+  and importantForAccessibility="no" (XML).
+- Icon-only buttons: contentDescription must describe the ACTION, not the icon.
+  "Back" not "Left arrow". "Delete task" not "Trash icon".
+- Checkboxes and toggles: the label must be associated (Modifier.toggleable with semantics,
+  or labelFor in XML).
+
+iOS (SwiftUI/UIKit):
+- Images used as buttons or conveyors of meaning need .accessibilityLabel("description").
+- Decorative images: .accessibilityHidden(true).
+- Custom controls: set accessibilityTraits (.button, .selected, .adjustable) to tell
+  VoiceOver the element's role.
+- accessibilityValue for sliders, toggles, and steppers: VoiceOver reads both label + value.
+
+Flutter:
+- Semantics widget required for custom interactive widgets. Set label, hint, and button: true/false.
+- Exclude decorative elements: ExcludeSemantics or Semantics(excludeSemantics: true).
+- MergeSemantics: merge related child semantics into one accessible node for compound widgets.
+
+React Native:
+- accessibilityLabel on all touchable elements that don't have descriptive text children.
+- accessibilityRole: 'button', 'link', 'checkbox', 'header', etc.
+- accessibilityState for interactive state: {checked: bool, disabled: bool, selected: bool}.
+- accessibilityHint for actions whose purpose isn't obvious from the label alone.
+
+TOUCH TARGET SIZE
+- Minimum 48×48 dp (Android) / 44×44 pt (iOS) for all interactive elements.
+- Flag any button, icon button, or tap area smaller than this minimum.
+- Use padding to expand the touch area without changing visual size:
+  Android Compose: Modifier.minimumInteractiveComponentSize() or padding
+  iOS: contentEdgeInsets or .contentShape(Rectangle().inset(by: -8))
+  Flutter: Padding or SizedBox wrapping the widget
+  React Native: padding or hitSlop={{ top: 8, bottom: 8, left: 8, right: 8 }}
+
+FOCUS ORDER & KEYBOARD NAVIGATION
+- Logical reading order: screen readers read in the order elements appear in the view hierarchy.
+  Flag any absolute-positioned or z-index-manipulated elements where visual order ≠ DOM/hierarchy order.
+- Android: use android:accessibilityTraversalAfter/Before or Modifier.semantics { traversalIndex } in Compose.
+- iOS: accessibilityElements array on the parent to define custom order.
+- React Native: accessible={true} with accessibilityViewIsModal for modals (traps focus inside).
+
+DYNAMIC CONTENT ANNOUNCEMENTS
+- When content changes dynamically (success toast, error message, loading complete), announce it:
+  Android: View.announceForAccessibility("Upload complete") or AccessibilityEvent.TYPE_ANNOUNCEMENT
+  iOS: UIAccessibility.post(notification: .announcement, argument: "Upload complete")
+  Flutter: SemanticsService.announce("Upload complete", TextDirection.ltr)
+  React Native: AccessibilityInfo.announceForAccessibility("Upload complete")
+- Flag any dynamic UI state change (snackbar, badge update, count change) that has no announcement.
+
+COLOR & CONTRAST
+- The code cannot prove contrast ratios, but flag:
+  Any hardcoded color that is not from the theme/design system (cannot be verified for contrast).
+  Any text rendered over an image without a scrim/overlay (contrast is unpredictable).
+  Any disabled state that uses only color to convey disabled-ness (should also use reduced opacity + non-interactive).
+
+Severity:
+- CRITICAL: blocks screen reader users entirely (no label on interactive element, focus trap outside modal)
+- HIGH: degrades usability significantly (touch target too small, wrong role, no dynamic announcement)
+- MEDIUM: impacts some users (missing hint, suboptimal reading order)
+- LOW: minor improvement (redundant label, overly verbose hint)
+```
+
+---
+
+## Example
+
+**Input:**
+```kotlin
+// Compose
+IconButton(onClick = { onDelete(item.id) }) {
+    Icon(Icons.Default.Delete, contentDescription = null)
+}
+```
+
+**Output:**
+```
+CRITICAL — Icon button has no accessibility label
+  Problem: contentDescription = null on the Icon means TalkBack announces this as an
+           unlabeled button. Screen reader users cannot know what tapping it does.
+  Fix:
+  IconButton(onClick = { onDelete(item.id) }) {
+      Icon(
+          imageVector = Icons.Default.Delete,
+          contentDescription = "Delete ${item.name}"  // action-oriented, item-specific
+      )
+  }
+```
+
+---
+
+## Composition Example
+
+```
+Prepend this skill to any UI component review for a quick accessibility gate.
+For a full structured accessibility audit with severity counts and a platform-specific
+remediation guide, run agents/cross-platform/accessibility-auditor/agent.md.
+```
+
+---
+
+## Notes
+
+- Automated accessibility checkers (Accessibility Scanner on Android, Xcode Accessibility Inspector) catch some issues but miss semantic meaning, logical reading order, and dynamic announcement gaps.
+- Always test with TalkBack (Android) and VoiceOver (iOS) on a real device — emulator behavior differs.

package/skills/shared/crash-analysis.md

@@ -0,0 +1,110 @@
+# Skill — Crash Log Analysis
+
+**Platform:** Cross-Platform (Android / iOS)  
+**Category:** Debugging & Crash Analysis  
+**Composable With:** agents/android/crash-analyzer/agent.md
+
+---
+
+## Purpose
+
+Teaches an LLM how to read and triage mobile crash logs. Useful as a standalone skill for quick triage or as a module inside a larger debugging workflow.
+
+## When to Use
+
+- When you paste a crash log into a chat and want a quick explanation
+- When composing a workflow that processes multiple crash logs in bulk
+- When onboarding a junior developer on how to read stack traces
+
+---
+
+## Skill Prompt
+
+```
+When analyzing a mobile crash log (Android logcat / iOS .crash file), follow this process:
+
+1. IDENTIFY THE CRASH TYPE
+   - Exception class (Java/Kotlin): NullPointerException, IllegalStateException,
+     IndexOutOfBoundsException, OutOfMemoryError, etc.
+   - Signal (native/NDK): SIGSEGV (null dereference), SIGABRT (assertion/abort),
+     SIGBUS (unaligned memory access)
+   - ANR: Look for "ANR in" at the top. Check the main thread stack for blocking calls.
+   - OOM: "java.lang.OutOfMemoryError" — look at heap allocation chain.
+
+2. FIND THE FIRST APPLICATION FRAME
+   - Skip system frames: android.*, java.*, kotlin.*, kotlinx.*, com.google.*, androidx.*
+   - The first frame with YOUR package name is where the crash originated in your code.
+   - That frame is the starting point for root-cause analysis — not just the exception site.
+
+3. TRACE THE CALL CHAIN
+   - Read the stack trace bottom-to-top (entry point → crash site).
+   - Identify the user action or lifecycle event that triggered the chain.
+   - Note thread name (main thread crash vs. background thread crash).
+
+4. STATE THE ROOT CAUSE
+   - Do not just say "null pointer at line 42." Explain WHY the value was null,
+     or WHY the index was out of bounds, given the code path.
+   - Common root causes by exception type:
+     NPE: async result used before completion; activity/fragment reference held after destroy
+     IOOB: list modified during iteration; off-by-one in manual index calculation
+     ISE: Fragment transaction after onSaveInstanceState
+     OOM: bitmap not recycled; memory leak accumulating over time
+     ANR: network/disk I/O on main thread; lock contention
+
+5. REMEDIATION
+   - State a concrete code fix, not "add null check."
+   - If the fix involves async timing, explain the correct lifecycle hook to use.
+   - Suggest a test case that would have caught this crash.
+```
+
+---
+
+## Example
+
+**Input:**
+```
+Fatal Exception: java.lang.IllegalStateException: Fragment ProfileFragment not attached to a context.
+   at androidx.fragment.app.Fragment.requireContext(Fragment.java:947)
+   at com.example.app.ProfileFragment.updateUI(ProfileFragment.kt:88)
+   at com.example.app.ProfileViewModel$loadProfile$1.invokeSuspend(ProfileViewModel.kt:41)
+```
+
+**Output:**
+```
+Crash Type: IllegalStateException — Fragment not attached to context
+First App Frame: ProfileFragment.updateUI (line 88)
+
+Root Cause:
+The ViewModel's coroutine completes and calls back into the Fragment after the Fragment
+has been detached (e.g., user navigated away). requireContext() throws if the Fragment
+is not currently attached to an Activity.
+
+Fix:
+In ProfileFragment.updateUI, guard with `if (!isAdded) return` before calling
+requireContext(). Better: collect the ViewModel's StateFlow in onViewCreated using
+`viewLifecycleOwner.lifecycleScope`, which automatically cancels when the view is destroyed,
+preventing the callback from reaching the Fragment at all.
+
+Test Case:
+Navigate to Profile screen → trigger a slow network call → immediately navigate back →
+confirm no crash in Crashlytics within 5 minutes of the scenario.
+```
+
+---
+
+## Composition Example
+
+```
+Use this skill as a lightweight triage step before running the full Crash Log Analyzer agent.
+Paste the skill prompt, then paste the crash log for a quick 3-sentence explanation.
+For full structured output (root cause + AFFECTED SURFACE + REMEDIATION steps),
+run agents/android/crash-analyzer/agent.md instead.
+```
+
+---
+
+## Notes
+
+- Works for both Android and iOS crash reports.
+- For symbolicated iOS crashes, the skill assumes the crash file has already been symbolicated via `symbolicatecrash` or Xcode Organizer.
+- ANR analysis requires the full `traces.txt` dump from `/data/anr/` — a single-thread excerpt is insufficient.