agentleFS
JuanMarchettoJuanMarchetto/agent-skills/skills/demo-pipeline/SKILL.md

demo-pipeline

Skill5 starsChanged 8 months agoMITView on GitHub

Record automated demos for mobile and web apps. Converts natural language demo scripts into Maestro flows (mobile) or webreel configs (web), executes them to capture screenshots and video, and generates a QA report. Use when: record demo, demo recording, record app demo, grab demo, automated demo.

  • Pipes a download into a shell

The file

Show its rules and text

We split this skill into the rules it gives an agent

20 rules. About 0 are common, 12 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈12

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read the file-based routing structure:

    line 36
  2. Distinctive:

    Search for navigation calls to build a flow graph:

    line 60
  3. Distinctive:

    Search for native module usage per screen:

    line 70
  4. Distinctive:

    Before anything, determine what kind of project this is and whether it's running.

    line 90
  5. Distinctive:

    Check in order (stop at first match):

    line 94
  6. Very specific:

    Check if app.json has "web" in platforms → Expo universal

    line 97
  7. Very specific:

    Default app ID: from expo.ios.bundleIdentifier or expo.android.package

    line 99
  8. Distinctive:

    If no device/emulator → tell user: "No running device detected.

    line 117
  9. Distinctive:

    If no server → tell user: "No dev server detected.

    line 126
  10. Very specific:

    If any step in the YAML has a state: block or native: mock, demo mode is required.

    line 141
  11. Distinctive:

    No injection — let the real native flow execute

    line 166
  12. Distinctive:

    After all steps complete:

    line 170
  13. Very specific:

    Search codebase for testID props: grep -r 'testID=' src/

    line 198
  14. Distinctive:

    If no testID exists, use text-based selection

    line 200
  15. Very specific:

    Search for id=, data-testid=, or distinctive text

    line 203
  16. Very specific:

    When output.video_mode is device-only, record only the device screen (no terminal/Maestro UI):

    line 294
  17. Very specific:

    When video_mode is full (default), use maestro record as before.

    line 317
  18. Distinctive:

    If webreel not installed:

    line 343
  19. Distinctive:

    Verify all expected screenshots exist.

    line 364
  20. Very specific:

    Create ./docs/demo-report.md using the report template:

    line 376

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Demo Pipeline

Record polished app demos from a natural language script. Works with Expo mobile (Maestro) and web apps (webreel/Playwright).

Pipeline: DISCOVER → DETECT → STATE SETUP → PARSE → EXECUTE → COMPILE

Quick Start

User says: "record demo — show the login, navigate to rewards, highlight featured items, end on profile"

You:

  1. Discover all screens, states, and flows via static analysis
  2. Detect the project type and running state
  3. Set up demo state injection (if demo_mode is enabled)
  4. Generate a unified YAML script from the description
  5. Present YAML for user approval
  6. Execute with the right tool (Maestro or webreel)
  7. Collect screenshots, video, and generate report

Phase 0: DISCOVER — Flow & State Analysis

Analyze the codebase to map all screens, states, flows, and native dependencies.

Step 1: Discover screens

Read the file-based routing structure:

find src/app -name "*.tsx" -not -name "_layout.tsx" -not -name "+not-found.tsx" | sort

For each screen file, extract the route path from its filesystem location.

Step 2: Identify states per screen

For each screen file, search for UI conditionals that reveal possible states:

grep -n "loading\|isLogged\|isEmpty\|error\|balance.*>\|\.length.*==.*0" src/app/**/*.tsx

Common patterns to look for:

  • {loading ? <Skeleton/> : ...} → loading state
  • {isLoggedIn && ...} or {user ? ... : ...} → guest vs logged-in
  • {items.length === 0 ? <EmptyState/> : ...} → empty state
  • {balance > 0 ? ... : ...} → empty-balance vs has-balance
  • {error ? <Error/> : ...} → error state

Step 3: Map navigation flows

Search for navigation calls to build a flow graph:

grep -rn "router\.push\|router\.replace\|href=" src/app/ src/components/

Group into named flows (e.g., "Full reward claim": home → rewards → [id] → scan → confirmation).

Step 4: Identify native dependencies

Search for native module usage per screen:

grep -rn "expo-camera\|CameraView\|useMobileWallet\|SeedVault\|Linking\|expo-local-authentication" src/

Mark each screen's native dependencies. These will be flagged as native: real | mock in the YAML.

Step 5: Present flow map

Generate a flow map in YAML format (see templates/flow-map.yaml) and present to user:

"I discovered N screens with M possible states and K flows. Here's the map: [flow map YAML] Which flows do you want in the demo?"

Then proceed to Phase 1.

Phase 1: DETECT — Project Type & State

Before anything, determine what kind of project this is and whether it's running.

Step 1: Identify project type

