opencode-skills-collection 4.0.72 → 4.0.74

package/bundled-skills/film-crew/references/roles/editor.md

@@ -0,0 +1,34 @@
+# Editor
+
+**Job:** make the shots add up to a video: durations, order, cuts, pacing. You think about
+the timeline, not the frame.
+
+## Output
+
+```
+TOTAL: 15.0 s  (sum of shots, trimmed)
+S1 2.5 s  → hard cut
+S2 4.0 s  → match cut on motion
+S3 3.0 s  → smash cut
+…
+GENERATE: each shot +1 s handles (so S2 is generated at 5 s, used at 4 s)
+HOOK CHECK: frame 1 is S1 ECU, motion starts at 0.2 s ✅
+LOOP: last frame of S5 matches S1 composition ✅/❌
+```
+
+## Rules
+
+- **Fit the model.** Every shot must be ≤ the model's max clip length (see
+  `references/model-prompting.md`). If a beat needs longer, split it into two shots with a
+  change of angle.
+- **Generate long, use short.** Plan 0.5–1 s of handles at each end. The first and last
+  frames of AI clips are often the weakest.
+- **Fixed-length models** (only preset lengths such as 5 s / 10 s): generate at the
+  shortest preset and pick the strongest section. A 2.5 s shot uses the best 2.5 s of a
+  5 s clip; note which section in the timeline.
+- **Short-form pacing:** 1.5–3 s per shot is normal; a 6 s static shot kills retention
+  unless something is happening in it.
+- **Cut on action.** If S1 ends with a hand moving right, S2 should start with motion
+  continuing right.
+- **Text goes in the edit,** not the prompt. Note captions/supers here with timings.
+- Call out any shot that exists only for coverage. Coverage costs generations.

package/bundled-skills/film-crew/references/roles/gaffer.md

@@ -0,0 +1,30 @@
+# Gaffer
+
+**Job:** light the scene so it looks intentional and stays consistent between shots.
+
+## Output
+
+```
+TIME / SOURCE: late afternoon sun through west window (motivated)
+KEY: camera-left, 45°, soft
+FILL: low, bounce from white tabletop
+RIM / BACK: warm sun edge on hair
+COLOR TEMP: warm key ~3200K vs cool ambient ~5600K
+CONTRAST: medium-high, deep shadows
+PRACTICALS: pendant bulbs visible in background, slightly blown
+LOOK: 35mm film, fine grain, mild halation
+```
+
+## Rules
+
+- **Motivate the light.** Say where it comes from (window, neon sign, streetlight,
+  monitor glow). Unmotivated "dramatic lighting" gives you random results.
+- **Same key direction in every shot of a scene,** or the cut breaks continuity.
+- **Contrast beats brightness.** Flat, evenly lit prompts are what make AI video look
+  like AI video. Ask for shadows.
+- Color: pick one warm/cool contrast and hold it. Write it in plain words plus a
+  temperature if useful.
+- Night scenes: name the sources (sodium streetlight, phone screen, neon). "Dark" alone
+  gets you murk.
+- Products: soft key, clean rim to separate from background, a highlight that shows the
+  material (gloss, brushed metal, glass).

package/bundled-skills/film-crew/references/roles/production-designer.md

