kachouri/mobile-hybrid-audit

mobile-hybrid-audit

Audit and fix web projects for pixel-perfect mobile experience as PWA, Capacitor app, or hybrid.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/kachouri/mobile-hybrid-audit --skill mobile-hybrid-audit

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

Mobile Hybrid Pixel-Perfect Audit & Fix

This skill audits and fixes web projects to deliver a production-grade mobile experience as PWA, Capacitor app, or both. The goal is a native-feeling app that is stable, responsive, safe-area aware, keyboard-friendly, with a clean splash and status bar, and installable as a PWA — without breaking existing styling or features.

When to use

Trigger this skill when the user wants to:

  • Audit an existing web app for mobile readiness
  • Fix specific mobile bugs (notch overlap, keyboard, scroll, viewport)
  • Add or improve PWA support (manifest, service worker, install)
  • Add or improve Capacitor wrapping (iOS/Android)
  • Prepare a project for App Store / Play Store submission
  • Migrate from web-only to hybrid mobile

When NOT to use

  • Building a brand new app from scratch with a full visual redesign — this skill preserves existing design, it doesn't reinvent it
  • Pure native development (Swift, Kotlin) — Capacitor only
  • Pure CI/CD pipelines — use a dedicated Capacitor CI/CD skill
  • Backend / API work
  • React Native or Flutter projects — this skill is web-based hybrid only

Working principles

  1. Read before editing. Always inspect the current state of a file before modifying it. Preserve existing styles and conventions.
  2. Minimal but robust changes. Improve what exists; don't duplicate or rewrite wholesale.
  3. Justify every change. The final report must list each modification with reasoning.
  4. Detect, then act. Framework, Capacitor version, and PWA state determine which references to load.
  5. Never refactor visuals without explicit consent. Mobile fixes shouldn't change the look unless the user asks.

Workflow

Step 1 — Detect the environment

Run the detection script first:

bash
bash scripts/detect.sh

This outputs a JSON-ish summary of:

  • Framework (Vite/React, Next.js, Vue, Nuxt, Svelte, Angular, plain)
  • Build output directory (dist, build, out, .next)
  • Package manager (npm, pnpm, yarn, bun)
  • PWA state (manifest, service worker, vite-plugin-pwa)
  • Capacitor state (installed, version, android/, ios/, capacitor.config.*)
  • Capacitor plugins installed
  • CSS entry file
  • HTML entry file (index.html, _document.tsx, app/layout.tsx)

If the script can't be run, perform the same checks manually by reading package.json, listing the root directory, and grepping for @capacitor/ imports.

Step 2 — Decide the target mode

Confirm with the user (or infer from project state):

ModeTrigger
Web + PWA onlyNo @capacitor/ deps, user wants installable web app
Capacitor onlyandroid/ or ios/ exists, no manifest needed for distribution
PWA + CapacitorUser wants both (recommended for max reach)

If Capacitor is in scope, also decide how the shell loads web content — embedded (webDir, offline-first, re-build per change) vs remote (server.url, OTA instant updates, App Review 4.2 risk). This is architectural and hard to reverse. See references/hybrid-architecture.md before choosing.

If unsure, ask the user one question with ask_user_input_v0 style options.

Step 3 — Load the relevant references

Read only the references needed for the detected mode. Each reference is self-contained.

  • `references/audit-checklist.md` — The full audit checklist. Load this first when running a complete audit. It covers HTML head, CSS globals, safe areas, responsive, accessibility, performance, build verification.
  • `references/pwa.md` — Load if PWA is in scope. Covers manifest, service worker, install prompt, offline strategies, vite-plugin-pwa configuration.
  • `references/capacitor.md` — Load if Capacitor is in scope. Covers capacitor.config, plugin selection, npx cap sync workflow, version-specific behavior (Capacitor 6/7/8).
  • `references/hybrid-architecture.md` — Load when deciding how the shell loads web content (embedded vs remote server.url / OTA) and for cross-cutting production pitfalls: chunk-reload net for hash-based builds, auth-listener deadlock (Supabase), Sign in with Apple requirement, WebView storage durability.
  • `references/ios.md` — Load when working on iOS specifics: Dynamic Island, notch, status bar styles, splash screen, Universal Links, ATT, Privacy Manifest, font sizing to prevent input zoom.
  • `references/android.md` — Load when working on Android specifics: edge-to-edge (mandatory on SDK 36+), status bar, navigation bar, back button, adaptive icons, App Links, splash screen API.
  • `references/safe-areas.md` — Load for any safe-area issue (notch overlap, footer under home indicator, edge-to-edge handling, Chromium <140 bug on Android).
  • `references/keyboard.md` — Load for keyboard issues (footer jump, input zoom, focus scroll, viewport resize behavior).
  • `references/responsive.md` — Load for responsive/pixel-perfect audit (test widths, touch targets, overflow, table-to-card patterns).
  • `references/performance.md` — Load for mobile performance work (lazy loading, virtualization, bundle, Web Vitals targets).
  • `references/accessibility.md` — Load for a11y audit (contrast, focus, labels, reduced motion, dark mode, system fonts).

