mobile-hybrid-audit

A Claude Code skill that audits and fixes web projects for a pixel-perfect, native-feeling mobile experience — as a PWA, a Capacitor app (iOS + Android), or both.

It detects your framework and mobile setup, loads only the references it needs, fixes the issues that actually break mobile (notch overlap, keyboard jump, input zoom, 100vh, safe areas, splash, status bar), and ends with a structured audit report. It preserves your existing design — mobile fixes are structural, not cosmetic.

---

Why

Turning a web app into a store-grade hybrid app is a long tail of small, easy-to-miss bugs: a font-size: 14px input that zooms on iOS focus, a bottom nav swallowed by the home indicator, 100vh scrolling under the toolbar, a splash that flashes white, a status bar overlapping your header on Android edge-to-edge. This skill encodes the checklist — including the 2026-era gotchas (Capacitor 8 mandatory edge-to-edge, the Chromium < 140 safe-area bug, iOS Privacy Manifest, the Play Store 12-testers rule) — so Claude fixes them consistently instead of rediscovering them each time.

---

Installation

Option A — clone into your skills folder (recommended)

User-scoped (available in every project):

git clone https://github.com/kachouri/mobile-hybrid-audit.git \
  ~/.claude/skills/mobile-hybrid-audit

Project-scoped (only this repo):

git clone https://github.com/kachouri/mobile-hybrid-audit.git \
  .claude/skills/mobile-hybrid-audit

Option B — packaged .skill file

Download mobile-hybrid-audit.skill from the latest release and install it through Claude Code's skill management, or unzip it into your skills folder:

unzip mobile-hybrid-audit.skill -d ~/.claude/skills/

The .skill file is just a ZIP whose top folder is mobile-hybrid-audit/. Build it yourself with bash build-skill.sh.

Verify

Start Claude Code in any project and ask "audit my app for mobile" — the skill should trigger. Or run the detector directly:

bash ~/.claude/skills/mobile-hybrid-audit/scripts/detect.sh .

---

Usage

Just talk to Claude. The skill auto-triggers on phrasing like:

• "Make this web app work on mobile / ship it as an app"
• "Audit my PWA / Capacitor app"
• "Prepare for the App Store / Play Store"
• "Fix the notch overlap / keyboard pushing my footer / input zoom on iOS"
• "Add PWA installability" · "Wrap my app with Capacitor"

It also triggers on symptoms: content under the notch, footer hidden by keyboard, splash stuck, status bar overlap, 100vh issues, input zoom.

What happens

1. Detect — scripts/detect.sh reports framework, build dir, package manager, PWA state, Capacitor version + platforms + plugins, Android target SDK, iOS Privacy Manifest presence.
2. Decide mode — Web+PWA / Capacitor / both, and (for Capacitor) embedded vs remote server.url.
3. Load references on demand — only the files relevant to your setup.
4. Apply minimal fixes — using the ready-to-copy templates in assets/.
5. Verify — lint, build, npx cap sync.
6. Report — every fix, every file changed, manual device checks, store-submission checklist.

---

What it covers

Area	Highlights
Frameworks	Vite (React/Vue/Svelte), Next.js, Nuxt, SvelteKit, Angular, CRA, plain HTML
PWA	manifest, maskable icons, service worker strategy, install prompt, offline fallback, vite-plugin-pwa / next-pwa
Capacitor	versions 6/7/8, config, plugin selection, cap sync, live-reload, assets generation
Hybrid architecture	embedded vs remote server.url (OTA), chunk-reload net, auth-listener deadlock, Sign in with Apple, WebView storage
iOS	notch / Dynamic Island, status bar, splash, input-zoom prevention, Universal Links, ATT, Privacy Manifest, Info.plist usage strings
Android	edge-to-edge (SDK 36+ forced), status & nav bar, hardware back, adaptive icons, App Links, splash API, runtime permissions
Safe areas	env(safe-area-inset-*), viewport-fit=cover, Chromium < 140 bug, 100vh → 100dvh
Keyboard	input zoom, resize modes, footer jump, focus scroll
Responsive	320–430px widths, 44/48px touch targets, overflow, table→card
Performance	Web Vitals (LCP/INP/CLS), lazy loading, virtualization, bundle
Accessibility	contrast, focus-visible, reduced motion, dark mode, no user-scalable=no

---

Repository structure

mobile-hybrid-audit/
├── SKILL.md                      # Entry point — Claude reads this first, routes to references
├── README.md                     # This file
├── LICENSE                       # MIT
├── build-skill.sh                # Package into a distributable .skill (ZIP)
├── references/                   # Loaded on demand by the skill
│   ├── audit-checklist.md        # The full audit workflow (master reference)
│   ├── hybrid-architecture.md    # Embedded vs remote, chunk-reload, deadlocks, SiwA
│   ├── pwa.md
│   ├── capacitor.md
│   ├── safe-areas.md
│   ├── keyboard.md
│   ├── responsive.md
│   ├── performance.md
│   ├── accessibility.md
│   ├── ios.md
│   └── android.md
├── assets/                       # Ready-to-copy templates
│   ├── mobile-base.css           # Safe-area vars, resets, input rules, touch targets
│   ├── initMobileApp.ts          # Capacitor runtime init (StatusBar/Splash/Keyboard/back/deep-link)
│   ├── manifest.template.json    # PWA manifest skeleton
│   ├── capacitor.config.template.ts
│   ├── viewport-meta.html
│   └── haptics.ts                # No-op-on-web haptic wrappers
└── scripts/
    └── detect.sh                 # Auto-detect framework / Capacitor / PWA state

---

The detector

scripts/detect.sh is standalone — run it on any project, no Claude required:

bash scripts/detect.sh /path/to/project

pkg_manager=npm
framework=vite-react
build_dir_guess=dist
css_entry=src/styles/index.css
tailwind=yes
pwa_manifest=public/manifest.json
pwa_plugin=vite-plugin-pwa
capacitor=yes
capacitor_version=8.3.0
capacitor_major=8
has_ios=yes
has_android=yes
capacitor_plugins="@capacitor/app","@capacitor/haptics",...
android_target_sdk=35
ios_privacy_manifest=missing

It lists runtime plugins only (excludes core/cli/android/ios/assets tooling) and searches all of ios/ for the Privacy Manifest.

---

Boundaries

This skill does not:

• Redesign your UI (it preserves existing visuals)
• Do pure native (Swift/Kotlin) development — Capacitor only
• Cover React Native or Flutter
• Build CI/CD pipelines
• Do backend / API work
• Disable zoom (user-scalable=no) or kill text selection globally — both are a11y violations and it won't add them unless you explicitly ask

---

Contributing

Issues and PRs welcome. Good contributions: new framework detection in detect.sh, additional store-review gotchas, version notes for new Capacitor / OS releases. Keep references self-contained and load-on-demand so the entry SKILL.md stays small.

License

MIT — free to use, adapt, and redistribute.