novahiz 0.1.0

package/bundled-skills/expo-web-to-native/references/false-friends.md

@@ -0,0 +1,119 @@
+# False Friends: web idioms → native
+
+Disclosed reference for [`expo-web-to-native`](../SKILL.md). A *false friend* is a web idiom that looks portable but isn't - it compiles in your head, then breaks (or silently no-ops) on native. Each row is `web idiom → native equivalent → the gotcha`. Reach for this in steps 3–5 of a migration, and whenever you're learning native after the web.
+
+This is the single source of truth for the mapping; the SKILL.md steps name a few high-traffic swaps but defer the full list here.
+
+## Elements & text
+
+| Web | Native | Gotcha |
+|---|---|---|
+| `<div>`, `<section>`, `<span>` | `<View>` | `View` is the only generic container; no semantic element variants. |
+| `<p>`, `<h1>`, raw text in JSX | `<Text>` | **All** text must sit inside `<Text>`. Bare strings in a `View` throw. |
+| `<img src>` | `<Image>` / `expo-image` | `expo-image` adds caching, blurhash, transitions. Remote images need an explicit `width`/`height` or a flex parent. |
+| `<button>`, `<a>` | `<Pressable>` | No default styling, no hover. Wrap label text in `<Text>`. |
+| `<input>` | `<TextInput>` | Controlled via `value` + `onChangeText` (not `onChange`/`e.target.value`). |
+| `<ul>/<li>` rendered with `.map()` | `<FlatList>` / `<FlashList>` | `.map()` over a long list mounts every row at once → jank. Use a virtualized list with `data` + `renderItem`. |
+
+## Events & interaction
+
+| Web | Native | Gotcha |
+|---|---|---|
+| `onClick` | `onPress` | Also `onLongPress`, `onPressIn/Out`. There is no click. |
+| `onChange={e => e.target.value}` | `onChangeText={text => ...}` | The handler receives the string directly, not an event. |
+| `onSubmit` (form) | `onPress` / `onSubmitEditing` | No `<form>` element and no submit event; wire the button/keyboard return key. |
+| `:hover`, `:focus` | press/focus state | No hover on touch. Track state and style from it, or use `Pressable`'s state callback. |
+| `e.preventDefault()` | — | No default actions to prevent; remove it. |
+
+## Styling & layout
+
+| Web | Native | Gotcha |
+|---|---|---|
+| `className` / CSS files | `StyleSheet.create` or NativeWind | Plain RN has no className. For Tailwind muscle memory use NativeWind. |
+| CSS cascade & inheritance | none | Styles don't inherit (except a few `Text` props like `color`/`fontSize` to nested `Text`). Style each node. |
+| `display: flex` opt-in, default `row` | flex always on, default **`column`** | Biggest layout surprise: flex is the only layout model and the main axis is vertical by default. |
+| `px`, `rem`, `%` | unitless numbers (dp) | `padding: 16` = density-independent pixels. `%` works in some props; no `rem`/`em`/`vh`. |
+| `@media` queries | `useWindowDimensions()` / `Platform` | No media queries. Branch on dimensions or platform at runtime. |
+| `position: fixed` | `position: absolute` + safe area | No `fixed`. Pin with `absolute` and respect insets (`react-native-safe-area-context`). |
+| `z-index` | `zIndex` (+ `elevation` on Android) | Works mostly, but Android shadow/stacking also needs `elevation`. |
+| CSS transitions / `@keyframes` | `Animated` / Reanimated | No CSS animation. Reanimated is the standard; gestures via `react-native-gesture-handler`. |
+| `gap`, flexbox | `gap`, flexbox | These largely transfer — flexbox is the one big win for web devs. |
+
+## Navigation & URLs
+
+| Web | Native | Gotcha |
+|---|---|---|
+| React Router / Next.js routes | Expo Router (file-based) | File-based like Next App Router; `react-router` concepts map but the API differs. |
+| `<a href>` / `<Link>` | `expo-router` `<Link href>` | Works in DOM components too. |
+| `useNavigate()` / `router.push` | `useRouter()` from `expo-router` | `router.push/replace/back`. |
+| `useParams` / `useSearchParams` | `useLocalSearchParams()` | Note: doesn't work *inside* a DOM component - read in the native parent, pass as props (see `expo-dom`). |
+| `window.location` | `usePathname()` / router | No `location` object. |
+| Deep links / `myapp://` | URL scheme + universal links | Configure `scheme` in app config; native gives you real deep linking and (with AASA) app links - see `expo-app-clip` for the AASA file. |
+
+## React architecture & data (Next.js / SSR apps)
+
+| Web | Native | Gotcha |
+|---|---|---|
+| Async Server Component (`async function Page()`) | client component + data fetch | No RSC on native (Expo's is experimental and different). Split into a client component that fetches via the API + a presentational child *before* porting. |
+| Server actions (`'use server'`) | API route + `fetch` | No server actions. Expose an endpoint and call it. |
+| `cookies()` / `headers()` (server) | token in `expo-secure-store` | Server-only. Auth moves to a bearer token sent as a header. |
+| ORM / DB client in a page (Drizzle, Prisma) | server only - call over HTTP | The device never talks to the DB. Keep the backend deployed, or move routes to EAS Hosting (`eas-hosting`); the app fetches. |
+| `next/navigation` (`notFound`, `redirect`) | `expo-router` | `redirect()` → `router.replace`; `notFound()` → a native `+not-found` route. |
+| `_layout` as a DOM component | always native | Layout routes can't be DOM components — they *are* the native shell. Rewrite web-only layout logic (theme scripts, providers) with native APIs. |
+
+## Storage, state & sessions
+
+| Web | Native | Gotcha |
+|---|---|---|
+| `localStorage` / `sessionStorage` | `expo-sqlite` (`globalThis.localStorage`) | `import 'expo-sqlite/localStorage/install';` polyfills the global `localStorage`, so existing code works as-is (or `expo-sqlite/kv-store`). **No `sessionStorage` equivalent** — native has no session concept. |
+| Cookies / `document.cookie` | `expo-secure-store` + headers | No cookie jar by default. Store tokens in SecureStore; send as auth headers. |
+| Auth via session cookie | token in SecureStore | Redesign auth around bearer tokens, not browser sessions. |
+| In-memory React state | same | `useState`/`useReducer`/`useContext` transfer unchanged. |
+
+## Browser & platform APIs
+
+| Web | Native | Gotcha |
+|---|---|---|
+| `window`, `document` | none | Don't exist. Guard web-only libs, or keep them in a DOM component (`expo-dom`). |
+| `window.matchMedia('(prefers-color-scheme: dark)')` | `useColorScheme()` | Hook from `react-native`, reactive to the system theme. Web theme bootstrap scripts in the layout don't run. |
+| `window.innerWidth/Height` | `useWindowDimensions()` | Reactive hook; updates on rotation. |
+| `navigator.*`, Web APIs | Expo SDK modules | e.g. camera → `expo-camera`, geolocation → `expo-location`, clipboard → `expo-clipboard`. |
+| `alert()` / `confirm()` / `prompt()` | `alert()` works; `Alert.alert(...)` for the rest | RN provides a global `alert()`; `confirm()` / `prompt()` don't exist — use `Alert.alert` with a button array. |
+| `process.env.X` | `process.env.EXPO_PUBLIC_X` | Only `EXPO_PUBLIC_`-prefixed vars are inlined into the client bundle. |
+| `console.log` | `console.log` | Works — shows in the dev tools/terminal. |
+| `dangerouslySetInnerHTML` | — | No DOM to inject into. Render data, or use a DOM component / WebView. |
+| inline SVG | `react-native-svg` | No native `<svg>`; the library mirrors the element API. |
+
+## Networking
+
+| Web | Native | Gotcha |
+|---|---|---|
+| `fetch('/api/x')` (relative) | absolute URL | Native has no origin — relative paths fail. Use a configured base URL (`EXPO_PUBLIC_API_URL`). |
+| CORS | n/a | No browser CORS, but you still need a reachable absolute host. |
+| `fetch`, React Query, SWR | same | The libraries themselves work on native - see `expo-data-fetching`. |
+| Next.js API routes | Expo Router API routes | Move server endpoints to Expo API routes on EAS Hosting - see `eas-hosting`. |
+| Streaming responses (SSE, AI SDK `useChat`) | `expo/fetch` with `textStreaming` | RN's built-in `fetch` can't read a streaming response body. Use `expo/fetch` (streams, and works with the Vercel AI SDK) or an XHR-based polyfill. |
+
+## Third-party services & SDKs
+
+Browser SDKs don't run on native — each needs a native equivalent. The canonical, version-matched integrations live in the `expo-examples` skill (the `expo/examples` repo); reach for those instead of wiring from scratch.
+
+| Web service | Native | Gotcha |
+|---|---|---|
+| **Stripe.js — digital goods / subscriptions** | store **In-App Purchase** via **RevenueCat** (`react-native-purchases`) | **Policy, not just an SDK swap.** Apple & Google *require* IAP for in-app digital goods and take ~15–30%; shipping Stripe for them gets the app rejected. Decide at assess time — it can change the business model. |
+| **Stripe.js — physical goods / services** | `@stripe/stripe-react-native` (PaymentSheet, Apple/Google Pay) | Stripe's RN SDK is allowed for physical goods; see `expo-examples` `with-stripe`. |
+| Google Maps JS | `react-native-maps` | A native map view, not an embedded iframe. |
+| Web Push | `expo-notifications` (APNs / FCM) | Different delivery + permission model. |
+| OAuth redirect flow | `expo-auth-session` (deep-link OAuth), or a native auth SDK (Clerk, Supabase…) | No browser redirect — an app deep link completes the flow. |
+| GA / Segment.js analytics | native SDK (`posthog-react-native`, Segment RN) | The web JS snippet won't load; swap for the native SDK. |
+| `<input type=file>` / `getUserMedia` | `expo-image-picker` / `expo-camera` / `expo-document-picker` | Native pickers + runtime permissions. |
+
+## Scrolling, keyboard & safe area
+
+| Web | Native | Gotcha |
+|---|---|---|
+| Body scrolls by default | `<ScrollView>` / `<FlatList>` | Nothing scrolls unless you make it. Wrap overflowing content explicitly. |
+| `overflow: scroll` | `<ScrollView>` | Don't nest a `ScrollView` inside a `FlatList` of the same axis. |
+| Keyboard overlaps inputs | `KeyboardAvoidingView` | The keyboard covers inputs by default; wrap forms to push content up. |
+| Notch / status bar | `react-native-safe-area-context` | Content flows under the notch/home indicator unless you apply safe-area insets. |
+| `:focus` ring, tab order | manual | No automatic focus management; wire `ref`/`focus()` and `returnKeyType`. |

package/bundled-skills/expo-web-to-native/references/native-patterns.md

@@ -0,0 +1,39 @@
+# Native patterns: redesigning web UX for native
+
+Disclosed reference for [`expo-web-to-native`](../SKILL.md), step 4. `false-friends.md` translates *idioms* (`div` → `View`); this translates *UX patterns* - a web interaction into its native equivalent. Step 4 isn't a port, it's this redesign.
+
+**Reach for `@expo/ui` first.** It renders real SwiftUI (iOS) and Jetpack Compose (Android), so its components look and feel *exactly* like the OS — the difference between "native-ish RN" and "indistinguishable from an app Apple/Google shipped." See the `expo-ui` skill. Drop to styled RN primitives only for what `@expo/ui` doesn't cover: custom layouts (chat bubbles, bespoke cards) and **large data lists** (`@expo/ui` `List` is a JS-thread node per item — use `FlashList`/`FlatList` for feeds). `@expo/ui` runs in **Expo Go** (SDK 56+) — no dev build needed; reach for a dev build (the `expo-dev-client` skill) only for *custom* native modules.
+
+| Web pattern | Native redesign — reach for first | Why |
+|---|---|---|
+| Top tab bar / nav links | **NativeTabs** - bottom, liquid glass on iOS 26 (`expo-router`) | Thumb-reachable, OS-native bar |
+| Page header / breadcrumb | **large-title** Stack header + header **search field** (`expo-router`) | The native screen frame |
+| In-page tabs / toggle group | **SegmentedControl** — `@expo/ui` (`community/segmented-control`) | Native segmented switch |
+| Modal / dialog | **BottomSheet** — `@expo/ui` | Sheets *are* the native modal |
+| `<select>` / dropdown | **Picker**, or long-press **MenuView** — `@expo/ui` (`community/menu`) | Native wheel / menu, no popover |
+| Accordion / "show more" | **Collapsible** — `@expo/ui` | Native disclosure |
+| Settings / short list | **List** + **FieldGroup** rows (Switch / Picker / TextInput) — `@expo/ui` | The Settings-app look |
+| Data feed / table / long list | **FlashList** / `FlatList`, virtualized + momentum | Tables don't exist on mobile; `@expo/ui` `List` isn't for big data |
+| Checkbox / toggle | **Switch** (on/off) or **Checkbox** (multi-select) — `@expo/ui` | Native control, not a styled box |
+| Date / time input | **DateTimePicker** — `@expo/ui` (`community/datetime-picker`) | Native wheel / calendar |
+| Range slider | **Slider** — `@expo/ui` | |
+| Onboarding / carousel / swipe pages | **PagerView** — `@expo/ui` (`community/pager-view`) | Native paging, not a scroll strip |
+| Refresh button / auto-poll | pull-to-refresh (`RefreshControl`) | The native refresh gesture |
+| Hover menu / tooltip | long-press **MenuView** context menu — `@expo/ui` (`community/menu`) | No hover on touch |
+| Toast / snackbar | native banner + **haptic** (`expo-haptics`) | |
+| Buttons | `@expo/ui` **Button**; `Pressable` for custom | Native press + haptics |
+| Multi-column layout | single column + tabs / stack | One thing at a time on a phone |
+
+**The test:** if a screenshot of the native screen could pass for the web version, you reskinned it. Redesign until it could pass for a screen the OS shipped.
+
+## Feel — beyond the components
+
+The table gets the right *components*; "native" also lives in *motion and touch* - and a web port arrives with almost none, so you must add it. The tooling is in `expo-router` (navigation/transitions) and `expo-native-ui` (motion/effects); reach for it, don't hand-roll:
+
+- **Transitions for free** - use Expo Router's native-stack so push/pop, modals, and sheets animate with real platform physics; shared-element zoom via `expo-router` `zoom-transitions.md`.
+- **Motion** - Reanimated (`withSpring`/`withTiming`) + `react-native-gesture-handler` for swipes/drags → load the `expo-animation` skill (purpose gate, timing values, interruption).
+- **Touch** — `expo-haptics` on commits, selection changes, and pull-to-refresh — choreography, not just a toast buzz.
+- **Native rhythm** — large-title collapse on scroll, momentum / inverted scroll, a keyboard that pushes content (`KeyboardAvoidingView`).
+- **Respect reduced motion** — gate non-essential animation on Reanimated's `useReducedMotion()`.
+
+**Feel can't be screenshotted.** A janky transition or wrong easing passes a still-image parity check and still betrays the app — for screens with motion, verify with a short recording (iOS `xcrun simctl io booted recordVideo feel.mov`; Android `adb shell screenrecord`; or a device-agent flow), not just a screenshot.

package/bundled-skills/expo-web-to-native/references/run-as-goal.md

@@ -0,0 +1,48 @@
+# Run the migration as a goal loop
+
+Disclosed reference for [`expo-web-to-native`](../SKILL.md) - the recommended way to drive the whole migration. The migration is a repeat-until-done loop (assess → nativize each screen → verify → check off), which is exactly the shape of a **goal loop**: a single objective re-injected every turn until the worklist is empty. This file carries a ready-shaped, migration-specific objective - and, crucially, the objective **re-reads this skill every iteration**, so the loop keeps following the playbook (and self-bootstraps the assess step if no worklist exists yet).
+
+Use it in one of two modes depending on the agent you're running.
+
+## Mode A — the agent can run a goal loop
+
+Harnesses with a goal/loop command (Claude Code `/goal`, Codex CLI, or any harness of the same shape) can drive this themselves. Fill the template below and hand it to that command — the loop re-runs it until `migration-progress.md` has no unchecked nativize-now items.
+
+## Mode B — the agent can't loop itself
+
+Write the filled-in objective to `migration-goal.md` in the project, then give the user the one-line instruction to launch it (e.g. *"run your agent's goal loop with the objective in `migration-goal.md`"*). The objective is plain text and portable, so the user runs it in whatever harness they have.
+
+## The objective (template)
+
+Fill the two `<…>` slots, then run or hand off verbatim. It is written to survive re-injection — it restates its own worklist, direction, and stop condition every turn.
+
+```
+Goal: migrate <APP NAME> from web to a native Expo app by following the expo-web-to-native skill, one screen per iteration, until done.
+
+Each iteration, FIRST re-read the playbook - plugins/expo/skills/expo-web-to-native/SKILL.md (and its references) - then:
+1. If migration-progress.md doesn't exist yet, do the skill's step 1 (Assess) to
+   create the worklist, then stop. Otherwise open it and take the top unchecked
+   item under "nativize-now"; if none are left unresolved (every nativize-now is
+   done or blocked), STOP and summarize what shipped + what's blocked and why.
+2. Redesign that screen native per the skill's step 4 — reach for @expo/ui FIRST
+   (real SwiftUI/Compose), then expo-router (NativeTabs, large titles);
+   RN primitives only for custom layouts. NEVER a webview port.
+   Use references/native-patterns.md (UX patterns) and references/false-friends.md
+   (idioms). Match the web screen's content and behavior.
+3. Verify per references/verify-on-device.md: compare the running web original
+   (browser agent) against the native screen (simulator / argent) — content and
+   behavior parity, NOT pixels (it should look more native). If it's off for reasons
+   IN the code, fix it this iteration. If it's blocked by something OUTSIDE the code
+   (missing backend/auth/data, or a secret you can't supply), don't loop — mark it
+   blocked in step 4 and move on.
+4. Check the item off in migration-progress.md, appending one line:
+   "<screen> — done", or "<screen> — blocked: <reason> — needs <what would unlock>".
+   Either way the item is resolved; never revisit a blocked one.
+
+Rules: one screen per pass; the app builds green each iteration; @expo/ui before RN primitives; never touch "nativize-later" items.
+Base API URL for native (no relative paths): <EXPO_PUBLIC_API_URL>
+```
+
+## Why a pre-shaped objective
+
+The objective is filled in for this migration — worklist, redesign rules, and self-verification path already wired to the skill's references — so you can launch the loop without authoring one from scratch. Tailor the `<…>` slots and direction when a specific migration needs more than the template covers.

package/bundled-skills/expo-web-to-native/references/verify-on-device.md

@@ -0,0 +1,45 @@
+# Verify a migrated screen against the running web app
+
+Disclosed reference for [`expo-web-to-native`](../SKILL.md), steps 3–4. Verification means **running both apps and comparing the same screen** - the native port beside the web original. A clean compile or a green `expo export` proves nothing - a screen can build and still render blank or mis-render. This parity check is the gate the strangle loop runs each iteration.
+
+Two agents drive it, and this skill is **opinionated**: it requires both and installs them rather than falling back to manual screenshots.
+
+- **Web side — `agent-browser`** (vercel-labs, a Rust browser CLI): `open <url>`, `snapshot --json` (accessibility tree with refs), `screenshot <path>`, `read` (rendered DOM/text).
+- **Native side — `argent`** (`@swmansion/argent`): drives the simulator — `describe` (a11y tree), `debugger-component-tree` (RN tree), `gesture-tap`/`keyboard`, `flow` to record a check and replay it each pass. Invoke as `argent run <tool> --udid <udid>` (get the udid from `argent run list-devices`).
+
+## Setup — install if missing (don't skip, don't fall back to manual)
+
+Check both are on PATH; if either is absent, ask the user, then install before proceeding:
+
+```bash
+which agent-browser || (npm i -g agent-browser && agent-browser install)   # web agent (+ its Chrome)
+which argent        || npm i -g @swmansion/argent                          # device agent
+```
+
+## The workflow
+
+**A. Capture the web original** with agent-browser — the source of truth for parity. Run the web app (its `pnpm dev` server, or the **deployed URL** if local setup needs DB/auth env), then:
+
+```bash
+agent-browser open "<web-url>/<route>?<params>"
+agent-browser snapshot --json      # structure to diff
+agent-browser screenshot web.png   # visual reference
+```
+
+**Tip:** capture web baselines for every screen once, up front, then diff against them instead of re-opening the web app each iteration.
+
+**B. Capture the native screen** (iOS shown via `simctl`; Android note below):
+1. Run the app: `npx expo start --ios` (Expo Go). On **SDK 56+ both `@expo/ui` and DOM components run in Expo Go** — no dev build, no `react-native-webview` to install; reach for a dev build (the `expo-dev-client` skill) only for *custom* native modules. Stale-bundle trap: a CI-mode Metro + cached Expo Go can show an old build — terminate Expo Go and add `--clear` if a change doesn't appear.
+2. Boot a sim: `xcrun simctl boot <udid>` (`xcrun simctl list devices available`); `open -a Simulator`.
+3. Open the route: deep-link `xcrun simctl openurl booted "exp://<lan-ip>:8081/--/<route>?<params>"`, or argent `launch-app` + `gesture-tap`.
+4. Capture: `xcrun simctl io booted screenshot native.png`, or `argent run describe --udid <udid>` for structure.
+
+> **Android:** `simctl` / `expo run:ios` are iOS-only. Use an Android emulator + `adb` — `adb exec-out screencap -p > native.png`, `adb shell am start -a android.intent.action.VIEW -d "<deep-link>"`, `adb shell screenrecord` for motion — or `npx expo run:android` for a dev build.
+
+**C. Compare** the two for the same route — layout, content, behavior. Diff the structures (agent-browser `snapshot` against argent `describe` / `debugger-component-tree`), not just pixels. Pass only on parity: same data, and params passed into a DOM webview must produce the same result.
+
+**Feel needs motion, not a still.** For a nativized screen with transitions, gestures, or haptics, a screenshot can't catch a janky push or wrong easing — capture a short recording (iOS `xcrun simctl io booted recordVideo feel.mov`; Android `adb shell screenrecord`; or an argent flow) and confirm it moves like a native app (see `native-patterns.md` → Feel).
+
+## What "pass" looks like
+- **DOM-shelled screen (step 3):** the web UI renders inside the native header/shell; params from the native route drive it the same as on web.
+- **Nativized screen (step 4):** native primitives only, no webview; matches the web original screen.

package/bundled-skills/find-skills/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query] [--owner <owner>]` - Search for skills interactively or by keyword, optionally scoped to a GitHub owner
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Check the Leaderboard First
+
+Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options.
+
+For example, top skills for web development include:
+- `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each)
+- `anthropics/skills` — Frontend design, document processing (100K+ installs)
+
+### Step 3: Search for Skills
+
+If the leaderboard doesn't cover the user's need, run the find command:
+
+```bash
+npx skills find [query] [--owner <owner>]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+### Step 4: Verify Quality Before Recommending
+
+**Do not recommend a skill based solely on search results.** Always verify:
+
+1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100.
+2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors.
+3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism.
+
+### Step 5: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install count and source
+3. The install command they can run
+4. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+(185K installs)
+
+To install it:
+npx skills add vercel-labs/agent-skills@react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
+```
+
+### Step 6: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```

