YouTube Tutorial Creation Skill

Artifact Directory Convention

All durable outputs go under:

<resolved_artifacts_root>/youtube-tutorial-creation/{YYYY-MM-DD}/{video-slug}__{HHMMSS}/

⚠️ Path hygiene: Never put a literal UA_ARTIFACTS_DIR in a path.
BAD: UA_ARTIFACTS_DIR/... or /opt/universal_agent/UA_ARTIFACTS_DIR/...
GOOD: Resolve the root first (Step 2 below), then append youtube-tutorial-creation/...

Workflow

Step 1 — Confirm inputs

• If no URL provided, ask for one.
• Ask for the goal: concept-only vs concept + implementation.
• Ask for target language/framework if the video is ambiguous about it.

Step 2 — Preflight: resolve artifacts root (MANDATORY)

Never rely on Bash inheriting env vars. Resolve the artifacts root explicitly:

python3 -c "from universal_agent.artifacts import resolve_artifacts_dir; print(resolve_artifacts_dir())"

If this fails, STOP and report the error. Do not fall back to writing only under transient scratch.

Then:

• Compute video-slug from the video title (preferred) or URL video ID.
• Create the run directory under the resolved artifacts root.
• Start manifest.json immediately — fill fields as you go.

Tool preference: Use write_text_file for all writes into UA_ARTIFACTS_DIR. Native Write may be restricted to the session workspace depending on runtime.

Step 3 — Transcript + metadata ingestion (MANDATORY)

Run the core ingestion script with parallel transcript + metadata extraction:

UV_CACHE_DIR=/tmp/uv_cache uv run .claude/skills/youtube-transcript-metadata/scripts/fetch_youtube_transcript_metadata.py \
  --url "<YOUTUBE_URL>" \
  --language en \
  --json-out "$CURRENT_RUN_WORKSPACE/downloads/youtube_ingest.json" \
  --transcript-out "$CURRENT_RUN_WORKSPACE/downloads/transcript.txt" \
  --pretty

CURRENT_RUN_WORKSPACE is the canonical workspace variable. CURRENT_SESSION_WORKSPACE may still be present as a legacy alias during migration, but new examples should prefer the run workspace name.

Read youtube_ingest.json and look at ok, failure_class, transcript_text, and metadata.

Degraded-mode decision tree:

Source-of-truth policy:

• Transcript: YouTubeTranscriptApi().fetch(video_id) — never get_transcript() (legacy)
• Metadata: yt-dlp only — never use yt-dlp for transcript text

Step 3b — Transcript cleanup (recommended)

Caption transcripts often contain consecutive duplicate lines. Deduplicate:

python3 - <<'PY'
import os
from pathlib import Path

ws = Path(
    os.environ.get("CURRENT_RUN_WORKSPACE")
    or os.environ["CURRENT_SESSION_WORKSPACE"]
)
src = ws / "downloads" / "transcript.txt"
dst = ws / "downloads" / "transcript.clean.txt"

lines = src.read_text(encoding="utf-8", errors="replace").splitlines()
out, prev = [], None
for line in lines:
    if line != prev:
        out.append(line)
    prev = line

dst.write_text("\n".join(out).strip() + "\n", encoding="utf-8")
print(f"Wrote {dst} ({len(out)} lines, from {len(lines)} original)")
PY

Step 3c — Full-transcript pass (MANDATORY)

Do a full-file read of the cleaned transcript to avoid "cut-off" issues from partial previews, and produce a stats snapshot for the manifest:

python3 - <<'PY'
import json, os
from pathlib import Path

ws = Path(
    os.environ.get("CURRENT_RUN_WORKSPACE")
    or os.environ["CURRENT_SESSION_WORKSPACE"]
)
src = ws / "downloads" / "transcript.clean.txt"
dst = ws / "downloads" / "transcript.stats.json"

text = src.read_text(encoding="utf-8", errors="replace")
lines = text.splitlines()
stats = {
    "path": str(src),
    "bytes": len(text.encode("utf-8", errors="replace")),
    "chars": len(text),
    "lines": len(lines),
    "head": lines[:5],
    "tail": lines[-5:],
}
dst.write_text(json.dumps(stats, indent=2), encoding="utf-8")
print(f"Wrote {dst} ({stats['lines']} lines, {stats['chars']} chars)")
PY

Step 3d — Metadata handoff (MANDATORY)

Carry key fields from youtube_ingest.json into:

• manifest.json: title, channel, duration, upload_date, metadata_status, metadata_source
• README.md: context block at the top (URL, title, channel, duration, upload date)

Step 4 — Visual analysis (best-effort)

Attempt Gemini multimodal analysis against the YouTube URL:

UV_CACHE_DIR=/tmp/uv_cache uv run .claude/skills/youtube-tutorial-creation/scripts/gemini_video_analysis.py \
  --url "<YOUTUBE_URL>" \
  --out "<run_dir>/visuals/gemini_video_analysis.md" \
  --json-out "<run_dir>/visuals/gemini_video_analysis.json"

