vidIQ

View saved version →

---
name: vidiq-channel-audit
description: Audit an authorized YouTube channel's last 30, 60, or 90 days with private vidIQ analytics (views, watch time, subscribers, format mix, top videos), then prioritize improvements. Use when asked 'analyze, audit, or review my YouTube channel', 'is my channel doing well', 'why are my views or subscribers dropping', or 'monthly channel report'. Whole-channel only; one new upload is vidiq-new-upload-review.
---

# vidIQ Channel Audit

Read [Live surface notes](references/live-surface-notes.md) first, even when using only supplied evidence.

Produce a private, read-only diagnosis of the authorized channel from its own evidence.
Do not generate assets, score packaging, or make state changes.

## Set comparable scope

Use the requested 30-, 60-, or 90-day window; propose 30 days in the research plan if unspecified.
Choose the latest completed calendar days, excluding today, and the immediately preceding equal
period. State both exact date ranges and date basis before querying.

Use a bounded analytics plan. Resolve the intended authorized channel with
`vidiq_user_channels`; stop private analysis if it is absent instead of substituting a similarly
named public channel. Request sensitive revenue, demographic, or geography breakdowns only when
the creator explicitly needs them.

## Gather relevant reports

- **Trajectory:** `vidiq_channel_analytics` with explicit dates and `dimensions: ["day"]`.
  Choose supported decision-relevant metrics, such as views, watch time, average duration/
  percentage, subscriber gains/losses, likes, and comments. Report latest observed date and
  gaps; a returned date is not proof of complete ingestion.
- **Format contribution:** use a separate `creatorContentType` report when the split matters.
  Keep long-form, Shorts, and live evidence distinct and use metrics valid for that report shape.
- **Portfolio:** a separate `video` report provides a bounded top-N view, not the full upload
  distribution. Use `vidiq_channel_videos` for recent titles/dates only when needed, with a
  required `videoFormat: long`, `short`, or `live` per call. Label that set a sample.
  Filter analytics to sampled IDs using `filters: "video==ID1,ID2"` in batches of at most 150;
  absent requested IDs remain unknown.
- **Public growth context:** `vidiq_channel_stats` with the `channelId` and the same `from`/`to`
  window gives public subscriber, view, and video-count growth for the channel or a comparison
  channel; keep it separate from private analytics.
- **Audience overlap or publishing windows:** use `vidiq_subscriber_insights` only when explicitly
  requested for the authorized channel. Its histogram is sampled public activity,
  not watch history or a live online-audience signal. Keep overlap data private.

## Interpret valid comparisons

Require equal-day coverage and comparable formats. If shifting bounds for ingestion lag, retain
equal full-length periods, disclose revised dates, and scope extra calls first. When an
inside-period change matters, compare equal-day halves (15/15, 30/30, or 45/45), showing observed
versus expected day counts. Missing values cannot be invented or unequal observed sums treated
as equal-day performance.

Sum additive metrics only. Weight rates/percentages using valid available denominators;
otherwise show rows separately. Compute net subscribers as gained minus lost, report both net
counts and the absolute delta, and add percent change only from a positive prior net. Counts
never change in percentage points.

Assess trajectory, watch efficiency, audience response, format contribution, and top-video
concentration against comparable channel history and the stated goal. Disclose cadence, upload
ages, sample size, and format-mix changes as competing explanations. Missing coverage or
nonpositive baselines leave relative decline unknown; show available absolute deltas.

Do not impose universal healthy-channel thresholds, unsupported peer benchmarks, or causal claims.
Thumbnail CTR/impressions are unavailable in this analytics schema; use supplied Studio data
when needed and label its source.

## Deliver

Give the authorized target, periods, relevant coverage/freshness limitations, and a compact health
summary separating observations, interpretations, and recommendations. Include an inside-period
comparison only when relevant, with its coverage or availability limit.

Prioritize up to three interventions, or the requested number, with evidence, competing explanation,
confidence, smallest action, success measure, and reassessment date. Report contradictions and
the next read that would most improve confidence. Route a focused launch question to
`vidiq-new-upload-review` and a single video's retention to `vidiq-retention-analysis`.

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

View saved version →

---
name: vidiq-comment-insights
description: Mine YouTube comments for what viewers ask, want, and object to, with identities removed, then turn it into hooks, titles, FAQs, or script angles, and draft replies. Use when asked 'what do my viewers want', 'summarize or analyze the comments on this video', 'what is my niche's audience asking for', 'does this idea resonate', or 'reply to this comment'.
---

# vidIQ Comment Insights

Read [Live surface notes](references/live-surface-notes.md) first, even when using only supplied evidence.

Extract reusable audience language from comments while protecting commenter identity. Works on
own or public videos and never reports usernames.
Keep viewer wording distinct from the creator's transcript and from original copy. Sample named
videos, research a whole niche, or draft replies, as the request requires.

## Sample the requested audience

1. Establish topic, intended use, language/market, and period; use a bounded sample.
   Use supplied videos. Discover additional sources only when needed and within scope.
2. For discovery, use `vidiq_channel_videos`, `vidiq_youtube_search`, or `vidiq_outliers` to
   include typical, recent, and breakout examples. Catalog calls require matching
   `videoFormat: long`, `short`, or `live`; use `popular: false` for recent uploads.
   YouTube search needs `type: ["video"]` so channels/playlists do not enter comment calls.
   Keep language/format explicit where supported; outliers cannot discover non-English Shorts.
3. Read [Discovery evidence](references/discovery-evidence.md) when discovering source videos or
   asserting a recurring pattern. Inspect thumbnails only
   if visual context changes source selection; missing image access does not invalidate comment
   analysis. Fetch independent samples in parallel within scope.
4. Start `vidiq_video_comments` with `videoId`, explicit `order`, and singular `maxResult`
   (1–100 threads per page). Report the sample cap and selection bias. Count actual returned
   replies; `replyCount` is not the number inspected. When the live tool returns `nextPageToken`,
   continue within the sample limit using `pageToken` and the same source, `order`, and
   `minLikes`. Like filtering can leave a page short or empty while more pages remain.
   Filter dates locally; undated comments have unknown recency.
5. Use representative `vidiq_video_transcript` results only when useful; `transcription` is
   untimed creator language, not viewer evidence.

## Research a niche instead of named videos

For "what does my niche's audience keep asking for" or "does this idea resonate", use
`vidiq_comment_insights` instead of sampling videos one by one. `mode: "discover"` with `niche`
(and optional `language`) returns recurring requests and pain points across a niche-wide cohort;
`mode: "validate"` with `niche` and `idea` tests one proposed idea against comment evidence;
`mode: "raw"` returns underlying threads and is the only mode that accepts `includeReplies`,
`intents`, `minLikes`, `sort`, `pageSize`, `maxThreadsPerChannel`, and `cursor`, which other modes
reject. Continue a raw search with `mode: "raw"` and `cursor` only, and omit
`commentPublishedAfter` unless the creator asks for a time window. Every mode returns an
`mcpJobId`: read [Job lifecycle](references/job-lifecycle.md), then poll `vidiq_job_poll` until
completed. The tool picks its own cohort, so it does not replace `vidiq_video_comments` for named
videos or channels, and the Claude.ai directory connector does not expose it; sample videos there.

## Deidentify and count accurately

Verify the video's owner channel from metadata, using `vidiq_get_videos_by_ids` only when needed.
Compare `authorChannelUrl` in the same identifier form: `/channel/ID` against the owner ID,
or `/@handle` against a verified owner handle. If the handle is missing, one
`vidiq_channel_search` with `channelTitleMatch: "exact"` can resolve it; require the returned
`channelId` to match the video's owner before trusting its handle.

