Youtube Description Autoposter

Generate SEO-optimized YouTube timestamps from a YouTube URL or a raw transcript string, then optionally append them to the description of that specific vide...

installs

stars

karma

SkillRank score ↗

7.2/ 10

evaluated by implexa, claude-haiku-4-5 · 2026-05-26

yt-timestamp-autoposter generates seo-optimized youtube chapters from urls, raw transcripts, or latest uploads via gemini, with optional direct posting to video descriptions.

structure

9.0

trigger phrases

8.0

procedure

7.0

edge cases

6.0

documentation

8.0

strengths

view original SKILL.md from clawhubclick to expand

---
name: yt-timestamp-autoposter
description: Generate SEO-optimized YouTube timestamps from a YouTube URL or a raw transcript string, then optionally append them to the description of that specific video or your latest upload. Use when you need to create chapters for a YouTube video. Also use when the user asks to generate timestamps, append timestamps to YouTube, or process transcript text.
---

# YouTube Timestamp Generator & Auto-Poster

Transforms a YouTube URL or a raw transcript string into SEO-optimized timestamps (chapters) powered by Gemini. Optionally appends the result directly to the description of a specific YouTube video or your latest upload via the YouTube Data API.

## ⚠️ Requirements Checklist

Before using this skill, ensure you have:

- [ ] **Python 3** installed
- [ ] **Dependencies installed**: `pip install youtube-transcript-api google-generativeai google-auth-oauthlib google-api-python-client`
- [ ] **Gemini API Key** available to pass as an argument
- [ ] **`credentials.json`** placed in `scripts/` *(only required for `--post` — download from Google Cloud Console as an OAuth 2.0 Desktop App client)*

## Features

- 🕐 **SEO Timestamps**: Generates 0:00-based chapters with keyword-rich, scannable labels
- 🔗 **Three Input Modes**: Works from a YouTube URL, a raw transcript string, or auto-targets your latest video
- 🚀 **Smart Auto-Poster**: URL mode appends to that specific video; transcript and latest modes append to your latest upload
- 🛡️ **Duplicate Prevention**: The `--latest` mode checks for existing timestamps before attempting to generate new ones
- 🔑 **Keyword Optimization**: Natural integration of primary, secondary, and LSI keywords from the transcript
- 🧹 **Clean Output**: Returns only the final timestamps — no extra headings or commentary

## Quick Start

### Mode 1 — YouTube URL
Fetches the transcript from the video, generates SEO timestamps, and optionally appends them to the description of **that specific video**.

```bash
# Generate only (view output)
python scripts/youtube_desc_generator.py --url "<youtube_url>" "<gemini_api_key>"

# Generate and post to that video
python scripts/youtube_desc_generator.py --url "<youtube_url>" "<gemini_api_key>" --post
```

### Mode 2 — Raw Transcript Text

Reads a raw transcript string, generates SEO timestamps, and optionally appends them to the description of your **latest YouTube upload**.

```bash
# Generate only (view output)
python scripts/youtube_desc_generator.py --transcript "0:00 Welcome..." "<gemini_api_key>"

# Generate and post to latest video
python scripts/youtube_desc_generator.py --transcript "0:00 Welcome..." "<gemini_api_key>" --post
```

### Mode 3 — Latest Video
Automatically fetches your most recent video, checks if timestamps already exist (to prevent duplicates), downloads the transcript, generates SEO timestamps, and optionally appends them to the description.

```bash
# Generate and post timestamps for your latest video (if they don't already exist)
python scripts/youtube_desc_generator.py --latest "<gemini_api_key>" --post
```

**Examples:**

```bash
python scripts/youtube_desc_generator.py --url "https://youtu.be/abc123" "$GEMINI_API_KEY"
python scripts/youtube_desc_generator.py --url "https://youtu.be/abc123" "$GEMINI_API_KEY" --post
python scripts/youtube_desc_generator.py --transcript "0:00 Welcome..." "$GEMINI_API_KEY" --post
```

## Raw Transcript Text Format

When using `--transcript`, the transcript must be a string with timestamps in `MM:SS` format, separated by newlines:

```
0:00 Welcome to this video about AI agents.
0:12 Today we're going to cover what an AI agent actually is.
1:00 Let me show you a live demo of an agent booking a flight.
...
```