If the script fails (no API key, model unavailable, rate limited), do not skip the whole skill. Set extraction.visual = "attempted_failed" in the manifest and continue with transcript only.

Do NOT skip visual analysis just because you assume the transcript is sufficient. Attempt it, record the result, and proceed.

Self-test (verifies imports only, no API call):

UV_CACHE_DIR=/tmp/uv_cache uv run .claude/skills/youtube-tutorial-creation/scripts/gemini_video_analysis.py --self-test

Step 5 — Synthesis

Merge "what they said" (transcript) with "what they showed" (visual findings):

• Identify gaps and ambiguities in the content
• Do supplementary research when needed (prefer official docs, then reputable sources)
• Record all gap-filling sources in research/sources.md with URLs and access dates

Step 6 — Write durable artifacts

Write each artifact to the run directory. Quality bar for each:

README.md

• Video title, channel, URL, duration, upload date (from metadata)
• 2–3 sentence summary of what the video covers
• Links to CONCEPT.md and IMPLEMENTATION.md
• Markdown Formatting: Ensure a highly readable, premium layout. Use clear headings, ample spacing, bullet points, and a clean visual hierarchy so it is easy on the eyes when rendered in the UI. Specify visually calm typography elements where possible.

CONCEPT.md — standalone tutorial, no video required

• Introduction explaining why this technology/approach exists
• Core concepts with enough depth to understand the implementation
• Diagrams or references to visuals/ when available
• Code snippets with provenance comments linking to source timestamps or visuals/code-extractions/
• Must be readable by someone who has never seen the video
• Markdown Formatting: Format beautifully for the UI panel. Provide breathing room (blank lines between blocks), use blockquotes for key takeaways, well-structured headers, and a calm, readable typographic flow.

IMPLEMENTATION.md — practical runbook (or procedural guide for concept-only)

• Prerequisites (exact versions where known)
• Step-by-step instructions with expected outputs at each step
• Troubleshooting section for likely failure modes
• References to implementation/ scripts

implementation/ — runnable code (only when learning_mode=concept_plus_implementation)

• Use uv inline scripting (PEP 723) for all Python scripts (see Step 8)
• Add comments with provenance (timestamp reference or visual extraction source)
• Store raw OCR code extractions with confidence headers in visuals/code-extractions/

Step 7 — Finalize manifest

Update manifest.json to its final state. See references/output_contract.md for the full schema. Required fields:

{
  "skill": "youtube-tutorial-creation",
  "status": "full | degraded_transcript_only | failed",
  "learning_mode": "concept_only | concept_plus_implementation",
  "video_url": "...",
  "video_id": "...",
  "source": "manual | composio | direct",
  "metadata": { "title": "...", "channel": "...", "duration": 0, "upload_date": "...", "metadata_status": "...", "metadata_source": "yt_dlp" },
  "extraction": {
    "transcript": "attempted_succeeded | attempted_failed | not_attempted",
    "metadata": "attempted_succeeded | attempted_failed | not_attempted",
    "visual": "attempted_succeeded | attempted_failed | not_attempted"
  },
  "outputs": { "CONCEPT.md": "...", "IMPLEMENTATION.md": "...", "manifest.json": "..." },
  "retention": { "transcript.txt": "temp", "transcript.clean.txt": "temp" },
  "notes": []
}

Step 8 — Implementation validation (MANDATORY)

Every Python script in implementation/ must be runnable without a separate venv.

Requirements:

1. Include PEP 723 inline dependency metadata at the top:

# /// script
# requires-python = ">=3.11"
# dependencies = ["google-genai>=1.0.0", "python-dotenv>=1.0.1"]
# ///

1. Add a --self-test flag that checks imports + basic object construction without requiring secrets.
2. Load secrets from environment only (never hardcode), using load_dotenv(find_dotenv(usecwd=True)).
3. Valid secret env var names: GOOGLE_API_KEY, GEMINI_API_KEY, Z_AI_API_KEY, ANTHROPIC_API_KEY.
4. Validate with: UV_CACHE_DIR=/tmp/uv_cache uv run implementation/<script>.py --self-test

Hard rules:
Do NOT run pip install, uv pip install, or uv add as part of a skill run.
If deps are missing, fix the PEP 723 header and re-run via uv run.

SDK drift note: Prefer google.genai for all new code. If the tutorial video uses google.generativeai, note it as "video used legacy SDK" and implement with the current SDK.

Success Criteria

• All required artifacts live under the resolved UA_ARTIFACTS_DIR (never only in run scratch)
• manifest.json exists, is accurate, and has a valid status
• CONCEPT.md is understandable without watching the video
• implementation/ scripts pass --self-test (or has clear documented reason if not applicable)

Reference files

Read these when you need deeper detail: