---
name: vtt-to-markdown
description: Convert VTT transcript files to clean, filtered Markdown format - processes files directly without requiring command-line knowledge
---

# VTT to Markdown Converter

This skill converts VTT (WebVTT) transcript files into clean, filtered Markdown documents suitable for study and reference.

## What This Does

1. **Parses VTT files** - Extracts speaker names and content from transcript files
2. **Filters content** - Removes administrative remarks, fillers, and extraneous content
3. **Sorts chronologically** - Orders sessions by date
4. **Generates Markdown** - Creates clean, readable output without timestamps

## When to Use

Use this skill when the user:
- Provides VTT transcript file(s)
- Mentions converting transcripts to Markdown
- Wants to clean up Zoom/video transcripts
- Asks to process lecture recordings

## How to Use

**IMMEDIATELY upon skill invocation:**

1. Ask the user for the VTT file path(s) or directory using AskUserQuestion
2. Ask for the desired output filename (suggest a sensible default)
3. Ask for an optional document title

**Then execute the workflow:**

1. Use Glob to find all VTT files in the provided path(s)
2. Parse each VTT file
3. Filter extraneous content
4. Generate chronologically-sorted Markdown
5. Write the output file
6. Report statistics (entries parsed, filtered, file size)

## VTT Parsing Logic

VTT files have this structure:
```
WEBVTT

1
00:00:01.430 --> 00:00:03.659
Speaker Name: Content goes here

2
00:00:03.860 --> 00:00:11.399
Speaker Name: More content
```

Parse by:
1. Reading line by line
2. Skip "WEBVTT" header and empty lines
3. Look for entry numbers (digits)
4. Next line is timestamp (HH:MM:SS.mmm --> HH:MM:SS.mmm)
5. Following lines until empty line are content
6. Split content on first colon to get "Speaker: Content"

## Filtering Rules

**Remove these (extraneous content):**

- Very short utterances (< 3 characters)
- Single-word fillers: yes, no, okay, um, uh, hmm, well, alright, great, cool, excellent, perfect
- Attendance codes and administrative remarks
- Office hours/scheduling mentions (unless substantive)
- Technical/Zoom issues
- Greetings without substance (just "good morning", "hello")
- Navigation/computer interaction ("scroll down", "click here")
- Incomplete fragments ending in … (if < 30 chars)
- Questions about student location ("where are you", "are you here")

**Keep these (substantive content):**

- Entries containing legal terms: commerce clause, tenth amendment, constitution, supreme court, congress, federal, state, statute, case, holding
- Case names: wickard, filburn, darby, lopez, morrison, gonzalez, reich, perez, heart of atlanta, mcculloch
- Legal concepts: necessary and proper, enumerated powers, interstate commerce, aggregation, substantial effect, economic activity
- Policy topics: obamacare, affordable care act, medicaid, individual mandate, taxing power
- Longer explanatory content (> 100 characters)
- Substantive questions (> 40 characters, not about location/attendance)

## Date Extraction

For Zoom filenames like `GMT20260128-162725_Recording.transcript.vtt`:
- Extract YYYYMMDD from filename
- Convert to readable format: "January 28, 2026"
- Use for section headers

## Markdown Output Format

```markdown
# [Document Title]
*Extracted from Zoom class recordings*
---

## Session: [Date]
*Source: [filename.vtt]*

**Speaker Name**: Content here.

**Speaker Name**: More content here.

---

## Session: [Next Date]
*Source: [next-file.vtt]*

**Speaker Name**: Content continues.
```

## Implementation Steps

1. **Gather input** (use AskUserQuestion with options):
   - VTT file path(s) or directory
   - Output filename (default: "transcript.md")
   - Document title (default: "Transcript")

2. **Find VTT files**:
   ```
   Use Glob to find *.vtt files
   If user provided directory, search directory
   If user provided files, use those directly
   ```

3. **Parse all VTT files**:
   - For each file, extract entries
   - Store: entry_number, start_time, end_time, speaker, content, source_file
   - Combine all entries into single list

4. **Filter entries**:
   - Apply filtering rules above
   - Track statistics (total vs. kept)

5. **Group and sort**:
   - Group entries by source_file
   - Sort groups by filename (chronological order)

6. **Generate Markdown**:
   - Create header
   - For each session (sorted):
     - Add session header with date
     - Add all entries as "**Speaker**: content"
   - NO timestamps in output

7. **Write and report**:
   - Use Write tool to save Markdown
   - Report to user:
     - Number of VTT files processed
     - Total entries parsed
     - Entries kept after filtering (with percentage)
     - Output file location and size

## Error Handling

- If no VTT files found, report error clearly
- If VTT file malformed, skip and report which file had issues
- If output file already exists, warn user (don't overwrite without confirmation)

## Success Criteria

A successful conversion includes:
- All VTT files parsed without errors
- 50-70% of content retained (typical for filtered transcripts)
- Chronologically ordered sessions
- Clean Markdown output with no timestamps
- Clear statistics reported to user

## Example Usage

User provides directory: `/Users/Seth/Downloads/transcripts/`
- Find 6 VTT files
- Parse 2,942 total entries
- Filter to 1,786 entries (60.7%)
- Generate chronologically sorted Markdown
- Report: "✓ Processed 6 files → transcript.md (321 KB, 1,786 entries)"