An ID/handle mismatch or display name does not establish non-owner status. Without a comparable
owner identity, all affected authors remain unverified: paraphrase separately, exclude them from
verified viewer counts, and use no verbatim fragments. Exclude matched owner comments and replies.
Use author IDs and handles transiently, never in the language bank or evidence trail.

Decode entities, strip HTML, URLs and handles, and normalize whitespace. Drop sensitive or
identifying fragments instead of trying to salvage them by partial redaction. Prefer paraphrases.
For useful verbatim evidence, take one contiguous deidentified fragment of at most eight
whitespace-delimited words, shorter than the full cleaned comment. Otherwise paraphrase or omit.
Never stitch fragments or reproduce full comments, even short ones.

Cluster questions, desired outcomes, objections, misconceptions, and emotional language.
Count support by videos: N of M with usable sampled comments, with M out of all selected videos.
Multiple replies in one thread are not independent video support. Preserve per-video caps,
returned/retained threads and replies, exclusions, and date coverage. Empty, disabled, or missing
comments are coverage gaps, not absence of audience concerns.

Use `vidiq_keyword_research` only to test a requested or decision-relevant search-demand
hypothesis; conversational phrasing does not establish search intent. Do not infer demographics
or sensitive traits from wording.

## Draft replies

For reply ideas to one specific comment, use `vidiq_generate_comment_replies` with the video
`title`, the exact `comment`, and optional `tones` (3 to 10 labels; the defaults are General,
Humorous, Thankful, Witty, and Informal). It returns drafts only; the creator posts the reply they
choose on YouTube. The Claude.ai directory connector does not expose this tool.

## Deliver

Return the requested language bank or audience findings with meaning, support, recency, source-video
labels, limitations, and suggested use. Label paraphrases, verbatim evidence, creator language,
and original copy distinctly.

Add hooks or content briefs only when requested, using the requested count. Keep all examples
original and the evidence trail deidentified.

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

View saved version →

---
name: vidiq-competitor-watchlist
description: Find and manage the competitor channels tracked in vidIQ for an authorized YouTube channel, adding or removing channels only after explicit approval. Use when asked 'who are my competitors', 'youtube competitor analysis', 'find channels like mine', 'channels similar to [channel]', or 'clean up my competitor list'.
---

# vidIQ Competitor Watchlist

Read [Live surface notes](references/live-surface-notes.md) first, even when using only supplied evidence.

Audit or update a watchlist for the intended authorized channel. Research only what the request
needs; a recommendation never authorizes a mutation. Only this skill changes the saved watchlist.

## Establish the list and candidate fit

1. Resolve the intended owner with `vidiq_user_channels`, then
   capture `vidiq_list_competitors` for its `youtubeChannelId` as the original canonical-ID set.
   Enrich titles with `vidiq_get_channels_by_ids` only when useful.
2. Exclude self, known siblings, and unrelated channels from analysis, but present removals as
   recommendations. Unknown ownership/fit is not an automatic removal reason; preserve
   intentional references.
3. For discovery, `vidiq_similar_channels` takes canonical `channelId` with optional `size` and
   `sort`, or manual `niche` with its declared filters. Do not mix modes or pass `subNiches`.
   Reuse known IDs; resolve manual context through `vidiq_channel_search` only when needed,
   matching the returned canonical ID. Country/format can influence ranking rather than strict
   eligibility, so check actual fit.
4. Use generic niche `vidiq_channel_search` for broader discovery and `breakoutChannel: true`
   for emerging challengers (`vidiq_breakout_channels` is a deprecated alias of that search). Set `subscriberCountMin` only for a requested or justified cohort
   boundary. Disclose it; tiny or nonpositive baselines make growth ratios unreliable.
5. Read [Discovery evidence](references/discovery-evidence.md) for candidate discovery or
   audience/mechanism pattern claims; individual candidate fit can
   remain tentative. Use semantic mechanism matching where declared.
6. Verify upload recency only when it affects a recommendation: use `vidiq_channel_search`
   with `channelTitle` and `channelTitleMatch: "exact"` when declared, verify the ID, and read
   `lastVideoPublished`. Channel `publishedAt` is creation time. Alternatively, a scoped
   `vidiq_channel_videos` read needs `popular: false` and `videoFormat: long`, `short`, or
   `live`; that format sample cannot prove channel-wide inactivity. Missing dates mean unknown.
   `vidiq_channel_stats` with the `channelId` and a `from`/`to` window verifies a growth claim
   before a candidate is added.

Classify useful candidates as direct competitors, format references, or emerging challengers.
Raw fame or size is insufficient; do not invent audience-overlap or private competitor analytics.

## Propose and execute an exact change

1. Present owner ID, original snapshot, canonical-ID `add`/`remove` sets, rationale, and expected
   final set: `(snapshot - remove) ∪ add`. Deduplicate, prevent overlap, and omit already-present
   additions or absent removals. Map additions to `follow` and removals to `unfollow`.
   An empty diff needs no mutation. Do not invent a watchlist/plan cap.
2. Obtain approval of the exact owner and add/remove diff.
3. Immediately before mutation, re-read the list within that approval. Compare canonical-ID sets
   with the original snapshot. If changed, abort, show the concurrent difference, and obtain
   approval for a revised diff. If the read fails, pause.
4. With unchanged preflight and approval, call `vidiq_update_competitors` once with
   `youtubeChannelId`, `follow`, and `unfollow`. Preserve the response and read back with
   `vidiq_list_competitors`.
5. Compare actual added/removed and final sets with the approved expectation. Report discrepancies,
   partial updates, or limit failures; never silently repair, roll back, or resubmit. Readback
   detects but cannot prevent a race after preflight because no atomic compare-and-swap is
   declared. If verification fails, label readback unverified and distinguish
   any response-confirmed state.

## Deliver

For an audit, return the diagnosis and proposed changes. After an approved update, report the
confirmed final list or exact verification gap, approval state, and unresolved discrepancies.
Keep the owner explicit for multi-channel accounts.

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

View saved version →

---
name: vidiq-get-started
description: Set up, verify, or troubleshoot vidIQ MCP and pick a first workflow. Use when asked to connect vidIQ or a YouTube channel, 'is vidIQ connected', 'which channel is linked', 'check my credits', or when vidIQ tools are missing, a call returns 401, 403, or verification errors, credits run out, or a thumbnail, watch, or script job is stuck. Not for creator research.
---

# vidIQ Get Started

Read [Live surface notes](references/live-surface-notes.md) first, even when using only supplied evidence.

Help the creator connect, diagnose a problem, or choose a workflow. Run only the relevant branch:

- Connection, channel, or balance checks: use the relevant steps below.
- Errors or charge questions: read [Troubleshooting](references/troubleshooting.md).
- Existing or interrupted jobs: read [Job recovery](references/job-recovery.md). To list active
  jobs, use `vidiq_jobs_list` with `status: "inprogress"`.
- No YouTube channel connected, or a write tool asks for verification: use steps 3 and 6 below.
- Saved research: `vidiq_bookmarks_list` returns the creator's saved videos, channels, and
  keywords when they ask what they bookmarked.
- Capabilities: summarize the outcomes supported by the exposed tools.

## Connect and verify

1. Inspect whether vidIQ tools are visible. Visibility confirms that the client loaded the
   server; successful account-state calls establish authorization.
2. If tools are missing, check installation, enablement, and client reload requirements.
   Use the client's native MCP authentication action when available; otherwise follow its
   connection flow and the [official setup guide](https://support.vidiq.com/en/articles/15082430-vidiq-mcp).
   Wait for browser authorization, then re-check. Never request credentials in chat.
3. Call `vidiq_user_channels` once and report the returned authorized IDs.
   Account labels are optional and useful only for diagnosis.
   An empty or unexpected list can indicate the wrong account; suggest reconnecting with the
   intended account without claiming token expiry. When no channel is connected, or another
   tool reports that no YouTube channel is connected, call `vidiq_connect_youtube_channel`, show
   its widget, wait for the creator to finish, then retry the original request. The connection
   and authorization tools are free and are not exposed by the Claude.ai directory connector.
4. Resolve the intended channel only before channel-specific work. If several IDs are returned,
   use the user's explicit selection; do not pick the first or largest. Enrich titles with
   `vidiq_get_channels_by_ids` only when needed. A channel outside the authorized
   set can receive public research, but not private analytics.
5. Use `vidiq_balance` to explain returned renewable and
   add-on credits, preserving `unlimited` and `null`.
6. Before a write workflow (video details or thumbnail) or when a tool returns
   `status: verification_required`, call `vidiq_authorize_with_youtube`, show its widget, and wait
   for the creator to use it. Do not repeat the write until they confirm verification is complete.

## Choose the next step

After setup, use the creator's stated decision. If it is unclear, ask one compact question and offer:

- **Package an existing idea or video:** `vidiq-packaging-studio`.
- **Discover an idea:** `vidiq-video-ideas`; feed its concept cards into packaging for an
  end-to-end request.
- **Review performance:** `vidiq-channel-audit`, or `vidiq-new-upload-review` for a recent upload.
- **Change something on YouTube:** `vidiq-video-metadata` for a video's details or thumbnail.

Honor a more specific request with its matching skill; ask what vidIQ can do and the answer is
the routing table in the agent guide. Supplied-context analysis or text drafting
may need no MCP calls. Do not run research merely to demonstrate the connection.
Onboarding alone does not authorize later generation or state changes.

## Report

Report the requested check's result, any issue, and the next action. For setup, include connection
and authorization state, relevant channels and credits, and one recommended workflow. For job
recovery, report the actual job state and result or pending ID.

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

View saved version →

---
name: vidiq-new-upload-review
description: Triage a just-published YouTube video or Short against the channel's own curve at the same publication age and decide whether to wait, investigate, or change packaging. Use when a creator says 'I just uploaded', 'my new video is not getting views or impressions', 'is my latest video flopping', 'my Shorts are getting 0 views', or 'should I change the thumbnail or title'.
---

# vidIQ New Upload Review

Read [Live surface notes](references/live-surface-notes.md) first, even when using only supplied evidence.

Judge a new upload against the channel's performance at the same publication age. Recommend
whether to hold, inspect, or prepare a packaging change; do not change YouTube metadata/settings.
For whole-channel trends switch to `vidiq-channel-audit`; apply an approved change through
`vidiq-video-metadata`.

## Compare the trajectory

1. Establish video, channel, goal, format, publication time, and current age from supplied context.
   Use a bounded evidence plan.
2. For “my channel” or private analytics, resolve the authorized target with `vidiq_user_channels`.
   For “my newest upload,” use `vidiq_user_videos` with the owning `channelId`, `order: "newest"`,
   and the relevant `privacyStatus` (it includes unlisted and scheduled private videos), or
   `vidiq_channel_videos` with `popular: false` and confirmed `videoFormat: long`, `short`, or
   `live` for a public catalog; then confirm the returned video.
3. Use `vidiq_get_videos_by_ids` for context, `vidiq_video_stats` for history, and
   `vidiq_channel_performance_trends` for the recent-video post-publication curve.
   Stats requires `granularity`: prefer `hourly` for early launches; use coarser intervals only
   when age/window warrants them. Read `vidiq_video_change_history` before recommending a packaging
   change: a title or thumbnail edited since publication, or a running thumbnail A/B test, changes
   the interpretation.
4. Compare cumulative `views` at equivalent `minutesSincePublication`. Use returned
   `views.perc30`, median, and `views.perc70`; missing percentiles are unavailable, not replaceable
   by min/max. VPH is not cumulative views. Disclose age mismatch and mixed-format limitations
   of the channel-wide curve. Do not manufacture checkpoints or extrapolate beyond observations.

## Choose the next action

- **Hold:** evidence is sparse, incomparable, or insufficient to justify intervention.
- **Inspect:** repeated weakness against an age-matched baseline warrants investigation.
  A percentile crossing alone cannot identify packaging as the cause.
- **Prepare a change:** weakness has corroboration from supported analytics, supplied Studio
  data, or qualitative comments, with competing explanations and confidence stated.
  Without corroboration, keep the decision at hold or inspect.

Inspect only decision-relevant evidence within scope: authorized `vidiq_channel_analytics`,
supplied Studio CTR/impressions, or `vidiq_video_comments`. Thumbnail CTR/impressions are not in
the analytics metric enum; annotation CTR and ad impressions are not substitutes. Comments and
scores cannot prove low CTR or its cause. Use `vidiq_score_title`/`vidiq_score_thumbnail` only
when useful within the requested diagnosis.

A known factual or formatting error can warrant correction at any age, independently of
performance. Choose a reassessment point from the observed channel curve, with no universal
waiting period or fixed checkpoint count.

## Deliver

Report publication age, evidence window, observed trajectory/bands and their gaps, and the
count/ages of checkpoints used. Give the decision, strongest evidence for and against it,
confidence, and next measurement/checkpoint. An unresolved video or channel prevents a trajectory
claim; a recommendation does not mean a change was applied.

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

View saved version →

---
name: vidiq-next-video-planner
description: Rank what an authorized YouTube creator should publish next from their own analytics plus live search demand, audience requests, trends, and competitor gaps. Use when asked 'what should my next video be', 'what should I post on YouTube to grow', or 'rank these ideas for my channel'. Needs the creator's own channel; for ideas from breakout videos in any niche use vidiq-video-ideas.
---

# vidIQ Next Video Planner

Read [Live surface notes](references/live-surface-notes.md) first, even when using only supplied evidence.

Rank next-video opportunities from channel fit, competitors, demand, and timing. Keep this workflow
read-only: no generation, packaging scoring, refinement, or mutations. Switch to
`vidiq-video-ideas` for open-ended idea discovery and to `vidiq-packaging-studio` to package a
chosen idea.

## Scope and channel fit

1. Use supplied audience, format, language/market, horizon, constraints, and goal. Ask one compact
   question only for gaps affecting tool inputs or ranking.
2. Use a capped evidence plan: start with one call per relevant lane and expand only for facts
   that could change the decision.
3. Resolve the intended authorized channel with `vidiq_user_channels`. For recent channel fit,
   use `vidiq_channel_videos` with `popular: false` and matching `videoFormat: long`, `short`,
   or `live`.
4. Request `vidiq_channel_analytics` with explicit dates, `dimensions: ["video"]`, and
   `filters: "video==ID1,ID2"` for those IDs in batches of at most 150. Set `maxResults` to cover
   the batch within live limits and join by video ID. Missing rows are unknown; a mixed-format
   top-N report cannot define recent same-format fit. Compare sensible publication ages and
   label the upload set a sample. If private analytics are declined, disclose that missing lane.

## Research useful evidence lanes

Read [Discovery evidence](references/discovery-evidence.md) when discovering or evaluating
candidate opportunities, including supplied examples.

- **Competitors:** use `vidiq_list_competitors` when useful. Exclude self, known siblings, and
  unrelated channels from the analysis cohort; disclose uncertain ownership/fit and leave the
  saved list unchanged. Otherwise use `vidiq_similar_channels` with canonical `channelId` and
  optional `size`/`sort`. Manual `niche` mode has separate filters, no `subNiches` field, and
  ranking preferences that require checking returned fit.
- **Outliers:** gate the format/language combination before `vidiq_outliers`. Shorts are restricted
  to English; outliers and trending have no live-only lane. For non-English outliers, `all` narrows
  to long-form and discovery is capped at six months. Pass supported `contentType` and `language`;
  never silently substitute English or another format. Cluster premises, audience needs, and
  payoffs. Treat absent matches as a sampling limit, not proof of an unclaimed opportunity.
- **Search demand:** use `vidiq_keyword_research` with `mode: "research"`, seed `keyword`, and
  optional supported `country`. For momentum, `rising` uses `period` and `language`; discover
  `availableTopics` before supplying a `topic`. It ignores `keyword` and `country`; where declared,
  `includeKeyword` narrows results to a whole word or adjacent phrase.
  Keep measured demand/growth separate from scores or ranking; missing, stale, or
  nonpositive baselines cannot establish relative growth.
- **Audience requests:** `vidiq_comment_insights` with `mode: "discover"` and the `niche` returns
  recurring viewer requests and pain points across the niche as an asynchronous job; read
  [Job lifecycle](references/job-lifecycle.md) and poll `vidiq_job_poll`. `mode: "validate"` with
  `idea` tests a finalist. It is one lane, not a verdict, and the Claude.ai directory connector
  does not expose it.
- **Timing:** `vidiq_trending_videos` measures absolute velocity in the confirmed format and
  market. `vidiq_video_stats` on a finalist can test acceleration/decay; choose required
  `granularity: hourly`, `daily`, or `monthly` to match its age/window. Normalize epoch-second
  outlier dates and ISO timestamps before age comparisons. Do not equate velocity with
  channel-relative outlier performance.

Apply the shared relevance/independence rule to every discovery lane. For cross-niche mechanisms,
match viewer motivation and use semantic `requireAllTitleTerms: false`; strict matching is
supporting evidence only on tools declaring that field. Inspect actual images or mark visual
findings provisional.

## Decide and deliver

Compare up to three supported opportunities, or the requested count, on channel fit, competitive
opportunity, demand, timing, originality, and feasibility. Use ordinal judgments; do not sum
incompatible metrics. Prefer corroborating evidence types and state what could change the choice.

Return the shortlist and strongest supported brief with evidence scope/dates, confidence, and
counterevidence. Use original framing, examples, and expression. If evidence cannot support a
choice, state the gap; do not force a winner.

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

View saved version →

---
name: vidiq-packaging-comparison
description: Compare distinct YouTube title-and-thumbnail concepts for the same video when alternative creative directions are explicitly requested. Route single titles, thumbnail edits, or complete packages without a comparison request to vidiq-packaging-studio.
---

# vidIQ Packaging Comparison

Read [Live surface notes](references/live-surface-notes.md) first, even when using only supplied evidence.

Compare the requested number of distinct title-thumbnail concepts for the same video, defaulting
to three if unspecified. Use `vidiq-packaging-studio` for focused edits or one package. Generated
images are optional.

## Compare concepts

Preserve what each number measures: video length does not prove how quickly an action was
completed. Use a speed claim only when demonstrated or explicitly supported by the brief.

1. Use the supplied viewer, promise, proof, format, language, and assets. Establish which story
   facts are supported and whether the host is the subject or an analyst.
2. Keep research within scope. Generate images only when requested, using the selected direction
   or the requested number of variants.
3. Clarify content only when necessary: `vidiq_video_transcript` supplies untimed spoken text;
   `vidiq_video_watch` serves long-form and `vidiq_watch_shortform_content` serves Shorts.
   Verify the source before watching. Read
   [Job lifecycle](references/job-lifecycle.md) before any asynchronous watch or production call.
4. Create distinct, truthful promises or framing choices, not cosmetic rewrites. Pair each title
   with thumbnail tension, proof, or stakes that adds information. Make subject attribution clear.
5. Research references only when they can change the comparison. Use the guidance below.
6. Compare audience fit, truthful payoff, differentiation, production feasibility, and evidence.
   A concept can remain useful despite a lower model score. Before using vidIQ tools for
   title generation/scoring, rendering, refinement, or thumbnail scoring, read
   [Production and scoring](references/production.md).

## Optional reference research

Read [Discovery evidence](references/discovery-evidence.md) before searching or evaluating external
references. Skip research when the supplied brief suffices.

For long-form visual conventions, `vidiq_similar_thumbnails` takes exactly one of `description`
or `videoId`; it does not support Shorts. Description retrieval is approximate and may be
irrelevant. Inspect actual images before claiming visual similarity or saturation.

For title mechanisms, use `vidiq_outliers` with semantic `requireAllTitleTerms: false`; strict
`true` phrases provide supporting evidence only. Preserve format and language: outliers rejects
non-English Shorts, has no live-only lane, narrows non-English `all` to long-form, and caps
non-English discovery at six months. Pass a supported `language` explicitly; use a supported
alternative or disclose missing coverage.
Normalize outlier `videoPublishedAt` epoch seconds and ISO dates before comparing publication ages.

Exclude the story's originating video/creator and sources of material adapted for the story from
the packaging reference set, even if licensed. Without image access, mark visual relevance unverified.

A reference is optional design evidence, not permission to copy another creator's distinctive
expression. Preserve the creator's authorized assets and name any reference's abstract contribution.

## Deliver

Return the agreed concepts, their matched titles and thumbnail directions, evidence and
limitations, and the recommended choice with its strongest counterargument. Honor a request for
comparison without forcing a winner.

For executed production, report image URLs or pending job IDs, visual-review status, and score/proxy
context. Separate concept judgments from inspected renders; never claim a
visual winner before inspection. Log only useful iterations actually performed.

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

View saved version →

---
name: vidiq-packaging-studio
description: Write, score, compare, and improve YouTube titles and thumbnails, and optionally a script, for an idea, script, reference video, or underperforming video. Use whenever a creator asks for titles or thumbnails, even a quick list; vidIQ scoring improves them. Triggers include 'title ideas', 'rewrite my title', 'thumbnail ideas', 'make or refine a thumbnail', 'which title is better', 'A/B test these titles or thumbnails', 'why didn't this video get clicks', or 'write a script for this video'.
---

# vidIQ Packaging Studio

Read [Live surface notes](references/live-surface-notes.md) first, even when using only supplied evidence.

Create an honest title-thumbnail package from a concept, script, reference, or published video.
Use the creator's supplied audience, format, language, tone, and assets.

## Match the request

- For a focused title or thumbnail edit, go directly to that edit. Resolve a channel or fetch
  evidence only when the action needs it.
- For an idea or script, establish what the content can truthfully deliver.
- For a published video's performance diagnosis, investigate before attributing weakness to
  packaging. Read [Research and diagnosis](references/research.md).
- For a full package, research only gaps that can change the creative decision. Reuse sufficient
  supplied evidence.
- Before evaluating external references, including examples already supplied by the creator,
  read [Discovery evidence](references/discovery-evidence.md).
- For "which of these directions should I use", run the compare section below.

A critique does not imply generation; a title request does not imply a thumbnail or script.
Ask only for missing information that changes the requested result.

## Develop the package

Preserve what each number measures: video length does not prove how quickly an action was
completed. Use a speed claim only when demonstrated or explicitly supported by the brief.

1. State the viewer payoff, tension or proof, and factual limits. Preserve the supplied story and
   numbers. When covering someone else's story, distinguish its subject from the host analyzing it.
2. If references need to be retrieved, read [Research and diagnosis](references/research.md).
   Transfer
   abstract mechanisms and composition principles while using original expression. Respect the
   creator's own or appropriately licensed assets.
3. Develop the requested title candidates. Keep them truthful and within the platform limit.
   Describe originality as a creative judgment; claims about other videos need supporting evidence.
   Pair the title with thumbnail imagery or text that adds tension, proof, or stakes.
   Judge the pair against the brief; a model score is not a performance verdict.
4. Before using vidIQ tools to generate, score, or refine titles, thumbnails, or scripts,
   read [Production and scoring](references/production.md).
   Before an asynchronous call, read [Job lifecycle](references/job-lifecycle.md).
5. Inspect completed images for factual accuracy, legibility, rights, and attribution.
   If visual inspection is unavailable, return the draft with that limitation; do not claim it
   passed. Keep the version that best meets the brief, explaining any score tradeoff.

## Compare distinct directions

When the creator asks which of several title and thumbnail directions to use, compare the requested
number of distinct concepts (three if unspecified) for the same video. Make each a different
truthful promise or framing, not a cosmetic rewrite, and pair every title with thumbnail tension,
proof, or stakes that adds information. Compare audience fit, truthful payoff, differentiation,
production feasibility, and evidence; a concept can stay useful despite a lower score. Research
references only when they can change the comparison, and generate images only when requested, for
the selected direction or the requested variants. Return the concepts with their matched titles
and thumbnail directions, the evidence and limitations, and the recommended choice with its
strongest counterargument. Honor a request for comparison without forcing a winner, and never
claim a visual winner before inspecting renders.

## Deliver

Return the requested titles, thumbnail directions, edited assets, or critique, with the rationale
and material limitations. Include source-to-adaptation reasoning when references informed the
work. For executed tools, report generated URLs or pending job IDs, relevant scores and their
context.

Omit unused stages and empty report sections. Include a script, comparison table, or iteration log
only when requested or useful to understand work actually performed.

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

View saved version →

---
name: vidiq-retention-analysis
description: Find where and why viewers leave an authorized YouTube video using vidIQ audience-retention analytics, the transcript, watched scenes when available, and comments. Use when asked about 'audience retention', 'watch time', 'where people drop off', 'my intro or hook loses viewers', or 'average view duration is low', or for pacing and structure advice on one video.
---

# vidIQ Retention Analysis

Read [Live surface notes](references/live-surface-notes.md) first, even when using only supplied evidence.

Investigate retention changes with private analytics and relevant content evidence.
Treat explanations as hypotheses, not proof of why every viewer left.

## Establish authorized evidence

1. Identify video, format, and review dates; keep analysis and optional watch/poll work within scope.
2. Resolve authorized IDs with `vidiq_user_channels`. If no video is supplied, discover candidates
   with `vidiq_channel_videos`, `popular: false`, and confirmed `videoFormat: long`, `short`,
   or `live`, or with `vidiq_user_videos` and the owning `channelId` when the video is unlisted
   or private; confirm the candidate. Use `vidiq_get_videos_by_ids` and require its `channelId`
   to match an authorized ID before private analytics. Otherwise offer a public-content critique
   with retention evidence unavailable, or hand the video to `vidiq-video-breakdown`.
3. Request `vidiq_channel_analytics` with explicit dates, `report: "audience_retention"`,
   `filters: "video==VIDEO_ID"`, `metrics: ["audienceWatchRatio", "relativeRetentionPerformance"]`,
   and `maxResults: 100`. The equivalent `dimensions: ["elapsedVideoTimeRatio"]` still requires
   that video filter. Read `columnHeaders` before interpreting the 100-point curve.

## Interpret the curve

`audienceWatchRatio` is segment watches relative to video views; repeat viewing can exceed 1
(100%). `relativeRetentionPerformance` compares videos of similar length on a 0–1 scale:
0.5 is the median, with higher values above it and lower values below it. This is comparative
rank, not the percentage of this video's viewers; see [YouTube's metric definition](https://developers.google.com/youtube/analytics/metrics#relativeRetentionPerformance).
If requested, `totalSegmentImpressions` counts segment watches, not unique viewers or thumbnail
impressions. Report available sample/denominator context; scope any extra read needed for missing counts.

Identify material drops, recoveries, or sustained changes against surrounding observations and
relative-retention context. Use actual non-null endpoints; percentage-point change is 100 times
the ratio difference. Record endpoints, interval, magnitude, and why it warrants attention.
Do not impose universal editing cutoffs or interpolate gaps into evidence. Sparse curves, small/unknown
samples, and near-end drops lower confidence without establishing an editing fault.

## Align content only with appropriate evidence

`vidiq_video_transcript` returns untimed `transcription`. Use it for spoken themes.
For scene alignment within the requested analysis, verify the source before watching:
`vidiq_video_watch` serves long-form; `vidiq_watch_shortform_content` serves Shorts.
Verify eligibility separately for live streams or recordings. Before a watch call, read
[Job lifecycle](references/job-lifecycle.md) for submission, bounded polling, and recovery.

Elapsed ratio times known duration gives an approximate analytics position, not an observed
scene timestamp. Attach scenes or timed hypotheses only when completed watch evidence supports
the alignment; scene ranges are not frame-accurate ground truth. Never attach a transcript quote
to a time range without evidence at that precision.

Without watch evidence, separate numeric zones from untimed content hypotheses. Use
`vidiq_video_comments` only for useful corroboration, preferring deidentified paraphrases;
comments are not representative of every viewer.

## Deliver

Report the scoped retention findings with actual metric values/deltas, approximate analytics
positions, watched scenes when available, hypotheses, confidence, and material sample limits.
Include requested watch job status and distinguish missing visual evidence.

When the creator requests editing advice, prioritize supported structural changes and the next
experiment; preserve what worked. Rewrite the opening or section order only when requested.

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

View saved version →

---
name: vidiq-shorts-inspiration
description: Find original YouTube Shorts ideas by studying what is breaking out on Instagram Reels and TikTok, then adapting the hook, pacing, format, and payoff. Use when asked for 'Shorts ideas', 'how to go viral on Shorts', 'viral TikTok or Reels formats I can use', 'what's working on TikTok in [niche]', or 'how are my Reels doing'.
---

# vidIQ Shorts Inspiration

Read [Live surface notes](references/live-surface-notes.md) first, even when using only supplied evidence.

Study Instagram Reels or TikTok examples and adapt their abstract mechanisms into original
YouTube Shorts concepts. Transfer hypotheses need evidence from the target platform. For
long-form YouTube ideas switch to `vidiq-video-ideas`.

## Research a bounded sample

1. Establish the source platform, target audience, niche, region, and production constraints.
2. Search with `vidiq_instagram_tiktok_outlier_search`, building `audienceQuery` from the supplied
   audience. Ask when context is vague rather than inferring sensitive traits. Set `embeddingType`
   (`concept`, `hook`, or `format`) and `query`. Date bounds require full ISO 8601 datetimes with
   timezone, not date-only strings.
3. Read [Discovery evidence](references/discovery-evidence.md) when evaluating source examples,
   including supplied results. Search only relevant concept, hook, or format lanes. Apply its
   minimum separately per platform before claiming a recurring pattern.
4. Use `vidiq_watch_shortform_content` on strong examples within scope. Verify the source and
   pass full public URLs, expanding Instagram shortcodes into full reel
   URLs; bare IDs, shortcodes, and TikTok short links are invalid. Preserve, poll, and recover
   jobs using [Job lifecycle](references/job-lifecycle.md); read it before a watch call.
5. Compare hook, pacing, on-screen text, reveal, payoff, duration, and production complexity
   from actually watched content or completed watch results. Covers, captions, URLs, and pending
   or failed watches cannot establish moving-image details. Mark missing visual evidence;
   use caption/title-only findings when that is all available.
6. For needed Instagram creator context or shortcode verification, selectively use
   `vidiq_ig_accounts_from_outliers`, `vidiq_ig_profile`, or `vidiq_ig_profile_reels`.
   Match the target shortcode in returned reels; never assume the first result is the target.
7. For the creator's own Instagram results, call `vidiq_instagram_connected_accounts` first. For an
   account with `accessLevel: "owner"`, `vidiq_instagram_owner_insights` with that
   `platformAccountId` adds shares, saves, watch time, and skip rate; a `public_fallback` account
   gets only public Reel data through `vidiq_ig_profile_reels`, labeled as such. Publishing a Reel
   with `vidiq_instagram_publish_reel` is a separate write that needs an explicit request, a
   vidIQ-hosted video URL, and approval of the exact account, caption, and settings.

## Verify transfer to Shorts

Use `vidiq_outliers` with `contentType: short` or `vidiq_trending_videos` with
`videoFormat: short` where the requested language is supported. Outliers rejects non-English
Shorts; use a supported alternative or disclose the gap. YouTube search with
`type: ["video"]` and `videoDuration: short` means under four minutes, not verified Shorts.
Check actual format before counting candidates; `vidiq_channel_videos` requires
`videoFormat: short`.

Use semantic mechanism searches primarily (`requireAllTitleTerms: false` when declared), with
strict phrases as supporting evidence. Apply the same relevance gate to YouTube results; a
bounded search cannot establish that nobody has adopted a mechanism.

Explain which viewer motivation transfers and how opening, reveal, and payoff need adapting.
Check dependencies on platform-specific audio, trends, interface, and audience context against
relevant watched target examples. Without that evidence, label transfer a hypothesis.

## Deliver original adaptations

Return the requested patterns/adaptations with source evidence grouped by platform, target-platform
support, production notes, confidence, and contradictions. Keep incomparable platform scores
separate. State actual watch status and material coverage limits.

Change subject, wording, examples, visuals, and payoff; use original or appropriately licensed
footage/audio, preserving required attribution. Do not copy or reupload source clips. Additional
generation requires a request and relevant source and likeness rights. Voice cloning also
requires explicit speaker consent.

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

View saved version →

---
name: vidiq-trend-radar
description: Judge YouTube trends by urgency, durability, saturation, and accessibility to smaller channels using live vidIQ data. Use when asked 'what's trending on YouTube today', 'trending topics in [niche] this week', 'is this trend worth a video', or 'should I jump on this now or is it too late'. Classifies topics as urgent, durable, mature, or misleading.
---

# vidIQ Trend Radar

Read [Live surface notes](references/live-surface-notes.md) first, even when using only supplied evidence.

Separate current velocity, channel-relative breakout, durable demand, and creator accessibility.
Recommend timing from evidence and production lead time. Switch to `vidiq-youtube-seo` for keyword
volume and tags, and to `vidiq-next-video-planner` for a ranked next-video choice.

## Gather a bounded evidence set

Read [Discovery evidence](references/discovery-evidence.md) before evaluating trend examples,
including supplied results.

1. Define niche, audience, region/language, format, and horizon; use a bounded research
   plan. Before a saved-watchlist scan, exclude self, known siblings, and unrelated channels from
   analysis, disclose uncertainty, and leave the list unchanged.
2. Use `vidiq_trend_categories` only when its taxonomy can narrow outliers through
   `trendCategories`; those slugs are not inputs to `vidiq_trending_videos`.
3. Use `vidiq_trending_videos` for absolute velocity with required `videoFormat: long` or
   `short`, `videoTitleLanguage`, and a relevant `channelCountry`. Creator country is not
   audience geography. Use `vidiq_outliers` separately for channel-relative performance, with
   explicit supported `contentType`/`language`; omission defaults to English. Outliers rejects
   non-English Shorts, narrows non-English `all` to long-form, and caps non-English discovery at
   six months. Neither discovery tool provides a live-only lane; disclose unsupported coverage.
4. Apply the shared relevance/independence rule to inspected titles and images. Match transferable
   viewer motivation for cross-niche searches. Use semantic `requireAllTitleTerms: false` where
   declared, with strict matching as supporting evidence.
5. Use `vidiq_keyword_research` for search durability. Seed `research` gives demand context;
   `rising` accepts supported trend windows/categories and ignores `keyword`; narrow it to a phrase
   only with `includeKeyword` where declared (whole words or adjacent phrases).
   Search demand alone does not prove format fit.
6. Use `vidiq_video_stats` on finalists with required age-appropriate `granularity`; prefer
   `hourly` for recent trends and explicit ISO `from`/`to` bounds. Analyze historical `vph`,
   not cumulative views. Use comparable windows, allowing younger videos less than a full day
   of history. Normalize outlier epoch seconds and other ISO dates to a common timezone.
7. When accessibility matters, use `vidiq_channel_search` with `breakoutChannel: true`.
   Apply `subscriberCountMin` only for a requested or justified cohort boundary; disclose the
   reason and flag tiny-base growth as uncertain instead of excluding new creators by default.

## Classify from evidence

The labels are reporting aids, not fixed thresholds or deadlines. Leave unsupported cases
unclassified and state what observation could change the recommendation.

| Class | Evidence and response |
| --- | --- |
| **Urgent** | Relevant independent examples exceed positive comparable baselines with measured rising velocity. Act soon only if production fits the opportunity window. |
| **Durable** | Recurring need supported by relevant content over time and search demand; normal production timing can fit. |
| **Mature** | Measured plateau or decay across relevant examples with established demand. Differentiate or pass; age alone is insufficient. |
| **Misleading** | Evidence on relevance, independence, or sustained demand contradicts the apparent opportunity. State the contradiction; the topic itself need not be worthless. |

For urgency, use at least two timestamped non-null historical VPH observations per qualifying
example. Report baseline source, comparable format/age scope, window, and contrary movement.
One VPH snapshot, total views, or age cannot establish acceleration. Missing historical VPH or
positive comparable baselines leaves urgency unconfirmed.

Claim measured search-demand growth only for the same keyword with current value, positive
baseline, comparable market/window, and usable freshness timestamp. Prefer returned
`searchDemandGrowthPct` with that context; related keywords, upstream ranking, or raw growth are
not substitutes. Stable demand may support durable fit without positive growth.

High channel concentration plus declining VPH is a warning, not proof of a misleading trend.
Show cohort size, concentration denominator, sampling limits, and corroborating contradictions.

## Deliver

Return relevant opportunities with velocity, relative breakout, search durability, accessibility,
class, timing, production fit, and confidence. State the evidence date, actual filters, strongest
counterevidence, and next reassessment signal. Offer an original format/angle; keep timing a
reasoned estimate rather than a guaranteed trend half-life.

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

View saved version →

---
name: vidiq-video-breakdown
description: Analyze any public YouTube video from a URL or ID, covering view history and velocity, title and thumbnail changes, transcript hooks and structure, comment themes, similar videos, and estimated earnings. Use when asked 'analyze this video', 'why did this video go viral', 'break down this competitor's video', 'summarize this YouTube video', or 'how much did this video earn'. No channel authorization needed.
---

# vidIQ Video Breakdown

Read [Live surface notes](references/live-surface-notes.md) first, even when using only supplied evidence.

Explain how a public YouTube video performed and why, from its own evidence. Any video qualifies;
private analytics are neither required nor assumed.

## Identify the video

1. Resolve the video ID from the supplied URL or ID. Fetch title, channel, publication date, duration,
   format, and current stats with `vidiq_get_videos_by_ids`. Without a resolvable video, stop and ask.
2. Use a bounded evidence plan: start with one call per lane below and add calls only when a finding
   could change the conclusion.

## Gather the lanes

- **Performance:** `vidiq_video_stats` with a required `granularity` matching the video's age
  (`hourly` for recent uploads, `daily` or `monthly` otherwise) and explicit ISO `from`/`to`
  bounds. Read historical `vph` for acceleration or decay; cumulative views are not velocity.
  Compare against the channel's typical results with `vidiq_channel_videos` (`popular: false`,
  matching `videoFormat`) as a sample, never as the full catalog. `vidiq_channel_stats` with the
  `channelId` and an optional `from`/`to` window adds subscriber, view, and video-count growth for
  size context.
