--- name: youtube-weekly-channel-report description: "Every Wednesday: last week's YouTube views, watch hours and subscribers against the week before, with the top three videos and new uploads. Use when the user asks for this, or when it runs on a schedule." --- # YouTube Analytics weekly channel report Every Wednesday: last week's YouTube views, watch hours and subscribers against the week before, with the top three videos and new uploads. YouTube Studio defaults to the last 28 days and keeps changing its realtime numbers, so a clean week-on-week comparison means setting custom dates every time. Creators and marketing teams who report weekly end up with screenshots instead of numbers. The agent asks the YouTube Analytics API for last Monday to Sunday and the week before, for views, watch time and subscribers, then finds the three videos that drew the most views and how this week's uploads did. It runs on Wednesday because YouTube needs a couple of days to settle the numbers. ## Two ways to get the data Use the API or MCP route when you have an MCP server, a CLI or an API token for the app. Otherwise, if you can drive a browser the user is signed in to (Claude in Chrome, a Playwright or Chrome DevTools MCP server), use the browser route. Say which one you used. ## Route A: API or MCP server ### What you need - A Google account that owns or manages the channel, authorized with the `yt-analytics.readonly` and `youtube.readonly` OAuth scopes. - For a brand account, authorize as a user with access to that channel and choose the channel during sign-in. If something is missing, say what and stop; do not invent numbers. ### Steps 1. **Pull channel totals by day** (YouTube): YouTube Analytics API `reports.query` with `ids=channel==MINE`, `startDate` and `endDate` for last Monday to Sunday, `metrics=views,estimatedMinutesWatched,averageViewDuration,subscribersGained,subscribersLost` and `dimensions=day`. Repeat for the week before. 2. **Find the top videos** (YouTube): The same call with `dimensions=video`, `metrics=views,estimatedMinutesWatched,subscribersGained`, `sort=-views` and `maxResults=10`. Get titles with the Data API `videos.list` (`part=snippet`, up to 50 IDs per call). 3. **List the week's uploads** (YouTube): `channels.list?part=contentDetails&mine=true` gives the uploads playlist; `playlistItems.list` on it returns recent uploads with `publishedAt`. Report each new video's views so far next to the channel's typical first-week views. 4. **Report**: Views, watch hours (minutes divided by 60) and net subscribers with the weekly change, the top three videos with views and watch hours, and how the new uploads are doing. ## Route B: the browser ### What you need - Signed in to Google as the channel owner or a manager of the brand channel; Studio needs at least the Viewer role on the channel. The person picks the channel first. If something is missing, say what and stop; do not invent numbers. ### Steps Start at https://studio.youtube.com/. The user is signed in already; never type passwords or codes, and ask if a sign-in page appears. 1. **Open Analytics in Advanced mode**: Studio opens on the channel of the signed-in account; switch channels from the avatar menu if needed. Go to **Analytics** and click **Advanced mode** at the top right. Set the date picker to **Custom** with last Monday to Sunday. 2. **Compare with the week before**: Click **Compare to** > **Previous period**. On the **Channel** level read views, watch time (hours), average view duration and subscribers for both weeks; the table under the chart shows the day-by-day numbers, so note the best and worst day. 3. **Find the top videos**: Switch the breakdown to **Video** (or open the **Content** tab) with the same dates, add the **Subscribers** metric, and sort by **Views**. Take the top three with views, watch time and subscribers gained. 4. **Check the week's uploads**: Go to **Content** in the left menu, filter by **Date** for last week, and read each new video's views so far. Compare with what your videos usually reach in their first week, from the same list with an older date range. Note: Advanced mode shows 50 rows at a time, enough for weekly top videos. Studio's realtime cards are estimates; the Advanced mode table for completed days is what matches the API. Numbers for the last two days can still move. ## The report - **Views**, **watch hours** and **net subscribers** last week, with the change. - **By day**: the best and worst day. - **Top three videos**: views, watch hours, subscribers gained. - **New uploads** and how they compare with your usual first week. - One line on what worked. ## Post it to Briefkin When `BRIEFKIN_TOKEN` is set, or `~/.config/briefkin/env` exists (the installer from https://briefkin.dev/docs writes it), also send the result to the user's Briefkin board as one card. Keep the `item_key` the same on every run so the card updates in place, use a new `event_id` per run, and put today's real numbers in place of the example ones. If the request fails, say so once and carry on. ```bash [ -n "${BRIEFKIN_TOKEN:-}" ] || . ~/.config/briefkin/env curl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \ -H "authorization: Bearer $BRIEFKIN_TOKEN" \ -H "content-type: application/json" \ -d @- <<'JSON' { "v": 1, "event_id": "youtube-weekly-channel-report/", "item_key": "youtube-weekly-channel-report", "project": "Acme Channel", "source": "YouTube Analytics weekly channel report skill", "kind": "update", "title": "Views up 22% last week, led by one Short", "summary": "**48,200** views and **2,140** watch hours last week. Net subscribers **+312**. One Short brought 14,800 views, a third of the week.", "widget": [ { "type": "Grid", "props": { "columns": 3 }, "children": [ { "type": "Stat", "props": { "label": "Views", "value": 48200, "delta": 22 } }, { "type": "Stat", "props": { "label": "Watch hours", "value": 2140, "delta": 9 } }, { "type": "Stat", "props": { "label": "Net subscribers", "value": 312, "delta": 41 } } ] }, { "type": "Table", "props": { "columns": [ "Video", "Views", "Watch hours", "Subscribers" ], "align": [ "left", "right", "right", "right" ], "rows": [ [ "The 30-second desk setup fix (Short)", "14,800", 62, 118 ], [ "Building a standing desk from scratch", "9,450", 712, 74 ], [ "5 cable management mistakes", "6,130", 388, 39 ] ] } }, { "type": "Callout", "props": { "text": "Last Tuesday's upload reached 9,450 views by Sunday, about 40% above your usual first week.", "tone": "ok" } } ] } JSON ``` Widgets come from the Briefkin catalog (https://briefkin.dev/v1/catalog). Without a token, just give the user the report. ## Run it on a schedule Suggested: Wednesdays at 9:00 (`0 9 * * 3`). From cron, with the agent signed in on that machine: ```bash 0 9 * * 3 claude -p "Run the youtube-weekly-channel-report skill" # Codex: codex exec, Gemini CLI: gemini -p, Copilot CLI: copilot -p, OpenCode: opencode run ``` Or use the agent's own scheduler (Claude Code routines, Codex automations, Claude or ChatGPT scheduled tasks): https://briefkin.dev/skills/youtube-weekly-channel-report#schedule Source: https://briefkin.dev/skills/youtube-weekly-channel-report