## Natural Language Command Mapping

When the user speaks naturally, map their intent to the correct command using the table below. Always extract the YouTube URL or transcript text from their message and substitute it into the command.

| What the user says                                                                     | Command to run                                                                                      |
| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| "Create timestamps for my latest video"                                                | `python scripts/youtube_desc_generator.py --latest "$GEMINI_API_KEY" --post`                          |
| "Generate timestamps for this video: https://youtu.be/abc123"                          | `python scripts/youtube_desc_generator.py --url "https://youtu.be/abc123" "$GEMINI_API_KEY"`        |
| "Create SEO chapters from this YouTube link: https://youtu.be/abc123"                  | `python scripts/youtube_desc_generator.py --url "https://youtu.be/abc123" "$GEMINI_API_KEY"`        |
| "Give me the timestamps for this video: https://youtu.be/abc123"                       | `python scripts/youtube_desc_generator.py --url "https://youtu.be/abc123" "$GEMINI_API_KEY"`        |
| "Generate timestamps for this video and post it: https://youtu.be/abc123"              | `python scripts/youtube_desc_generator.py --url "https://youtu.be/abc123" "$GEMINI_API_KEY" --post` |
| "Generate SEO timestamps and post them back to this video: https://youtu.be/abc123"   | `python scripts/youtube_desc_generator.py --url "https://youtu.be/abc123" "$GEMINI_API_KEY" --post` |
| "Process this transcript text: 0:00 Welcome..."                                        | `python scripts/youtube_desc_generator.py --transcript "0:00 Welcome..." "$GEMINI_API_KEY"`                |
| "Generate timestamps from my transcript text: 0:00 Welcome..."                         | `python scripts/youtube_desc_generator.py --transcript "0:00 Welcome..." "$GEMINI_API_KEY"`                |
| "Process my transcript text and post it to my latest video: 0:00 Welcome..."                            | `python scripts/youtube_desc_generator.py --transcript "0:00 Welcome..." "$GEMINI_API_KEY" --post`         |
| "Generate timestamps from my transcript and upload to YouTube: 0:00 Welcome..."        | `python scripts/youtube_desc_generator.py --transcript "0:00 Welcome..." "$GEMINI_API_KEY" --post`         |

### Decision Rules

Use these rules to determine which command to run when the intent is ambiguous:

- **"latest video" or similar** → always use `--latest` mode
- **URL present** → always use `--url` mode
- **Transcript text present** → always use `--transcript` mode
- **"post", "update", "upload", "push"** anywhere in the message → add `--post` flag (Note: commands like "create timestamps for my latest video" imply updating it, so `--post` is added)
- **No `--post`** → generate and print only, do not touch YouTube
- **`--transcript --post`** and **`--latest --post`** → always targets the **latest upload** on the channel
- **`--url --post`** → always targets **that specific video**

## Generated Output

The script returns a single clean block — no labels or extra text:

- **SEO-Optimized Timestamps** — YouTube chapters starting at `0:00` with keyword-rich labels and SEO suffix tags (e.g. `(Tutorial)`, `(Overview)`, `(2026)`)

> **Important:** Output only the final timestamps. Do not include any introductory sentences, headings, labels, preamble, or commentary before or after the output.

## How It Works

**URL mode:**

1. Extracts the video ID from the provided YouTube URL
2. Fetches the English transcript via `youtube-transcript-api`
3. Formats the transcript with `MM:SS` timestamps
4. Sends a prompt to Gemini for timestamps
5. Prints the timestamps
6. _(With `--post`)_ Authenticates via OAuth2 and appends the new timestamps to **that specific video's** description

**Transcript mode:**

1. Reads the provided raw transcript text string
2. Sends a prompt to Gemini for timestamps
3. Prints the timestamps
4. _(With `--post`)_ Authenticates via OAuth2, finds your **latest upload**, and appends the new timestamps to its description

## OAuth Setup (for `--post` only)

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a project and enable the **YouTube Data API v3**
3. Create **OAuth 2.0 credentials** (Desktop App type)
4. Download the file as `credentials.json` and place it in `scripts/`
5. On first run with `--post`, a browser window will open for you to authorize access
6. A `token.pickle` file will be saved automatically for future runs

