Skip to main content
skill CX Codex

youtube-stats — Claude Code skill for YouTube analytics

The youtube-stats Claude Code skill gathers performance data for published YouTube videos and channels. It runs for requests about views, retention, traffic sources, or which videos performed well.

MIT 354 installs ★ 2,697 updated 2026-10-21

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add digitalsamba/claude-code-video-toolkit --skill youtube-stats -a claude-code
Open on GitHub

What youtube-stats does

The skill runs tools/youtube_stats.py to report views, likes, comments, and subscribers per video, alongside watch time, retention, and traffic sources. Each run stores a snapshot in _internal/.youtube/stats/<account>/, allowing later runs to show changes. The --github flag adds repository referrals from the last 14 days.

Views, likes, and comments use the cached token from youtube_upload.py --auth --account NAME. Watch time, retention, and traffic sources require the YouTube Analytics API and the https://www.googleapis.com/auth/yt-analytics.readonly scope. Enable the API in the uploader’s Google Cloud project, add the scope, then refresh the token with uv run --extra youtube tools/youtube_stats.py --auth --account personal. Analytics trails by 1–2 days. The API may reject impressions and click-through rate, which remain visible in Studio.

What it helps with

  • compare views, likes, and subscribers across published videos
  • identify the traffic sources sending viewers to a video
  • check a video’s retention and watch time
  • compare YouTube referrals with GitHub traffic

Example prompts for the agent

  • Show my YouTube channel stats and compare them with the previous snapshot.
  • Check retention and traffic sources for video 1hyDgC5Qg_o.
  • Compare YouTube stats with repository referrals from the last 14 days.

How to install youtube-stats

1Skills CLI (Vercel)

npx skills add digitalsamba/claude-code-video-toolkit --skill youtube-stats -a claude-code

2Manually: put the files in place

~/.claude/skills/youtube-stats/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/youtube-stats/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about youtube-stats

How do I install youtube-stats in Claude Code?

Run npx skills add digitalsamba/claude-code-video-toolkit --skill youtube-stats -a claude-code. The skill file is placed at ~/.claude/skills/youtube-stats/SKILL.md.

What does youtube-stats do?

It gathers channel and video metrics, saves snapshots for comparison, and can include referrals to GitHub. The reports cover views, retention, and traffic sources.

What does youtube-stats need to work?

Views, likes, and comments use the cached token from youtube_upload.py. Watch time, retention, and traffic sources require the YouTube Analytics API and the https://www.googleapis.com/auth/yt-analytics.readonly scope; refresh the token with uv run --extra youtube tools/youtube_stats.py --auth --account personal after enabling the API and adding the scope.

Source text

SKILL.md · MIT
---
name: youtube-stats
description: How published videos are doing on YouTube, and what to learn from it. Views, likes, comments and subscribers per video, plus watch time, retention and traffic sources (Shorts feed, search, external) with the Analytics scope, saved as snapshots so trends show; GitHub traffic beside it to see whether YouTube sends people to the repo. Use when asked how a video or the channel is doing, which title, cover or genre worked, whether to make more of something, or for a weekly stats check.
---

# YouTube stats

```bash
uv run --extra youtube tools/youtube_stats.py --account personal                 # every upload, newest first
uv run --extra youtube tools/youtube_stats.py --account personal --video 1hyDgC5Qg_o e4HW-tvi8-8 --since 7d
uv run --extra youtube tools/youtube_stats.py --account personal --github --json  # plus repo referrers
```

Each run saves a snapshot to `_internal/.youtube/stats/<account>/` and reports the change since the last one, so a
daily or weekly run is the trend. `--no-save` for a look without a snapshot.

## Setup

It reuses the token `youtube_upload.py --auth --account NAME` cached, so views, likes and comments work at once.
Watch time, retention and traffic sources need the YouTube Analytics API:

1. Google Cloud Console, the uploader's project: **APIs & Services → Library → YouTube Analytics API → Enable**.
2. **OAuth consent screen → Data access → Add or remove scopes**: add
   `https://www.googleapis.com/auth/yt-analytics.readonly`. It is a sensitive scope, the same class as the
   `youtube` scope the uploader already has, so the consent screen should behave as it did at the first login.
