video/skills/pipelines/explainer/publish-director.md

Publish Director — Explainer Pipeline

When to Use

You are the Publisher for a generated explainer video. You have a render_report with the final video file. Your job is to prepare the video for distribution: generate SEO metadata, create thumbnails, package exports, and log the publish event.

This is where a great video reaches its audience. Without proper metadata and packaging, even the best content gets buried.

Prerequisites

Layer	Resource	Purpose
Schema	schemas/artifacts/publish_log.schema.json	Artifact validation
Prior artifacts	state.artifacts["compose"]["render_report"], state.artifacts["proposal"]["proposal_packet"], state.artifacts["research"]["research_brief"]	Video file and original proposal
Playbook	Active style playbook	Visual style for thumbnail

Process

Step 1: Gather Context

Collect everything needed for metadata:

• Proposal packet: title, hook, key points, target platform, tone
• Render report: output path, duration, resolution
• Script: section summaries for description/chapters

Step 2: Generate SEO Metadata

Title (max 60 characters for YouTube):

• Include the primary keyword from the proposal packet
• Lead with a hook or number
• Avoid clickbait but be compelling
• Examples: "Vector Databases Explained in 60 Seconds" > "About Vector Databases"

Description (first 150 chars are critical — shown in search):

• Opening line: restate the hook with the main value proposition
• Body: key topics covered, with relevant keywords naturally included
• Chapters: timestamp markers for each major section (from script sections)
• Call to action: subscribe/like/follow
• Links: relevant resources mentioned in the video

Tags/Keywords (platform-dependent):

• 5-10 specific tags derived from proposal packet's key_points
• Mix broad and specific: "machine learning" + "vector database tutorial"
• Include the topic, format ("explainer"), and related terms

Hashtags (for social platforms):

• 3-5 relevant hashtags
• Mix trending and niche

Step 3: Generate Thumbnail Concept

Describe a thumbnail that:

1. Uses the playbook's visual style
2. Features the video's core concept visually
3. Includes 3-5 words of text (the hook or key stat)
4. Has high contrast and is readable at small sizes
5. Uses the playbook's accent colors for text

{
  "thumbnail": {
    "concept": "Split screen: left side shows slow SQL query (red X), right shows fast vector search (green check). Large text: '100x FASTER'",
    "text_overlay": "100x FASTER",
    "style_notes": "Use playbook accent colors, bold Inter font, dark background"
  }
}

Note: Actual thumbnail generation happens via image_selector if available, otherwise it's a concept for manual creation.

Step 4: Create Chapter Markers

From the script sections, generate YouTube-style chapters:

0:00 - Introduction
0:15 - What are Vector Databases?
0:45 - How Embeddings Work
1:20 - The Search Algorithm
1:55 - Real-World Examples
2:30 - When to Use Vector DBs

Each chapter maps to a script section's start_seconds.

Step 5: Package Export

Create the export directory structure:

exports/
  <project_name>/
    video/
      output.mp4            # Final rendered video
    metadata/
      metadata.json         # All SEO metadata
      chapters.txt          # Chapter markers
      description.txt       # Ready-to-paste description
      tags.txt              # One tag per line
    thumbnails/
      concept.json          # Thumbnail concept (or generated image)

Step 6: Build Publish Log

{
  "version": "1.0",
  "entries": [
    {
      "platform": "youtube",
      "status": "draft",
      "timestamp": "2024-01-15T10:30:00Z",
      "metadata": {
        "title": "Vector Databases Explained in 60 Seconds",
        "description_length": 450,
        "tags_count": 8,
        "chapters_count": 6,
        "thumbnail_ready": false
      },
      "export_path": "exports/vector-db-explainer/",
      "video_path": "renders/output.mp4"
    }
  ]
}

Step 7: Self-Evaluate

Score (1-5):

Criterion	Question
SEO quality	Would this title and description rank well for the topic?
Description completeness	Does the description include chapters, CTA, and keywords?
Thumbnail concept	Would this thumbnail stand out in a feed?
Export package	Is everything a creator needs in the export directory?
Platform fit	Is metadata tailored to the target platform?

If any dimension scores below 3, revise.

Step 8: Submit

Validate the publish_log against the schema and persist via checkpoint.

Common Pitfalls

• Generic titles: "Video About X" loses to "X Explained in 60 Seconds" every time. Be specific and compelling.
• No chapters: YouTube rewards videos with chapters. Always include them.
• Description keyword stuffing: Write for humans first, search engines second. Natural language with keywords woven in.
• Forgetting the CTA: Every description should end with a call to action.
• Wrong platform format: YouTube descriptions differ from TikTok captions. Tailor to the target platform.