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:

bash
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:

markdown
# [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:

markdown
# [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"