- **Packaging history:** `vidiq_video_change_history` accepts a video ID or a watch, youtu.be,
  Shorts, or live URL and returns observed title and thumbnail `changes`, with archived snapshots,
  plus thumbnail `abTests`. Align them with the stats timeline; an empty history means no change
  was observed, not that none happened.
- **Content:** `vidiq_video_transcript` returns untimed `transcription`; use it for the hook,
  promise, structure, and payoff. Read [Discovery evidence](references/discovery-evidence.md) before
  claiming a pattern from the transcript or from similar videos.
- **Audience response:** sample `vidiq_video_comments` with explicit `order` and singular
  `maxResult`. Summarize themes with paraphrases; never reproduce usernames or full comments. Hand a
  deeper language bank to `vidiq-comment-insights`.
- **Independent executions:** `vidiq_similar_videos` with the live `matchOn` and
  `excludeSeedChannel: true` shows whether the premise works for other channels; inspect
  `signalsUsed`, `signalsFailed`, and `matchedBy` first.
- **Packaging quality:** `vidiq_score_title` with confirmed `type` and `vidiq_score_thumbnail` with
  the real `videoId`, current `title`, and thumbnail `image` give directional scores, not verdicts.
- **Earnings:** when asked what the video earned, `vidiq_video_earnings_estimate` with the
  `videoId` gives a low, mid, and high USD range from vidIQ's RPM model; label it an estimate that
  assumes a monetized channel and ad-serving views. For "what would X views earn" scenarios use
  `vidiq_earnings_calculate` with `subject`, `monthlyViews`, `category`, and `format`.
