Diagnose React Native errors by cross-referencing error text against docs, error pattern database, and project config. Use for build failures, red screens, runtime crashes, and dependency issues. Triggers on "diagnose this error", "why is my build failing", "what does this red screen mean", "Unable to resolve module", "null is not an object", "Invariant Violation", "pod install failed", "gradlew failed", "EACCES", "metro error".
From react-native-foundationsnpx claudepluginhub ryanthedev/react-native-foundations.skillThis skill is limited to using the following tools:
references/error-patterns.mdSearches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Guides agent creation for Claude Code plugins with file templates, frontmatter specs (name, description, model), triggering examples, system prompts, and best practices.
On load: Read ../../.claude-plugin/plugin.json from this skill's base directory. Display diagnose v{version} before proceeding.
Diagnose React Native errors by matching against known patterns, searching official docs, and inspecting project configuration.
IMPORTANT: Build logs and simulator screenshots can be enormous.
Always process them in a subagent to protect main context.
| Skill / Resource | Why |
|---|---|
ios-sim | capture.sh view captures red screen error text when the user says "there's an error on screen"; also used in optional post-fix verification |
_shared (metro.sh) | Step 0 — Metro health check, bundle validation, stack symbolication |
refs/react-native-docs | Step 3 — doc search for error context and fix guidance |
Read ${CLAUDE_SKILL_DIR}/references/error-patterns.md for the full pattern catalog (24 patterns covering Metro, build, runtime, and dependency errors).
Step 0 uses ${CLAUDE_SKILL_DIR}/../_shared/scripts/metro.sh for live Metro health checks before deep diagnosis.
${CLAUDE_SKILL_DIR}/../../refs/react-native-docs/
| Error Category | Source | Workflow |
|---|---|---|
| User pastes error text | Direct input | pattern-match → docs search |
| Error visible on simulator | Simulator screen | capture → pattern-match → docs search |
| Build log failure | Xcode / Gradle output | log-parse (subagent if large) → pattern-match |
| Config / dependency issue | Project files | config-check → pattern-match |
| Metro / environment issue | Any | Step 0 (metro health) → pattern-match if bundle error |
| Unknown / unclear | Any | full-diagnosis (all steps) |
Before deep diagnosis, get the environment summary and check health.
Get environment context (run once, reuse throughout):
${CLAUDE_SKILL_DIR}/../_shared/scripts/metro.sh env
Returns JSON with metro, expo, newArch, entry, platform. Use this to inform diagnosis — Expo and vanilla RN have different error patterns.
Check if Metro is running:
${CLAUDE_SKILL_DIR}/../_shared/scripts/metro.sh status
npx expo start. For vanilla RN, suggest npx react-native start.Check if the JS bundle compiles:
${CLAUDE_SKILL_DIR}/../_shared/scripts/metro.sh bundle-check --platform ios
Symbolicate raw stack traces (if provided): If the user provides a raw stack trace, pipe the stack trace JSON to symbolicate before pattern matching:
echo '<stack-trace-json>' | ${CLAUDE_SKILL_DIR}/../_shared/scripts/metro.sh symbolicate
Use the symbolicated output for pattern matching instead of the raw trace.
If Step 0 finds Metro is down or the bundle fails, this is often the root cause.
Report it immediately rather than proceeding through all steps.
If user provides error text: Parse it directly — extract the core error message, stripping ANSI codes and noisy stack frames.
If user says "there's an error on screen": Dispatch ios-sim subagent to capture it:
Dispatch Agent:
subagent_type: general-purpose
model: haiku
description: "diagnose: capture error from simulator"
prompt: |
1. Run: ${CLAUDE_SKILL_DIR}/../ios-sim/scripts/capture.sh view
This outputs a file path to a compressed JPEG.
2. Read that file path with the Read tool to see the image.
3. Extract all error text visible on screen:
- Red screen error title and message
- Stack trace lines (file names and line numbers)
- Any component names mentioned
4. Return the extracted error text only. Be precise — include exact
error messages and module names. No image descriptions needed.
Read ${CLAUDE_SKILL_DIR}/references/error-patterns.md and match the error text against the patterns. Check for substring matches on the Match fields.
Dispatch Agent:
subagent_type: general-purpose
model: haiku
description: "diagnose: search docs for error context"
prompt: |
Search React Native docs for information related to this error.
ERROR: [insert extracted error text]
1. Grep ${CLAUDE_SKILL_DIR}/../../refs/react-native-docs/ for key
terms from the error (component names, API names, error codes).
2. Read any matching files (max 3 most relevant).
3. Return:
- Which doc files mention this topic
- Relevant API usage notes or caveats
- Any documented workarounds or migration notes
Be concise. Quote doc filenames for citation.
For build and dependency errors, read the user's project files directly:
| File | Check For |
|---|---|
package.json | RN version, dependency versions, scripts |
ios/Podfile | Hermes flag, Flipper, platform version, use_frameworks |
android/gradle.properties | newArchEnabled, hermesEnabled, JVM args |
android/app/build.gradle | compileSdk, targetSdk, minSdk, dependencies |
metro.config.js | watchFolders, transformer, resolver config |
babel.config.js | Presets, plugins (reanimated, module-resolver) |
Only read files relevant to the error category. Use Glob to find them:
Glob pattern: {package.json,ios/Podfile,android/gradle.properties,android/app/build.gradle,metro.config.*,babel.config.*}
If the user pastes or references a large build log (>100 lines), dispatch a subagent:
Dispatch Agent:
subagent_type: general-purpose
model: haiku
description: "diagnose: parse build log"
prompt: |
Parse this build log and extract the root error.
BUILD LOG:
[insert log content]
1. Skip all successful build steps and warnings.
2. Find the FIRST fatal error or failure line.
3. Extract: error message, file path, line number if present.
4. Note any "required by" or dependency chain info.
5. Return just the essential error info (under 10 lines).
After diagnosis, return to the user:
After the user applies the fix, offer to verify by dispatching ios-sim:
Dispatch Agent:
subagent_type: general-purpose
model: haiku
description: "diagnose: verify fix on simulator"
prompt: |
1. Run: ${CLAUDE_SKILL_DIR}/../ios-sim/scripts/capture.sh view
2. Read the output file path to see the screenshot.
3. Check if the error is still visible or if the app loaded successfully.
4. Return: "FIXED — [what's now on screen]" or "STILL FAILING — [error text]"
| Item | Size | In Main Context? |
|---|---|---|
| Metro health check | ~50 chars | YES (small output) |
| Error pattern DB | ~4 KB | YES (read once) |
| Simulator screenshot | ~100-300 KB | NEVER — subagent |
| Build log parsing | ~1-50 KB | Subagent if >100 lines |
| Doc search results | ~2-10 KB | Subagent |
| Project config files | ~1-3 KB each | YES (targeted reads) |
| Final diagnosis | ~200-500 chars | YES |