TubeGrade

View saved version →

---
name: tubegrade-comment-insights
description: Mine YouTube comments for what viewers actually ask, want, complain about and praise — in their own words — and turn it into video ideas, title language and script fixes. Use for "what do viewers want", "analyze the comments on this video", "find content gaps from comments".
---

# Comment insights

Read `references/tubegrade-tools.md` first.

Goal: viewer demand and language, counted honestly from a bounded sample.

## 1. Scope
Pick the sample:
- **Specific videos** the user names, or
- **A topic**: find 3–5 relevant, well-performing videos with
  `tubegrade_find_outliers` or `tubegrade_search_videos` (5–10 credits), or
- **A channel**: `tubegrade_get_channel_outliers` or `tubegrade_channel_videos`
  and take its 3–5 most relevant recent videos.

## 2. Collect — ≈ 15–30 credits
`tubegrade_get_comments` per video (5 each), `limit` 50–100, `sort` top. Add a
`newest` pull on one video only if recent reactions matter (e.g. a fresh
upload). Keep the sample to 5 videos unless the user asks for more.

If the user wants to know what a video *said* that triggered reactions,
`tubegrade_get_transcript` (10) on that one video.

## 3. Analyse
Read every comment you pulled. Sort them into:
- **Questions** — things viewers asked that the video didn't answer
- **Requests** — "do a video on…", "part 2", follow-ups
- **Pain points / objections** — confusion, disagreement, problems
- **Praise** — what specifically landed (a moment, an explanation, a format)
- **Language** — the exact phrases viewers use for the problem and outcome

Count how many comments fall into each theme across the sample (approximate
is fine; say "about"). Weigh likes: a highly liked comment speaks for many.
Ignore spam, self-promotion and pure emoji.

## 4. Deliver
1. **Sample** — the videos (linked) and how many comments you read.
2. **Top themes** — ranked, each with an approximate count and 1–2 short,
   representative quotes (trimmed; no usernames).
3. **Video ideas** — 3–5 directly from unanswered questions and requests.
4. **Words to use** — viewer phrases for titles, hooks and thumbnails.
5. **Fixes** — if these are the user's own videos, what to clarify or add.

## Don't
- Quote comments without the commenter's name unless the user asks who said
  it; `isChannelOwner` marks the creator's own replies.
- Don't generalise beyond the sample — say how many comments and videos it covers.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: tubegrade-competitor-breakdown
description: Break down a rival YouTube channel — size and growth, which videos over-perform for it and why, its packaging style, how its best videos open — and turn it into opportunities for the user. Also finds who a channel's real competitors are. Use for "analyze @channel", "how is my competitor growing", "who are my competitors", "track this channel".
---

# Competitor breakdown

Read `references/tubegrade-tools.md` first.

Goal: what is working for a competitor, backed by numbers, and what the user
should do about it.

## 1. Scope
- **Breakdown of one channel**: you need its handle or URL. Knowing the user's
  own channel makes the "what it means for you" part sharper — ask once.
- **"Who are my competitors?"**: run `tubegrade_similar_channels` (5) on the
  user's channel, and `tubegrade_my_competitors` (2) if they track any. Present
  the list with sizes and links; offer to break one down or track them.
- **"Track this channel"**: `tubegrade_track_competitor` (free) — only on request.

## 2. Evidence — budget ≈ 30–45 credits (+ optional transcripts)
1. `tubegrade_get_channel` — size, average views, upload frequency, and the
   `growth` block when present.
2. `tubegrade_get_channel_outliers` — its breakout videos vs its own baseline.
3. `tubegrade_channel_videos` (`popular`) — what built the channel, versus its
   recent outliers (what works now).
4. `tubegrade_channel_thumbnails` (`recent`, `limit` 10–12) — look at the style.
5. Optional, ask first: `tubegrade_get_transcript` on its top 1–2 recent
   outliers (10 each) to study the hooks.

## 3. Analyse
- **Trajectory**: growing, flat or declining (from `growth`; say if there is no
  history yet). Multiply per-period averages by the gap for totals.
