YouTube Skillbox

13 free YouTube skills for AI agents — research, transcripts, and the full creator workflow.
No user-supplied YouTube Data API key · no credits · no expiry — $0 forever

Table of Contents · Demo · Research · Transcripts · Gap-fill engine · Creator tools · Install · Agent prompt

⚠️ Important Disclaimer

This tool accesses public YouTube data for research purposes only.

• Respect YouTube's Terms of Service and Community Guidelines
• Respect rate limits — add delays between bulk requests
• Not affiliated with YouTube or Google
• For research/educational use only

📺 Demo

Watch the agent in action — one prompt, "why isn't this channel growing?" OpenCode researches the videos, Shorts and transcripts, then surfaces the hooks, scripts and what to fix (why one Short hit 8K views while the rest couldn't pass 1K):

_{Click to watch on YouTube →}

📋 Table of Contents

What is this?

A drop-in set of SKILL.md skills for agent harnesses like OpenCode (works anywhere skills are discovered from a folder). Each skill in skills/ is self-contained: a SKILL.md the agent reads, plus small Python tools it runs.

Two layers:

Everything is free. There is no paid tier, no user-supplied YouTube Data API key, and no account anywhere in the stack.

🔗 How the Skills Chain Together (The Pipeline)

The skills aren't isolated — they form an 7-phase analysis pipeline that agents can run end-to-end:

graph TD
    A["User: Channel Analysis"] --> B["Phase 1: youtube"]
    B --> C["Phase 2: transcript"]
    C --> D["Phase 3: yt-script"]
    D --> E["Phase 4: yt-package"]
    E --> F["Phase 5: youtube (SEO/keywords)"]
    F --> G["Phase 6: youtube (outliers/gaps)"]
    G --> H["Phase 7: yt-retention*"]
    
    B --> J["Data: sections, videos, home, profile"]
    C --> K["Transcripts for top 3 videos"]
    D --> L["Hook scores 0-100"]
    E --> M["Title/thumbnail scores"]
    F --> N["Keywords, competition, scorecards"]
    G --> O["Outliers, competitor gaps"]
    H --> P["ONE fix + 3 working + don't-do"]

*Phase 7 (yt-retention) optional — requires YouTube Studio CSV export.

Each skill declares its pipeline position in its SKILL.md — agents read this to know what comes before/after.

Final synthesis: After running all phases, the agent synthesizes: ONE biggest fix + 3 things working + what NOT to do.

📺 The youtube research skill

Thirteen subcommands behind one script — skills/youtube/scripts/ytdata.py:

python skills/youtube/scripts/ytdata.py search "query" --limit 10     # find videos on a topic
python skills/youtube/scripts/ytdata.py keywords "seed idea" --patterns  # keyword ideas (2 engines), scored
python skills/youtube/scripts/ytdata.py track "keyword" --video <url> # where your video ranks (+ history)
python skills/youtube/scripts/ytdata.py profile "@handle"             # About: subs, description, keywords
python skills/youtube/scripts/ytdata.py sections "@handle"            # count EVERY tab at once
python skills/youtube/scripts/ytdata.py home "@handle"                # home shelves + Featured Channels
python skills/youtube/scripts/ytdata.py channel "@handle" --tab shorts
python skills/youtube/scripts/ytdata.py latest "@handle" --limit 10
python skills/youtube/scripts/ytdata.py posts "@handle" --limit 30    # community posts, paginated
python skills/youtube/scripts/ytdata.py shows "@handle"               # Shows tab (episode collections)
python skills/youtube/scripts/ytdata.py playlist "<playlist-url>"
python skills/youtube/scripts/ytdata.py info "<video-url-or-id>"      # views, likes, tags, date

search, keywords, track and compete take --gl / --hl (default US / en) to pin a region and language, so a rank position means the same thing on every machine. keywords merges two engines by default — YouTube's suggest plus DuckDuckGo's (--sources yt or --sources ddg to use one).

Add --json to any command for structured output. Example:

$ python skills/youtube/scripts/ytdata.py sections "@MrBeast"
Channel: https://www.youtube.com/@MrBeast
  videos   : 805
  shorts   : 205
  streams  : no tab
  shows    : 5
  playlists: no tab
  community: 20+ posts (use `posts` to read them)

📜 The transcript skill

Spoken text of any video, free via yt-dlp:

python scripts/gettranscript.py "<url-or-id>"                    # clean text
python scripts/gettranscript.py "<url-or-id>" --format stamped   # [MM:SS] per line
python scripts/gettranscript.py "<url-or-id>" --format json      # segments + metadata
python scripts/gettranscript.py "<url-or-id>" --lang es,es-419   # language priority list

Prefers human captions, falls back to auto-generated. The JSON form carries start/duration per cue — ready for chapters, quotes, or edit lists.

🛠 When yt-dlp can't do it, we build it

yt-dlp is the data engine for channels, playlists, metadata and transcripts — but it explicitly refuses a few things (returns 0 entries, says "no home tab", or quietly localizes results to your own IP). Rather than pay an API, each gap is filled with a small pure-Python scraper (urllib + JSON parsing of YouTube's own page data / Innertube endpoints):

All of it is dependency-free Python — no API key, no credits, no tokens to manage.

$ python scripts/ytdata.py home "@MKBHD" --limit 3
  1. [featured video] Macbook PROLED XDR Impressions: ...  (1 item)
  2. [videos] Videos  (12 items)
  3. [featured channels] 🔥 MKBHD Approved 🔥  (6 items)
       - The Studio      https://www.youtube.com/channel/UCG7J20...
       - Auto Focus      https://www.youtube.com/channel/UC2J-0g...
       - WVFRM Podcast   https://www.youtube.com/channel/UCEcrRX...

✂️ The 10 creator skills

Local tools that turn raw transcripts/data into publishing artifacts:

They pair naturally with the data layer: youtube finds the videos → transcript pulls the text → yt-* does the work.

📦 Install

Requirements: Python 3.10+ and yt-dlp:

python -m pip install --user -U yt-dlp

posts, home, shows, search, keywords and track work even without yt-dlp (pure HTTP). Everything else runs through it. Run it as a module (python -m yt_dlp) if the exe isn't on PATH.

Option 1: Install from PyPI (Recommended)

pip install youtube-skillbox

This installs the ytdata CLI globally and all skills for your agent.

Option 2: Install from Source (Development)

git clone https://github.com/hackers-reality/youtube-skillbox.git
cd youtube-skillbox
pip install -e .

Option 3: Manual Skill Installation (for agents)

Point the installer at your agent's skills directory (where it discovers SKILL.md files):

./install.sh "/path/to/your/agents/skills"          # Linux / macOS — e.g. ~/.config/opencode/skills

.\install.ps1 "C:\path\to\your\agents\skills"       # Windows — e.g. %USERPROFILE%\.config\opencode\skills

…or by hand — copy any folder from skills/ there yourself:

cp -r skills/* ~/.config/opencode/skills/            # example: OpenCode

Restart the agent session; the skills are auto-discovered by their description frontmatter.

🤖 Have your agent set it up for you

Don't want to install by hand? Paste this into any coding agent that can read files — Claude Code, OpenCode, Cursor, or any agent with skill discovery:

Set up my YouTube skills from https://github.com/hackers-reality/youtube-skillbox

1. Get the repo: git clone https://github.com/hackers-reality/youtube-skillbox.git
   (or fetch files from GitHub if you can't clone)
2. Install the data engine: python -m pip install --user -U yt-dlp
   (This is the ONLY runtime dependency — all skills share this one ytdata.py module)
3. Copy the data module to your agent's global skills directory (REQUIRED):
   - Linux/macOS: cp -r skills/youtube/scripts ~/.config/opencode/skills/youtube/
   - Linux/macOS: cp -r skills/transcript/scripts ~/.config/opencode/skills/transcript/
   - Windows: xcopy skills\youtube\scripts %USERPROFILE%\.config\opencode\skills\youtube\ /E /I
   - Windows: xcopy skills\transcript\scripts %USERPROFILE%\.config\opencode\skills\transcript\ /E /I
   (The SKILL.md files reference `scripts/ytdata.py` and `scripts/gettranscript.py`
    relative to their SKILL.md location. The scripts MUST be in the same folder structure.)
4. Point your agent at the skills:
   - **OpenCode / Cursor / local agents**: skills auto-discovered from
     .opencode/skills/ (project) and ~/.config/opencode/skills/ (global)
   - **Claude Code / web agents**: Add the skills/ folder path in settings,
     or copy skills/*/ to your agent's skills directory
   - **Any agent with "add skill" UI**: Point to skills/ folder or paste SKILL.md files
5. Smoke-test: run
   python ~/.config/opencode/skills/youtube/scripts/ytdata.py search "rick astley" --limit 1
   (should return 1 video with title, views, channel, URL)
6. Ask your agent: "List all 13 YouTube skills and when to use each"
   It should read each skills/*/SKILL.md and answer from there.

Important: All 13 skills (youtube, transcript, 10 yt-*) share one data module: skills/youtube/scripts/ytdata.py. The skills reference it via relative paths (scripts/ytdata.py from SKILL.md). You must copy the scripts/ folder alongside each skill's SKILL.md in your agent's skills directory (step 3 above). Or install globally with pip install -e . (then ytdata works from anywhere).

📝 Notes & limits

• YouTube may throttle (HTTP 429) if you hammer it — a small delay between bulk calls is enough.
• posts costs one HTTP request per ~10 posts; keep --limit ≤ 100 per invocation.
• sections shows N+ for community counts when more pages exist (exact when they fit on page 1).
• Flat list view counts can show ? occasionally — use info on a specific video for exact numbers.
• Private / age-restricted / deleted targets fail with a clear message instead of silence.

⚖️ Responsible use

This project reads publicly available YouTube data directly from the web rather than through the official API — strictly outside what YouTube's Terms of Service permit, even though that's common practice for personal tools like this.

• Personal use — read-only public data, no login, low volume: low risk. Keep it that way.
• Commercial or high-volume use — not recommended. Scaling it up, reselling data, or hammering YouTube meaningfully raises the risk of rate-limits, IP blocks, or takedown requests.
• Never point it at private, age-restricted, or members-only content — the tools intentionally fail instead of bypassing.
• No user-supplied YouTube Data API key is required — the project dynamically extracts YouTube's INNERTUBE_API_KEY from YouTube's public page configuration. This does not imply unlimited access, guaranteed uptime, unlimited requests, or immunity from YouTube rate limits.

Use it at your own risk; this project is not affiliated with YouTube or Google. The code itself stays MIT-licensed — this section is guidance about how you use it against YouTube, not a restriction on the code.

📄 Third-Party Licenses

This project includes third-party code under the following licenses:

Full license texts are available in THIRD_PARTY_LICENSES/.

📄 License

Released under the MIT License — free to use, modify, and redistribute.

🙏 Credits

• yt-dlp — the extraction engine underneath the data layer.
• The 10 creator (yt-*) skills come from the community GitHub collection youtube-agent-skill — installed here nearly as-is (deduplicated only), not rewritten from scratch.
• The youtube and transcript skills (scripts and docs, including every gap-fill in this README) were built and rewritten in this project.
• This project reads publicly available YouTube data; use it responsibly and respect YouTube's Terms of Service.

Made so nobody has to pay for a YouTube API key again 🎉