youtube-description

youtube-description

Turns a finished video cut into a copy-paste-ready YouTube description. Three parts, always in this order:

1. Description — very short, 2 sentences, in your voice.
2. Fixed CTA block — your product + social links, verbatim, never edited.
3. Timestamps — YouTube chapters derived from the transcript.

The transcription engine is ElevenLabs Scribe (word-level timestamps), the same one /video-use uses. The output is a block you paste into YouTube yourself (this skill does not touch the live video).

---

SETUP (run this once)

1. Lock your fixed CTA block by filling the placeholders in step 4: <YOUR_BRAND>, <YOUR_DOMAIN>, <YOUR_LINKEDIN_URL>. After that the CTA is reproduced verbatim on every video, never reworded.
2. Set ELEVENLABS_API_KEY in your env (or .env). Scribe needs it. /video-use in this vault already uses the same key.
3. (Optional) Point <YOUR_BRAND_DOC> at your voice rules so the description passes the same slop checks as your other copy.

---

When to use

Trigger on:

• "Write the YouTube description for "
• "Generate chapters / timestamps for this video"
• "Describe this YT video"
• User types /youtube-description

Sibling skills (don't confuse):

• Upload + thumbnails + playlist → /youtube-publisher
• Edit raw footage into a cut → /video-use
• Write the script before filming → /youtube-script

---

Inputs

A finished video. Accept any of:

• An absolute path to an .mp4 / .mov.
• An existing ElevenLabs Scribe JSON (a /video-use transcript on disk) — reuse it to skip the API call and the wait. /video-use edits store these under <videos_dir>/edit/transcripts/<stem>.json.

---

Workflow

1. Get a timestamped transcript

Reuse a /video-use Scribe JSON if one exists (no API call, no wait — Scribe on a 25-min video costs minutes and credits). Otherwise call Scribe once and cache the result.

Either way, build a [M:SS] text transcript — one line per ~20s — and note the total duration (no chapter may land at or past it). The ElevenLabs Scribe endpoint returns word-level start/end times; group words into ~20s buckets and prefix each line with its start timestamp.

Read the whole transcript. It is your only source for both the description and the chapters.

2. Write the description (very short · 2 sentences)

House format for a tutorial:

Learn how to set up a cold email system with Claude Code that can handle 100k+ emails / month. We'll be using Claude Code, <YOUR_BRAND>, and a set of other tools.

Pattern:

• Sentence 1: Learn how to <outcome> with <concrete spec>. The outcome and the number are the hook. Lead with what the viewer can do.
• Sentence 2: We'll be using <tool stack>. Lowercase the tool names, end with "and other tools" / "and a set of custom skills" if the list runs long.

Rules: two sentences, no more. No em dashes (use . , : ( ·). No banned words (leverage, seamless, powerful, … full list in <YOUR_BRAND_DOC>). Concrete numerals over adjectives. It must read like you typed it, not like a SaaS template.

3. Build the chapters

From the transcript, pick chapter boundaries at real topic shifts and title each. Hard YouTube rules:

• First chapter is 0:00. Always. Without it YouTube shows no chapters.
• At least 3 chapters; each at least 10s after the previous.
• Use the timestamp format the transcript prints (M:SS, or H:MM:SS past an hour).
• Titles: terse, descriptive, no numbering, no em dashes. Lead with the thing the viewer learns ("Connecting your CRM"), not "Part 3".
• 8–15 chapters for a 20–30 min tutorial is the right density. Don't make one per transcript line.

4. Assemble the block

Exactly this structure. The fixed CTA block sits between the description and the timestamps and is reproduced verbatim — never reword, never drop a line, never change the handle:

<description · sentence 1>
<description · sentence 2>

Try <YOUR_BRAND> for free:
<YOUR_DOMAIN>

Connect with me on LinkedIn:
<YOUR_LINKEDIN_URL>

Timestamps:
0:00 <first chapter title>
<m:ss> <title>
<m:ss> <title>
...

5. Write it into your content record

Put the assembled block where your content lives so it's tracked and copy-pasteable:

• Markdown content vault: add or replace a ## YouTube description section in the video's .md file. Wrap the block in a fenced ```text code block so line breaks survive the paste into YouTube. The section is idempotent — replace the existing one, don't append a second.
• Notion Content DB: paste the block into the video row's body / a "YouTube description" property.

Report back where you wrote it and the chapter count. Show the assembled block in chat too.

---

Definition of done

1. A timestamped transcript exists for the video.
2. A 2-sentence description in your voice (no em dashes, no banned words).
3. The fixed CTA block, verbatim, between description and timestamps.
4. Chapters starting at 0:00, none past the printed duration.
5. The whole block written into your content record as an idempotent section, inside a copy-paste-ready code block, and the location reported.

---

Don'ts

• Don't pad the description. Two sentences. (This is the opposite of the terse-CTA-only rule in /youtube-publisher; here you explicitly want the short description + timestamps. But "short" still means two sentences.)
• Don't edit the CTA block. Verbatim, including the LinkedIn URL (use your canonical profile — no tracking params).
• Don't invent chapter times. Every timestamp comes from the transcript.
• Don't push to the live YouTube video. The content record only, unless asked. To set descriptions live, /youtube-publisher's finalize step (--only-descriptions) is the path.
• Don't burn Scribe on an existing transcript. Check for a /video-use JSON first and reuse it.