: string[]; rnVersion: string; tags: string[]; summary: string; filePath: string; }

interface QueryContext { query: string; targetSdk: string; rnVersion: string; platform: 'ios' | 'android' | 'all'; }

class ContextSkillRouter { private skills: SkillManifest[] = []; private baseDir: string;

constructor(projectRoot: string) { this.baseDir = path.join(projectRoot, '.ai-skills'); }

async initialize(): Promise<void> { const entries = await fs.readdir(this.baseDir, { withFileTypes: true }); const manifests = entries.filter(d => d.isDirectory());

for (const dir of manifests) {
  const manifestPath = path.join(this.baseDir, dir.name, 'manifest.yaml');
  try {
    const raw = await fs.readFile(manifestPath, 'utf-8');
    const data = yaml.load(raw) as any;
    this.skills.push({
      id: data.id,
      domain: data.domain,
      sdkRange: data.sdkRange,
      rnVersion: data.rnVersion,
      tags: data.tags,
      summary: data.summary,
      filePath: path.join(this.baseDir, dir.name, 'reference.md')
    });
  } catch {
    console.warn(`Skipping invalid skill: ${dir.name}`);
  }
}

}

async resolve(queryCtx: QueryContext): Promise<string[]> { const matches = this.skills.filter(skill => { const versionMatch = skill.rnVersion === queryCtx.rnVersion; const sdkMatch = skill.sdkRange.includes(queryCtx.targetSdk); const tagMatch = skill.tags.some(tag => queryCtx.query.toLowerCase().includes(tag.toLowerCase()) ); return versionMatch && sdkMatch && tagMatch; });

const loadedContexts: string[] = [];
for (const skill of matches) {
  const content = await fs.readFile(skill.filePath, 'utf-8');
  loadedContexts.push(`## ${skill.domain} Context\n${content}`);
}

return loadedContexts;

} }

export default ContextSkillRouter;

The router isolates version constraints from query matching. It validates React Native and Expo SDK versions before loading reference material, preventing architectural mismatches. The progressive loading pattern ensures only matched skills consume context tokens.

## Pitfall Guide

### 1. Context Bleed from Over-Matching
**Explanation**: Keyword-based routing without version or platform validation injects irrelevant skills. The model receives conflicting patterns and generates hybrid code that fails at runtime.
**Fix**: Enforce strict version and platform checks in the routing logic. Require explicit tag matches before loading reference material.

### 2. New Architecture vs. Legacy Bridge Confusion
**Explanation**: React Native 0.76+ enables the New Architecture by default, but AI models frequently generate bridge-based native module code. Mixing C++ TurboModule patterns with legacy JNI/ObjC bridges causes build failures.
**Fix**: Include architecture flags in skill manifests. Route New Architecture queries to C++/JSI patterns and explicitly block legacy bridge generation when `rnVersion >= 0.76`.

### 3. State Library Collision
**Explanation**: Projects often experiment with Zustand, Jotai, and Redux Toolkit simultaneously. AI assistants generate mixed patterns, creating inconsistent state access and hydration logic.
**Fix**: Define a single source of truth strategy per project. Create dedicated skills for each library and enforce mutual exclusion in the routing configuration.

### 4. Reanimated UI-Thread Violations
**Explanation**: Reanimated v3 requires animation worklets to run on the UI thread. AI-generated code frequently places network calls or heavy computations inside `useAnimatedStyle`, causing frame drops.
**Fix**: Embed explicit worklet constraints in the animation skill. Include linting rules that flag non-worklet-safe operations inside animation blocks.

### 5. Testing Library API Drift
**Explanation**: Testing Library v13 and v14 introduced changes to async queries and mock rendering. AI models trained on older versions generate deprecated `waitFor` patterns or incorrect `render` options.
**Fix**: Pin test skills to specific major versions. Include migration notes in the reference material and validate query syntax against the target version.

### 6. Expo Config Plugin Overcomplication
**Explanation**: Developers hardcode native module linking instead of using Expo config plugins. AI assistants follow the pattern, breaking EAS Build and OTA update pipelines.
**Fix**: Standardize `app.config.ts` patterns in the Expo skill. Enforce plugin-based configuration and document native module resolution workflows.

### 7. Styling Inconsistency with NativeWind v4
**Explanation**: Mixing utility classes with inline styles or legacy StyleSheet objects creates unpredictable rendering and breaks Tailwind compilation.
**Fix**: Mandate utility-first conventions in the reusable component skill. Include build-time validation that rejects inline style overrides in production builds.

## Production Bundle

### Action Checklist
- [ ] Audit current AI prompts for version drift and replace with modular skill references
- [ ] Create `.ai-skills/` directory structure with domain-specific subfolders
- [ ] Write YAML manifests for each skill including SDK ranges, RN versions, and trigger tags
- [ ] Implement a TypeScript router that validates versions before injecting context
- [ ] Pin state management, animation, and testing skills to specific library major versions
- [ ] Add platform-specific overrides for iOS/Android native module patterns
- [ ] Integrate skill routing into CI/CD to validate context alignment before merges
- [ ] Document skill contribution guidelines for team-wide maintenance

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Solo developer / MVP | Single skill folder with broad tags | Fast setup, minimal maintenance | Low |
| Mid-size team / Expo SDK 54+ | Domain-split skills with version pinning | Prevents architectural drift across contributors | Medium |
| Enterprise / Multi-platform | Strict routing with CI validation + platform overrides | Guarantees build consistency and OTA update reliability | High |
| Legacy bridge migration | Separate legacy vs New Architecture skills | Isolates migration patterns and prevents mixed code generation | Medium |

### Configuration Template

```yaml
# .ai-skills/navigation-react-nav-v7/manifest.yaml
id: nav-react-nav-v7
domain: Navigation
sdkRange: ["53", "54", "55", "56"]
rnVersion: "0.76"
tags: ["navigation", "stack", "tabs", "deep-linking", "react-navigation"]
summary: "React Navigation v7 patterns for Expo Router integration, type-safe routes, and deep linking."
platform: "all"

# .ai-skills/navigation-react-nav-v7/reference.md
## Route Typing
Use `RootStackParamList` for compile-time route validation.
## Deep Linking
Configure `linking.prefixes` in `app.json` and handle with `useLinking()`.
## Performance
Lazy-load screens with `unmountOnBlur` for tab navigators.

// ai-context-loader.ts
import ContextSkillRouter from './ContextSkillRouter';

const router = new ContextSkillRouter(process.cwd());
await router.initialize();

const context = await router.resolve({
  query: "implement tab navigation with lazy loading",
  targetSdk: "54",
  rnVersion: "0.76",
  platform: "all"
});

console.log(context.join('\n\n'));

Quick Start Guide

1. Initialize the skill directory: Run mkdir -p .ai-skills/{core,ecosystem,expo,reusables,performance,testing} in your project root.
2. Populate manifests: Copy the configuration template into each folder, adjusting sdkRange, rnVersion, and tags to match your stack.
3. Deploy the router: Add the TypeScript router to your development tooling or AI assistant configuration. Point it to .ai-skills/.
4. Validate routing: Run a test query against the router. Verify that only version-matched skills load and that context output excludes unrelated patterns.
5. Integrate with AI workflow: Configure your AI assistant to call the router before generating code. Replace static system prompts with dynamic context injection.