package/bundled-skills/fix/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: "fix"
+description: >-
+  Fix failing or flaky Playwright tests. Use when user says "fix test",
+  "flaky test", "test failing", "debug test", "test broken", "test passes
+  sometimes", or "intermittent failure".
+---
+
+# Fix Failing or Flaky Tests
+
+Diagnose and fix a Playwright test that fails or passes intermittently using a systematic taxonomy.
+
+## Input
+
+`$ARGUMENTS` contains:
+- A test file path: `e2e/login.spec.ts`
+- A test name: ""should redirect after login"`
+- A description: `"the checkout test fails in CI but passes locally"`
+
+## Steps
+
+### 1. Reproduce the Failure
+
+Run the test to capture the error:
+
+```bash
+npx playwright test <file> --reporter=list
+```
+
+If the test passes, it's likely flaky. Run burn-in:
+
+```bash
+npx playwright test <file> --repeat-each=10 --reporter=list
+```
+
+If it still passes, try with parallel workers:
+
+```bash
+npx playwright test --fully-parallel --workers=4 --repeat-each=5
+```
+
+### 2. Capture Trace
+
+Run with full tracing:
+
+```bash
+npx playwright test <file> --trace=on --retries=0
+```
+
+Read the trace output. Use `/debug` to analyze trace files if available.
+
+### 3. Categorize the Failure
+
+Load `flaky-taxonomy.md` from this skill directory.
+
+Every failing test falls into one of four categories:
+
+| Category | Symptom | Diagnosis |
+|---|---|---|
+| **Timing/Async** | Fails intermittently everywhere | `--repeat-each=20` reproduces locally |
+| **Test Isolation** | Fails in suite, passes alone | `--workers=1 --grep "test name"` passes |
+| **Environment** | Fails in CI, passes locally | Compare CI vs local screenshots/traces |
+| **Infrastructure** | Random, no pattern | Error references browser internals |
+
+### 4. Apply Targeted Fix
+
+**Timing/Async:**
+- Replace `waitForTimeout()` with web-first assertions
+- Add `await` to missing Playwright calls
+- Wait for specific network responses before asserting
+- Use `toBeVisible()` before interacting with elements
+
+**Test Isolation:**
+- Remove shared mutable state between tests
+- Create test data per-test via API or fixtures
+- Use unique identifiers (timestamps, random strings) for test data
+- Check for database state leaks
+
+**Environment:**
+- Match viewport sizes between local and CI
+- Account for font rendering differences in screenshots
+- Use `docker` locally to match CI environment
+- Check for timezone-dependent assertions
+
+**Infrastructure:**
+- Increase timeout for slow CI runners
+- Add retries in CI config (`retries: 2`)
+- Check for browser OOM (reduce parallel workers)
+- Ensure browser dependencies are installed
+
+### 5. Verify the Fix
+
+Run the test 10 times to confirm stability:
+
+```bash
+npx playwright test <file> --repeat-each=10 --reporter=list
+```
+
+All 10 must pass. If any fail, go back to step 3.
+
+### 6. Prevent Recurrence
+
+Suggest:
+- Add to CI with `retries: 2` if not already
+- Enable `trace: 'on-first-retry'` in config
+- Add the fix pattern to project's test conventions doc
+
+## Output
+
+- Root cause category and specific issue
+- The fix applied (with diff)
+- Verification result (10/10 passes)
+- Prevention recommendation