3. `uv run --extra youtube tools/youtube_stats.py --auth --account personal`: one consent that asks for the upload
   scopes and Analytics together and replaces the cached token, so the uploader keeps working.

Impressions and click-through rate are asked for separately: the metrics reference lists them, but the API has
refused them in the past. When it refuses, the report says so; Studio still shows them.

## Reading it

- **A Short lives or dies in the feed.** Traffic source `SHORTS` is the feed; `YT_SEARCH`, `EXT_URL` (links from
  the README, chat) and `SUBSCRIBER` are the rest. A Short with views only from `EXT_URL` was never pushed by the
  feed: change the cover frame and first second, not the title.
- **A Short's views stay on the Short unless it points somewhere.** Compare its views with the long video's and
  with `youtube.com` in the repo referrers. Give it a way on: the long video as its related video (set by hand in
  Studio; `youtube_upload.py` says when), and the link in its description and a pinned comment.
- **Average view percentage is the Short's real score.** Over 100% means people loop it. Under ~50% on a 60-90 s
  Short means the hook or the middle lost them; check where with Studio's retention graph.
- **Long videos: impressions × CTR × view duration.** A low CTR is the title or thumbnail; a short duration is the
  opening.
- **YouTube lags.** Analytics is 1-2 days behind, and a new Short's first 48 hours are the feed testing it; judge
  after a week.
- **The repo is the goal.** `--github` shows the last 14 days of repo referrers; `youtube.com` appearing there is
  the signal that a video sends people to the toolkit.

## Before the next Short

What the numbers above point at is nearly always the opening. Three things to settle while planning, each of
which `qc.py --render` then measures on the finished file (and `--layout` for the text):

- **The first 2 seconds.** Start on the action: movement, a strong picture or a line already being said. Cut the
  lead-in, the establishing shot and any pause before the first word.
- **Text from the first frame.** A short line that says what the viewer gets by staying. Frame 0 is also the
  cover, so the same line sells the video in a grid.
- **Something new every few seconds.** A cut, a push in, a new piece of text. The check reports how long the
  first shot runs and warns past 5 s.

Treat these as defaults to depart from on purpose, and let the retention graph say whether the departure
worked: a slow opening that people watch through is a finding worth writing below.

## What has worked on Shorts

Findings, not numbers: write each as what changed and what happened, with the dates, once there is a week of data.

- 2026-11-08, baseline: You're On Mute (`1hyDgC5Qg_o`) and The Great Return (`e4HW-tvi8-8`) public for about a
  day, 1 and 0 views; channel 26 subscribers. The repo got ~10k unique visitors in 14 days, mostly from Google,
  none from YouTube yet.

© digitalsamba · MIT · digitalsamba/claude-code-video-toolkit

Similar skills

All skills for Marketing and content →

From the same set13

The whole set →
video_toolkit video_toolkit builds short explainer videos from a brief through background jobs with quality control checks. CX Codex +1 1,500installs qwen-edit qwen-edit is a Claude Code skill that prepares prompts and settings for image edits with Qwen-Image. It activates for photo changes such as reframing, outfit edits, pose adjustments, and style transfers. CX Codex +1 1,500installs runpod A skill for running open-source AI models on cloud GPUs through RunPod serverless. Useful when a job needs more VRAM than your machine has. CX Codex +1 1,400installs ideogram4 Generates images with legible in-image text and brand color control via Ideogram 4. Useful for video title cards and thumbnails. CX Codex +1 978installs synthetic-ui-demo The synthetic-ui-demo Claude Code skill builds product videos without screen recording. It recreates selected app screens in React, then scripts cursor and camera movement in Remotion. CX Codex +1 614installs video-design video-design is a Claude Code skill that defines typography scales, act palettes, and layout rules for 16:9 and 9:16 video scenes. Runs during slide styling and scene critique. CX Codex +1 588installs parody-short The parody-short Claude Code skill helps create comedy shorts about a team, family, or shared event in a chosen genre. It activates on requests for a parody, holiday video, or animated photos of people. CX Codex +1 334installs blender blender is a Claude Code skill that turns a JSON shot spec into Blender footage. It handles character animation, product shots, and clips for Remotion. CX Codex +1 255installs

Project sponsors

Companies that keep this analytics open