- **Moving image:** only when pacing or on-screen structure changes the conclusion, read
  [Job lifecycle](references/job-lifecycle.md), then submit `vidiq_video_watch` for long-form or
  `vidiq_watch_shortform_content` for Shorts. Transcripts and thumbnails cannot establish scene
  timing.

## Explain the result

Separate observations from hypotheses. Attribute performance to demand, packaging, distribution,
retention, or timing only with corroborating evidence, and state the strongest competing explanation.
Views and channel size give context; a breakout on a large channel is not a transferable mechanism
for a small one.

## Deliver

Report the video, evidence window and gaps, performance trajectory, packaging and content findings,
audience themes, transferable lessons, confidence, and the next read that would most improve it.
Keep adaptations original.

For the creator's own fresh upload use `vidiq-new-upload-review`; for an authorized channel's
retention curve use `vidiq-retention-analysis`; to repackage the video use `vidiq-packaging-studio`.

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

View saved version →

---
name: vidiq-video-ideas
description: Find original YouTube video ideas from outlier videos overperforming right now in the creator's niche and adjacent niches. Use when asked for 'video ideas', 'content ideas', 'what's working in my niche', 'videos breaking out', or '10 ideas for a [niche] channel'. Returns concept cards for packaging. For a ranked choice based on the creator's own analytics use vidiq-next-video-planner.
---

