analyze-creator-videos

name

analyze-creator-videos

description

Analyze a creator's complete public video portfolio and build an evidence-backed operating Dashboard. Use when Codex must collect or resume a creator inventory; verify downloaded media; study one creator or blogger across all visible posts; compare high, median, arithmetic-mean-near, and low performers; explain positioning, audiences, topics, formats, visual language, publishing patterns, success and failure mechanisms; select representative videos for deep reconstruction; turn findings into launch or account-growth decisions; or update the reusable List + Gallery creator intelligence Dashboard. Supports a creator profile URL, collected corpus JSON, or an existing local research directory. For Xiaohongshu acquisition, use ego-browser with the user's authenticated session; never substitute a Chrome/Google scraping route.

Analyze Creator Videos

Build a creator operating system, not a decorative long report. Separate corpus facts, video-internal evidence, author claims, system inferences, external verification, and unknowns throughout.

Read session-derived-infrastructure.md before creating a new run or changing the pipeline. Its gates come from the real build history that produced the reference Dashboard.

Core model

Run two connected layers:

1. Portfolio layer: inspect every visible post at metadata/annotation level to learn the account's baseline, positioning, content system, distribution, topics, formats, publishing rhythm, and outliers.
2. Evidence layer: deeply reconstruct a bounded representative set with $video-content-reconstruction before making claims about content mechanisms.

Default deep set: high, median, arithmetic-mean-near, and low performance, 3 videos per group. Use the full corpus for quantitative context, a comparison set of 5–7 per group for pattern induction, and 3 per group for evidence-grade reconstruction. Median and mean are separate because breakout posts can pull the mean far above the typical post. If no post lies within 25% of the mean, label mean_gap and compare its nearest lower/upper neighbors instead of inventing an average tier. Do not reconstruct every video unless the user explicitly requests it and accepts the cost.

Inputs

Accept one or more:

• creator profile URL;
• normalized corpus JSON matching creator-corpus.schema.json;
• existing local creator research directory;
• optional local videos, subtitles, covers, comments, and public metrics;
• optional target account or business strategy to inform the final launch plan.

Create a new run directory. Never overwrite an existing creator artifact unless the user explicitly asks to update it. Store authenticated URLs, session state, and login information outside public outputs.

Workflow

1. Establish the analysis contract

Write analysis-contract.json and run-manifest.json before collecting or interpreting data:

• why the creator is being analyzed;
• decisions the result must support;
• available platforms and snapshot time;
• allowed public metrics;
• unavailable backend metrics;
• default full-corpus, comparison-set, and deep-set sizes;
• target account constraints, if any.

run-manifest.json is the single control plane for artifact paths, source revisions, stage status, validation status, and downstream invalidation. Never maintain a second canonical Dashboard or duplicate specification tree for the same creator run.

The Dashboard must answer why this creator is analyzed, what method was used, and which decisions can and cannot be made from the evidence.

2. Acquire or normalize the corpus

For Xiaohongshu, read acquisition-xhs.md and collection-infrastructure.md, then use $ego-browser. Reuse the authenticated hhh-01 session when available. Respect handoff and user-control rules. Do not use Chrome, Google browser automation, or hidden credential extraction.

When the user asks for broad platform discovery through Xiaohongshu's in-site AI, also read xhs-site-ai-discovery.md. Treat its answer as a candidate generator only; independently open and verify cited creators/posts before they enter the canonical corpus.

Initialize and maintain the resumable collection control plane:

node <SKILL_DIR>/scripts/init-collection.mjs \
  --out /absolute/path/run/collection-inventory.json \
  --creator-id <known-or-provisional-id> \
  --creator-name <creator-name> \
  --profile-url <profile-url> \
  --server hhh-01

Ingest sanitized profile, crawl-round, and detail observations with the bundled ingestion scripts. Never call a timeout or extraction error “end of profile.”

For local input, normalize it directly. Preserve raw snapshots separately from normalized data.

