Transcript to Tutorial

What this skill does

Reads a YouTube or podcast transcript (SRT, VTT, or plain text with timestamps) and produces a stepped, written tutorial. Each step that names a command, file path, or URL is rendered with a fenced code block and a back-reference to the timestamp.

Inputs

• transcript_path: SRT, VTT, or plain .txt with timestamps.
• topic: the tutorial subject (e.g., "Set up a Postgres replica with pgBouncer").
• Optional video_url: used to render ?t=Xs deep links per step.

Steps

1. Detect format by extension; parse with a small reader: SRT/VTT have numbered cues with HH:MM:SS,mmm --> HH:MM:SS,mmm.
2. Concatenate cues into paragraphs at speaker pauses (gap > 1.5s) to recover natural sentences.
3. Identify "step boundaries": sentences that contain action verbs at the start (Run, Open, Install, Type, Edit, Save) or a transition cue ("next", "then", "now").
4. For each candidate step, extract the command or path mentioned. Patterns: a token starting with /, ~, ./, or matching <verb> '<command>'. Quote-strip and lowercase.
5. If the speaker dictated a command verbally ("git push origin main"), reconstruct as a fenced bash block.
6. Number steps sequentially. Title each with the leading verb phrase (max 10 words).
7. Insert a [<HH:MM:SS>](<video_url>?t=<seconds>) back-link at the end of each step.
8. Add a Prerequisites section at the top: scrape any "you'll need" sentences from the first 10% of the transcript.
9. Add a Troubleshooting section at the end: collect any sentences containing "if you see", "common error", "won't work".
10. Save to tutorials/<slug>.md where slug is derived from topic.

Output

tutorials/<slug>.md with: H1 (topic), Prerequisites bullet list, numbered steps with code blocks and timestamp anchors, Troubleshooting bullet list. Stdout reports step count and unmatched verb-cue lines.

Verification

Re-read the markdown and confirm every fenced code block is preceded by a verbal description in the step body. Spot-check three timestamp links by computing seconds from HH:MM:SS and confirming the math. If more than 30% of paragraphs produced no step boundaries, the transcript may be a discussion rather than a how-to — surface a warning rather than emit a hollow tutorial.

Edge cases

• Transcript with no timestamps: omit deep links and warn in the report header.
• Speaker uses placeholder values ("your-api-key"): preserve as-is in the code block; do not substitute.
• Multi-speaker transcript (e.g., interview): pick the speaker doing the demonstration; ignore the interviewer's questions for step extraction.
• Auto-generated transcript with garbled words: keep the step structure but mark suspect lines with "(verify spelling)".