/yt-to-course

name: yt-to-course
description: >
  Turn a YouTube video into a structured Circle course package: decides full course vs section addition (against course_structure.md), cuts sentence-aligned lessons via video-cutter, writes lesson content in Ben's voice, and outputs clips, lesson.md, description.txt, README, and manifest. STEP 2 of the YouTube pipeline: yt-to-community always runs first; invoke only after the community post is saved and the user confirms course material. TRIGGERS: "yes, course it", "turn this into a course", "yt to course", "video to course", "create lessons from this video", "add this to a course". NOT for community announcement posts (use yt-to-community).

YouTube to Course Material

Turn YouTube videos into structured, ready-to-upload course content for the BenAI Accelerator community on Circle. Two output types: a full new course (long-form, multi-section videos) or new lessons added to an existing course (shorter, topic-specific videos).

Pipeline Position

This skill is **step 2 of 2** in the YouTube repurposing pipeline.

1. `yt-to-community`: community post + thumbnail. Always runs first. 2. `yt-to-course` (this skill): course material. Runs only after the post is done and the user has confirmed.

If a YouTube URL lands in chat and the community post hasn't been created yet, do not start here. Hand back to `yt-to-community`. The pipeline order is fixed: post first, course second.

Why This Exists

Community members are professionals running businesses. They don't have time to watch hour-long YouTube videos end-to-end. So we cut videos into focused lessons, write lesson copy around each clip, and structure it as a self-paced course in Circle. This skill automates ingestion, section planning, lesson writing, and cutting. The only manual step is uploading the clips into Circle's course builder (the Circle API doesn't expose course-lesson CRUD).

Profile boundary

All output writes to `Profiles/Milan/`. Course packages land in `Profiles/Milan/Community/course-packages/{date}-{slug}/`. See [[yt-pipeline SPEC|SPEC.md]] for the full invariant.

The Flow

Step 1: Ingestion

**If invoked from `yt-to-community` (the normal pipeline path):** the community post step has already run `yt-ingestion-agent` and you've been passed an ingestion manifest. Reuse it. Do not re-run ingestion. it wastes minutes and re-downloads gigabytes. Only the video file and word-level timestamps may need a top-up if the community post run skipped them (community-only runs sometimes do).

**If invoked standalone (user explicitly asked for course material on a video that already has a post, or skipped the post intentionally):** invoke the `yt-ingestion-agent` sub-agent with the YouTube URL and target output directory. The agent handles:

• Download (yt-dlp fallback chain for SABR/PO-token blocks)
• Transcript (3-method priority: MCP, youtube-transcript-api, user-provided)
• Word-level timestamps (faster-whisper)
• Thumbnail
• Metadata

If the agent surfaces a download-blocked choice (e.g., 1080p unavailable), present the three options to the user (accept lower res, manual provide from YouTube Studio, cut-sheet-only mode) and pass the user's selection back to the agent.

When ingestion completes, you have a manifest pointing at the artifacts.

Step 2: Determine Output Type

Read `[[course_structure]]` (reference file in this skill folder). It maps every active course in the community, what topics it covers, and what sections/lessons already exist.

Decide based on two factors:

**Full new course** if:

• Video is 45+ minutes long
• Covers a broad topic from beginning to end
• Doesn't overlap significantly with any existing course's topic
• Has enough natural sections to justify a multi-lesson structure (4+ sections)

**New lessons in existing course** if:

• Video is shorter (under 45 minutes, though length alone isn't decisive)
• Topic directly extends or complements an existing course
• Would fit naturally as new lessons within an existing course's structure

Present your recommendation with reasoning. Wait for the user to confirm before proceeding.

Step 3: Plan the Sections

Analyze the transcript and break it into logical sections. Each section should:

• Cover one distinct concept or skill
• Be 3 to 10 minutes long (sweet spot for focused learning)
• Have a clear beginning and end in the transcript
• Flow naturally from the previous section

For each section, determine:

• Section title (clear, specific, no fluff)
• Approximate start timestamp
• Approximate end timestamp
• Core concept (the one thing the viewer learns)
• Key takeaway (what they can do after watching)

Present the section plan as a table. The user might adjust sections, merge some, or split others. Iterate until confirmed. This is the editorial gate between ingestion and cutting.

Step 4: Write Lesson Content (draft + humanizer pass per lesson)

For each section, you go through three substeps in order before moving to the next section. Do **not** batch all drafts first and humanize at the end. The per-lesson loop is the contract.

**4a. Draft lesson.md.** Read these vault files for voice calibration once at the start of Step 4 (not per lesson):

• `Context/brand.md` (brand identity and public/marketing tone)
• `Context/ben-voice.md` (how Ben actually writes 1:1: answer-first, loose-not-polished, peer-to-peer warmth, banned corporate phrases)
• `Resources/frameworks/youtube-voice.md` (YouTube-specific voice)
• `Resources/frameworks/newsletter-structure.md` (structural patterns)
• `Resources/frameworks/newsletter-examples.md` (real examples of Ben's writing)

Structure per lesson:

## {Section Title}

{1 to 2 sentence teaser that makes you want to watch the clip. Direct, practical, slightly provocative. Not a summary. A hook.}

### What you'll learn
{2 to 3 bullet points. Specific outcomes, not vague promises. "How to connect your first MCP server" beats "Understanding MCP concepts."}