node <SKILL_DIR>/scripts/normalize-corpus.mjs \
  --input /absolute/path/raw-or-normalized.json \
  --out /absolute/path/run/creator-corpus.json

Do not silently convert missing values to zero. Record capture failures and incomplete pagination in collection-status.json.

Before portfolio analysis, build the collection gate:

node <SKILL_DIR>/scripts/build-collection-status.mjs \
  --inventory /absolute/path/run/collection-inventory.json \
  --out /absolute/path/run/collection-status.json

Require inventory_ready. Before deep reconstruction, require selected media to pass scripts/verify-media.mjs and the status to become deep_media_ready.

3. Annotate every post at portfolio depth

Read data-contract.md. For every post, add open-ended, multi-label annotations grounded in title, cover, post copy, and available video evidence:

• topic and user problem;
• content form and intent;
• hook and promised payoff;
• target audience and use context;
• proof mode;
• presenter, composition, aspect ratio, screen/UI role, text density, and result visibility;
• content mechanism and likely audience action;
• uncertainty and annotation evidence.

Do not force posts into a closed taxonomy. Add new labels when the corpus demands them. Keep unclassified when evidence is insufficient.

4. Compute the full-corpus baseline

node <SKILL_DIR>/scripts/analyze-corpus.mjs \
  --input /absolute/path/run/creator-corpus.json \
  --out /absolute/path/run/corpus-analysis.json

Calculate count, video count, mean, median, percentiles, maximum, distribution, weekday/daypart statistics, topic and format clusters, and candidate pools for high/median/low comparison.

Prefer median and distribution over mean. Display maximum alongside median and mean. Treat likes, comments, collections, and shares as public engagement signals—not exposure, retention, conversion, or follower growth.

5. Build the comparison set and choose the deep set

Read selection-method.md.

• Compare 5–7 videos per high/median/average/low group when available.
• Select 3 videos per group for deep reconstruction, reusing an overlapping median/average item only once.
• Cover distinct mechanisms, content forms, durations, eras, and evidence modes.
• Do not choose nine videos solely by ranking.
• Record selectionReason, represented mechanism, alternatives considered, and known confounds for every selected item.

If the corpus is small, shrink tiers and disclose the denominator. Never label a three-video sample “the creator's universal rule.”

6. Reconstruct selected videos

Use $video-content-reconstruction for each deep-set video. Require its hard gates to pass before using a reconstruction as evidence.

For every selected video preserve:

• complete verbatim transcript;
• cue ↔ representative frame ↔ all overlapping shots;
• sparse and dense frame views;
• content architecture and core knowledge units;
• viewer cognitive change;
• procedural or argument relationships;
• claims, observations, inferences, and unknowns;
• full readable article that restores the video's key information.

Do not infer tool causality, product capabilities, commercial rights, performance, or success from montage adjacency.

7. Synthesize across videos

Generate creator-analysis.json matching creator-analysis.schema.json. Read analysis-method.md.

Separate observed portfolio facts, sample associations, mechanism hypotheses, optional external verification, and unknowns. Explain high vs median vs low through user value, content promise, proof strength, comprehension cost, information density, visual structure, novelty, audience fit, and CTA—not likes alone.

8. Produce the launch system

Translate findings into the user's account:

• positioning and audience wedge;
• three content lanes serving save, share, and trust goals;
• first 12 ideas;
• reusable script skeletons;
• proof checklist;
• one-variable experiments;
• dashboard metrics to add when backend data becomes available.

Mark what is transferable, what depends on the original creator's identity or era, and what must be tested.

9. Build or update the Dashboard

Read dashboard-contract.md. Produce dashboard-data.json matching dashboard-data.schema.json, then run:

node <SKILL_DIR>/scripts/build-dashboard-data.mjs \
  --corpus /absolute/path/run/creator-corpus.json \
  --stats /absolute/path/run/corpus-analysis.json \
  --analysis /absolute/path/run/creator-analysis.json \
  --selection /absolute/path/run/selection.json \
  --out /absolute/path/run/dashboard-data.json

