transcript-to-tutorial

name	transcript-to-tutorial
description	Use when converting video or audio transcripts into self-contained, actionable developer tutorials. Use when you have a raw transcript file and need a comprehensive written reference that readers can follow without watching the original video. Especially suited for AI workflows, developer tools, and technical content.
user-invocable	true
argument-hint	<transcript-file-path>

Transcript to Tutorial

Convert raw video/audio transcripts into comprehensive, self-contained developer tutorials.

Overview

Video tutorials lock knowledge in a format that can't be searched, copied, or version-controlled. This skill extracts that knowledge and repackages it as a written reference that works without the original video.

Core principle: A transcript is a starting point, never a source of truth. Every technical claim must be verified against current official documentation before inclusion.

Expansion factor: A 60-second video segment typically becomes 150-200 lines of written tutorial. Written formats require complete setup steps, full config contents, multiple examples, troubleshooting, and platform-specific notes that videos skip.

When to Use

• Converting a YouTube video transcript into a developer tutorial
• Turning conference talk notes into actionable documentation
• Transforming webinar/workshop recordings into step-by-step guides
• Creating written references from any technical video content

Best suited for: AI workflows, developer tools, framework tutorials, technical how-tos

When NOT to use:

• Content requiring visual demonstration (UI design, art)
• Opinion/discussion videos without actionable technical content
• Content already well-documented in official docs

Input

$ARGUMENTS should be the path to a transcript file containing:

• Raw transcript text (timestamped or plain)
• Video URL and metadata (title, description, channel) if available

If a structured summary from another LLM is available, provide it alongside the transcript for cross-referencing.

The 7-Phase Pipeline

digraph pipeline {
  rankdir=TB;
  node [shape=box];
  collect [label="1. Collect"];
  summarize [label="2. Structure"];
  verify [label="3. Fact-Check"];
  plan [label="4. Plan"];
  write [label="5. Write"];
  review [label="6. Review"];
  fix [label="7. Fix + Deliver"];
  collect -> summarize -> verify -> plan -> write -> review -> fix;
  review -> write [label="critical issues" style=dashed];
}

Phase 1: Collect Source Material

1. Read the transcript file at $ARGUMENTS
2. Identify the video's topic, structure, and scope
3. Extract metadata (title, channel, date if available)
4. Note the content format (see format table below)

Phase 2: Identify Structure and Topics

1. Parse the transcript into logical sections/topics
2. For each topic, note:
   • Name and one-sentence description
   • Key technical claims made
   • Tools, libraries, commands, or configs mentioned
3. Identify filler to exclude (subscribe prompts, sponsor segments, transitions)
4. Map the video format to a tutorial approach:

Video Format	Tutorial Approach
Numbered tips/tricks	One section per tip, consistent template
Single deep-dive	Progressive sections building on each other
Live coding/demo	Step-by-step recreation with complete code
Conference talk	Extract actionable insights, add implementation
Comparison/review	Decision matrix with setup for each option

Phase 3: Research and Fact-Check

This is the most critical phase. Videos are recorded at a point in time. Documentation evolves.

1. List every technical claim needing verification:

   • CLI commands and flags
   • Config file schemas and options
   • API names and parameters
   • Version requirements
   • Installation commands

2. Fetch official documentation for each tool/library/framework mentioned

3. Cross-reference video claims against current docs. Record discrepancies:

| Video Claim | Current Reality | Action |
|---|---|---|
| Use --old-flag | Replaced by --new-flag in v2.0 | Use current, note legacy |
| npm install old-pkg | Package renamed to new-pkg | Use current name |

4. Use parallel research agents when multiple doc sources need checking. Spawn one agent per documentation domain using the Task tool.

5. Fetch changelogs if available to understand version history

Phase 4: Plan the Tutorial

Enter plan mode or create a structured plan before writing.

1. Target audience: What prerequisites should readers have?
2. Section template: Every topic follows the same structure (see tutorial-template.md)
3. Shared prerequisites: Dependencies needed across multiple sections
4. Platform: Primary OS + cross-platform notes
5. Risks and mitigations:

Risk Type	Mitigation
Undocumented features	Describe observable behavior
Experimental APIs	Set expectations, list limitations
Outdated video info	Use current approach, note legacy
Platform differences	Explicit instructions per OS

Get user approval on the plan before writing.

Phase 5: Write the Tutorial

Write the complete tutorial as a single file in one pass.

Why one pass: Consistent terminology, formatting, and cross-references. Later sections reference earlier ones naturally.

For each topic:

• Translate conversational descriptions into precise technical instructions
• Add complete setup steps (videos assume viewers figure this out)
• Write config files with valid syntax -- every JSON/YAML block must parse
• Create 2-3 examples progressing from basic to advanced
• Add verification steps so readers confirm each section works
• Include platform-specific variants where needed
• Add tips and gotchas sourced from official docs

For supporting sections:

• Prerequisites: consolidate all dependencies
• Quick reference: one-row-per-topic cheat sheet
• Troubleshooting: 5-7 common issues with fixes
• Glossary: define technical terms introduced

See tutorial-template.md in this skill directory for the full template.

Phase 6: Automated Review

Deploy a reviewer agent (Task tool with a review-capable subagent) with this checklist:

1. Completeness: All topics present with all required sections
2. Consistency: Each topic follows the same section template
3. Code validity: All config snippets are syntactically valid
4. Command accuracy: All CLI commands use correct current syntax
5. Platform coverage: OS-specific notes present where needed
6. Navigation: Table of contents links resolve correctly
7. Quick reference: All topics represented in cheat sheet
8. Self-containedness: No unresolved external dependencies

Rate each category 1-10. Overall score should be 8+ before proceeding.

Phase 7: Fix and Deliver

1. Fix all critical and high issues from review
2. Make judgment calls on medium/low issues (consistency vs. clarity)
3. Present the completed tutorial to the user

Key Principles

1. Transcript is a starting point, never source of truth -- verify every claim against current official docs
2. Plan before writing -- structural decisions are expensive to change at 1,500+ lines
3. Parallelize research -- spawn multiple agents for independent documentation sources
4. Write in one pass -- consistency beats incremental assembly
5. Automated review catches what the writer misses -- always deploy a reviewer
6. Complete config over fragments -- beginners need full file structure, not just a snippet
7. Copy-pasteable code -- no pseudocode, no "fill in your values" placeholders
8. Platform awareness -- state the primary OS, note differences for others

Common Mistakes

Mistake	Fix
Trusting video claims without verification	Always fetch current official docs
Showing config fragments without context	Wrap in complete file structure
Single example per topic	2-3 examples, basic to advanced
Skipping verification steps	Every topic needs "how to confirm it works"
Writing section by section	One-pass writing maintains consistency
Ignoring platform differences	State primary OS, note variants
No troubleshooting section	Add 5-7 common issues with fixes
Skipping the review phase	Always deploy an automated reviewer
Including filler from transcript	Strip subscribe prompts, transitions, sponsors
Not checking changelogs	Version history reveals renamed flags, breaking changes

Quality Checklist

Before delivering the tutorial:

• All topics from transcript are covered
• Each topic has: Setup, How to invoke, Examples (2-3), Verify, Tips
• All JSON/YAML config blocks parse correctly
• All CLI commands verified against current official docs
• Prerequisites section consolidates all dependencies
• Quick reference cheat sheet covers every topic
• Troubleshooting section addresses likely failure points
• Glossary defines all introduced technical terms
• Platform-specific notes where relevant
• No external resource dependencies for understanding content
• Table of contents anchor links resolve correctly