# vidIQ Video Ideas

Read [Live surface notes](references/live-surface-notes.md) first, even when using only supplied evidence.

Find concepts in videos that overperform on their source channels. Use own-channel and competitor
context to discover title mechanisms across adjacent niches serving the same viewer motivation.
Hand off full packaging to `vidiq-packaging-studio`.

## Establish the scan

Read [Discovery evidence](references/discovery-evidence.md) before evaluating concept sources,
including supplied examples.

Reuse supplied channel, niche, viewer, format, language, and market context; ask only for gaps that
change the scan. Keep the scan bounded, e.g. one or two outlier calls per mechanism lane,
including the shared bounded correction.

Resolve canonical channel IDs from supplied context, `vidiq_user_channels`, or exact-handle
`vidiq_channel_search`. Authorized IDs do not supply niche classifications. Reuse a supplied
niche; otherwise search a known handle/title and verify the returned `channelId` before using
`niche` or `subNiches`. Use `vidiq_get_channels_by_ids` for a missing title only if necessary.
Missing classification stays unknown or needs creator input.

Keep these evidence lanes distinct:

- **Own channel:** use matching-format `vidiq_channel_videos` and authorized analytics when useful.
  Catalog calls require `videoFormat: long`, `short`, or `live`. For sampled per-video analytics,
  use `dimensions: ["video"]` and `filters: "video==ID1,ID2"` in batches of at most 150.
  Missing requested rows are unknown.
