| name | clean |
| description | Intelligent environment reset for React Native projects — diagnoses stale caches before cleaning instead of blindly nuking everything. Triggers on "clean build", "reset caches", "fresh start", "metro won't start", "build is broken", "nuclear clean", "clear derived data". |
| allowed-tools | Bash, Read, Grep |
Skill: clean
On load: Read ../../.claude-plugin/plugin.json from this skill's base directory. Display clean v{version} before proceeding.
Diagnose-first environment reset for React Native projects. Checks what is actually stale before cleaning, then executes only the necessary steps.
Workflow
1. Diagnose
Run the diagnosis script to check environment state:
bash ${CLAUDE_SKILL_DIR}/scripts/diagnose.sh
This outputs a JSON report covering all cache/state checks. Review the report and summarize findings for the user.
2. Recommend
Based on the diagnosis, recommend targeted clean steps. Present only what is needed — do not suggest cleaning things that are healthy.
3. Clean
Run the clean script with flags for the necessary targets:
bash ${CLAUDE_SKILL_DIR}/scripts/clean.sh [flags]
WARNING: Always confirm with the user before running destructive clean operations.
Do not run --all or --node-modules without explicit user approval.
4. Verify (optional)
After cleaning, optionally verify the environment works:
- Start Metro:
npx react-native start
- Launch app via
ios-sim skill if available
Clean Targets
| Flag | What it removes | When to use |
|---|
--metro | /tmp/metro-*, /tmp/haste-*, React Native temp caches | Metro bundling errors, stale module resolution |
--watchman | Watchman watches and internal state | File change detection broken, phantom "file not found" errors |
--node-modules | node_modules/ + reinstall | Dependency corruption, version mismatch after branch switch |
--pods | ios/Pods/, ios/Podfile.lock re-install | iOS build errors after native dependency changes |
--derived-data | ~/Library/Developer/Xcode/DerivedData | Xcode build failures, stale Swift/ObjC caches |
--gradle | android/.gradle/, android/app/build/ | Android build failures, stale Gradle caches |
--all | All of the above | True nuclear option — last resort |
Diagnosis Checks
| Check | How | Indicates |
|---|
| Port 8081 | lsof -i :8081 | Metro already running / port conflict |
| Watchman | watchman watch-list | Stale or broken file watches |
| node_modules integrity | Compare .package-lock.json mtime vs package-lock.json | Modules out of sync with lockfile |
| Pods staleness | Compare ios/Pods mtime vs ios/Podfile mtime | Pods need reinstall |
| DerivedData size | du -sh ~/Library/Developer/Xcode/DerivedData | Large DerivedData may cause issues |
| Android build state | Check android/.gradle, android/app/build existence | Stale Android build artifacts |
| Metro cache | Check /tmp/metro-* existence | Stale Metro bundler cache |
Tips
- Start with diagnosis — most issues only need 1-2 targeted cleans, not a full nuke
--pods will run pod install after removing Pods--node-modules will run npm install (or yarn) after removing node_modules- If Metro won't start, check port 8081 first — often a zombie process is the cause
- Cross-reference build errors with the
docs skill for API/config guidance