- **What over-performs**: cluster the outliers by topic, format and title
  pattern. Which clusters repeat? What has stopped working (popular-but-old vs
  recent)?
- **Packaging style**: what their thumbnails consistently do.
- **Hooks** (if transcripts): how the openings earn attention.
- **Gaps**: topics their audience clearly wants (outliers, or demand in
  comments if checked) that they cover rarely or poorly.

## 4. Deliver
1. **Snapshot** — subscribers, average views, upload cadence, trajectory.
2. **What works for them** — 3–5 patterns, each with linked example videos and
   their outlier ratios.
3. **Packaging style** — 3–4 observations from the thumbnails.
4. **Opportunities for the user** — 3–5 concrete moves (topics, formats,
   angles), each tied to the evidence and adapted to the user's channel.
5. Offer: track this channel (free, if their account includes tracking), or
   hand-offs → **tubegrade-video-ideas**, **tubegrade-packaging-studio**.

## Don't
- Don't speculate about a competitor's revenue, private analytics, or contact
  details.
- Don't recommend copying their videos; recommend the mechanism.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: tubegrade-get-started
description: Start here with TubeGrade — what it can research on YouTube, how credits work, checking the balance, and fixing errors (not enough credits, indexing, missing fingerprints, tracking not available). Use for "what can TubeGrade do", "how many credits do I have", or when a TubeGrade call fails.
---

# TubeGrade — get started

Read `references/tubegrade-tools.md` before answering anything about tools,
costs or errors.

## When this applies
- The user is new to TubeGrade or asks what it can do.
- They ask about their balance or what something costs.
- A TubeGrade call failed and they want to know why or what to do next.

## What TubeGrade is for
YouTube research grounded in real numbers: which videos broke out (beat their
own channel's normal views) and why, the title and thumbnail formats behind
them, how channels are growing, what viewers say in comments, and what was
actually said in videos (transcripts). Thumbnails come back as real images.

Offer the workflows that fit the user's goal:
- New ideas from breakout videos → **tubegrade-video-ideas**
- Choosing the single best next video for their channel → **tubegrade-next-video-planner**
- Titles and thumbnails for a video → **tubegrade-packaging-studio**
- A researched script with cited sources → **tubegrade-script-writer**
- Studying a rival channel → **tubegrade-competitor-breakdown**
- Why one video worked → **tubegrade-video-teardown**
- What viewers want, in their own words → **tubegrade-comment-insights**

## Balance and costs
1. Call `tubegrade_balance` (free) and report the number.
2. If they plan something specific, estimate its cost from the table in the
   tool notes and say it before running anything. A typical research session
   is 30–80 credits; bulk transcripts are the expensive part (10 each).

## Fixing errors
Match the error to the tool notes' **Errors** section and give the concrete
next step. Specific cases:
- **Not enough credits** — report the call's cost and the balance, then
  suggest the cheapest way to still answer (fewer videos, `limit` lower,
  `tubegrade_search_videos` instead of bulk transcripts). Do not retry the
  same call.
- **Sign-in problems** — the user signs in with their TubeGrade (Google)
  account when the connection is first made; reconnecting the TubeGrade
  plugin/connector in the assistant's settings re-runs sign-in.
- **Anything else** — point to https://www.tubegrade.com/support/ (support
  email is listed there).

## Don't
- Don't run paid research just to demonstrate the tools — ask what they
  want to find out first.
- Don't describe plans, prices or ways to get more credits; if asked, point to
  https://www.tubegrade.com/support/.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: tubegrade-next-video-planner
description: Decide the single best next video for a creator's own channel, weighing what already works for them, what is breaking out with similar channels, and which title formats are rising. Use for "what should my next video be", "plan my next upload", "which of these ideas should I make first".
---

# Next video planner

Read `references/tubegrade-tools.md` first.

Goal: ONE recommended next video (plus two runners-up), justified by the
user's own channel and by what is working for channels like theirs.

## 1. Scope
You need the user's channel (handle or URL). If they gave candidate ideas,
evaluate those instead of generating new ones.

## 2. Evidence lanes — budget ≈ 50–80 credits (say so before starting)
1. **Their baseline**: `tubegrade_get_channel` (size, average views, growth)
   and `tubegrade_get_channel_outliers` (what already over-performs for them).
