AGENT SKILL

ams-pwa-craftsman

暂无简介

License 许可
MIT
所属仓库
TanNhatCMS/jarvis
最近更新
2026-11-07
Stars
★ 0
Forks
1

03 SKILL.md 正文

PWA Craftsman

Overview

A great PWA — installable, offline-capable, and app-like — is a craft of details: the manifest that makes it installable, the service worker that makes it reliable, caching strategies matched to content types, and UX that respects connectivity. This skill covers building PWAs that feel native rather than "a website with a manifest."

The through-line: reliable (works offline), fast (instant loads), engaging (installable, push-capable) — in that order.

When to use

  • Building a new PWA or converting a web app.
  • Designing offline support and caching strategies.
  • Debugging service worker issues (stale content, update flows).
  • Improving installability, push notifications, or app-like UX.
  • Auditing an existing PWA against quality criteria.

Core concepts

  • The manifest. manifest.json: name, icons (maskable + any, multiple sizes), theme/background colors, display mode (standalone), start URL, shortcuts, share target. This is the install contract — get icons and colors right, because they're the app's face on the home screen.
  • Service worker lifecycle. Install → activate → fetch interception; versioned caches; skipWaiting + clients.claim for prompt updates (or deliberate delayed updates). The #1 PWA bug class is lifecycle confusion — learn it cold before writing strategies.
  • Caching strategies per content type. This is the core design work:
    • App shell (HTML/CSS/JS): precache, cache-first with versioned updates.
    • API data: stale-while-revalidate (fresh UI, background refresh) or network-first with cache fallback for must-be-fresh data.
    • Images/media: cache-first with quota management.
    • Truly dynamic: network-only. One strategy for everything is always wrong.
  • Offline as a designed state. Not just "cached shell + spinner" — queued mutations (background sync), clear offline UI, conflict resolution policy for synced data. Offline support is a product decision with UX design, not a service worker flag.
  • Installability criteria. HTTPS, manifest with icons, service worker with fetch handler, and meeting the browser's engagement heuristics. Plus the UX: when to prompt (after value demonstrated, not on first visit) and a graceful custom install button.
  • Push notifications (with restraint). Push API + Notifications API via the service worker; VAPID keys; user permission requested in context with clear value. Notifications are a retention tool that becomes an uninstall tool when abused — every push must earn the next one.

Practical workflow

  1. Start with the baseline. HTTPS, responsive design, and a fast site — a slow broken site with a manifest is still a slow broken site. Lighthouse PWA audit as the starting scorecard.
  2. Write the manifest. Complete icons (192/512 + maskable), theme colors matching the UI, display: standalone, shortcuts to key actions. Validate with DevTools → Application.
  3. Build the service worker with Workbox (or hand-rolled if small). Precache the app shell (build-integrated revisioning); runtime caching routes per content type with the right strategy; quota/expiration policies so caches don't grow unboundedly.
  4. Design offline UX. Offline page/fallbacks, queued actions with background sync, "you're offline" states that explain what's available. Test with DevTools offline + real airplane mode.
  5. Handle updates gracefully. New service worker → notify user ("Update available") rather than force-reloading mid-task; or auto-update for non-critical apps. Never strand users on stale versions silently, never yank the rug mid-flow.
  6. Add engagement carefully. Custom install prompt at the right moment; push only for genuinely time-sensitive, user-valued events; notification settings in-app. Measure opt-in and disable rates — they're the truth about your push strategy.

Caching strategy map:

/app-shell (/, /styles/*, /app.js)   → precache, cache-first (versioned at build)
GET /api/feed                        → stale-while-revalidate (5 min max age)
/api/user/* (must be fresh)          → network-first, cache fallback on failure
/images/*                            → cache-first, max 200 entries, 30-day expiry
POST /api/* (mutations)              → network-only + background-sync queue when offline

Common pitfalls

  • Cache-everything service worker. One cache-first strategy for all routes = stale API data and confused users. Strategies per content type, always.
  • Update purgatory. Users stuck on old versions because the new SW never activates (or activates mid-session breaking state). Deliberate update UX: notify + user-triggered reload.
  • Unbounded caches. Caching every image forever until storage pressure evicts everything unpredictably. Expiration + max entries on every runtime cache.
  • Offline as an accident. "It kind of works offline" — untested, with spinners and broken mutations. Offline is a feature: design, implement, and test it like one.
  • Install prompt on first paint. Begging for installation before demonstrating value — dismissed forever. Prompt after the aha moment; provide a persistent manual install entry point.
  • Notification spam. Every marketing whim as a push. Permission revoked, app uninstalled. High-value, user-controlled, infrequent — or don't do push at all.
  • iOS assumptions. Safari's PWA support has real gaps/limits (push arrived late, storage limits, no install prompt API — manual share-menu install). Design for the weakest platform you support; test on real iOS.

04 同仓库更多 Skills

TanNhatCMS
TanNhatCMS/jarvis

web-scrape

Turn web pages into LLM-ready markdown via the Firecrawl API (renders JS, anti-bot handling). Use when browser_open/fetch fails on JS-heavy pages, or when you need clean markdown/structured extraction from a site. Requires FIRECRAWL_API_KEY.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

design-taste-frontend

tasteskill v2, the anti-slop frontend skill. Art direction for websites, distilled from a study of 247 curated gallery sites (One Page Love, Awwwards Sites of the Day). Deals researched directions (idea, composition, type, palette, photographs, section blueprints) from a library, enforces a strict no-slop house style with a real-browser inspector, and runs a look-and-fix loop on screenshots. Use this whenever you build, design, redesign, restyle, polish or review a landing page, marketing site, portfolio, product page, one-pager, hero or any public-facing web page, in any stack (HTML/CSS, React, Next.js, Vue, Svelte, Astro, Tailwind) — also when the user says a page looks generic, templated, "AI-made", sloppy, or asks to make it look designed, premium, award-level or less like every other site. Not for dashboards or app screens.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

test-driven-development

Use when implementing any feature or bugfix, before writing implementation code

★ 0
TanNhatCMS
TanNhatCMS/jarvis

systematic-debugging

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

★ 0
TanNhatCMS
TanNhatCMS/jarvis

requesting-code-review

Use when completing tasks, implementing major features, or before merging to verify work meets requirements

★ 0
TanNhatCMS
TanNhatCMS/jarvis

brainstorming

You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).

★ 0