video-to-article

What this skill does

# Video to Article Conversion Workflow

This skill automates the conversion of lecture/presentation videos into various text formats including transcripts, outlines, and article drafts.

## Workflow Overview

1. **Setup Folder** - Create properly named folder if needed
2. **Validate Input Metadata** - Check for README.md with required frontmatter
3. **Extract Audio** - Convert video to MP3 using ffmpeg
4. **Transcribe** - Generate text transcript using ElevenLabs API
5. **Process Text** - Create progressive text refinements

## Step 0: Folder Setup (if starting from scratch)

If user is starting a new talk/lecture conversion and no folder exists yet:

Create folder using format: `YYYY Title of Talk`

After creating folder, navigate into it and proceed with workflow.

## Step 1: Validate Metadata

Look for `README.md` in the current directory with these frontmatter fields:

- `title` - Lecture/presentation title
- `speaker` - Speaker name
- `date` - Presentation date (YYYY-MM-DD)
- `lang` - Presentation language (e.g., "english", "czech", "spanish")
- `abstract` - Brief description
- `slides` - Link to slides (or file path)
- `video` - Optional: link to video

### If README.md is Missing or Incomplete

Use the AskUserQuestion tool to collect missing information:

```
- What is the lecture title?
- Who is the speaker?
- What date was this presented?
- What language is the presentation in?
- Brief description or abstract?
- Link to slides or presentation file?
```

Create or update README.md with collected information.

## Step 2: Find or Download Video File

### Check for Local Video

Look for video file in current directory:

- Common patterns: `*.mp4`, `*.mov`, `*.avi`, `*.mkv`
- If multiple found, ask user which to process

### If No Local Video Found

Ask user if they have a YouTube URL using AskUserQuestion tool:

- "Do you have a YouTube URL for this talk?"
- If yes, collect the YouTube URL
- If no, ask for local video file path

### Download from YouTube (if URL provided)

```bash
bash ${CLAUDE_SKILL_DIR}/scripts/download-youtube.sh <youtube-url>
```

This downloads the video as `video.mp4` in medium quality (720p max).

**Requirements**: User needs yt-dlp installed. If missing, show:

```
Install yt-dlp:
- pip install yt-dlp
- brew install yt-dlp (macOS)
- sudo apt install yt-dlp (Ubuntu/Debian)
```

## Step 3: Extract Audio

Check if `audio.mp3` already exists. If not:

Run the extract-audio.sh script using the plugin root variable:

```bash
bash ${CLAUDE_SKILL_DIR}/scripts/extract-audio.sh <video-file>
```

This creates `audio.mp3` in the current directory.

## Step 4: Transcribe Audio

Check if `generated-transcript.txt` already exists. If not:

### Map Language to ISO Code

Convert the `lang` field from README.md to the appropriate ISO 639-1 language code for ElevenLabs API. Use your knowledge of language codes to map language names to their two-letter codes (e.g., "english" → "en", "czech" → "cs", "spanish" → "es").

### Run Transcription

```bash
bash ${CLAUDE_SKILL_DIR}/scripts/transcribe-audio.sh <language-code>
```

## Step 5: Generate Text Outputs

### Execution Protocol

Before generating content, complete these steps in order:

1. **List all required outputs** - Read and acknowledge the complete list below
2. **Check which files already exist** - Use file existence checks for each output
3. **Read all existing source files** - Load transcript, outline, key-ideas as context
4. **Confirm which outputs need generation** - Explicitly state which files are missing
5. **Only then begin generation** - Generate missing files one by one

### Required Outputs

Generate all of these files:

1. `generated-transcript-cleaned.md` - Cleaned transcript
2. `generated-transcript-readable.md` - Readable transcript
3. `generated-transcript-outline.md` - Content outline
4. `generated-key-ideas.md` - Key takeaways
5. `generated-article-formal.md` - Explanatory blog post (long-form, narrative)
6. `generated-article-direct.md` - Scannable technical brief (concise, bullets)

**Note:** Outputs 5 and 6 are two different article variants with distinct styles and audiences. Generate both.

**Workflow:**

- Check file existence for all files above
- Automatically generate any missing files without asking user
- Skip files that already exist (inform user which were skipped)
- Don't declare completion unless all files exist
- Don't ask user if they want to generate missing files - just generate them
- Generate both article variants (formal and direct) - they serve different purposes

### Idempotent Generation Strategy

This process is idempotent - running the skill multiple times will only generate missing files, never overwrite existing ones:

1. **Check each output file before generating** - Use file existence checks
2. **Skip files that already exist** - Inform user which files are being skipped
3. **Generate only missing files** - Don't overwrite existing content
4. **Use existing files as context** - When generating later outputs (like key-ideas), read all available previous outputs for context

Example: If only `generated-key-ideas.md` is missing:

- Read existing: `generated-transcript-cleaned.md`, `generated-transcript-readable.md`, `generated-transcript-outline.md`
- Generate: `generated-key-ideas.md` using the existing files as context
- Skip: All other outputs

This allows users to:

- Resume interrupted workflows
- Generate only specific missing outputs
- Re-run safely without data loss

### Output 1: Cleaned Transcript

**File:** `generated-transcript-cleaned.md`
**Input:** `generated-transcript.txt`
**Check:** Skip if file exists

Convert the transcript into a more readable form by dividing it into paragraphs and adding headings.

**Instructions:**

- Do not change the content, except for obvious typos
- Do not change the tone of voice - if the speaker uses informal language, keep it
- Remove filler words like "Eh", "Ehm", "Um", "Uh"
- Remove comments related to the transcription itself, or rewrite them elegantly if possible (e.g., "(laughter)" or "(2 second pause)")
- Respond in {lang} language - maintain the same language as the original transcript

The cleaned transcript should preserve the speaker's authentic voice while being easier to read and follow.

### Output 2: Readable Transcript

**File:** `generated-transcript-readable.md`
**Inputs:** `generated-transcript.txt` and `generated-transcript-cleaned.md`
**Check:** Skip if file exists

You have two inputs:

1. The first text contains the direct transcript of a lecture
2. The second text contains a better structured version of this transcript

The slides are available here: {slides}

Create a more readable text from this transcript:

**Instructions:**

- Preserve the style, but optimize for reading comprehension
- Fix typos, repetitions, and improve stylistic clarity
- Shorten where it doesn't affect the message
- Make it flow naturally for readers while keeping the speaker's voice
- Respond in {lang} language - the output must be in the same language as the input

The goal is to make the content accessible to readers while maintaining the essence of the spoken presentation.

### Output 3: Outline

**File:** `generated-transcript-outline.md`
**Inputs:** Cleaned and readable transcripts
**Check:** Skip if file exists

From the provided transcript inputs, create an outline of what was discussed.

**Instructions:**

- List the main ideas and messages with very brief content
- Use bullet points for clarity
- Focus on key takeaways and core concepts
- Keep descriptions concise - just enough to understand the point
- Respond in {lang} language - the outline must be in the same language as the source material

This outline should serve as a quick reference guide to the presentation's structure and main points.

### Output 4: Key Ideas

**File:** `generated-key-ideas.md`
**Inputs:** Cleaned and readable transcripts (or all available generated files if running incrementally)
**Check:** Skip if file