- **Exact niche:** use an existing `vidiq_list_competitors` result or `vidiq_similar_channels`.
  Canonical `channelId` mode permits optional `size`/`sort`; manual `niche` mode has separate
  filters and no `subNiches` input. Country may affect ranking rather than eligibility.
  Exclude self, known siblings, and unrelated channels from analysis; disclose uncertainty and
  leave the saved list unchanged.
- **Adjacent niches:** use audience-focused semantic `vidiq_channel_search` and known creators.
  Verify returned market fit. Shared viewer motivation, not topical similarity alone, supports
  transfer; a small scan cannot prove the creator's audience has never seen a concept.

## Discover and judge concepts

1. Search `vidiq_outliers` with mechanism-shaped `keyword` queries, such as “I analyzed 100…”.
   Use `requireAllTitleTerms: false` for semantic discovery and strict `true` phrases as support;
   verify exact wording locally. Reserve own/competitor `channelIds` scans for separate context
   (up to 50 IDs). Set recent `publishedWithin`, matching `contentType`, and `sort: breakoutScore`.
2. Check the format/language combination. Outliers rejects non-English Shorts and has no live-only
   lane. For non-English outliers, `all` narrows to long-form and discovery is capped at six months.
   Pass a supported `language` explicitly; omission means English. A supported
   `vidiq_trending_videos` alternative uses `videoFormat` and `videoTitleLanguage`, but measures
   absolute velocity rather than channel-relative breakout. Disclose unavailable coverage.
3. Use `vidiq_similar_videos` selectively for independent executions of a seed. Choose the live
   `matchOn`, set `excludeSeedChannel: true` when appropriate, and inspect `signalsUsed`,
   `signalsFailed`, and `matchedBy` before relying on matches.
4. Apply the shared relevance/independence rule to inspected titles and images. Test whether the
   promise survives adaptation, audience overlap is credible, and production is feasible.
   Exclude fame-dependent or unaffordable mechanisms from feasible adaptations.
5. Name each surviving mechanism and explain its transfer. Rank with an editorial rubric for
   audience fit, originality, truthful payoff, and feasibility; label the rubric result separately
   from evidence confidence. Consider views, channel size, publication age, baseline stability,
   and market. Nonpositive or tiny baselines cannot establish reliable relative uplift.
   Favor feasible small-channel examples without excluding larger sources.
   Parse outlier `videoPublishedAt` as epoch seconds before comparing ages with ISO dates.
   Validate adapted-topic demand with `vidiq_keyword_research`, `mode: research`, only if useful.

For recurring scans, exclude previously shown video IDs; persist lanes and the seen list in a
client file/project note only when the creator wants a standing workflow.

## Deliver

Return concept cards with source/link and lane, actual performance context, inspected thumbnail
evidence or its limitation, the adapted concept, mechanism/transfer reasoning, and a working title,
hook, and format direction. Include separate rubric judgments and evidence confidence.

Report coverage and exclusions once per scan. Use original wording and present concepts as
research candidates, not performance predictions. Generate no assets or tool-based scores.

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

View saved version →

