walkthrough-script-agent

Walkthrough Script Agent

Generate professional, screen-by-screen walkthrough video scripts for app features — ready for recording or voiceover production.

This skill uses 3 specialized agents that analyze your app, write feature scripts from different angles, then synthesize them into a polished script package.

What It Produces

Output	Description
Feature Scripts	Individual timed scripts for each app feature
Full Walkthrough	Complete app tour script covering all features
Screen Directions	What to show on screen at each moment
Narration Text	Voiceover-ready narration with pacing cues
Shot List	Ordered list of screens/actions to capture

Prerequisites

• No API keys required
• Works best with app screenshots, screen recordings, or a detailed feature list
• Optionally pair with app-demo-agent to produce the final video

Workflow

Step 1: Gather App Context (REQUIRED)

⚠️ DO NOT skip this step. Use interactive questioning — ask ONE question at a time.

Question Flow

⚠️ Use the AskUserQuestion tool for each question below. Do not just print questions in your response — use the tool to create interactive prompts with the options shown.

Q1: App Overview

"I'll write walkthrough scripts for your app! First — what's the app called and what does it do?

(A brief description is fine — e.g., 'Bubba Fishing — a fishing app for logging catches, tracking trips, and competing in tournaments')"

Wait for response.

Q2: Target Audience

"Who's the target audience for these walkthrough videos?

• New users (onboarding/tutorial style)
• Potential customers (marketing/conversion style)
• Investors / stakeholders (pitch/demo style)
• Internal team (training/documentation style)
• Or describe"

Wait for response. This determines tone, pacing, and emphasis.

Q3: Features to Cover

"Which features should I write scripts for?

• All major features — I'll analyze the app and cover everything
• Specific features — list the ones you want
• Single feature deep-dive — one feature, thorough walkthrough"

Wait for response. If they say "all", use the feature analyzer agent to identify them.

Q4: Source Material

"What do I have to work with?

• Screenshots — provide paths to app screenshots
• Screen recording — provide path to a recording
• Codebase — I'll read the source code to understand features
• Description only — you'll describe the screens to me
• Multiple sources — combination of the above"

Wait for response. More context = better scripts.

Q5: Video Style

"What style for the walkthrough?

• Quick tour — fast-paced, 15-30s per feature, highlight reel
• Standard walkthrough — 30-60s per feature, show key flows
• Detailed tutorial — 60-90s per feature, step-by-step instructions
• Marketing showcase — benefit-focused, emotional, persuasive
• Or describe your own style"

Wait for response.

Q6: Tone

"What tone should the narration use?

• Professional — polished, confident, product demo feel
• Friendly / conversational — casual, like showing a friend
• Energetic / excited — upbeat, enthusiastic
• Calm / instructional — patient, step-by-step
• Or describe"

Wait for response.

Q7: Output Format

"How do you want the scripts delivered?

• Markdown files — one .md per feature + a master script (default)
• Single document — everything in one file
• JSON — structured data for programmatic use
• Ready for app-demo-agent — formatted for direct handoff to video production"

Wait for response.

Quick Reference

Question	Determines
App Overview	Context and domain knowledge
Target Audience	Tone, depth, and persuasion strategy
Features	Scope of scripts to generate
Source Material	How we analyze the app
Video Style	Pacing and duration targets
Tone	Narration voice and language
Output Format	Deliverable structure

---

Step 2: Analyze the App

Based on the source material provided, build a complete picture of the app's features and screens.

If screenshots provided:

Read each screenshot with the Read tool. Document what you see:

• Screen name / purpose
• Key UI elements and interactions
• Navigation flow between screens
• Feature entry points

If codebase provided:

Use the feature-analyzer agent to examine the source code:

• ViewControllers / screens
• Navigation flows (segues, routes)
• Key user-facing features
• Data models that map to features

If screen recording provided:

Extract frames for analysis:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/app-demo-agent/scripts/extract_frames.py \
  INPUT_VIDEO \
  -o ~/walkthrough_project/frames/ \
  --scene-detect \
  --timestamps

Read the extracted frames to map the flow.

If description only:

Work from the user's description, asking follow-up questions if any feature is unclear.

Output a feature map before proceeding:

Feature Map:
1. [Feature Name] — [Brief description] — [Key screens involved]
2. [Feature Name] — [Brief description] — [Key screens involved]
3. ...

Present this to the user for confirmation before writing scripts.

---

Step 3: Generate Walkthrough Scripts

Deploy the specialized agents in parallel to write scripts for each feature:

Agent 1: Feature Analyzer

Examines the app and produces a structured breakdown of each feature including:

• User flow (step-by-step actions)
• Key screens and transitions
• Value proposition of the feature
• Common user goals within the feature

Agent 2: Script Writer

Takes each feature breakdown and writes the walkthrough script with:

• Timed narration synced to screen actions
• Screen direction notes (what to show/tap/scroll)
• Transition cues between screens
• Pacing matched to the chosen video style