For a full audit request, the typical reading order is: audit-checklist.md → then the platform-specific files matching detected state.

Step 4 — Apply fixes

For each issue found:

  1. Read the target file
  2. Make the minimum change needed
  3. If a template fits exactly (e.g. CSS globals, init mobile script, manifest), copy from assets/ and adapt — don't retype from scratch
  4. Track every modified file for the final report

Available templates in assets/:

  • mobile-base.css — Safe-area variables, body resets, input rules, touch targets
  • initMobileApp.ts — Capacitor runtime init (StatusBar, SplashScreen, Keyboard, lifecycle)
  • manifest.template.json — PWA manifest skeleton with all required fields
  • capacitor.config.template.ts — Capacitor config with recommended plugin settings
  • viewport-meta.html — Correct viewport + Apple meta tags
  • haptics.ts — Safe wrappers for haptic feedback (no-op on web)

Each template has comments marking what to customize (brand color, app ID, app name).

Step 5 — Verify the build

After fixes, run in order:

bash
# Lint (if available)
npm run lint 2>/dev/null || echo "no lint script"

# Build
npm run build

# Capacitor sync (if applicable)
npx cap sync 2>/dev/null || echo "no capacitor"

If any step fails, fix and re-run before producing the report.

Step 6 — Produce the audit report

Use the report template structure (see references/audit-checklist.md section "Final report format"). The report must include:

  • Detected framework & mode
  • Capacitor version (if applicable)
  • All checks passed
  • All issues found and how they were fixed
  • All files modified with one-line justification each
  • Items the user must verify manually on a real device
  • A short follow-up checklist for App Store / Play Store submission if Capacitor is in scope

Critical version-aware behaviors

These cause the most regressions. Always check before applying.

Capacitor version detection

bash
npx cap --version 2>/dev/null
# Also check: cat package.json | grep '"@capacitor/core"'
  • Capacitor 6 — Android edge-to-edge optional, adjustMarginsForEdgeToEdge available
  • Capacitor 7 — adjustMarginsForEdgeToEdge: "auto" recommended, becomes default in 8
  • Capacitor 8 (2026+) — Edge-to-edge mandatory on Android, adjustMarginsForEdgeToEdge removed, all safe-area handling via env(safe-area-inset-*) CSS. iOS defaults to SPM (Swift Package Manager) for new projects.

See references/capacitor.md for full version migration notes.

Android targetSdkVersion 36+

When android/variables.gradle has targetSdkVersion = 36 or higher and the device runs Android 16+, edge-to-edge is forced by the OS regardless of Capacitor config. Safe-area CSS is mandatory or content will render under the status bar and gesture nav.

Chromium < 140 bug on Android

Older Chromium WebViews return 0px for env(safe-area-inset-*) even in edge-to-edge mode. If the project targets older Android devices, install @capacitor-community/safe-area which patches this. See references/safe-areas.md.

iOS Privacy Manifest (PrivacyInfo.xcprivacy)

Required by Apple since May 2024 for App Store submission. The Capacitor iOS template includes a starter, but any added native plugin may require declaring API usage reasons. See references/ios.md.

iOS input zoom

If any input, textarea, or select has font-size < 16px, iOS Safari/WKWebView zooms in on focus and doesn't zoom back out reliably. Always enforce font-size: 16px minimum on form fields. This is the single most common mobile bug in web-to-hybrid migrations.

Report format

Always end with a structured report. Keep it scannable. See references/audit-checklist.md for the full template. The short form:

# Mobile Hybrid Audit Report

## Detected
- Framework: …
- Mode: …
- PWA: …
- Capacitor: vX.Y on iOS/Android

## Fixed
- [critical] …
- [important] …
- [nice-to-have] …

## Files modified
- path/to/file.css — added safe-area variables and dvh fallback
- …

## Verified
✅ Viewport  ✅ Safe areas  ✅ Manifest  ✅ Build  ✅ cap sync

## Manual checks needed
- Test on real iPhone (notch + keyboard)
- Test on real Android (edge-to-edge + back button)
- Test cold start splash
- Test offline shell
- Test add-to-home-screen on iOS Safari

## Submission readiness (if Capacitor)
- [ ] App icon all sizes
- [ ] Privacy policy URL
- [ ] App Store screenshots 6.7" + 6.1"
- [ ] Play Store feature graphic

Boundaries

  • Do not redesign UI. Mobile fixes are structural (padding, viewport, focus, scroll), not aesthetic.
  • Do not install plugins the project doesn't need. Camera, Push, Geolocation are only added when the user explicitly requires them.
  • Do not add a service worker to a project that doesn't need offline. Propose minimal config.
  • Do not disable zoom (user-scalable=no) unless the user explicitly asks — it's an accessibility violation.
  • Do not set user-select: none globally. Inputs and content must stay selectable.
  • Do not silently downgrade Capacitor or framework versions.