Check in order (stop at first match):

  1. Read app.json — if it has an "expo" key → Expo project
    • Check if app.json has "web" in platforms → Expo universal
    • Extract expo.slug or expo.name for app ID
    • Default app ID: from expo.ios.bundleIdentifier or expo.android.package
  2. Glob for next.config.* — if found → Next.js web project
  3. Read package.json scripts — if has "dev" or "start" → Generic web project
  4. If none match → ask user

Step 2: Check running state

For mobile (Expo):

# Android
adb devices 2>/dev/null | grep -v "List"
# iOS (macOS only)
xcrun simctl list booted 2>/dev/null

If no device/emulator → tell user: "No running device detected. Start your emulator/device and the Expo dev server, then try again."

For web:

curl -s -o /dev/null -w "%{http_code}" http://localhost:8081 2>/dev/null
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 2>/dev/null
curl -s -o /dev/null -w "%{http_code}" http://localhost:5173 2>/dev/null

If no server → tell user: "No dev server detected. Start your dev server and try again."

Step 3: Announce detection

Tell the user what you detected, e.g.:

"Detected: Expo mobile project (com.example.myapp) with Android emulator running. I'll use Maestro for recording."

Then proceed to Phase 2.

Phase 1.5: STATE SETUP — Demo State Injection

Only runs when the unified YAML has demo_mode: true. Skip this phase entirely for regular demos without state emulation.

Step 1: Check if demo mode is needed

If any step in the YAML has a state: block or native: mock, demo mode is required.

Step 2: Inject state via adb

For each step that has a state: block, inject the mock data before executing that step's actions.

Injection mechanism:

# Write mock state to AsyncStorage via adb
adb shell "run-as <APP_ID> sh -c 'cat > /data/data/<APP_ID>/files/demo-state.json'" <<< '{"wallet":"0x123","balance":5000}'

Alternative — use deep links to navigate to specific states:

adb shell am start -a android.intent.action.VIEW \
  -d "<SCHEME>://demo?screen=<SCREEN>&state=<STATE_JSON_ENCODED>"

Step 3: Handle native mocks

For steps with native: mock:

  • Inject the mock result into AsyncStorage before the step executes
  • The app's demo bootstrap reads this and skips the native module, showing the result directly

For steps with native: real (or no native field):

  • No injection — let the real native flow execute

Step 4: Cleanup after recording

After all steps complete:

adb shell "run-as <APP_ID> sh -c 'rm -f /data/data/<APP_ID>/files/demo-state.json'"

Important: App-side requirement

The project needs a demo bootstrap file. If it doesn't exist, tell the user:

"Demo mode requires a bootstrap file. I'll create src/demo/bootstrap.ts — a dev-only file that reads mock state from AsyncStorage. This file has zero impact on production builds since it's gated behind __DEV__."

See state-injection.md for the full bootstrap implementation.

Phase 2: PARSE — Natural Language → Unified YAML

Convert the user's natural language demo description into a structured YAML script.

Step 1: Analyze the description

Extract:

  • Screens/sections to show (each becomes a step)
  • Interactions (taps, scrolls, typing)
  • Key elements to highlight (get screenshot actions)
  • Flow order (navigation sequence)

Step 2: Identify testIDs or selectors

For mobile (Expo/React Native):

  • Search codebase for testID props: grep -r 'testID=' src/
  • Match testIDs to screens/elements in the description
  • If no testID exists, use text-based selection

For web:

  • Search for id=, data-testid=, or distinctive text
  • Use CSS selectors

Step 3: Generate unified YAML

target: <expo-mobile|web|expo-universal>
app_id: <detected app ID>        # mobile only
base_url: <detected URL>         # web only

demo_mode: false               # true to enable state injection
env:                           # environment variables (optional)
  DEMO_MODE: "true"

steps:
  - name: "<Screen Name>"
    state:                       # optional — mock state to inject
      key: value
    native: real                 # optional — real | mock (default: real)
    actions:
      - <action>: <value>
      - screenshot: "<NN-name>"

output:
  screenshots: ./screenshots/
  video: ./videos/demo.mp4
  video_mode: device-only      # device-only | full
  report: ./docs/demo-report.md

Supported actions (see reference.md for full details):

ActionExample
taptap: "tab-rewards" or tap: "Button Text"
typetype: { target: "search-input", text: "Espresso" }
scrollscroll: down
swipeswipe: left
waitwait: 2s
wait_forwait_for: "loading-done"
screenshotscreenshot: "03-rewards"
navigatenavigate: "http://localhost:3000/dashboard"
keykey: "Enter"

Auto-number screenshots with NN- prefix (01, 02, 03...).

Step 4: Present for approval

Show the generated YAML to the user. Ask:

"Here's the demo script I generated. Review it and let me know if you'd like to change anything, or approve to proceed with recording."

HARD GATE: Do NOT proceed to Phase 3 until the user explicitly approves the YAML.

Phase 3: EXECUTE — Run the Recording

Translate approved unified YAML → tool-specific format → execute.

Mobile Path: Maestro

