vidIQ

View saved version →

---
name: vidiq-channel-audit
description: Audit an authorized YouTube channel over 30, 60, or 90 days. Compare performance, formats, and portfolio patterns; recommend evidence-led actions without generating content or changing state.
---

# 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.
- **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 or retention question
to its matching skill.

Referenced files: 2

View saved version →

---
name: vidiq-comment-insights
description: Find deidentified viewer phrases, questions, objections, and desired outcomes in YouTube comments, with transcripts as creator context. Use for audience research, hooks, titles, scripts, or offers.
---

# 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.
Keep viewer wording distinct from the creator's transcript and from original copy.

## 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.

## 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.

## 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: 3

View saved version →

---
name: vidiq-competitor-watchlist
description: Audit an authorized YouTube channel's competitor watchlist, identify direct competitors and format references, discover emerging channels, and propose or execute explicitly approved follow/unfollow changes.
---

# 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.

## 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. 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.

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

View saved version →

---
name: vidiq-get-started
description: Connect vidIQ MCP, check channels and credits, troubleshoot errors, recover jobs, and choose a workflow. Use for setup, connection or capability checks, and account or job problems.
---

# 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"`.
- 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.
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`.

## 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.

Honor a more specific request with its matching skill. 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

View saved version →

---
name: vidiq-new-upload-review
description: Assess a new YouTube upload against its channel's performance at the same publication age. Recommend whether to wait, inspect packaging, or reassess during its first hours or days.
---

# 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.

## 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_channel_videos` with `popular: false` and confirmed
   `videoFormat: long`, `short`, or `live`, 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.
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

View saved version →

---
name: vidiq-next-video-planner
description: Rank original next-video opportunities for an authorized YouTube channel using channel fit, competitors, outliers, search demand, and trend timing. Use for topic selection and evidence-based briefs, without generating assets or changing state.
---

# 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.

## 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 has no arbitrary `keyword`/`country`
  filter. Keep measured demand/growth separate from scores or ranking; missing, stale, or
  nonpositive baselines cannot establish relative growth.
- **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: 3

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

View saved version →

---
name: vidiq-packaging-studio
description: Create or improve YouTube titles and thumbnails from ideas, scripts, references, or published videos. Use for full packaging or focused edits, including title-only rewrites from supplied context without MCP calls.
---

# 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 an explicit comparison of distinct concepts, use `vidiq-packaging-comparison`.

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.

## 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

View saved version →

---
name: vidiq-retention-analysis
description: Analyze an authorized YouTube video's retention to investigate drop-offs, pacing, expectations, or structure. Align findings with timestamped scenes only when visual analysis is within scope and available.
---

# 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`; 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.
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

View saved version →

---
name: vidiq-shorts-inspiration
description: Study Instagram Reels or TikTok to develop original YouTube Shorts concepts. Use for cross-platform hook, pacing, format, and payoff research.
---

# 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.

## 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.

## 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

View saved version →

---
name: vidiq-trend-radar
description: Assess YouTube trends by urgency, durable demand, maturity, misleading signals, and accessibility to smaller channels. Use to prioritize timely content and distinguish current velocity from sustained search demand.
---

# 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.

## 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, not an arbitrary keyword filter.
   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

View saved version →

---
name: vidiq-video-ideas
description: Find original YouTube video concepts inspired by outlier title mechanisms across adjacent audiences. Use for breakout inspiration, recurring idea scans, and concept cards for vidiq-packaging-studio.
---

# 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