---
name: vidiq-video-metadata
description: Apply approved changes to a YouTube video you own through vidIQ (title, description, tags, chapters, privacy, scheduled publish time, or thumbnail), with a snapshot and readback. Use when asked 'update my video title', 'change the description', 'add these tags', 'add chapters', 'schedule this video', or 'swap the thumbnail'. Requires owner authorization and explicit approval of the exact change.
---

# vidIQ Video Metadata

Read [Live surface notes](references/live-surface-notes.md) first, even when using only supplied evidence.

Apply an explicitly approved change to a YouTube video the connected account owns. Drafting belongs
to other skills; this workflow applies one exact change safely.

## Confirm scope and ownership

1. Confirm the live tool list includes `vidiq_update_video` (title, description, tags, privacy,
   scheduled publish time) or `vidiq_update_video_thumbnail`. If absent, stop: the Claude.ai directory
   connector and API-key connections expose no write tools, so the creator needs the custom connector
   URL with browser sign-in. Route to `vidiq-get-started`; do not improvise with another tool.
2. Resolve the owner with `vidiq_user_channels` and the target video with `vidiq_user_videos` (the
   owning `channelId`, with `privacyStatus`, `videoType`, `search`, `order: "newest"` or
   `"oldest"`, `limit`, and `pageToken` filters; it lists public, unlisted, and private videos) or
   a supplied ID. Require the video's `channelId` to match an authorized ID; a public video on another
   channel cannot be edited.
3. Capture a snapshot of the current title, description, tags, privacy, and publish time with
   `vidiq_get_videos_by_ids`, and read `vidiq_video_change_history` (the `videoId`; it returns
   observed title and thumbnail `changes` and thumbnail `abTests`). Say so before changing a title
   or thumbnail while an A/B test is running.

## Prepare the exact change

1. Use supplied drafts. If the creator wants keyword or scoring help first, run `vidiq-youtube-seo`
   or `vidiq-packaging-studio` and return here with the chosen text.
2. Present a field-by-field diff: current value, proposed value, and unchanged fields. Keep every
   field within YouTube limits (title 100 characters, description 5,000, tags 500 in total).
   `tags` replaces the whole list, and an empty `description` or `tags` clears it. For "add these
   tags", propose the snapshot's tags plus the additions and show any tag that would be removed.
3. For a schedule, `publishAt` takes a UTC time ending in `Z` and applies only to a private video.
   Convert the creator's stated time and timezone, show both, and include `privacyStatus: "private"`
   in the diff. A public or unlisted video cannot be scheduled as it stands; making it private first
   hides it and needs its own explicit approval.
4. For a thumbnail, pass exactly one of `thumbnail` (an HTTPS URL served without redirects, or a
   PNG or JPEG data URI) or `thumbnailFile`; PNG or JPEG up to 2 MiB. For "add chapters", start
   `vidiq_generate_video_chapters` with the `videoId` and optional `chapterCount`, `language`, and
   `startBufferSeconds`; it is asynchronous, so read [Job lifecycle](references/job-lifecycle.md),
   poll `vidiq_job_poll`, let the creator pick one of the three titles per chapter, and place the
   block in the description diff. It needs an accessible transcript and changes nothing by itself.
5. Call out consequences: a new title or thumbnail resets viewer expectations, a privacy change is
   visible immediately, and a schedule change can move a launch.
6. Obtain approval of the exact diff and the credit cost. Approval of a draft is not approval to
   publish; ask once, precisely.

## Apply once and verify

1. Immediately before the call, re-read the current values. If they differ from the snapshot, abort,
   show the concurrent difference, and ask for approval again.
2. Call `vidiq_update_video` once with the owning `channelId`, the `videoId`, and only the approved
   fields, or `vidiq_update_video_thumbnail` once with the same IDs and the approved image. Preserve
   the response.
3. A `verification_required` status means the write is waiting on YouTube verification, not that it
   failed. Show the returned verification step, wait until the creator confirms it is complete, then
   repeat the same approved call once; it needs no new approval.
4. Read back with `vidiq_get_videos_by_ids` and compare every approved field. Report any
   discrepancy, partial update, or limit failure; never silently retry, roll back, or resubmit. If
   the readback fails, label the result unverified and distinguish response-confirmed state.

## Deliver

Report the owner and video, the approved diff, the confirmed final values or the exact verification
gap, the charged credits as returned, and anything the creator still needs to do in YouTube Studio.

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

View saved version →

---
name: vidiq-youtube-seo
description: Research YouTube keywords and search demand with vidIQ, then draft tags, a description, and title angles. Use when asked 'youtube keyword research', 'search volume for [topic]', 'youtube seo', 'tags for my video', or 'write my video description'. Text output only; applying changes to a video belongs to vidiq-video-metadata.
---

# vidIQ YouTube SEO

Read [Live surface notes](references/live-surface-notes.md) first, even when using only supplied evidence.

Research search demand for a topic or video and draft SEO-ready keywords, tags, a description, and
title angles. Keep this workflow read-only: no generation tools and no YouTube changes.

## Establish the target

1. Use the supplied topic, draft title, script, or video URL plus audience, language, market, and
   format. Ask one compact question only when a gap changes the keyword inputs.
2. For a published video, fetch its current title, description, and tags with
   `vidiq_get_videos_by_ids` so drafts improve the existing metadata instead of replacing it blindly.
3. Resolve the creator's channel with `vidiq_user_channels` only when channel context, such as format
   mix or past topics, changes the recommendation.

## Research demand

Read [Discovery evidence](references/discovery-evidence.md) when judging recurring patterns in
competing titles, including supplied examples.

- **Seed keywords:** call `vidiq_keyword_research` with `mode: "research"`, one seed `keyword`, and
  an optional supported `country`. Capture search volume, competition, and related terms as returned.
  Run additional seeds only when the first set cannot cover the topic; keep the plan bounded.
- **Momentum:** use `mode: "rising"` with `period` and `language` only when timing matters. Discover
  `availableTopics` before supplying a `topic`. Rising mode ignores `keyword` and `country`; to test
  a specific phrase, pass it as `includeKeyword` where declared, which matches whole words or
  adjacent phrases only.
- **Competing results:** use `vidiq_youtube_search` with `type: ["video"]` for the top results on the
  chosen phrase. Note title patterns, publication ages, and channel sizes without copying wording.
- **Short-form demand:** when the creator makes Shorts, use `vidiq_trending_videos` with the phrase
  as `titleQuery`, `videoFormat: short`, and the matching `videoTitleLanguage` to check whether it
  appears in short-form at all. Velocity measures current interest, not search durability.

Keep measured demand, competition, and growth separate from scores or rank. Missing, stale, or
nonpositive baselines cannot establish growth, and search demand alone does not prove format fit.

## Draft the metadata

1. Shortlist up to five keywords, or the requested count, with the measured demand and competition
   for each and a note on why it fits the creator's audience and channel size.
2. Draft tags from the shortlist and natural variants within YouTube's 500-character tag limit.
3. Draft a description that leads with the primary phrase in the first two lines, reads naturally,
   and never repeats terms for their own sake. Include chapters or links only when supplied; for a
   chapter block from captions, `vidiq-video-metadata` runs `vidiq_generate_video_chapters`.
4. Suggest title angles that contain the primary phrase truthfully. Score candidates with
   `vidiq_score_title` using the confirmed `type: long` or `short` only when the creator wants scores;
   scores are directional, not predicted traffic.

## Deliver

Return the keyword shortlist with evidence, the draft tags, the draft description, title angles, and
the limitations of the sample (market, language, date). State what would change the recommendation.

Do not apply anything. To update a published video's title, description, or tags, hand the approved
drafts to `vidiq-video-metadata`. For trend timing use `vidiq-trend-radar`; for creative title and
thumbnail concepts use `vidiq-packaging-studio`.

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