A YouTube Research Agent is a Claude Code setup built from three plain text files in a .claude folder. It pulls data from the free YouTube Data API and a web research tool, then runs five modes, content gaps, keyword research, channel audits, Shorts research, and thumbnail analysis, tuned to your niche and named competitors instead of generic data.
What you will be able to do
- Set up a YouTube Research Agent in Claude Code using three files: an agent YAML file plus context profile markdown files.
- Run five research modes, --discover, --topic, --audit, --shorts, --thumbnails, to cover content gaps, keyword research, competitor audits, Shorts research, and thumbnail patterns.
- Connect the free YouTube Data API (10,000 units/day) and a web research MCP, Perplexity or Tavily, as your data layer.
- Write a custom signal score formula that ranks video opportunities by views relative to channel subscriber count, comments, and likes, instead of raw view count.
- Control API costs by writing explicit cost limits into the agent file so Claude does not burn through your daily quota.
Before you start
- VS Code installed (free), ideally with the Claude Code extension.
- A YouTube Data API key from Google Cloud Console (free tier, 10,000 units/day).
- Either a Perplexity API key (paid) or a Tavily account (1,000 free credits/month) for web research.
- Basic familiarity with Claude Code agents, the article points to a separate primer on building your first Claude Code agent for this.
Reference
| Item | Detail |
|---|---|
| --discover | Content gap analysis on a topic: what exists, what's missing, what angle isn't covered yet |
| --topic [keyword] | Deep research on a specific keyword: search volume signals, competitor video performance, trending angles |
| --audit | Channel audit for a named competitor: top performers, content patterns, gaps |
| --shorts | Shorts-specific research: which formats and topics convert well |
| --thumbnails | Thumbnail and title pattern analysis: which title structures get the most clicks in your niche |
| YouTube Data API quota | 10,000 free units/day; each search costs roughly 100 units, about 100 searches/day |
| Tavily free tier | 1,000 free credits/month (Perplexity requires a paid key from day one) |
| Signal score formula | signal_score = (views / channel_subscribers) * (comments + likes) * recency_weight |
Common errors and fixes
| What goes wrong | The fix |
|---|---|
| Claude makes hundreds of YouTube API calls in a single session | Write explicit cost limits in plain English into the agent file (Layer 3) before running research |
| You hit your daily YouTube API quota within minutes | Set the cost limit once in the agent file; it holds permanently after that |
| Research output is generic, the same gaps every other creator would see | Fill out the three context profiles, business-context.md, content-strategy.md, competitor-watch-list.md, so the agent loads your niche and named competitors before it queries the API |
| You never revisit or act on the research because raw markdown is hard to read | Pick an output format that fits how you think, Notion, Obsidian, Google Docs, or a custom hub, instead of leaving output as loose markdown files |
| Hesitation to start because the tool is called "Claude Code" and sounds like it requires coding | You describe what you want in plain English; Claude Code handles the implementation, no code required |
Read the full walkthrough
The complete lesson, with screenshots and any downloads, is published on Substack as part of PubFlow OS Agents: Build Your AI Research Team.
Continue the course
Browse all lessons in the PubFlow OS Agents: Build Your AI Research Team course, or subscribe to the GenAI Unplugged newsletter to get new lessons in your inbox.
