ytscript

name	ytscript
description	Download YouTube video transcripts and format them as readable markdown documents. Use when user wants a transcript saved to file, or when explicitly invoked ytscript skill.
argument-hint	<video-url-or-id> [--lang <langs>]
allowed-tools	Bash, Read, Write, Edit

YouTube Transcript Downloader Skill (ytscript)

This skill reliably fetches full text transcripts from YouTube videos using a local Python script (via youtube-transcript-api).

The script is intended to be executed with uv run. Its Python requirement and package dependencies are embedded directly in the script header, so they do not need to be added to the repository-wide dependency files.

Key Features:

• Auto-Formatting: Saves as Markdown (.md) with video link.
• Self-Contained: Python script included with the skill for portability.
• Embedded Requirements: Runtime requirements are declared in the script header and resolved automatically by uv run.
• Clean Filenames: Automatically removes emojis and special characters for better file system compatibility.
• Configurable Output: Uses environment variable YTSCRIPT_OUTPUT_DIR for output location (default: output/ subdirectory).

Workflow Checklist (ALL STEPS REQUIRED)

1. Download transcript to output/ directory
2. Format with sections and proper markdown
3. Verify with markdownlint (only MD013 ignored)
4. Move to YYYY/MM/DD/ archive directory
5. Commit to git with proper message
6. Deliver summary to user

Usage

Use this skill when:

• User wants a transcript saved to file.
• User specifically invokes ytscript.

Command

The script is included in the skill directory at scripts/get_transcript.py. Run it from the skill directory with uv run:

cd <SKILL_PATH>/ytscript
uv run scripts/get_transcript.py "<VIDEO_URL_OR_ID>"

Or set the output directory via environment variable:

export YTSCRIPT_OUTPUT_DIR="/path/to/output"
cd <SKILL_PATH>/ytscript
uv run scripts/get_transcript.py "<VIDEO_URL_OR_ID>"

Parameters

• VIDEO_URL_OR_ID: The full URL or video ID.
• --lang: Priority list of languages for transcript selection (default: ru en). Example: --lang en de fr to prefer English, then German, then French transcripts.
• Environment Variable YTSCRIPT_OUTPUT_DIR: Output directory path (default: <SKILL_PATH>/ytscript/output/)

Runtime Requirements

• Always execute the script with uv run scripts/get_transcript.py ...
• Do not invoke it with plain python unless the embedded dependencies have been installed separately into the current environment
• The # /// script header in scripts/get_transcript.py declares the Python version and required packages

If uv is not installed:

python3 -m pip install uv

Then run:

cd <SKILL_PATH>/ytscript
uv run scripts/get_transcript.py "<VIDEO_URL_OR_ID>"

Example

User: "Save transcript for https://youtu.be/dQw4w9WgXcQ" Agent Action:

cd <SKILL_PATH>/ytscript
uv run scripts/get_transcript.py "https://youtu.be/dQw4w9WgXcQ"

Output:

"Successfully saved transcript to: <SKILL_PATH>/ytscript/output/Rick_Astley_-_Never_Gonna_Give_You_Up.md"

Post-Processing (Formatting)

IMPORTANT RULES FOR TRANSCRIPT INTEGRITY:

NEVER change words or alter the original meaning of the transcript. The transcript must remain faithful to the video content.

Section Formatting Guidelines:

