# Youtube Planner

> YouTube source intelligence dashboard. Tracks channel videos, pulls transcripts, monitors view velocity (VPH), and generates a sortable HTML dashboard showing trending videos with sparkline charts. Use when you want to analyze source channel performance, track viral videos, plan content strategy, or add new channels to track.

- Skill: `harperaa/youtube-planner` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add harperaa/youtube-planner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/harperaa/youtube-planner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: harperaa (https://skillmd.com/u/harperaa)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/harperaa/youtube-planner

---


# YouTube Planner

YouTube source intelligence dashboard. Monitors tracked channels, tracks view velocity, and surfaces trending videos with visual trend charts.

## When to use this skill

- User invokes `/youtube-planner` or `youtube-planner`
- User asks to "add [channel] to sources" or "track [channel]"
- User wants to "update the dashboard" or "refresh source data"
- User asks about source video performance or trending content

## What it does

1. **Fetches latest videos** from tracked channels (configured in `sources.json`)
2. **Pulls transcripts** (via youtube-full skill, respecting cache)
3. **Tracks metadata over time** — saves timestamped snapshots to calculate VPH and trends
4. **Generates dashboard** — sortable HTML table with sparkline charts showing view trajectory

## Setup

Add tracked channels to `sources.json`:

```json
{
  "sources": [
    "@realrobtheaiguy",
    "@aiadvantage",
    "@matthewberman"
  ]
}
```

## How to run

```
youtube-planner
```

Or target specific date:

```
youtube-planner --date 2026-02-16
```

## Workflow

### 1. Fetch latest videos for each tracked channel (Python script)

**Use direct Python/curl approach** for efficient batch processing:
- Read channels from `sources.json`
- Fetch latest 15 videos from each channel (free endpoint) using curl in parallel
- Save each to `workspace/group/youtube/{date}/{channel-name}/latest.json`
- **First run**: Filter to videos published in last 30 days
- **Subsequent runs**: Filter to videos published in last 24 hours

**First run detection**: Check if any metadata files exist in `workspace/group/youtube/`. If empty, this is the first run.

### 2. Process all videos (Python script)

**Use direct Python script** to process all videos efficiently:

1. Collect all videos from `latest.json` files that match the time range
2. For each video:
   - Check transcript cache: `find workspace/group/youtube -path "*/{channel-slug}/{title-slug}/transcript.txt"`
   - If not found, fetch transcript via curl to TranscriptAPI
   - Save transcript.json and transcript.txt
   - Always save new metadata snapshot to `metadata/{timestamp}.json`
3. Use rate limiting (0.25s between API calls) to respect API limits
4. Process in batches or all at once depending on count

**Python approach is faster and more reliable** than spawning hundreds of agents.

### 3. Generate dashboard

Run the dashboard generator:

```bash
python3 .claude/skills/youtube-planner/generate-dashboard.py
```

Output: `workspace/group/youtube/dashboard.html`

## Dashboard features

- **Sortable columns**: Click headers to sort by VPH, views, date
- **Default sort**: Highest VPH (views per hour since publish)
- **Columns**: Thumbnail, Title, Channel, Published, Views, VPH, Trend
- **Trend sparklines**: Mini chart showing view count progression from all metadata snapshots
- **Click thumbnails**: Opens video in new tab

## Trend visualization

The Trend column shows an inline sparkline chart based on all metadata files in `metadata/`:

- **X-axis**: Time (from first snapshot to latest)
- **Y-axis**: View count
- **Visual**: SVG mini line chart (80px × 30px)
- **Color**: Green if accelerating, red if decelerating, gray if flat

Example progression:
```
metadata/2026-02-16-0800.json → 1,200 views
metadata/2026-02-16-1200.json → 2,500 views
metadata/2026-02-16-1600.json → 4,100 views
```

Sparkline shows upward curve → green chart

## File organization

```
workspace/group/youtube/
  dashboard.html
  2026-02-16/
    rob-the-ai-guy/
      latest.json
      google-geminis-new-upgrades/
        transcript.txt
        transcript.json
        metadata/
          2026-02-16-0800.json
          2026-02-16-1200.json
          2026-02-16-1600.json
```

**VPH calculation**: `views / hours_since_publish`

**Trend direction**: Compare VPH from last 2 snapshots:
- If latest VPH > previous VPH by 10%+: accelerating (green)
- If latest VPH < previous VPH by 10%+: decelerating (red)
- Otherwise: flat (gray)

## Files created

| Path | Purpose |
|------|---------|
| `workspace/group/youtube/dashboard.html` | Sortable table with sparkline charts |
| `workspace/group/youtube/{date}/{channel}/latest.json` | Channel's latest 15 videos |
| `workspace/group/youtube/{date}/{channel}/{video}/transcript.txt` | Cached transcript |
| `workspace/group/youtube/{date}/{channel}/{video}/metadata/{datetime}.json` | Timestamped view count snapshot |

## Rules

- **First run behavior**: Pull all videos from last 30 days to bootstrap data
- **Subsequent runs**: Only process videos from last 24 hours to track recent uploads
- Transcript is cached forever (never re-fetch unless user says "refresh")
- Metadata is NEVER cached — always save new timestamped file in `metadata/` subdirectory
- Dashboard updates every time skill runs
- Channel list is in `sources.json` at skill base directory
- Sparklines render for videos with 2+ metadata snapshots

## Adding new sources

When the user asks to add a new channel (e.g., "add @ChannelHandle to sources"), automatically:

1. **Update sources.json**:
   ```bash
   # Read current sources
   sources=$(cat .claude/skills/youtube-planner/sources.json)
   # Add new channel to the list
   # Use Edit tool to add the channel
   ```

2. **Fetch last 30 days of data**:
   ```bash
   python3 .claude/skills/youtube-planner/catch-up-channel.py @ChannelHandle
   ```

3. **Regenerate dashboard**:
   ```bash
   python3 .claude/skills/youtube-planner/generate-dashboard.py
   ```

**Important**: Always use the catch-up script for new channels to bootstrap with 30 days of historical data, even if other channels are in "24-hour mode".

## Example usage

```
# First run: Fetches all videos from last 30 days
youtube-planner

# Subsequent runs: Only fetch videos from last 24 hours
youtube-planner

# Force specific date range (override auto-detection)
youtube-planner --date 2026-02-15

# Add new tracked channel (handled automatically)
# User says: "add @DanKoeTalks to sources"
# Skill will: update sources.json → fetch 30 days → regenerate dashboard
```

## Output

At the end, confirm:
- Number of channels checked
- Number of new transcripts fetched (API credits used)
- Number of metadata snapshots saved
- Dashboard location: `workspace/group/youtube/dashboard.html`