package/bundled-skills/fix/flaky-taxonomy.md

@@ -0,0 +1,134 @@
+# Flaky Test Taxonomy
+
+## Decision Tree
+
+```
+Test is flaky
+│
+├── Fails locally with --repeat-each=20?
+│   ├── YES → TIMING / ASYNC
+│   │   ├── Missing await? → Add await
+│   │   ├── waitForTimeout? → Replace with assertion
+│   │   ├── Race condition? → Wait for specific event
+│   │   └── Animation? → Wait for animation end or disable
+│   │
+│   └── NO → Continue...
+│
+├── Passes alone, fails in suite?
+│   ├── YES → TEST ISOLATION
+│   │   ├── Shared variable? → Make per-test
+│   │   ├── Database state? → Reset per-test
+│   │   ├── localStorage? → Clear in beforeEach
+│   │   └── Cookie leak? → Use isolated contexts
+│   │
+│   └── NO → Continue...
+│
+├── Fails in CI, passes locally?
+│   ├── YES → ENVIRONMENT
+│   │   ├── Viewport? → Set explicit size
+│   │   ├── Fonts? → Use Docker locally
+│   │   ├── Timezone? → Use UTC everywhere
+│   │   └── Network? → Mock external services
+│   │
+│   └── NO → INFRASTRUCTURE
+│       ├── Browser crash? → Reduce workers
+│       ├── OOM? → Limit parallel tests
+│       ├── DNS? → Add retry config
+│       └── File system? → Use unique temp dirs
+```
+
+## Common Fixes by Category
+
+### Timing / Async
+
+**Missing await:**
+```typescript
+// BAD — race condition
+page.goto('/dashboard');
+expect(page.getByText('Welcome')).toBeVisible();
+
+// GOOD
+await page.goto('/dashboard');
+await expect(page.getByText('Welcome')).toBeVisible();
+```
+
+**Clicking before visible:**
+```typescript
+// BAD — element may not be ready
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// GOOD — ensure visible first
+const submitBtn = page.getByRole('button', { name: 'Submit' });
+await expect(submitBtn).toBeVisible();
+await submitBtn.click();
+```
+
+**Race with network:**
+```typescript
+// BAD — data might not be loaded
+await page.goto('/users');
+await expect(page.getByRole('table')).toBeVisible();
+
+// GOOD — wait for API response
+const responsePromise = page.waitForResponse('**/api/users');
+await page.goto('/users');
+await responsePromise;
+await expect(page.getByRole('table')).toBeVisible();
+```
+
+### Test Isolation
+
+**Shared state fix:**
+```typescript
+// BAD — tests share userId
+let userId: string;
+test('create', async () => { userId = '123'; });
+test('read', async () => { /* uses userId */ });
+
+// GOOD — each test is independent
+test('read user', async ({ request }) => {
+  const response = await request.post('/api/users', { data: { name: 'Test' } });
+  const { id } = await response.json();
+  // Use id within this test
+});
+```
+
+**localStorage cleanup:**
+```typescript
+test.beforeEach(async ({ page }) => {
+  await page.goto('/');
+  await page.evaluate(() => localStorage.clear());
+});
+```
+
+### Environment
+
+**Explicit viewport:**
+```typescript
+test.use({ viewport: { width: 1280, height: 720 } });
+```
+
+**Timezone-safe dates:**
+```typescript
+// BAD
+expect(dateText).toBe('March 5, 2026');
+
+// GOOD — timezone independent
+expect(dateText).toMatch(/\d{1,2}\/\d{1,2}\/\d{4}/);
+```
+
+### Infrastructure
+
+**Retry config:**
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 2 : undefined,
+});
+```
+
+**Increase timeout for CI:**
+```typescript
+test.setTimeout(60_000); // 60s for slow CI
+```