node <SKILL_DIR>/scripts/render-dashboard.mjs \
  --data /absolute/path/run/dashboard-data.json \
  --out /absolute/path/run/dashboard

Use the bundled template. When updating an existing Dashboard, preserve its URL, navigation, visual system, and working interactions; add new evidence into the existing page rather than creating a weaker parallel Dashboard.

Treat dashboard/ as generated output. Change source data, schemas, scripts, or the template; do not hand-patch a delivered Dashboard as the only source of truth.

Required surfaces:

1. analysis purpose and account positioning;
2. full-corpus baseline and public-metric boundaries;
3. topic and format portfolios with count, median, mean, and maximum likes;
4. high/median/average/low comparison and success/failure mechanisms;
5. all-post List and Gallery views;
6. selected-video evidence with transcript, frames, content architecture, and unknowns;
7. publishing rhythm and video language;
8. launch plan, experiments, and methodology.

10. Validate

python3 <SKILL_DIR>/scripts/validate-json.py \
  --schema <SKILL_DIR>/schemas/analysis-contract.schema.json \
  --data /absolute/path/run/analysis-contract.json

python3 <SKILL_DIR>/scripts/validate-json.py \
  --schema <SKILL_DIR>/schemas/run-manifest.schema.json \
  --data /absolute/path/run/run-manifest.json

python3 <SKILL_DIR>/scripts/validate-json.py \
  --schema <SKILL_DIR>/schemas/collection-inventory.schema.json \
  --data /absolute/path/run/collection-inventory.json

python3 <SKILL_DIR>/scripts/validate-json.py \
  --schema <SKILL_DIR>/schemas/collection-status.schema.json \
  --data /absolute/path/run/collection-status.json

python3 <SKILL_DIR>/scripts/validate-json.py \
  --schema <SKILL_DIR>/schemas/creator-corpus.schema.json \
  --data /absolute/path/run/creator-corpus.json

python3 <SKILL_DIR>/scripts/validate-json.py \
  --schema <SKILL_DIR>/schemas/selection.schema.json \
  --data /absolute/path/run/selection.json

python3 <SKILL_DIR>/scripts/validate-json.py \
  --schema <SKILL_DIR>/schemas/creator-analysis.schema.json \
  --data /absolute/path/run/creator-analysis.json

python3 <SKILL_DIR>/scripts/validate-json.py \
  --schema <SKILL_DIR>/schemas/dashboard-data.schema.json \
  --data /absolute/path/run/dashboard-data.json

node <SKILL_DIR>/scripts/validate-run.mjs --run /absolute/path/run

Browser-smoke the final Dashboard on desktop and mobile. Check console errors, navigation, List/Gallery switching, selected-video switching, image loading, transcript links, overflow, and evidence-boundary visibility.

Completion gate

Do not announce completion unless:

• corpus coverage and collection failures are explicit;
• full-corpus statistics are reproducible from creator-corpus.json;
• all selected videos have selection reasons;
• every mechanism claim points to comparison or reconstruction evidence;
• no failed reconstruction is presented as validated;
• unknown backend metrics remain unknown;
• Dashboard List and Gallery both work;
• validation and browser smoke pass.

If any condition fails, report NOT_READY with the failed closure. Otherwise report READY_FOR_CREATOR_ANALYSIS and provide the canonical run path and Dashboard URL.

Output contract

analysis-contract.json
run-manifest.json
raw/                         # immutable collection snapshots
collection-inventory.json
crawl-ledger.jsonl
creator-corpus.json
collection-status.json
corpus-analysis.json
selection.json
videos/<post-id>/            # deep reconstructions and evidence
media-verification/<post-id>.json
creator-analysis.json
dashboard-data.json
dashboard/index.html
dashboard/styles.css
dashboard/app.js
validation-report.json

Do not publish raw media, private comments, authentication data, or signed URLs to a public repository.