Step 1: Generate Maestro flow

Action mapping:

UnifiedMaestro
tap: "id"- tapOn:\n id: "id"
tap: "Text"- tapOn: "Text"
type: { target, text }- tapOn:\n id: "target"\n- inputText: "text"
scroll: down- scroll
swipe: left- swipe:\n direction: LEFT\n duration: 400
wait: 2s(no-op — Maestro auto-waits; used for pacing only)
wait_for: "id"- extendedWaitUntil:\n visible:\n id: "id"\n timeout: 10000
screenshot: "name"- takeScreenshot: "name"

Step 2: Save to ./maestro/demo-recording.yaml

Step 3: Execute:

maestro record maestro/demo-recording.yaml --output videos/demo.mp4

Fallback (no video): maestro test maestro/demo-recording.yaml

Copy screenshots:

mkdir -p screenshots
cp ~/.maestro/tests/*/screenshots/* screenshots/ 2>/dev/null || true

Video Mode: device-only

When output.video_mode is device-only, record only the device screen (no terminal/Maestro UI):

# Start device screen recording in parallel
adb shell screenrecord /sdcard/demo-recording.mp4 &
RECORD_PID=$!

# Run Maestro flow in test-only mode
maestro test maestro/demo-recording.yaml

# Stop recording and extract
kill $RECORD_PID 2>/dev/null
adb shell "kill $(adb shell ps | grep screenrecord | awk '{print $2}')" 2>/dev/null
sleep 1
adb pull /sdcard/demo-recording.mp4 videos/demo.mp4
adb shell rm /sdcard/demo-recording.mp4

Limitation: adb screenrecord max 3 minutes per recording. For longer demos, chain multiple recordings and concatenate:

ffmpeg -f concat -safe 0 -i segments.txt -c copy videos/demo.mp4

When video_mode is full (default), use maestro record as before.

Web Path: webreel

Step 1: Generate webreel config

Action mapping:

Unifiedwebreel
tap: "id"{ "action": "click", "selector": "#id" }
tap: "Text"{ "action": "click", "text": "Text" }
type: { target, text }{ "action": "type", "selector": "#target", "text": "text" }
scroll: down{ "action": "scroll", "y": 500 }
wait: 2s{ "action": "pause", "ms": 2000 }
wait_for: "id"{ "action": "wait", "selector": "#id" }
screenshot: "name"{ "action": "screenshot", "output": "name.png" }
navigate: "url"{ "action": "navigate", "url": "url" }
key: "Enter"{ "action": "key", "key": "Enter" }

Step 2: Save to ./webreel.config.json

Step 3: Execute: npx webreel record

Web Fallback: Playwright

If webreel not installed:

  1. Generate Playwright TypeScript script with recordVideo context
  2. Execute: npx tsx scripts/demo-recording.ts
  3. Convert: ffmpeg -i recordings/demo.webm -c:v libx264 -preset fast videos/demo.mp4

Error Handling

If execution fails:

  1. Show error output to user
  2. Suggest fixes (missing testIDs, wrong selectors, app not running)
  3. Let user edit YAML and retry from Phase 3

Phase 4: COMPILE — Generate Outputs

Step 1: Organize screenshots

mkdir -p screenshots
ls -la screenshots/

Verify all expected screenshots exist. Report any missing.

Step 2: Verify video

ls -la videos/demo.mp4

Report file size. If missing, explain (e.g., maestro test doesn't record video).

Step 3: Generate report

Create ./docs/demo-report.md using the report template:

  • Project name and type (from Phase 1)
  • Tool used
  • Date
  • Step table with screenshot paths and status
  • Output file paths and sizes
  • Errors encountered

Step 4: Present summary

Demo recording complete!

  • Screenshots: N captured in ./screenshots/
  • Video: ./videos/demo.mp4 (X MB)
  • Report: ./docs/demo-report.md

Example Output

Demo recording complete!
- Screenshots: 5 captured in ./screenshots/
  01-login.png (1290x2796)
  02-home-feed.png (1290x2796)
  03-rewards-list.png (1290x2796)
  04-coupon-detail.png (1290x2796)
  05-profile.png (1290x2796)
- Video: ./videos/demo.mp4 (12.3 MB, 45s)
- Report: ./docs/demo-report.md

Error Handling

  • No device/emulator detected: "Start your emulator/device and the Expo dev server, then try again"
  • No dev server detected: "Start your dev server and try again"
  • testID not found: Suggest text-based selection as fallback, or ask user to add testID to component
  • Video recording failed: Fall back to maestro test (screenshots only, no video) and explain limitation
  • Maestro not installed: Provide install command: curl -Ls "https://get.maestro.mobile.dev" | bash

Related Skills

Context

This skill has companion files:

  • reference.md — complete action reference with tool mappings
  • templates/maestro-flow.yaml — Maestro flow template
  • templates/webreel-config.json — webreel config template
  • templates/demo-report.md — report template

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.