youtube-skillbox 0.4.1__tar.gz

youtube_skillbox-0.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hackers-reality
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

youtube_skillbox-0.4.1/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE
+include README.md
+recursive-include skills *
+recursive-include tests *
+recursive-include youtube_skillbox *
+recursive-include THIRD_PARTY_LICENSES *

youtube_skillbox-0.4.1/PKG-INFO

@@ -0,0 +1,384 @@
+Metadata-Version: 2.4
+Name: youtube-skillbox
+Version: 0.4.1
+Summary: Free YouTube research toolkit — search, keywords, competition, rank tracking, SEO scorecard, outliers, content gap, trends. No user-supplied YouTube Data API key required.
+Home-page: https://github.com/hackers-reality/youtube-skillbox
+Author: hackers-reality
+Author-email: phulariarnav@gmail.com
+Project-URL: Source, https://github.com/hackers-reality/youtube-skillbox
+Project-URL: Issues, https://github.com/hackers-reality/youtube-skillbox/issues
+Keywords: youtube seo keyword research rank tracking competition analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: yt-dlp>=2026.10.26
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+<div align="center">
+  <img src="assets/banner.svg" alt="YouTube Skillbox — 13 free YouTube skills for AI agents" width="100%">
+</div>
+
+<h1 align="center">YouTube Skillbox</h1>
+
+<p align="center">
+  <b>13 free YouTube skills for AI agents — research, transcripts, and the full creator workflow.</b><br>
+  No user-supplied YouTube Data API key · no credits · no expiry — <b>$0 forever</b>
+</p>
+
+<p align="center">
+  <a href="#-table-of-contents">Table of Contents</a> ·
+  <a href="#-demo">Demo</a> ·
+  <a href="#-the-youtube-research-skill">Research</a> ·
+  <a href="#-the-transcript-skill">Transcripts</a> ·
+  <a href="#-when-yt-dlp-cant-do-it-we-build-it">Gap-fill engine</a> ·
+  <a href="#%EF%B8%8F-the-10-creator-skills">Creator tools</a> ·
+  <a href="#-install">Install</a> ·
+  <a href="#-have-your-agent-set-it-up-for-you">Agent prompt</a>
+</p>
+
+---
+
+## ⚠️ Important Disclaimer
+
+**This tool accesses public YouTube data for research purposes only.**
+
+- Respect YouTube's [Terms of Service](https://www.youtube.com/t/terms) and [Community Guidelines](https://www.youtube.com/t/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):
+
+<div align="center">
+  <a href="https://www.youtube.com/watch?v=y9U_ZeJ713M" target="_blank">
+    <img src="assets/thumbnail.png" alt="YouTube Skillbox Demo" width="80%">
+  </a>
+  <br>
+  <sub>Click to watch on YouTube →</sub>
+</div>
+
+---
+
+## 📋 Table of Contents
+
+| Section | Description |
+|---------|-------------|
+| [📺 Demo](#-demo) | Video walkthrough of the agent using the skills |
+| [What is this?](#what-is-this) | Overview of the two-layer architecture |
+| [📺 The `youtube` research skill](#-the-youtube-research-skill) | 17 subcommands — search, keywords, compete, trends, track, scorecard, outliers, gap, channels, posts, shows |
+| [📜 The `transcript` skill](#-the-transcript-skill) | Free transcripts via yt-dlp |
+| [🛠 Gap-fill engine](#-when-yt-dlp-cant-do-it-we-build-it) | How we fill yt-dlp's gaps with raw scrapers |
+| [✂️ The 10 creator skills](#%EF%B8%8F-the-10-creator-skills) | Scripts, SEO, chapters, Shorts, and more |
+| [📦 Install](#-install) | Quick setup for any agent harness |
+| [🤖 Have your agent set it up for you](#-have-your-agent-set-it-up-for-you) | Copy-paste prompt for any coding agent |
+| [📝 Notes & limits](#-notes--limits) | Rate limits, pagination, edge cases |
+| [⚖️ Responsible use](#%EF%B8%8F-responsible-use) | Personal vs commercial use, risk notes |
+| [📄 License](#-license) | MIT License |
+| [🙏 Credits](#-credits) | yt-dlp, upstream skill sources |
+
+---
+
+## What is this?
+
+A drop-in set of **[SKILL.md](https://github.com/anthropics/skills) skills** for agent harnesses like **OpenCode** (works anywhere skills are discovered from a folder). Each skill in [`skills/`](skills/) is self-contained: a `SKILL.md` the agent reads, plus small Python tools it runs.
+
+Two layers:
+
+| Layer | Skills | Powered by |
+| ----- | ------ | ---------- |
+| **Data** (research) | `youtube`, `transcript` | `yt-dlp` + custom raw YouTube scrapers |
+| **Creator workflow** | 10 × `yt-*` | local Python scripts, zero network deps for logic |
+
+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:
+
+```mermaid
+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.
+
+| Phase | Skill | Input | Output | Purpose |
+|-------|-------|-------|--------|---------|
+| 1 | `youtube` | @handle | Channel data (sections, videos, home, profile) | Data foundation |
+| 2 | `transcript` | Top 3 video IDs | Full transcripts (JSON + timestamps) | Raw content |
+| 3 | `yt-script` | Transcripts | Hook scores (0-100) per video | Retention hooks |
+| 4 | `yt-package` | Titles + hook scores | Title/thumbnail scores + briefs | CTR optimization |
+| 5 | `youtube` | Niche + target video | Keywords, competition, scorecards | Search visibility |
+| 6 | `youtube` | Channel + niche | Outliers, competitor gaps | Growth levers |
+| 7 | `yt-retention` | Studio CSV (optional) | Drop-off points, curves | Pacing fixes |
+
+**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`:
+
+```bash
+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)
+```
+
+| Command | Returns |
+| ------- | ------- |
+| `search` | Videos matching a query — title, duration, views, channel, URL (`--gl` / `--hl` locale) |
+| `keywords` | Keyword ideas from **YouTube suggest + DuckDuckGo** — a–z + pattern expansion, scored by cross-engine demand, `Y` = trending this year |
+| `compete` | Competition score (0–100) for a keyword — views, authority, title density, entrenchment, velocity |
+| `trends` | Historical trend for a seed keyword — score trajectory, velocity, sparklines (from `keywords` runs) |
+| `track` | Where a video ranks for a keyword — with ↑↓ history across runs, kept per locale |
+| `scorecard` | SEO checklist for a video — title/desc/tags/keyword fit, 0–100 score with actionable fixes |
+| `outliers` | Videos overperforming their channel — views/subscriber ratio, finds breakout content |
+| `gap` | Content gap analysis — my seed keywords vs competitor's profile keywords |
+| `profile` | Channel About section — name, handle, subs, description, **all** keywords |
+| `sections` | One-call counts of every tab: videos / shorts / streams / shows / playlists / posts |
+| `home` | Home-tab shelves — featured video, Shorts, playlists, posts, **Featured Channels** (names + URLs) |
+| `channel` | Channel uploads (`--tab videos \| shorts \| streams`) |
+| `latest` | Most recent uploads, reverse-chronological |
+| `posts` | Community posts — text, author, date, like count, URL. **Paginated** (~10/page) |
+| `shows` | Shows tab — title, episode count, URL |
+| `playlist` | Every video in a playlist |
+| `info` | One video's exact stats — views, likes, subs, date, tags, categories, description |
+
+---
+
+## 📜 The `transcript` skill
+
+Spoken text of any video, free via yt-dlp:
+
+```bash
+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):
+
+| Gap | What yt-dlp does | Our fill |
+| --- | ---------------- | -------- |
+| **Community posts** | `/community` → `0 entries` (wontfix) | Raw `ytInitialData` scrape of `/posts` (with `/community` fallback) |
+| **Post pagination** | — | **Innertube `browse` continuation POSTs** — the exact request infinite-scroll fires when you scroll. `--limit 30` reaches ~3 pages / months back |
+| **Home sections** | `"This channel does not have a home tab"` | Home-tab shelf parser: featured video, Shorts, playlists, posts, and **Featured Channels** with URLs |
+| **Shows tab** | `0 entries` (can't parse `gridShowRenderer`) | Direct renderer parser → title, episode count, show URL |
+| **Tab counts** | one tab per invocation | `sections` probes every tab and merges yt-dlp + raw results |
+| **Locale-pinned search** | search follows your IP — `gl` is silently set to whatever country you're in, and no flag exists to change it | Raw Innertube `search` POSTs with `client.gl` / `client.hl` pinned explicitly: same rank in New York and New Delhi. Works for `search`, `keywords`, `track`, `compete`, `trends`. |
+| **Keyword competition score** | not available | Live SERP analysis: median views (log), verified %, title match density, median age, **velocity (views/day)** → 0–100 score + band (EASY/MEDIUM/HARD/SATURATED) + actionable advice |
+| **Historical keyword trends** | not available | `keywords` auto-logs score snapshots to `~/.ytdata-trendlog.json`; `trends` shows sparklines, velocity (↑/↓/→), Δ over time |
+| **Video SEO scorecard** | not available | `scorecard` audits title/desc/tags/chapters/freshness vs target keyword → 0–100 with weighted checks & fixes |
+| **Channel outliers** | not available | `outliers` finds videos where views/subs ratio exceeds threshold — breakout content regardless of channel size |
+| **Content gap analysis** | not available | `gap` compares your seed keywords vs competitor's profile keywords → unique/shared opportunities |
+
+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:
+
+| Skill | Does |
+| ----- | ---- |
+| `yt-script` | Full video script from a raw idea — 21 hook formulas, scored |
+| `yt-package` | Title + thumbnail text written and linted as one pairing |
+| `yt-seo` | Description, tags and search-facing text aimed at real queries |
+| `yt-chapters` | Validated YouTube chapters straight from a transcript |
+| `yt-shorts` | Finds the self-contained Shorts hiding inside a long video |
+| `yt-edit` | Transcript → edit decision list (dead air, fillers, retakes) |
+| `yt-retention` | Reads a Studio retention export, says where viewers leave |
+| `yt-viral` | What's actually working in a niche, ranked by channel-beat |
+| `yt-plan` | A week/month content calendar sized to real capacity |
+| `yt-comment` | Drafts comment replies in the creator's voice, triaged |
+
+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`](https://github.com/yt-dlp/yt-dlp):
+
+```bash
+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.
+
+Then, from this repo — point the installer at **your agent's skills directory** (where it discovers `SKILL.md` files):
+
+```bash
+./install.sh "/path/to/your/agents/skills"          # Linux / macOS — e.g. ~/.config/opencode/skills
+```
+
+```powershell
+.\install.ps1 "C:\path\to\your\agents\skills"       # Windows — e.g. %USERPROFILE%\.config\opencode\skills
+```
+
+…or by hand — copy any folder from [`skills/`](skills/) there yourself:
+
+```bash
+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**:
+
+```text
+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.
+
+## 📄 License
+
+Released under the **[MIT License](LICENSE)** — free to use, modify, and redistribute.
+
+## 🙏 Credits
+
+- **[yt-dlp](https://github.com/yt-dlp/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.
+
+<p align="center">Made so nobody has to pay for a YouTube API key again 🎉</p>