2. **Their peers**: `tubegrade_my_competitors` if they track any; otherwise
   `tubegrade_similar_channels` and pick 2–3. Run
   `tubegrade_get_channel_outliers` on at most 2 peers.
3. **The market**: one `tubegrade_find_outliers` on their core topic
   (`days` 180, `min_ratio` 2).
4. **Packaging climate**: one `tubegrade_viral_formats` (`kind` title, no
   filters); note which formats are emerging or rising.

Skip any lane the user's question doesn't need. If the channel is brand new
(few videos), lean on lanes 2–4 and say so.

## 3. Decide
Score each candidate topic on:
- **Proven for them** — similar topics already beat their own average
- **Proven nearby** — peers or the market show breakouts on it
- **Fresh** — recent breakouts (last 6 months), not a played-out topic
- **Feasible** — they can make it with what their channel shows
- **Packaging fit** — a strong (ideally rising) format suits it

Prefer topics with evidence in two or more lanes.

## 4. Deliver
**Make next: <working title>**
- Why: 2–3 sentences tying the lanes together
- Evidence: the specific videos (link, views, outlier ratio) from their
  channel and from peers/market
- Suggested angle and format; the proven title format it can use
- Risk: what could make it underperform

**Runners-up**: two more, one line each with their best evidence.

**What to check after publishing**: compare its first-week views with their
channel average (from `tubegrade_get_channel`).

## Hand-offs
Titles and thumbnails → **tubegrade-packaging-studio**; script →
**tubegrade-script-writer**.

## Don't
- Don't recommend a topic with evidence from a single video only, unless you
  label it low confidence.
- Don't exceed the stated budget without asking.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: tubegrade-packaging-studio
description: Write titles and design thumbnail concepts for a video, grounded in proven viral title/thumbnail formats and the actual thumbnails of breakout videos on the same topic. Also compares the user's own title or thumbnail options. Use for "title ideas for my video", "thumbnail concept", "which title is better", "improve my thumbnail".
---

# Packaging studio — titles and thumbnails

Read `references/tubegrade-tools.md` first.

Goal: titles and thumbnail concepts that use patterns which demonstrably
produce breakouts — adapted, never copied.

## 1. Scope
You need the video's topic and its core promise (what the viewer gets). If
the user has a draft title, thumbnail, or a published video link, start from
it. Ask about the audience only if it changes the packaging.

## 2. Evidence — budget ≈ 30–50 credits
1. `tubegrade_viral_formats` with `kind` title (default sort, no filters) —
   one call; a second with `kind` thumbnail if thumbnails are in scope. Among
   the results, prefer formats whose `state` is emerging or rising.
2. `tubegrade_find_outliers` on the topic (`min_ratio` 2) — breakouts whose
   packaging you'll study.
3. `tubegrade_thumbnails` on the 5–8 strongest of those (1 credit each) —
   LOOK at the images.
4. If the user gave a published video: `tubegrade_find_similar_thumbnails`
   (20 credits) only if they want to see lookalikes; say the cost first.

## 3. Analyse what wins here
From the formats and the images, note what repeats among the winners:
- title structure (number, contrast, "how/why", time-box, stakes, curiosity gap)
- title length and the words that carry the promise
- thumbnail: face/no face and expression, text (how many words), focal
  object, colour contrast, before/after or comparison layouts

Cite the videos each observation comes from.

## 4. Deliver
**Titles** (8–10): grouped by format. For each: the title, the format it uses,
and one line on why it suits this video. Keep each one truthful to the video's
actual content — no promise the video won't keep.

**Thumbnail concepts** (3): for each — layout, focal subject, text (≤4 words),
colours/contrast, and the winning thumbnail(s) it learns from (linked).
Concepts must be original compositions, not recreations.