1. Analyze content structure - Identify main topics and sections from the transcript
2. Add logical headings ONLY when clear sections exist - Break text into sections with descriptive headers ONLY when the content naturally divides into distinct topics
3. Improve formatting - Use proper markdown syntax for lists, emphasis, and code (DO NOT add formatting that wasn't in the original)
4. Enhance readability - Add spacing, clear section breaks
5. Save formatted version - Overwrite the original file with formatted content

When NOT to add sections:

• If the transcript flows continuously without clear topic boundaries
• If adding sections would require paraphrasing or summarizing
• If the content is not structured in a way that allows meaningful section breaks
• If you're uncertain about where section boundaries should be

In these cases, keep the original transcript WITHOUT any section headings. The original text should be preserved exactly as generated, only with markdown formatting fixes (like proper list syntax, spacing) if needed.

Golden Rule: If you cannot add sections without changing the original text or meaning, leave the transcript as-is with NO sections.

Filenames and Emojis

IMPORTANT RULE: Filenames MUST NOT contain emojis, non-ASCII characters, or ANY special symbols for maximum file system compatibility.

The sanitize_filename() function automatically removes:

• Emojis and non-ASCII Unicode characters
• ALL special characters (parentheses, brackets, punctuation, symbols, etc.)
• Extra whitespace (converted to underscores)

Resulting filenames contain ONLY: letters, numbers, underscores, and hyphens.

Example:

• Input: OpenClaw Full Tutorial – How to Set Up and Use OpenClaw (ClawdBot / MoltBot)
• Output: OpenClaw_Full_Tutorial_How_to_Set_Up_and_Use_OpenClaw_ClawdBot_MoltBot.md

Delivery

After formatting and validation, deliver the transcript to the user:

1. Archive to Git (REQUIRED) - ALWAYS archive the transcript to the repository with dated directory structure
2. Send the file - Use appropriate delivery method for your platform
3. Write summary - Provide a concise summary of the video content with key points
   • List main topics/reasons covered
   • Include conclusion/takeaway
   • Reference original video URL and transcript file location

Example message format:

# Transcript: [Video Title]

## Key Points

**Point 1:** [Brief description]

**Point 2:** [Brief description]

**Conclusion:** [Main takeaway]

**Source:** [YouTube URL]
**Full transcript:** [File path to transcript]

Git Archiving (MANDATORY STEP)

CRITICAL: ALL transcripts MUST be archived to git following this two-stage workflow.

Workflow:

1. Download & Edit (gitignored working directory):

   • Transcript downloads to .claude/skills/ytscript/output/ (gitignored)
   • AI formats and validates in place

2. Archive & Commit (final location):

   • Move formatted transcript to dated directory structure
   • Commit directly to git

Complete workflow:

# 1. Download (script outputs to .claude/skills/ytscript/output/)
cd <SKILL_PATH>/ytscript
uv run scripts/get_transcript.py "https://youtube.com/watch?v=VIDEO_ID"

# 2. Format and validate in place (AI adds sections, fixes linting)
# File: .claude/skills/ytscript/output/Video_Title.md

# 3. Move to archive directory (creates YYYY/MM/DD/ structure)
TRANSCRIPT_FILE=".claude/skills/ytscript/output/Video_Title.md"
ARCHIVE_DATE=$(date +%Y/%m/%d)
mkdir -p "$ARCHIVE_DATE"
mv "$TRANSCRIPT_FILE" "$ARCHIVE_DATE/Video_Title.md"

# 4. Commit to git
git add "$ARCHIVE_DATE/Video_Title.md"
git commit -m "Add transcript: Video Title

Source: https://www.youtube.com/watch?v=VIDEO_ID"

Note: The source file is removed when moved to the archive directory.

Windows (Git Bash / MSYS2)

The bash commands above work in Git Bash on Windows. If you encounter issues, use this alternative:

# 1. Download
cd <SKILL_PATH>/ytscript
uv run scripts/get_transcript.py "https://youtube.com/watch?v=VIDEO_ID"

# 2. Format and validate in place

# 3. Move to archive directory
TRANSCRIPT_FILE=".claude/skills/ytscript/output/Video_Title.md"
ARCHIVE_DATE="$(date +%Y/%m/%d)"
mkdir -p "$ARCHIVE_DATE"
mv "$TRANSCRIPT_FILE" "$ARCHIVE_DATE/Video_Title.md"

# 4. Commit to git (use -m and then open editor for multi-line message)
git add "$ARCHIVE_DATE/Video_Title.md"
git commit -m "Add transcript: Video Title" -m "Source: https://www.youtube.com/watch?v=VIDEO_ID"

Markdown Linter Compliance

CRITICAL: Always format transcripts to avoid markdownlint errors. Follow these rules:

Rule	Description	Fix
MD013	Line length	IGNORED - transcripts may have long lines
MD032	Lists must be surrounded by blank lines	Add blank line before/after lists
MD036	Don't use emphasis (asterisks or underscores) as headings	Use proper #, ##, or ### headings
MD060	Table separators need spaces around pipes	Use proper spacing: pipe-space-dash-space-pipe

Common Mistakes to Avoid

❌ WRONG (MD032 - Missing blank lines):

Here's a list:
- Item 1
- Item 2

Another paragraph.

✅ CORRECT:

Here's a list:

- Item 1
- Item 2

Another paragraph.

❌ WRONG (MD036 - Emphasis as heading):

*This is a heading*

✅ CORRECT:

## This is a heading

❌ WRONG (MD060 - No spaces in table separator):

| Column |
|--------|
| value  |

✅ CORRECT:

| Column |
| ------ |
| value  |

Verification

After formatting, check for errors:

markdownlint-cli2 "/path/to/transcript.md"

Fix all reported errors before delivering the transcript.