mkt-youtube-topic-researcher

name

mkt-youtube-topic-researcher

description

Research YouTube videos by topic/keyword — filter by views, subscriber count, and breakout ratio (views/subs). USE WHEN user says 'research video theo chủ đề', 'tìm video nhiều views', 'research youtube topic', 'tìm video theo keyword', 'youtube research', 'tìm video hot theo chủ đề', 'search youtube by topic', 'video nào nhiều views về', 'research video ideas', 'tìm video breakout theo topic', 'phân tích video theo keyword'.

YouTube Topic Researcher

Tìm kiếm và phân tích video YouTube theo chủ đề/keyword. Lọc theo số views tối thiểu, tính breakout ratio (views ÷ subscribers) để phát hiện video overperform. Giúp nghiên cứu nội dung trước khi sản xuất video.

---

When to Use

• User muốn research video YouTube theo một chủ đề cụ thể
• User muốn tìm video nhiều views trong một lĩnh vực
• User muốn phân tích video nào đang overperform (breakout) theo topic
• User muốn so sánh performance các video cùng chủ đề

---

Prerequisites

1. API Key trong .env:

   YOUTUBE_API_KEY=your_key_here
   

2. YouTube Data API v3 đã enable tại Google Cloud Console

---

Usage

Cú pháp

uv run .claude/skills/mkt-youtube-topic-researcher/scripts/research_topic.py "KEYWORD" [OPTIONS]

Options

Option	Mô tả	Mặc định
KEYWORD	Từ khóa tìm kiếm (bắt buộc)	—
--min-views	Số views tối thiểu	10000
--date	Khoảng thời gian: today, week, month, year	month
--max-results	Số kết quả tối đa	20
--sort	Sắp xếp: views, ratio, date, relevance	views
--lang	Lọc ngôn ngữ (vd: vi, en)	không lọc
--output	Đường dẫn file output	auto: research/youtube/topics/[slug]/videos.json
--no-save	Chỉ in ra terminal, không lưu file	false

Ví dụ

# Tìm video về "claude code" nhiều views nhất tháng này
uv run .claude/skills/mkt-youtube-topic-researcher/scripts/research_topic.py "claude code"

# Tìm video AI agents, ít nhất 50K views, trong tuần
uv run .claude/skills/mkt-youtube-topic-researcher/scripts/research_topic.py "ai agents" --min-views 50000 --date week

# Sắp xếp theo breakout ratio
uv run .claude/skills/mkt-youtube-topic-researcher/scripts/research_topic.py "mcp server" --sort ratio

# Video tiếng Việt về AI
uv run .claude/skills/mkt-youtube-topic-researcher/scripts/research_topic.py "AI automation" --lang vi --min-views 5000

# Chỉ in ra terminal
uv run .claude/skills/mkt-youtube-topic-researcher/scripts/research_topic.py "vibe coding" --no-save

---

Output

Bảng tóm tắt (terminal)

Script in ra bảng tóm tắt dạng:

╔═══════════════════════════════════════════════════════════════════╗
║  YouTube Topic Research: "claude code"                           ║
║  Filters: min 10,000 views | month | sorted by views            ║
║  Found: 15 videos                                                ║
╚═══════════════════════════════════════════════════════════════════╝

 #  | Title                          | Channel        | Views    | Subs     | Ratio | URL
----|--------------------------------|----------------|----------|----------|-------|---------------------------
 1  | Claude Code Changed Everything | @TechGuy       | 245,000  | 50,000   | 4.9x  | youtu.be/abc123
 2  | How I Use Claude Code Daily    | @AIBuilder     | 180,000  | 120,000  | 1.5x  | youtu.be/def456
...

JSON output (videos.json)

{
  "metadata": {
    "query": "claude code",
    "date_filter": "month",
    "min_views": 10000,
    "sort_by": "views",
    "language": null,
    "searched_at": "2026-04-03T23:55:00Z",
    "total_results": 15
  },
  "videos": [
    {
      "rank": 1,
      "title": "...",
      "video_id": "abc123",
      "url": "https://www.youtube.com/watch?v=abc123",
      "channel": "TechGuy",
       
       
       
       
       
       
       
       
       
    
  

File location

research/youtube/topics/[slug]/videos.json

Slug được tạo từ keyword: "claude code" → claude-code

---

API Quota

API Call	Cost	Per Run (20 results)
search.list	100 units	100 units
videos.list (stats + details)	1 unit	1 unit (batch)
channels.list (subscriber counts)	1 unit	~5-10 units
Total		~110 units

Daily quota: 10,000 units → ~90 searches/ngày.

---

Workflow khi nhận yêu cầu

Bước 1: Xác định keyword và filters

Hỏi user nếu chưa rõ:

• Keyword/chủ đề muốn research?
• Có yêu cầu gì về minimum views không?
• Khoảng thời gian nào?

Bước 2: Chạy script

uv run .claude/skills/mkt-youtube-topic-researcher/scripts/research_topic.py "KEYWORD" --min-views MIN --date DATE --sort SORT

Bước 3: Trình bày kết quả

• Hiển thị bảng tóm tắt
• Highlight top 5 video breakout (ratio cao nhất)
• Gợi ý insights từ kết quả (patterns về title, channel size, timing)

Bước 4: (Tùy chọn) Phân tích sâu

Nếu user muốn đi sâu hơn:

• Lấy transcript của top videos (dùng skill youtube-transcript)
• Phân tích content strategy (dùng skill mkt-competitor-video-strategy-analyzer)
• Bóc insight (dùng skill mkt-insight-extractor)

---

Troubleshooting

Lỗi	Nguyên nhân	Giải pháp
YOUTUBE_API_KEY not found	Key chưa set	Thêm vào .env
403 Forbidden	API key sai hoặc quota hết	Kiểm tra Google Cloud Console
No videos found	Keyword quá specific hoặc min-views quá cao	Hạ min-views, mở rộng date range
quotaExceeded	Hết quota hàng ngày	Chờ reset (Pacific midnight) hoặc dùng key khác