Agent 3: Hook Writer

Creates compelling openings and closings:

• Feature intro hooks (why this feature matters)
• Transition lines between features
• Closing CTAs
• Full walkthrough intro and outro

---

Step 4: Assemble the Script Package

Combine agent outputs into the final deliverable.

Per-Feature Script Format

Each feature script should follow this structure:

# [Feature Name] Walkthrough

**Duration:** ~[X]s | **Style:** [chosen style] | **Tone:** [chosen tone]

## Shot List
1. [Screen/action to capture]
2. [Screen/action to capture]
3. ...

## Timed Script

| Time | Screen Direction | Narration |
|------|-----------------|-----------|
| 0-3s | [App opens to home screen] | "Opening hook line..." |
| 3-6s | [User taps feature button] | "Narration for this moment..." |
| 6-10s | [Feature screen loads] | "Narration continues..." |
| ... | ... | ... |

## Narration (Full Text)

> [Complete narration as a single flowing block — ready for TTS or voiceover recording]

## Notes
- [Any special recording instructions]
- [Suggested transitions or effects]

Master Walkthrough Script

If multiple features, also produce a master script that chains them together:

# [App Name] — Complete Walkthrough

**Total Duration:** ~[X]min | **Features Covered:** [N]

## Script Order
1. App Intro (10-15s)
2. [Feature 1] (Xs)
3. [Transition] (3-5s)
4. [Feature 2] (Xs)
5. ...
6. Closing CTA (10-15s)

## Full Timed Script
[Combined timed table for the entire walkthrough]

## Full Narration
[Complete narration text — ready for a single recording session]

---

Step 5: Deliver and Iterate

Save the scripts to the requested location (default: ~/walkthrough_scripts/[app-name]/).

Delivery message:

"Your walkthrough scripts are ready!

App: [App Name] Features Scripted: [N] Total Narration: [X] words ([Y] minutes at natural pace)

Files:

• [feature-name].md — per-feature scripts
• master-walkthrough.md — full app tour script
• shot-list.md — consolidated recording checklist

Want me to:

• Adjust tone or pacing for any feature?
• Add/remove features from the walkthrough?
• Generate a version optimized for a specific platform (TikTok, YouTube, etc.)?
• Hand off to app-demo-agent to produce the actual video?"

---

Pacing Guide

Style	Duration/Feature	Words/Feature	Pace
Quick tour	15-30s	30-60 words	Punchy, highlight key value
Standard	30-60s	60-120 words	Show key flow, explain benefits
Detailed tutorial	60-90s	120-180 words	Step-by-step, thorough
Marketing showcase	20-45s	40-90 words	Benefit-led, emotional hooks

Script Writing Rules

1. Show, don't tell — every narration line must match what's on screen
2. Lead with value — open each feature with WHY it matters, not what it is
3. Use active voice — "Tap the plus button" not "The plus button can be tapped"
4. One idea per line — keep narration lines to one action or concept
5. Pause on transitions — use ... or — for natural breathing room
6. End with a hook — each feature should leave the viewer wanting to try it
7. Name UI elements — reference actual button names, labels, and screen titles
8. Include timing cues — mark where pauses, emphasis, or speed changes should occur

Platform-Specific Adjustments

Platform	Duration	Aspect	Script Notes
App Store preview	15-30s	9:16 or 19.5:9	Hook in first 3s, no audio assumed
TikTok / Reels	15-60s	9:16	Fast cuts, text overlays, trending hooks
YouTube	60s-5min	16:9	Can be thorough, SEO-friendly intro
Product Hunt	30-60s	16:9	Focus on unique value, show key differentiator
Investor demo	2-5min	16:9	Problem-solution framing, market context
Onboarding	30-90s/feature	Device native	Patient, instructional, sequential

---

Integration with Other Skills

Skill	Use Case
app-demo-agent	Produce the actual video from these scripts
brand-research-agent	Match brand voice and tone
copywriter-agent	Write marketing copy to accompany the videos
voice-generation	Generate voiceover audio from the narration text
video-producer-agent	Full video production with music and effects
social-producer-agent	Create social media cuts from the walkthrough

---

Agents

Agent	File	Focus
Feature Analyzer	feature-analyzer.md	Breaks down app features and user flows
Script Writer	script-writer.md	Writes timed narration with screen directions
Hook Writer	hook-writer.md	Creates intros, transitions, and CTAs

---

Example Prompts

Full app walkthrough:

"Write walkthrough scripts for all the features in my fishing app"

Specific features:

"Generate walkthrough scripts for the tournament and logbook features"

From screenshots:

"Here are screenshots of each screen — write a walkthrough video script for this flow"

Marketing style:

"Write a marketing-style walkthrough script for our App Store preview video"

With handoff:

"Write walkthrough scripts for my app, then use app-demo-agent to produce the videos"