@@ -0,0 +1,43 @@
+# Production designer
+
+**Job:** make the world consistent. You write the **continuity bible**: the exact words
+every other role must paste, verbatim, whenever a character, prop or location appears.
+
+Video models have no memory between clips. The *only* continuity you get is identical
+wording. Paraphrasing a character ("a woman in a red coat" → "the lady in crimson")
+gives you a different person.
+
+## Output
+
+```
+CHARACTERS
+  C1  <age range> <build> <hair: length, color, style> <skin tone> <face detail>,
+      wearing <top, color, material> and <bottom>, <one distinctive accessory>
+LOCATIONS
+  L1  <place type>, <era/style>, <3 concrete set details>, <floor/wall materials>
+PROPS
+  P1  <object>, <material>, <color>, <size cue>, <state: new/used/half-full…>
+PALETTE
+  3–5 colors, named plainly ("mustard yellow, teal, off-white")
+```
+
+Every entry gets two versions:
+- **FULL** — the whole description, for shots where the whole subject is in frame.
+- **TIGHT** — only what a close-up can see (e.g. `C1-TIGHT: weathered hands, short
+  clean nails, a thin silver ring, sleeves of a faded olive sweatshirt pushed up`).
+
+Close-ups use TIGHT verbatim; wider shots use FULL verbatim. Pasting a whole-person
+description into an ECU of hands drags the rest of the person (and the set) into frame.
+
+## Rules
+
+- 20–35 words per character. Concrete nouns and colors, no adjectives like "beautiful".
+- One **distinctive anchor** per character (a yellow beanie, a scar, round glasses).
+  Anchors survive model drift better than faces do.
+- Avoid real people, brands and logos. Describe the *type* ("a white leather low-top
+  sneaker") not the brand.
+- Props that matter to the story get a state ("a paper cup, lid off, full to the brim
+  with black coffee"). State is what makes the action physically possible.
+- Keep locations simple enough to re-generate: 3 set details, not 12.
+- If the user supplies a reference image, write the bible *from the image* so the text
+  and the image agree.

package/bundled-skills/film-crew/references/roles/script-supervisor.md

@@ -0,0 +1,35 @@
+# Script supervisor
+
+**Job:** protect continuity and catch the shots that will fail *before* anyone spends a
+generation on them. You have veto power: any shot you flag gets rewritten.
+
+## Checklist (run on every shot)
+
+**Continuity**
+- [ ] Every recurring character/prop/location is pasted verbatim from the continuity bible.
+- [ ] Key light direction and color temperature match the rest of the scene.
+- [ ] Screen direction is consistent (subject moving left→right keeps moving left→right).
+- [ ] Props are in the right state (the cup that spilled in S2 isn't full in S3).
+
+**Feasibility**
+- [ ] One subject action, one camera move.
+- [ ] Duration ≤ model max, with handles.
+- [ ] No readable text, logos, UI or signage in frame (unless the model handles text).
+- [ ] Hard physics (liquids, cloth, hands with small objects, multiple people touching) is
+      framed tight, isolated, and given a simple background.
+- [ ] Nothing depends on a specific real person's likeness or a trademark.
+- [ ] Counts are small: "two dogs" works better than "five dogs".
+
+**Unslop** (see `references/unslop.md`)
+- [ ] No empty quality words ("stunning, 8k, masterpiece, hyper-realistic, cinematic").
+- [ ] No mood-only instructions; every feeling is translated into something visible.
+- [ ] Skin, materials and motion have texture and imperfection specified where it matters.
+
+## Output
+
+```
+S2 ⚠️  two actions (pours AND turns to customer) → split into S2a / S2b
+S4 ⚠️  sign text "OPEN" in frame → remove, add in edit
+S3 ✅
+HIGHEST RISK: S2a (liquid physics). Reroll plan: tighten to ECU, lock camera.
+```

package/bundled-skills/film-crew/references/roles/sound.md

@@ -0,0 +1,23 @@
+# Sound
+
+**Job:** plan what the audience hears. Run this role only if the target model generates
+audio, or the user will add music/SFX in the edit.
+
+## Output
+
+```
+MUSIC: <genre, tempo in BPM, energy curve> (added in edit)
+S1 SFX: ceramic clink, café murmur (low)
+S2 DIALOGUE: C1: "Not again." (quiet, deadpan)
+S3 SFX: liquid splash, sneaker squeak
+```
+
+## Rules
+
+- **Audio-capable models:** put spoken lines in double quotes with the speaker named, keep
+  lines under ~8 words per shot, and name 1–2 SFX plus ambience. Too many sound cues
+  produce mush.
+- **Silent models:** don't write sound into the prompt at all. It wastes tokens and can
+  drift the visuals. Put sound in the edit notes.
+- Cut points should land on beats of the music (tell the editor the BPM).
+- Short-form: design for sound-off first. If a line is essential, it also goes in a caption.

package/bundled-skills/film-crew/references/templates/shot-list.md

@@ -0,0 +1,38 @@
+# SHOT LIST — <title>
+
+**Format:** <aspect> · <total length> · target model: <model>
+**Mode:** text-to-video | image-to-video (reference: <file/description>)
+**Brand / product:** <name, or "none given — generic">
+**Logline:** <one sentence>
+
+## Crew notes
+**Director** — intent, hook, beats
+**Production designer** — continuity bible (C1…, L1…, P1…)
+**DP / Gaffer** — look summary in two lines
+**Editor** — timeline summary
+**Sound** — (if applicable)
+**Script supervisor** — flags resolved
+
+## Shots
+| # | Time | Size · Lens · Move | Action (one) | Gen length | Risk |
+|---|---|---|---|---|---|
+| S1 | 0.0–2.5 | ECU · 100mm · locked | … | 4 s | low |
+
+## Prompts
+
+### S1
+```
+<prompt>
+```
+Negative (if supported): `<negative prompt>`
+
+## Edit notes
+- Captions / supers: <text> @ <time>
+- Music / SFX: <cue> @ <time>
+
+## Reroll plan
+| Shot | Likely failure | Change before reroll |
+|---|---|---|
+| S1 | … | … |
+
+**Highest-risk shot:** S? — <why>

package/bundled-skills/film-crew/references/unslop.md

@@ -0,0 +1,29 @@
+# Unslop: why AI video looks like AI video, and what to write instead
+
+| Slop signal | Usual cause in the prompt | Write instead |
+|---|---|---|
+| Plastic, poreless skin | "beautiful", "flawless", "perfect skin" | "visible pores, slight shine on the forehead, faint under-eye shadows" |
+| Everything evenly lit | no light source named | a motivated key ("hard sun through blinds, camera-left") and deep shadows |
+| Floaty slow-motion drift | no speed given, "cinematic" | real-time speed, or a stated speed ("normal speed", "2x slow motion") |
+| Camera wandering aimlessly | no camera instruction | one named move, or "locked-off tripod shot" |
+| Morphing hands / objects | complex hand action, wide framing | tight framing, simple grip, one object, slow action |
+| Faces changing between shots | paraphrased character descriptions | verbatim continuity-bible descriptors, or image-to-video from one reference |
+| Oversaturated, HDR-ish color | "vibrant", "8k", "ultra HD" | a film look ("Kodak Portra 400, soft contrast, fine grain") and a limited palette |
+| Symmetrical stock-footage framing | no composition choice | a lens, an angle and an off-center subject ("subject in left third") |
+| Gibberish text | signage, labels, UI in frame | no readable text in frame; add text in the edit |
+| Nothing actually happens | a mood instead of an action | one visible, physical action with a start and an end |
+
+## Words that add nothing
+
+`stunning, masterpiece, best quality, 8k, 4k, ultra-detailed, hyper-realistic, award-winning, trending, epic, cinematic (alone), breathtaking`
+
+Delete them. They don't hurt much on their own, but they push out words that would help.
+
+## Words that tend to help
+
+- A **lens** (24mm, 50mm, 85mm, macro)
+- A **camera move** (slow push-in, locked-off, handheld)
+- A **light source** (window light, sodium streetlight, overhead fluorescent)
+- A **film stock or look** (35mm film grain, Super 8, VHS camcorder, iPhone front camera)
+- **Imperfection** (scuffed, fingerprints, wrinkled, condensation, frayed)
+- **Real-time physics cues** (splashes, drips, recoils, bounces)

package/bundled-skills/jev-social/SKILL.md

@@ -11,7 +11,7 @@ author: socai-io
 tags: [social-media, research, instagram, tiktok, linkedin, browser-automation, jev]
 tools: [claude, codex]
 license: "MIT"
-license_source: "https://github.com/socai-io/jev-social/blob/05581cac6b8c21c85e54883b5f2b93c16f40f419/LICENSE"
+license_source: "https://github.com/socai-io/jev-social/blob/782d809c68e2015536359aa7dceede9a3cdbb7f1/LICENSE"
 ---
 # Jev Social
 
@@ -19,7 +19,7 @@ license_source: "https://github.com/socai-io/jev-social/blob/05581cac6b8c21c85e5
 
 Jev Social turns a natural-language social research goal into bounded Jev routing decisions, then delegates platform-read-only browser work to the local socai CLI. Use the captured posts, profiles, comments, videos, and opened details to produce a compact, source-linked report instead of exposing raw CLI output. "Read-only" means no social-account mutation; the CLI still writes private local run records and may download requested media.
 
-The executable examples below are pinned to the tested runtime commit included in Jev Social `v0.1.4`. A pin improves reproducibility but is not a trust guarantee; keep the package, browser data, and returned content inside the safety boundaries below.
+The executable examples below are pinned to the tested runtime commit included in Jev Social `v0.1.5`. A pin improves reproducibility but is not a trust guarantee; keep the package, browser data, and returned content inside the safety boundaries below.
 
 ## When to Use
 - Use when a user requests evidence-backed research on Instagram, TikTok, or LinkedIn and wants real public posts or profiles rather than a general web summary.
@@ -45,7 +45,7 @@ If the exact pinned package is not already available locally, explain that the n
 Run the status command before every research task:
 
 ```bash
-npx github:socai-io/jev-social#05581cac6b8c21c85e54883b5f2b93c16f40f419 status
+npx github:socai-io/jev-social#782d809c68e2015536359aa7dceede9a3cdbb7f1 status
 ```
 
 Require all of the following before continuing:
@@ -68,7 +68,7 @@ Pass the goal as one argument with an argv-capable process runner; never constru
 ```text
 program: npx
 argv:
-  - github:socai-io/jev-social#05581cac6b8c21c85e54883b5f2b93c16f40f419
+  - github:socai-io/jev-social#782d809c68e2015536359aa7dceede9a3cdbb7f1
   - search
   - <exact research goal as one argument>
   - --platform
@@ -126,7 +126,7 @@ Use only TikTok if its capability is reported as supported. Open details before
 When the user explicitly asks for the local demo UI, start it on loopback only:
 
 ```bash
-npx github:socai-io/jev-social#05581cac6b8c21c85e54883b5f2b93c16f40f419 serve --port 8766
+npx github:socai-io/jev-social#782d809c68e2015536359aa7dceede9a3cdbb7f1 serve --port 8766
 ```
 
 Report `http://127.0.0.1:8766`. Leave the process running only when the user asked for a local demo server, and do not expose it on a public interface.

package/bundled-skills/noaa-radar-satellite-fetching/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: noaa-radar-satellite-fetching
+description: "Retrieve NOAA NEXRAD and GOES products from public cloud archives using verified site, product, channel, sector, and scan-time selection."
+category: data
+risk: safe
+source: self
+source_type: self
+date_added: "2026-09-24"
+author: ShianMike
+tags: [weather, noaa, nexrad, goes, radar, satellite, aws-s3]
+tools: [claude, cursor, gemini, codex]
+---
+
+# NOAA Radar and Satellite Fetching
+
+## Overview
+
+Retrieve NOAA NEXRAD radar and GOES satellite objects from public cloud
+archives while preserving the product, platform, spatial sector, and scan-time
+identity. Discover through narrow prefixes, choose by observation time rather
+than upload time, and validate the downloaded scientific file before use.
+
+This skill covers raw or provider-produced radar and satellite products. It
+does not retrieve numerical model output or ordinary station observations.
+
+## When to Use This Skill
+
+- A task needs NEXRAD Level II archive volumes or real-time chunks.
+- A task needs selected NEXRAD Level III products.
+- GOES ABI, GLM, or another GOES-R product is needed for a time and region.
+- A download must select the nearest completed scan within a tolerance.
+- A public S3 key, satellite assignment, radar site, channel, or sector is
+  uncertain or has changed.
+
+Do not activate this skill merely to display a third-party map tile or to answer
+a general weather question.
+
+## Define the Product Contract
+
+For NEXRAD, specify:
+
+- Level II archive, Level II real-time chunks, or a named Level III product;
+- four-character radar site, such as `KTLX`;
+- desired scan time in UTC and nearest/previous/next selection policy;
+- maximum time tolerance;
+- full volume or exact product code;
+- raw file retention and decoder.
+
+For GOES, specify:
+
+- physical satellite number or operational role, such as East or West;
+- instrument and product level/short name;
+- Full Disk, CONUS, Mesoscale 1, or Mesoscale 2 sector where applicable;
+- ABI channel or derived product;
+- desired scan time in UTC and tolerance;
+- calibration form needed, such as radiance or brightness temperature.
+
+Resolve an operational role to a physical satellite using current NOAA
+documentation at request time. East and West assignments change over a
+satellite program's lifetime.
+
+## Current Public AWS Routes
+
+Consult the AWS Registry of Open Data before hard-coding a bucket. As of this
+skill's publication:
+
+- NEXRAD Level II archive: `s3://unidata-nexrad-level2/`
+- NEXRAD Level II real-time chunks: `s3://unidata-nexrad-level2-chunks/`
+- selected NEXRAD Level III real-time data: `s3://unidata-nexrad-level3/`
+- GOES imagery and metadata: satellite-specific buckets such as
+  `s3://noaa-goes18/` and `s3://noaa-goes19/`
+
+The former `noaa-nexrad-level2` bucket was deprecated and scheduled to become
+unavailable on September 1, 2025. Do not copy that retired route from old
+tutorials.
+
+## Discover with Narrow Prefixes
+
+NEXRAD Level II archive objects are organized by UTC date and site. GOES
+objects are organized by product, year, day of year, and hour. List only the
+smallest prefix that can contain the requested scan.
+
+```bash
+aws s3 ls --no-sign-request \
+  s3://unidata-nexrad-level2/YYYY/MM/DD/KXXX/
+
+aws s3 ls --no-sign-request \
+  s3://noaa-goes19/ABI-L2-CMIPC/YYYY/DDD/HH/
+```
+
+Replace every placeholder with a validated value. Include the adjacent hour or
+UTC day only when the time tolerance crosses that boundary. Paginate listings
+and bound the total keys inspected.
+
+Use real-time chunk buckets only when the consumer is designed to assemble and
+validate chunks. Prefer completed archive volumes for ordinary historical or
+post-event processing.
+
+## Select by Scan Time
+
+Object `Last-Modified` is publication metadata, not the measurement time.
+
+- For NEXRAD, parse the site and scan timestamp from the documented object name,
+  then confirm time and site from the decoded volume header.
+- For GOES-R, filenames encode platform plus scan start (`s`), end (`e`), and
+  creation (`c`) timestamps. Select by scan start or interval overlap, not file
+  creation time.
+- Default to the closest scan at or before the requested instant for a
+  retrospective view. Allow a future scan only when the caller explicitly asks
+  for nearest-in-either-direction behavior.
+- Reject every candidate outside the stated tolerance.
+- When sectors overlap, require the requested sector instead of choosing solely
+  by time.
+
+This standard-library helper extracts GOES-R scan timestamps without opening
+the NetCDF payload:
+
+```python
+import re
+from datetime import datetime, timezone
+from pathlib import PurePosixPath
+
+
+GOES_TIMES = re.compile(
+    r"_s(?P<start>\d{14})_e(?P<end>\d{14})_c(?P<created>\d{14})"
+)
+
+
+def parse_goes_times(object_key):
+    match = GOES_TIMES.search(PurePosixPath(object_key).name)
+    if not match:
+        raise ValueError(f"unrecognized GOES-R filename: {object_key}")
+
+    def parse(value):
+        return datetime.strptime(value, "%Y%j%H%M%S%f").replace(
+            tzinfo=timezone.utc
+        )
+
+    return {name: parse(value) for name, value in match.groupdict().items()}
+```
+
+Treat filename parsing as discovery. After download, verify the corresponding
+time coverage and platform attributes inside the file.
+
+## Download and Validate
+
+1. Record bucket, exact key, size, ETag, and `Last-Modified` before transfer.
+2. Download to a request-owned temporary path. For public buckets, use unsigned
+   S3 access rather than supplying credentials.
+3. If the object might still be publishing, require stable metadata or pin a
+   conditional request to the observed object identity.
+4. Verify the received byte count and a provider checksum when one is supplied.
+   Otherwise compute and record a local SHA-256 digest.
+5. Open the object with an existing format-aware decoder.
+6. Verify site/platform, product, scan interval, and expected dimensions or
+   radar sweeps before renaming it into the cache.
+
+Reuse an installed NEXRAD or NetCDF reader. Do not build a binary radar or
+satellite decoder merely to fetch a file.
+
+## Radar-Specific Checks
+
+- Confirm that the radar site is the requested site and was operational at the
+  scan time.
+- Treat Level II volumes, real-time chunks, and Level III products as different
+  contracts; they are not interchangeable encodings.
+- Verify volume start time, end time when available, sweep count, moments, and
+  elevation angles after decoding.
+- Keep range folding, missing gates, quality masks, and velocity ambiguity
+  explicit.
+- A radar's nominal coverage radius does not guarantee useful low-level data at
+  a location. Consider distance, beam height, terrain blockage, and outages.
+
+## Satellite-Specific Checks
+
+- Confirm the physical satellite, instrument, product short name, sector, scan
+  mode, channel, and time coverage from NetCDF attributes.
+- Do not treat ABI fixed-grid `x` and `y` coordinates as latitude and longitude.
+  Use the file's geostationary projection metadata.
+- Apply scale/offset, fill values, data-quality flags, and product-specific
+  calibration according to NOAA documentation.
+- A Mesoscale file is not identified only by its small dimensions; distinguish
+  Mesoscale 1 and 2 explicitly.
+- Do not blend files from different scan modes, sectors, satellites, or product
+  levels without recording the transformation.
+
+## Reliability, Cache, and Cleanup
+
+- Cache by bucket, key, and object identity, not a friendly timestamp alone.
+- Retry timeouts, `408`, `429`, and transient `5xx` responses with bounded
+  backoff and jitter.
+- Bound time tolerance, adjacent-hour listings, pagination, concurrency, and
+  disk usage.
+- Keep partial downloads separate from valid cache entries.
+- Use event notifications for continuous real-time ingestion when appropriate;
+  do not repeatedly scan broad prefixes.
+- For a one-shot image or export, delete request-owned raw objects in `finally`
+  only after the final artifact and provenance manifest are durable.
+- Never delete a shared user cache as request cleanup.
+
+## Verification Checklist
+
+- The source bucket is current and documented by NOAA or its data distributor.
+- Radar site or physical satellite and operational role are explicit.
+- Product level, code/short name, sector, channel, and scan mode match the
+  request.
+- The selected scan satisfies the direction policy and maximum time tolerance.
+- Object size and identity match the downloaded bytes.
+- The format-aware decoder opens the file and confirms internal metadata.
+- Geolocation uses the product's real coordinate reference system.
+- Temporary data cleanup preserves the requested artifact and manifest.
+
+## Security & Safety Notes
+
+- Fetch only public data or resources the user is authorized to access.
+- Never embed AWS credentials, signed URLs, private endpoints, or notification
+  subscription tokens in code or logs.
+- Keep TLS verification enabled; `--no-sign-request` does not disable TLS.
+- Validate site, product, channel, sector, and time inputs against allowlists
+  before constructing object prefixes or local paths.
+- Bound response size and available disk space before downloading high-rate
+  radar or satellite streams.
+- Preserve NOAA attribution and do not imply NOAA endorsement.
+
+## Common Pitfalls
+
+- **Old NEXRAD examples return no data:** They reference the retired Level II
+  bucket. Resolve the current bucket from the registry.
+- **The right minute shows the wrong image:** Creation time was used instead of
+  scan start/end time.
+- **GOES East points to the wrong bucket:** An operational role was hard-coded
+  to a satellite number. Resolve the assignment for the requested date.
+- **The map is displaced:** Fixed-grid scan angles were treated as geographic
+  coordinates. Apply the geostationary projection.
+- **A real-time radar volume will not decode:** Individual chunks were treated
+  as a completed archive volume. Assemble and validate them or use the archive.
+
+## Limitations
+
+- Buckets, satellite assignments, product availability, scan modes, and naming
+  conventions can change; verify current official documentation.
+- This skill retrieves source products but does not guarantee meteorological
+  suitability, perform mosaicking, or implement scientific calibration.
+- Historical gaps and instrument or site outages cannot be repaired by provider
+  fallback.
+
+## Additional Resources
+
+- [NEXRAD on the AWS Registry of Open Data](https://registry.opendata.aws/noaa-nexrad/)
+- [NOAA GOES on the AWS Registry of Open Data](https://registry.opendata.aws/noaa-goes/)
+- [NOAA GOES-R documents](https://www.ospo.noaa.gov/resources/documents/goes-r.html)
+- [NOAA STAR guide to satellite filenames](https://www.star.nesdis.noaa.gov/atmospheric-composition-training/satellite_data_decoding_data_file_names.php)
+- [NOAA Radar Operations Center interface documents](https://www.roc.noaa.gov/wsr88d/BuildInfo/Files.aspx)

package/bundled-skills/testdriver-e2e-testing/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: testdriver-e2e-testing
+description: "Build E2E tests with TestDriver.ai, the AI code reviewer that runs every pull request in a real desktop sandbox, finds bugs, and builds regression tests"
+category: testing
+risk: safe
+source: community
+source_repo: testdriverai/testdriverai
+source_type: official
+date_added: "2026-09-24"
+author: testdriverai
+tags: [testing, e2e, qa, automation, computer-use]
+tools: [claude, cursor, gemini]
+license: "Apache-2.0"
+license_source: "https://github.com/testdriverai/testdriverai/blob/main/LICENSE"
+---
+
+# TestDriver End-to-End Testing
+
+## Overview
+
+[TestDriver](https://testdriver.ai) is an AI code reviewer that actually runs your app. It automatically runs every pull request in a real desktop sandbox, finds bugs, and builds regression tests. Tests control browsers and native applications using natural language element descriptions and AI vision, and run as Vitest suites. This skill teaches an agent how to author, run, and debug TestDriver tests.
+
+## When to Use This Skill
+
+- Use when you need to write an end-to-end test for a web or desktop application
+- Use when automating a UI workflow that has no stable selectors (canvas, Electron, native apps)
+- Use when the user asks to verify that a page or flow works ("check if the login page works")
+- Use when debugging a failing TestDriver test
+
+## How It Works
+
+### Step 1: Set up the project
+
+```bash
+npx testdriverai init
+```
+
+This scaffolds `package.json`, example tests, `vitest.config.mjs`, and a GitHub Actions workflow. The user must set `TD_API_KEY` in `.env` (get a key at https://console.testdriver.ai/team).
+
+### Step 2: Write a test
+
+Tests are Vitest suites using the TestDriver hooks:
+
+```javascript
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/vitest/hooks";
+
+describe("Login", () => {
+  it("signs in successfully", async (context) => {
+    const testdriver = TestDriver(context);
+    await testdriver.provision.chrome({ url: "https://example.com/login" });
+
+    const email = await testdriver.find("email input field");
+    await email.click();
+    await testdriver.type("user@example.com");
+
+    const submit = await testdriver.find("Sign In button");
+    await submit.click();
+
+    const result = await testdriver.assert("the dashboard is visible");
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+### Step 3: Run and iterate
+
+```bash
+vitest run tests/login.test.mjs
+```
+
+Screenshots are captured automatically before and after every command and saved to `.testdriver/screenshots/`, named with the source line number for easy debugging.
+
+## Examples
+
+### Example 1: Testing a desktop (Electron) app
+
+```javascript
+await testdriver.provision.electron({ appPath: "./dist/my-app" });
+const menu = await testdriver.find("File menu in the menu bar");
+await menu.click();
+```
+
+### Example 2: Waiting for slow elements
+
+```javascript
+const done = await testdriver.find("Loading complete indicator", { timeout: 30000 });
+await done.click();
+```
+
+## Best Practices
+
+- ✅ Use specific element descriptions ("blue Sign In button in the header", not "button")
+- ✅ Set both `testTimeout` and `hookTimeout` to 900000 in `vitest.config.mjs`
+- ✅ Add `assert()` calls for verifiable pass/fail conditions
+- ✅ Always `await` every TestDriver call
+- ❌ Do not use `npx vitest`; run `vitest run` directly
+- ❌ Do not rely on CSS selectors; TestDriver locates elements visually
+
+## Limitations
+
+- Requires a TestDriver API key (`TD_API_KEY`) and network access to provision sandboxes.
+- Only works with Vitest as the test runner.
+- This skill does not replace environment-specific validation, testing, or expert review.
+
+## Security & Safety Notes
+
+- `npx testdriverai init` writes project files to the current directory; run it only in a project you intend to modify.
+- The `TD_API_KEY` credential belongs in `.env` (gitignored by the scaffold). Never commit it.
+- Tests execute inside an isolated remote sandbox, not on the local machine.
+
+## Common Pitfalls
+
+- **Problem:** Cleanup hooks fail with a 10s timeout.
+  **Solution:** Set `hookTimeout: 900000` in `vitest.config.mjs`; sandbox teardown and recording uploads take longer than Vitest's default.
+- **Problem:** Scrolling does nothing.
+  **Solution:** An input field has focus. Press Escape or click the page background first, then scroll.
+
+## Related Skills
+
+- `@webapp-testing` - Playwright-based alternative for local web apps with stable DOM selectors