fabriqaai-youtube-transcript

Standalone YouTube transcript skill and CLI toolkit (no MCP server).

This repository is designed for agent workflows where transcript retrieval is handled by Python, and summary/insight generation is handled by AI (preferably in a sub-agent to save context).

Compatibility

This skill works with any agent host that can:

• load skills.sh-style skills (SKILL.md)
• execute local Python commands
• optionally run an AI sub-agent/tool for summarization

What This Repo Provides

• SKILL.md: agent instructions for transcript workflows
• youtube_transcript_tool.py: Python CLI for transcript/language retrieval
• tests/: unit tests for parsing, mode routing, and payload shape

Why No MCP

This project intentionally avoids MCP transport.

• Retrieval: done locally with Python + youtube-transcript-api
• Summarization: done by AI agents after retrieval
• Context optimization: use sub-agents when available so raw transcript tokens do not bloat the main conversation context

Requirements

• Python 3.10+
• youtube-transcript-api

Setup

Recommended (virtual environment)

python3 -m venv .venv
./.venv/bin/pip install youtube-transcript-api

If your shell supports activation, you can also do:

source .venv/bin/activate
pip install youtube-transcript-api

Install As a Skill (skills.sh / Skills CLI)

This repository is for skills.sh-compatible agent environments.

Install from GitHub:

npx skills add https://github.com/fabriqaai/fabriqaai-youtube-transcript --skill youtube-transcript

After install, restart your agent host so the skill is reloaded.

Expected result:

• skill is installed under your host's skills directory
• SKILL.md is discoverable by the agent

Examples by host:

• Codex: ~/.codex/skills/youtube-transcript
• Agent setups that use project-local skills: .agents/skills/youtube-transcript

CLI Usage

1) Get transcript with timestamps

python3 youtube_transcript_tool.py \
  --mode transcript \
  --url "https://www.youtube.com/watch?v=VIDEO_ID" \
  --lang en \
  --include-timestamps true

2) Get transcript as plain text (recommended for AI summarization)

python3 youtube_transcript_tool.py \
  --mode transcript \
  --url "VIDEO_ID" \
  --include-timestamps false

3) List available transcript languages

python3 youtube_transcript_tool.py \
  --mode languages \
  --url "https://youtu.be/VIDEO_ID"

AI Summary Workflow (Recommended)

Use this two-step flow for high-quality results and better context control:

1. Retrieve transcript text:

python3 youtube_transcript_tool.py \
  --mode transcript \
  --url "VIDEO_ID" \
  --include-timestamps false \
  --json true

2. Summarize with AI:

• Preferred: delegate to a sub-agent if available.
• Fallback: summarize in the current agent.

Sub-agent-first approach keeps large transcript content out of your main context window.

CLI Arguments

• --mode (required): transcript, languages, analyze
• --url (required): YouTube URL or 11-char video ID
• --lang (default en): preferred transcript language
• --include-timestamps (default true): timestamped entries in transcript mode
• --analysis-type (default summary): only for analyze mode
• --max-items (default 5): output limit for analysis mode
• --json (default true): JSON output for machine-friendly pipelines

Note: this skill's recommended summary path is AI summarization after transcript retrieval (preferably in a sub-agent).

Output Contract

Success

{
  "ok": true,
  "mode": "transcript",
  "video_id": "dQw4w9WgXcQ"
}

Error

{
  "ok": false,
  "error": {
    "code": "no_transcript",
    "message": "...",
    "hint": "Try another language or use --mode languages"
  }
}

Error Codes

• invalid_video_id
• transcripts_disabled
• no_transcript
• video_unavailable
• rate_limited
• dependency_missing
• transcript_fetch_failed
• api_compat_error
• transcript_parse_error

Package Notes: youtube-transcript-api

The script supports multiple package API styles to remain resilient across versions:

• static-style calls such as YouTubeTranscriptApi.get_transcript(...)
• list calls such as YouTubeTranscriptApi.list_transcripts(...)
• instance-style variants such as api.list(...) / api.fetch(...)

This compatibility layer helps avoid breakage when package internals evolve.

Testing

Run tests:

python3 -m unittest discover -s tests -v

Current tests cover:

• boolean parsing
• YouTube ID normalization
• mode routing logic
• fallback language selection
• summary payload shape
• error payload shape

Repository Structure

.
├── README.md
├── SKILL.md
├── tests/
│   └── test_youtube_transcript_tool.py
└── youtube_transcript_tool.py