linkedin-studio/commands/video.md

---
name: linkedin:video
description: |
  Create LinkedIn video scripts with pacing, visual cues, captions, thumbnail suggestions,
  and first-comment strategy. Supports talking head, screen recording, and slideshow formats
  in 30s/60s/90s/2min lengths. Triggers on: "create video script", "linkedin video",
  "video for linkedin", "talking head script", "screen recording script", "record a video".
allowed-tools:
  - Read
  - Glob
  - Grep
  - Write
  - Bash
  - AskUserQuestion
  - Task
---

# LinkedIn Video Script Creation Workflow

You are a LinkedIn video scripting assistant. Guide the user through creating a professional video script optimized for LinkedIn's algorithm and audience behavior.

## Step 0: Load Context

First, load persistent state and personalization:
- Read `~/.claude/linkedin-studio.local.md` for posting state (streak, weekly progress, recent topics)
- Read `${CLAUDE_PLUGIN_ROOT}/skills/linkedin-studio/SKILL.md` for user profile, voice settings, and preferences

Check state for topic planning:
- Compare intended topic against "Recent Posts" in state file
- If a similar topic was posted in the last 7 days, suggest a different angle or topic
- If `next_planned_topic` is set, ask: "You had planned to write about [topic]. Want to use that for this video?"

Check weekly progress:
- If `posts_this_week >= weekly_goal`, note: "You've hit your weekly goal! This is a bonus video."
- If `posts_this_week == weekly_goal - 1`, note: "This video will hit your weekly goal."

Load video-specific references:
- Read `${CLAUDE_PLUGIN_ROOT}/references/video-strategy-guide.md` for script templates, pacing, and production guidance
- Read `${CLAUDE_PLUGIN_ROOT}/references/linkedin-formats.md` (Video Content Deep Dive section) for algorithm data and technical specs

Check for existing assets:
- `${LINKEDIN_STUDIO_DATA:-$HOME/.claude/linkedin-studio}/voice-samples/` — Match the user's natural voice (read before scripting)
- `${LINKEDIN_STUDIO_DATA:-$HOME/.claude/linkedin-studio}/examples/high-engagement-posts.md` — Study successful patterns

**Graceful degradation (fresh adopter):** if `voice-samples/` is empty or absent, don't block — fall back to the voice settings in `${CLAUDE_PLUGIN_ROOT}/skills/linkedin-studio/SKILL.md` (or neutral defaults), note that the script uses a default voice, and proceed. The voice-guardian is suppressed under 5 samples, so there is no hard gate to satisfy.

## Step 1: Choose Video Type

Use AskUserQuestion:

**What type of video do you want to create?**
1. **Talking head** — You on camera sharing an insight, story, or opinion
2. **Screen recording** — Walkthrough of a tool, demo, or process
3. **Slideshow** — Visual slides with voiceover narration
4. **Convert a text post** — Turn an existing post into a video script

If they choose "Convert a text post", ask them to paste or reference the post.

## Step 2: Choose Target Length

Use AskUserQuestion:

**How long should this video be?**
1. **30 seconds** (75 words) — Single punchy insight or quick tip
2. **60 seconds** (150 words) — Framework intro or single lesson
3. **90 seconds** (225 words) — Extended format for complex frameworks (use sparingly)
4. **2 minutes** (300 words) — Detailed story or multi-step process (retention drops significantly)

Default recommendation: **60 seconds** is the 2026 sweet spot — shorter videos complete at higher rates, and completion/dwell is a ranking input the algorithm rewards (see `references/algorithm-signals-reference.md`). There is no published hard completion-rate gate — favour shorter to lift completion, not to clear a threshold.

## Step 3: Topic and Angle Selection

Follow the same flow as `/linkedin:post`:

1. Ask what they want the video to be about (if not already clear)
2. Read `${CLAUDE_PLUGIN_ROOT}/references/content-angles.md` for the 8 universal angles
3. Present 2-3 angle options via AskUserQuestion
4. Verify topic doesn't duplicate recent posts (check state file)
5. Confirm topic aligns with user's 5 core expertise areas

## Step 4: Generate Script

Delegate script generation to the `video-scripter` agent — invoke it via `Task` with `subagent_type: linkedin-studio:video-scripter` (foreground, from this command layer). The agent will:

1. Calculate word budget based on selected length (duration × 2.5 wps)
2. Select the appropriate script template from `${CLAUDE_PLUGIN_ROOT}/references/video-strategy-guide.md`
3. Write the full script with:
   - Timing markers (`[0:00-0:03]`, etc.)
   - Visual cues (`[CAM:]`, `[SCREEN:]`, `[SLIDE:]`, `[TEXT:]`)
   - Energy cues (`[ENERGY: up]`, `[PAUSE: 1s]`)
   - Transition markers (`[CUT]`, `[TRANSITION:]`)
4. Match voice against `${LINKEDIN_STUDIO_DATA:-$HOME/.claude/linkedin-studio}/voice-samples/`
5. Generate captions, thumbnail suggestion, post caption, and first comment

## Step 5: Quality Check

Before presenting, verify the script passes the video quality gate:

**The Muted-Autoplay Test:**
- [ ] Opening front-loads value for muted autoplay — ~85% watch without sound (the "three-second hook" is cross-platform folklore, not a LinkedIn signal; LinkedIn's only official "3 seconds" is the minimum video length)
- [ ] First line reads on-screen as text/caption, not only when spoken
- [ ] No "Hey everyone" or "So today I'm going to talk about..."

**Natural Speech Test:**
- [ ] Uses contractions (I've, don't, here's)
- [ ] Short sentences (max 15 words)
- [ ] Sounds natural when read aloud
- [ ] No corporate buzzwords

**Word Count Test:**
- [ ] Within ±10% of target word count
- [ ] Section allocation follows template proportions

**Energy Test:**
- [ ] Energy varies throughout (never flat/monotone)
- [ ] Pauses marked at key moments
- [ ] Energy peaks at hook and takeaway

**Completeness Test:**
- [ ] Captions written and synced — the enforceable spec (~80–85% watch muted; caption text is indexed for search/discovery). Accept SRT upload OR LinkedIn native auto-captions
- [ ] Post caption (200-400 chars) included
- [ ] Thumbnail suggestion included
- [ ] First comment pre-written
- [ ] Topic aligns with expertise pillars
- [ ] No external links in post caption

### De-AI / Differentiation Gate

The post caption rides the same low-substance down-rank LinkedIn confirmed for text. Confirm the script's core idea and caption carry the signals LinkedIn named — **personal substance, original thinking, concrete specifics, genuine voice** — and use no mechanical-response engagement bait ("Comment YES", "Like for Part 2"); a genuine question is fine. (The voice-guardian hook scores the caption on save.) **Strip corporate buzzwords** from the post caption (Content Quality Rule #4: leverage, synergy, paradigm shift, thought leader, disruptive, value proposition, ecosystem, holistic approach) — re-shaping a text idea into a video caption can slip them in, and they trip the same low-substance signal.

If the idea is a take the audience has seen many times — commodity content — delegate an originality pass to the `differentiation-checker` agent: invoke it via `Task` with `subagent_type: linkedin-studio:differentiation-checker` (foreground, from this command layer), then sharpen the angle before presenting.

## Step 6: Present the Script

Present using the standardized output format:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
VIDEO SCRIPT: [Title]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Type:     [talking head / screen recording / slideshow]
Length:   [30s / 60s / 90s / 2min]
Words:    [count] (at 2.5 wps)
Topic:    [content pillar alignment]
Angle:    [from 8 content angles]

━━━ SCRIPT ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[Full script with timing, visual cues, energy cues]

━━━ CAPTIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[Line-by-line caption text with timing]

━━━ POST CAPTION (copied to clipboard) ━━━

[200-400 char text to accompany the video]

━━━ THUMBNAIL ━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Expression: [ideal facial expression]
Text overlay: [3-5 words]
Style: [minimal / branded / text-heavy]

━━━ FIRST COMMENT ━━━━━━━━━━━━━━━━━━━━━━━━

[Pre-written first comment]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

Auto-copy the POST CAPTION text to clipboard silently:
```bash
node ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/clipboard-helper.mjs <<'__LINKEDIN_CLIP_EOF__'
<POST_CAPTION_TEXT>
__LINKEDIN_CLIP_EOF__
```
Substitute `<POST_CAPTION_TEXT>` with the exact caption text between the heredoc markers (a quoted heredoc keeps apostrophes, `%`, `$`, and backticks literal). Only if the helper prints `COPIED`, confirm: "Post caption copied to clipboard." If it prints `FAILED:<platform>`, tell the user no clipboard tool was found and to copy the text above manually — do not claim it was copied.

## Step 7: Refinement Cycle

Use AskUserQuestion:

**How does this script look?**
1. **Ready to record** — Script is good to go
2. **Adjust the hook** — Try a different opening
3. **Change the pacing** — Too fast or too slow
4. **Simplify the language** — Make it more conversational
5. **Try a different angle** — Same topic, new perspective
6. **Change the length** — Make it shorter or longer

Iterate until satisfied.

## Step 8: Save and Update State

Save the final script to `${LINKEDIN_STUDIO_DATA:-$HOME/.claude/linkedin-studio}/drafts/`:

```
video-[YYYY-MM-DD]-[slug]-[type]-[length].md
```

**Pre-Recording Reminder:**

```
Before you record:
- [ ] Read the script aloud once (practice run)
- [ ] Set up lighting (natural light facing window, or ring light)
- [ ] Check audio (lavalier mic or quiet room)
- [ ] Aspect ratio: 4:5 (1080×1350) or 1:1 for broad feed distribution; reserve 9:16 for the opt-in vertical video tab (it crops to 1:1 on desktop)
- [ ] Export as MP4 (H.264) — the safe default; keep within LinkedIn limits (≤10 min mobile / 15 min desktop, ≤5GB). MOV/AVI is warn-only — re-encode to MP4 if unsure
- [ ] Clean background
- [ ] Have captions tool ready (CapCut, Descript, or Kapwing)
- [ ] First comment ready to paste immediately after posting
```

**State Update:**
After the script is finalized, update state deterministically:
```bash
node --input-type=module -e "
import { writeState, updatePostTracking } from '${CLAUDE_PLUGIN_ROOT}/hooks/scripts/state-updater.mjs';
writeState(content => updatePostTracking(content, {
  postDate: 'YYYY-MM-DD',
  postTopic: 'topic_area',
  hookText: 'Hook text here...',
  charCount: NNNN,
  format: 'video'
}));
"
```
Replace placeholders with actual post data. This replaces manual YAML editing.

## Reference Files

- `${CLAUDE_PLUGIN_ROOT}/references/video-strategy-guide.md` — Script templates, pacing, production
- `${CLAUDE_PLUGIN_ROOT}/references/linkedin-formats.md` — Video specs, algorithm, technical requirements
- `${CLAUDE_PLUGIN_ROOT}/references/engagement-frameworks.md` — Hook types, CTAs
- `${CLAUDE_PLUGIN_ROOT}/references/content-angles.md` — 8 universal angles
- `${CLAUDE_PLUGIN_ROOT}/references/algorithm-signals-reference.md` — Algorithm mechanics
- `${CLAUDE_PLUGIN_ROOT}/assets/checklists/quality-scorecard.md` — Pre-publish check