## Troubleshooting

**No transcript available (URL mode):**

- The video may have transcripts disabled or no English captions
- Switch to `--transcript` mode with a manually prepared transcript string

**Transcript text not loading (transcript mode):**

- Ensure the text format is correct
- Each line should follow `MM:SS text` format

**Gemini API errors:**

- Verify your API key is valid and has access to `gemini-3.1-flash-lite-preview`
- Check your quota at [Google AI Studio](https://aistudio.google.com/)

**`--post` not updating the video:**

- Ensure `credentials.json` is in the `scripts/` directory
- Delete `token.pickle` and re-authenticate if credentials have expired
- Confirm the YouTube Data API v3 is enabled in your Google Cloud project

**Wrong video appended to in transcript mode:**

- Transcript mode always targets your most recent upload — make sure the correct video is your latest
- If you need to target a specific video, use `--url` mode instead

## Privacy & Safety

⚠️ **Important:** The `--post` flag will append timestamps to a video's description automatically without manual confirmation in the CLI.

- The script always shows you the target video title being updated
- OAuth credentials are stored locally in `token.pickle` — keep this file secure
- Revoke access anytime via your [Google Account permissions](https://myaccount.google.com/permissions)

don't have the plugin yet? install it then click "run inline in claude" again.

restructured into implexa's six-component format, made decision logic explicit with if-else branches, documented all external connections and oauth setup as inputs, added edge cases (rate limits, token expiry, timeouts, duplicate detection), preserved original procedure and command mappings, removed marketing language and hedging.

YouTube Timestamp Generator & Auto-Poster

intent

generates seo-optimized youtube chapter timestamps from a youtube url, raw transcript string, or your latest video upload using gemini ai. optionally appends the timestamps directly to a video description via the youtube data api. use this when you need to create searchable chapters for youtube content, extract and format timestamps from a transcript, or automate timestamp posting to your channel.

inputs

required:

gemini api key (env var: GEMINI_API_KEY or passed as argument)
python 3.8+
pip dependencies: youtube-transcript-api, google-generativeai, google-auth-oauthlib, google-api-python-client

for --post flag only:

credentials.json file in scripts/ directory (oauth 2.0 desktop client credentials from google cloud console)
youtube data api v3 enabled in google cloud project
oauth scopes: https://www.googleapis.com/auth/youtube (read/write access to video descriptions)

input modes (choose one):

youtube url: --url "https://youtu.be/VIDEO_ID"
raw transcript text: --transcript "0:00 Welcome...\n0:12 Topic...\n1:00 Demo..."
latest upload: --latest (fetches your most recent video)

edge cases:

video may have transcripts disabled or captions unavailable (url mode will fail; use --transcript mode instead)
transcript text must use MM:SS or H:MM:SS format, newline-separated
gemini api rate limits: 15 requests per minute (free tier); exceeding triggers 429 backoff
oauth token expiry: token.pickle auto-refreshes; if expired, delete file and re-authenticate
youtube api quota: 10,000 units/day (description update costs ~50 units)
network timeout on api calls: 30-second default; fails gracefully with error message

procedure

step 1: parse user input and determine mode

input: user command or arguments (url, transcript text, or --latest flag)
output: identified mode (url, transcript, or latest) and --post flag presence
mapping: see decision points below

step 2: extract or fetch transcript

if mode is url: extract video id from url, call youtube-transcript-api to fetch english captions
if mode is transcript: parse the provided text string (no api call needed)
if mode is latest: call youtube data api to fetch your most recent video, then fetch its transcript
output: formatted transcript string with timestamps in MM:SS format
on failure (no captions, api error, timeout): return error message; do not attempt fallback

step 3: check for existing timestamps (latest mode only)

if mode is latest and --post flag present: fetch the video description from step 2
scan description for patterns matching timestamp format (e.g., "0:00", "1:23 -")
if timestamps found: stop, print "timestamps already exist for this video", exit
output: boolean (timestamps exist or not)

step 4: generate timestamps via gemini

input: transcript string from step 2
call gemini 3.1-flash-lite-preview with prompt: "generate seo-optimized youtube chapter timestamps. extract the 3-5 most important segments. format as MM:SS label, each on a new line. labels must be keyword-rich, scannable, 2-5 words, include seo suffix tags like (tutorial), (overview), (how-to). output only the timestamps, no intro text or headings."
output: raw timestamp block (e.g., "0:00 introduction (overview)\n0:45 core concept (tutorial)\n2:30 live demo (how-to)")
on gemini error (invalid api key, quota exceeded, timeout): return error; do not post

step 5: print timestamps to stdout

input: timestamp block from step 4
output: print raw timestamps only (no labels, no "here are your timestamps:", no markdown)

step 6: post to description (if --post flag present)

input: timestamps from step 4, target video id (from step 2 for url mode, or from latest fetch for transcript/latest modes)
authenticate via oauth2: check for token.pickle, else prompt browser oauth flow, save token
fetch current video description via youtube api
append timestamps to end of description (separated by newline if description non-empty)
update description via youtube api
output: success message with video title and url, or error message
on auth failure: prompt user to re-authenticate or move token.pickle
on api failure (quota exceeded, invalid video id, permission denied): return descriptive error; do not retry

decision points

mode selection:

if --url <url> present: use url mode (generate and optionally post to that specific video)
else if --transcript <text> present: use transcript mode (generate and optionally post to latest video)
else if --latest present: use latest mode (fetch latest video, check for existing timestamps, generate and optionally post)
else: print usage and exit

--post flag logic:

if --post absent: generate timestamps and print to stdout only; do not touch youtube
if --post present and url mode: post to the video in the url
if --post present and transcript mode: post to your latest upload (note: this is YOUR latest, not the video's latest)
if --post present and latest mode: post to your latest upload (after checking for duplicates)

error handling branches:

if transcript unavailable (url mode, no captions): return "error: no english transcript available for this video. use --transcript mode to manually provide text."
if transcript text malformed: return "error: transcript text does not match MM:SS format. example: 0:00 intro\n0:45 topic"
if gemini api key invalid: return "error: gemini api key is invalid or has no quota. check your key and quota at aistudio.google.com"
if --post requested but credentials.json missing: return "error: credentials.json not found in scripts/ directory. download oauth credentials from google cloud console and place file there."
if oauth token expired (post mode): delete token.pickle automatically, re-prompt oauth flow
if latest mode detects existing timestamps: stop and return "timestamps already exist for this video. no new timestamps will be generated. delete existing timestamps from the description manually and try again."
if youtube api rate limit hit during post: return "error: youtube api quota exceeded. try again in 24 hours or upgrade your quota."
if network timeout on any api call: return "error: connection timeout. check your internet and try again."

output contract

success output format:

0:00 Chapter Name (SEO Tag)
0:45 Second Chapter (Tutorial)
2:30 Third Chapter (Overview)
...

output file location: printed to stdout only; no files created unless --post flag used

posted to: youtube video description (appended to existing description, not overwriting)

timestamp properties:

each line: MM:SS label or H:MM:SS label
label: 2-5 words, includes 1-2 seo suffix tags from list (tutorial, overview, how-to, intro, demo, guide, explanation, tips, strategy, 2025, 2026, etc.)
format: seo-optimized, scannable, keyword-rich (natural language, not stuffed)
count: 3-5 chapters per video (gemini decides based on transcript length)

data integrity:

timestamps must be sequential and non-overlapping (0:00 before 0:45 before 2:30, etc.)
no duplicate timestamps
no malformed timestamps (always MM:SS or H:MM:SS, always followed by space and label)

outcome signal

no --post: user sees clean timestamp block printed in terminal. success means output is readable, formatted correctly, and contains only timestamps (no extra text).
with --post: user sees message "✓ timestamps appended to video: [video title] - https://youtube.com/watch?v=[id]". user can verify by opening the youtube video description and confirming timestamps appear at the end.
--latest mode with --post: user additionally sees message "✓ existing timestamps check passed" before posting (or "✗ timestamps already exist" if duplicates found).
failure: user sees error message describing the problem (missing api key, no transcript, quota exceeded, etc.) and suggested fix.

Youtube Description Autoposter

related skills

YouTube Timestamp Generator & Auto-Poster

intent

inputs

procedure

decision points

output contract

outcome signal