One trailing comma in manifest.webmanifest and browsers treat your app as having no manifest at all: no name, no icons, no install prompt. A Workbox route that serves /api/account with StaleWhileRevalidate keeps one customer's account data on a shared computer after they sign out, because the Cache API ignores Cache-Control: private. An event.respondWith() placed after an await throws, and the request goes to the network as if the worker did not exist. This skill finds those and the other PWA mistakes listed below before you ship, and tells you how to fix each one.

Your agent runs a scanner on your web app manifests (manifest.json, *.webmanifest, Next.js app/manifest.ts, the manifest in vite-plugin-pwa configs), service workers (hand-written, Workbox, Serwist), Workbox runtimeCaching configs (workbox-config.js, vite-plugin-pwa, next-pwa, webpack), Angular ngsw-config.json and service worker registration calls. It parses manifests as strict JSON the way browsers do, reads JavaScript and TypeScript with comments and strings set aside, matches whole URL path segments (so /api/session is private and /api/sessions, a conference schedule, is not), understands Workbox matchers that exclude URLs (if ... return false, a NavigationRoute denylist), and knows the defaults of vite-plugin-pwa and next-pwa. The service worker code of the Workbox, Create React App, vite-plugin-pwa and Serwist templates passes without findings. It never runs, builds or serves your app. It returns BLOCK, REVIEW, or NOT FLAGGED, with the file, line, reason, and a safer approach, and each rule links to the W3C, MDN, web.dev or Chrome documentation behind it. Secrets are never printed.

What it checks

BLOCK (fix before shipping)

• W01: a manifest that is not valid JSON (trailing comma, comment, single quotes), not an object, or saved as UTF-16
• W02: start_url outside scope (including "/app" with scope "/app/"), or start_url or scope on localhost
• W03: routes that answer session, token or sign-out URLs, or account, profile, cart or checkout data, from a stored copy while online
• W04: importScripts() over http://, or called inside a fetch, message or other event handler
• W05: event.respondWith() or the first event.waitUntil() called after an await or in a then() callback
• W06: the same URL twice in a cache.addAll() list, also written as ./index.html and index.html (the install fails)

REVIEW (check before release)

• W11: manifests that Chromium will not offer to install (no name, no icon of 144px or more, a display mode that is not installable, prefer_related_applications)
• W12: no maskable icon, or icons with purpose "any maskable"
• W13: manifests without an id
• W14: pages or .html files served cache-first
• W15: versioned caches that are never deleted
• W16: unconditional skipWaiting() in a worker that precaches the app, including next-pwa's default
• W17: API responses served with CacheFirst, CacheOnly or StaleWhileRevalidate (and Angular dataGroups with the default performance strategy), and session or token URLs stored for offline use
• W18: fetch handlers that store every response with cache.put()
• W19: service worker registrations whose scope misses the app's pages or needs a Service-Worker-Allowed header

What's included

• The scanner (Python 3.9+, standard library only)
• A rules guide with the reason, safer approach and official source link for each rule
• A risky and a safe example project (a static site with a hand-written service worker and a Vite shop with vite-plugin-pwa), and the real report the scanner produces on the risky one

Limits

It reads file text and follows only a few facts across files (manifests linked from pages, a Service-Worker-Allowed header in server configs, vite-plugin-pwa autoUpdate). Matchers defined in another file, minified or generated service workers, icon files, HTTPS and the HTTP headers your server sends are not checked, and caching of private URLs in hand-written fetch handlers is reported only as cache-first or cache-everything findings. vite-plugin-pwa's autoUpdate mode and Serwist's template, which choose immediate updates on purpose, are not reported by W16. NOT FLAGGED is not a guarantee.

Contents

One ZIP file with 20 files: SKILL.md, the scanner in scripts/ (7 Python files), references/rules.md (every rule with its reason and safer approach), and examples/ (10 example files plus report.md, the real scanner output on the risky example).

How to use: This is an agent skill: a folder with a SKILL.md file and Python scripts that an AI coding agent such as Claude Code, Cursor, or Codex CLI can run. Unzip it into your agent's skills folder (for Claude Code: ~/.claude/skills/), then ask your agent to check your project. The scripts also run on their own with Python 3.9 or newer, with nothing to install. They read your files only: no network access, and nothing is sent anywhere.