**Pairing**: the best title + thumbnail combo, and why they work together
(the thumbnail shows, the title tells — don't repeat the same words).

**If comparing the user's own options**: rank them against the evidence,
say what each does well/poorly, and suggest one improvement each. Be direct.

## Don't
- Don't reuse a competitor's exact title or describe a thumbnail recreation.
- Don't promise click-through numbers — say which option has more evidence.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: tubegrade-script-writer
description: Write a researched YouTube script — study how the top-performing videos on the topic hook, structure and pace it (from their transcripts), then write an original script with timestamped source citations and flagged claims to verify. Use for "write a script about X", "research and script this video idea".
---

# Research-backed script writer

Read `references/tubegrade-tools.md` first.

Goal: an original, ready-to-record script whose structure is learned from
videos that actually over-performed, with every borrowed fact traceable.

## 1. Scope
Ask only what you don't have: topic, target length (minutes), audience,
channel voice (a handle lets you check their style), long-form or Short.

## 2. Find the reference videos — ≈ 15–25 credits
- `tubegrade_find_outliers` on the topic (`days` 365, `min_ratio` 2), and/or
  `tubegrade_search_videos` (`upload_date` year, `video_type` long) keeping
  results with `outlierRatio` ≥ 2.
- Shortlist the 3 most relevant strong performers (on-topic beats biggest).
  Tell the user which three you picked and why.

## 3. Study them — 30 credits (hard cap: 4 transcripts without asking)
`tubegrade_get_transcript` for each of the 3. If one is unusable (no speech,
music only, wrong topic), replace it once — a 4th transcript. Anything beyond
that, ask first. From each usable transcript, extract:
- the **hook** (first ~30–45 seconds): how it earns attention
- the **structure**: sections with timestamps, and where the payoff lands
- **retention devices**: open loops, previews, pattern breaks, stakes
- **facts and claims** worth using, with their `[MM:SS]` timestamp
Optional: `tubegrade_get_comments` (5) on the strongest video to catch what
viewers felt was missing — fill that gap in the new script.

## 4. Write
- Original wording throughout. Learn the structure; never paraphrase a
  transcript line by line.
- Open with a hook that states the promise and the stakes within ~20 seconds.
- Sections with on-screen/B-roll notes in [brackets].
- After any fact, technique or statistic taken from a reference, add a
  citation line: `Source: <video title> — <link> at [MM:SS]`.
- Mark anything that needs outside verification (health, money, legal,
  statistics) with **[VERIFY]** — transcripts are not proof.
- Match the requested length (~140–160 spoken words per minute).

## 5. Deliver
1. The 3 reference videos (link, views, outlier ratio) and what each taught.
2. The script.
3. A **[VERIFY] checklist** of claims to confirm before recording.
4. Offer packaging next → **tubegrade-packaging-studio**.

## Don't
- Don't present a reference video's script, jokes, or unique stories as the
  user's.
- Don't state medical, financial, or legal claims as settled — flag them.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: tubegrade-video-ideas
description: Find video ideas a creator can adapt, backed by videos that actually broke out (beat their own channel's normal views) in their niche. Use for "give me video ideas about X", "what's working in my niche", "find breakout videos I could make my own version of".
---

# Video ideas from breakout evidence

Read `references/tubegrade-tools.md` first.

Goal: a short list of ideas the user can make, each backed by real videos that
over-performed — not a brainstorm.

## 1. Scope (ask only what changes the search)
Reuse what the user already said. Ask at most one question, and only if the
niche is unclear. Useful context: niche/topic, their channel (handle), long-form
or Shorts, language/market. If they gave their channel, one
`tubegrade_get_channel` call tells you their size and topic.

## 2. Gather evidence — budget ≈ 30–60 credits
Run 2–3 lanes, each bounded:
- **Breakouts on the topic**: `tubegrade_find_outliers` with 1–2
  mechanism-shaped queries (the promise, not just the noun — "beginner
  mistakes in X", "I tried X for 30 days"), `days` 180–365, `min_ratio` 2–3.
- **Live check** (if find_outliers is thin): one `tubegrade_search_videos`
  (`upload_date` month or year) and keep results with `outlierRatio` ≥ 2.
- **Adjacent channels** (optional): if the user named a competitor,
  `tubegrade_get_channel_outliers` on it.

Stop gathering when you have ~10 strong candidates. Don't call the same tool
with near-identical queries.

## 3. Judge
For each candidate, keep it only if:
- the ratio is meaningful (≥2x, and the channel isn't tiny),
- the **mechanism** transfers — name it: the promise, format, or angle that
  made it work (e.g. "time-boxed challenge", "myth vs reality", "ranking"),
- the user could actually produce it (no celebrity access, no huge budget),
- it isn't the same idea as another candidate.

Group candidates that share a mechanism; one idea per mechanism.

## 4. Deliver 5–8 idea cards
For each:
- **Idea** — a working title in the user's niche (original wording)
- **Why it should work** — the mechanism, in one sentence
- **Evidence** — 1–3 source videos, each as: title — https://www.youtube.com/watch?v=<id> — views, outlier ratio, age
- **Make it yours** — the specific twist for their channel
- **Confidence** — high / medium / low, and why (sample size, ratio strength,
  how far the adaptation stretches)

Then one line on coverage: what you searched, and anything thin or missing.

## Hand-offs
- Titles and thumbnails for a chosen idea → **tubegrade-packaging-studio**
- A full script → **tubegrade-script-writer**
- Picking ONE idea to make next → **tubegrade-next-video-planner**

## Don't
- Don't present a source video's title as the idea — write an original one.
- Don't rank by raw views alone; outlier ratio is the signal.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: tubegrade-video-teardown
description: Explain why one specific YouTube video worked (or flopped) — how far it beat its channel's normal views, its title format, what its thumbnail actually shows, how the first minute hooks, how it's structured, and how viewers reacted. Use for "why did this video blow up", "break down this video", "what can I learn from this video".
---

# Video teardown

Read `references/tubegrade-tools.md` first.

Goal: a clear, evidence-backed explanation of what made one video perform,
and the lessons the user can transfer.

## 1. Scope
You need the video link or id. Ask nothing else unless the user wants the
lessons applied to their own channel (then get their handle).

## 2. Evidence — ≈ 30 credits (+20 optional)
1. `tubegrade_get_video` (5) — views, age, duration, channel; `growth` if tracked.
2. `tubegrade_get_channel` (5) on its channel — the average views to compare
   against. Compute the outlier ratio yourself: views ÷ channel average.
3. `tubegrade_thumbnails` (1) — look at the thumbnail.
4. `tubegrade_get_transcript` (10) — the hook and structure.
5. `tubegrade_get_comments` (5, top) — what viewers responded to.
6. `tubegrade_viral_formats` (5, `kind` title) — does the title match a
   known format? Skip if the title pattern is obvious.
7. Optional, ask first: `tubegrade_find_similar_thumbnails` (20) — other
   videos packaged like it and how they did.

## 3. Analyse
- **Performance**: ratio vs the channel's normal, views per day of age. Is it
  a true breakout (≥3x), solid (1.5–3x) or normal? A big channel's routine
  upload isn't a breakout.
- **Title**: the promise, the format, the words doing the work.
- **Thumbnail**: what's in the frame and why it stops the scroll; how it
  pairs with the title. Only if you can actually see the image — otherwise
  say so and link it (see the tool notes).
- **Hook (first ~45s)**: quote 2–4 lines with their `[MM:SS]` (translated if
  the video isn't in English); how it sets stakes, previews the payoff,
  opens loops. Required — never just say the transcript was retrieved.
- **Structure**: a section map with timestamps from the transcript; where
  retention devices sit.
- **Audience reaction**: dominant themes from comments.

## 4. Deliver
1. **Verdict** — one paragraph: how well it did and the 2–3 main reasons.
2. **Scorecard** — performance, title, thumbnail, hook, structure: each with
   the evidence (timestamps, quotes, numbers).
3. **Transferable lessons** — 3–5, each phrased as something the user can do.
4. **What not to copy** — anything that depended on this creator's fame,
   timing or budget.

Hand-offs: apply the lessons to a new idea → **tubegrade-packaging-studio** or
**tubegrade-script-writer**.

## Don't
- Don't claim to know watch time, retention or CTR — TubeGrade only sees
  public data. Infer from structure and say it's an inference.

Referenced files: 2 — file references are metadata, not package contents.