⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v0.4.3

viral-video-teardown-remake

beatra-ai@beatra-ai⭐ 9 stars· last commit 5d ago· 0 open issues

Turn a short video that already worked into your own version. Paste the link and this viral video teardown and short-video remake workflow reads the reference itself on TikTok, Douyin, Xiaohongshu, Instagram, YouTube, or X — caption, author, visible metrics, comments, and on YouTube the full transcript — or work from a file, screenshots, or your own description instead. It breaks the clip into its hook, body beats, and call to action, names the script pattern behind it, scores what carried the performance, then rewrites that structure around your product or topic — delivering a shot list with visuals and narration kept apart, reference frames from your own assets before any are generated, a narration track, and either an animated clip or segmented sources with a timecoded edit list. Use it to study a competitor's viral short, borrow a proven structure for Reels, Shorts, or WeChat Channels, rebuild a benchmark video under your own brand, or turn a saved reference into a content formula you can run again.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐ 9 on GitHubGitHub ↗

New / niche

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Viral Video Remake Skill

English | 简体中文 | 日本語

👉 See also AI Storyboard Generator Skill

Break a short video that worked into its hook, beats, and call to action, then rebuild that structure around your own subject as a shot list, beat frames, and narration, delivered as one vertical clip or as segmented sources with captions and a timecoded edit list, from inside Claude Code, Cursor, Codex, Windsurf, Cline, or OpenClaw.

[!IMPORTANT] Rendering needs a Beatra account and uses credits. The skill itself is free to install.

QuestionAnswer
What it doesPaste the link or bring the file, break a short video that worked into its hook, beats, and call to action, then rebuild that structure around your own subject as a shot list, beat frames, and narration — delivered as one vertical clip animated from your opening frame, or, when the reference cuts too fast or runs too long for a single take, as segmented sources with captions and a timecoded edit list.
ModelsQwen Image 2.0 Fast, Qwen Image 3.0, Qwen Image 3.0 Pro, GPT Image 2.5 Flare, GPT Image 2.5 Sunburst, GPT Image 2, Wan Image 2.7 Fast, Qwen Image 2.0 Pro, Wan Image 2.7 Pro, MiniMax Image 01 Live, MiniMax Voice Clone, MiniMax Speech 2.8 HD, MiniMax Speech 2.8 Turbo, MiniMax M3, Wan 2.7, Wan 3.0 Video, MiniMax H3, Seedance 2.0 Mini, HappyHorse 1.1, Seedance 2.0 Fast, Seedance 2.0, Wan 3.0 Video Prime, Seedance 2.5
RequirementsPython 3.10+ and an agent that loads SKILL.md
CostFree to install. Each render uses credits on your Beatra account, and paid steps run only when you ask for that exact render or approve its card.
Works withClaude Code, Cursor, Codex, Windsurf, Cline, OpenClaw

Four 9:16 beat frames (Hook, Demo, Benefits, CTA) remaking a hypothetical pain-first short structure for Brightfold, a fictional foldable desk lamp. AI-generated with Beatra.

SkillEntry pointVersion
viral-video-teardown-remakeSKILL.md0.4.3

This repository is published automatically from beatra-ai/beatra-skills. Report issues there.

Install

With the skills CLI:

npx skills add beatra-ai/viral-video-remake-skill

As a Claude Code plugin:

claude plugin marketplace add beatra-ai/viral-video-remake-skill
claude plugin install viral-video-teardown-remake@viral-video-remake-skill

As a Codex plugin:

codex plugin marketplace add beatra-ai/viral-video-remake-skill
codex plugin add viral-video-teardown-remake@viral-video-remake-skill

As a GitHub Copilot CLI plugin:

copilot plugin marketplace add beatra-ai/viral-video-remake-skill
copilot plugin install viral-video-teardown-remake@viral-video-remake-skill

As a Gemini CLI extension:

gemini extensions install https://github.com/beatra-ai/viral-video-remake-skill

As an Antigravity CLI plugin:

agy plugin install https://github.com/beatra-ai/viral-video-remake-skill

With the GitHub CLI:

gh skill install beatra-ai/viral-video-remake-skill viral-video-teardown-remake

Or clone this repository and copy skills/viral-video-teardown-remake into ~/.claude/skills/ for Claude Code, ~/.cursor/skills/ for Cursor, ~/.agents/skills/ for Codex, ~/.codeium/windsurf/skills/ for Windsurf, ~/.cline/skills/ for Cline, or ~/.openclaw/skills/ for OpenClaw.

Or paste this into your agent:

Install the viral-video-teardown-remake skill from https://github.com/beatra-ai/viral-video-remake-skill (folder skills/viral-video-teardown-remake), then follow its SKILL.md to connect my Beatra account.

Examples

▶ Watch the full video (MP4)

A 6-second vertical remake clip for the fictional lamp Brightfold: the Hook frame animated with the four-line narration covering hook, demo, benefits and call to action. AI-generated with Beatra.

Ask your agent:

Break down this short video (link in ./reference.txt) into its hook, beats and call to action, then rebuild that structure for my foldable desk lamp Brightfold using ./brightfold.jpg: shot list, beat frames, narration, and a vertical clip.

Prompt:

Evening on a cramped desk. The folded sage-green desk lamp in the foreground slowly unfolds on its own: its single flat arm rises from the round base, the long flat light bar lifts open at the small brass hinge, and the light bar switches on with a warm white glow that brightens the desk. Slow gentle camera push-in toward the lamp. The laptop, papers, mug and plant stay still. Smooth, realistic product-video motion.

Inputs and outputs

TypeFormatsSpecifications
InputText — A link to the reference post, a transcript, or your own description, plus what your version is about——
InputVideo — Reference video file, read frame by frame (optional)MP4, MOV, WEBM1 video per request; up to 360 s; up to 50 MB each
InputImage — Screenshots of key moments, or your own assets for the framesJPG, PNG—
InputAudio — A sample of your own voice to clone for the narration (optional)MP3, WAV10–300 s; up to 20 MB each
OutputText — Beat table with timings, script pattern, six-dimension score, and a shot list with visuals and narration kept apart—editable
OutputImage — Beat frames, delivered as imagesPNG, JPG, WEBPaspect ratios 9:16
OutputAudio — One narration track for the whole remakeMP3—
OutputVideo — One vertical clip animated from your opening frame, or segment clips with captions and a timecoded edit listMP4aspect ratios 9:16

Technical Specifications & Output Limits

As of 2026-10-18. Live list: https://docs.beatra.ai/en/docs/models

  • Uploads — up to 100 MB per file; the per-model input limits below also apply
  • Text to image — 10 models (Qwen Image 2.0 Fast, Qwen Image 3.0, Qwen Image 3.0 Pro, GPT Image 2.5 Flare, GPT Image 2.5 Sunburst, GPT Image 2, Wan Image 2.7 Fast, Qwen Image 2.0 Pro, Wan Image 2.7 Pro, MiniMax Image 01 Live); PNG; up to 4 images per request; canvas up to 16.8 MP
    • 16.8 MP (4K tier): Wan Image 2.7 Pro (up to 4 images per request); GPT Image 2.5 Flare, GPT Image 2.5 Sunburst, GPT Image 2 (1 image per request)
  • Voice cloning — 1 model (MiniMax Voice Clone); sample 10–300 s, up to 20 MB; consent attestation required
  • Text to speech — 2 models (MiniMax Speech 2.8 HD, MiniMax Speech 2.8 Turbo); FLAC, MP3, OPUS, PCM, WAV; 40 languages; sample rates 8, 16, 22.05, 24, 32, 44.1 kHz; up to 50000 characters per request
    • Languages (ISO 639 codes): zh, yue, en, es, fr, ru, de, pt, ar, it, ja, ko, id, vi, tr, nl, uk, th, pl, ro, el, cs, fi, hi, bg, da, he, ms, fa, sk, sv, hr, fil, hu, no, sl, ca, nn, ta, af
  • Video understanding — 1 model (MiniMax M3); 1 file per request; up to 50 MB each; up to 360 s; sampled at 1 fps
  • Image to video — 9 models (Wan 2.7, Wan 3.0 Video, MiniMax H3, Seedance 2.0 Mini, HappyHorse 1.1, Seedance 2.0 Fast, Seedance 2.0, Wan 3.0 Video Prime, Seedance 2.5); 480p to 4K; 2–30 s; a

// HOW IT'S BUILT

// FILES

22 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/viral-video-teardown-remake/SKILL.md23 KBdc1a66e74a49upstream ↗
    ---
    name: "viral-video-teardown-remake"
    description: "Turn a short video that already worked into your own version. Paste the link and this viral video teardown and short-video remake workflow reads the reference itself on TikTok, Douyin, Xiaohongshu, Instagram, YouTube, or X — caption, author, visible metrics, comments, and on YouTube the full transcript — or work from a file, screenshots, or your own description instead. It breaks the clip into its hook, body beats, and call to action, names the script pattern behind it, scores what carried the performance, then rewrites that structure around your product or topic — delivering a shot list with visuals and narration kept apart, reference frames from your own assets before any are generated, a narration track, and either an animated clip or segmented sources with a timecoded edit list. Use it to study a competitor's viral short, borrow a proven structure for Reels, Shorts, or WeChat Channels, rebuild a benchmark video under your own brand, or turn a saved reference into a content formula you can run again."
    ---
    
    # Viral Video Teardown Remake
    
    Take one short video that already performed, work out the structure underneath it, and rebuild that structure around the user's own subject — ending in shot frames, a narration track, and, depending on the chosen route, either one finished vertical clip or a segmented set of sources with captions and an edit list for the user's own cut.
    
    ## Scope and adjacent routes
    
    The route is: a reference clip, a teardown, a rewritten shot list, and a remade video. It fits when someone points at a specific video and wants their own version of it.
    
    When there is no reference to work from, another workflow fits better. An original idea with no benchmark belongs in a storyboard workflow. A product photo that should become a selling video belongs in a product-video workflow. A finished script that only needs a voice belongs in a voiceover workflow. Restyling the reference footage itself, rather than rebuilding it, belongs in a video-restyle workflow.
    
    ## Inputs and defaults
    
    Two hard inputs: the reference — and what the remake is about.
    
    The reference can arrive in several shapes, and every shape works. A video file the host Agent can open is richest for anything visual. Screenshots of the key moments, a pasted transcript or caption, or the user's own description of what happens each beat are all enough to run the teardown. Take whatever form arrives and say plainly, once, which parts you read yourself and which came from the user's account of it. Never describe frames you did not see.
    
    A link is the shape most people reach for first, and this package can read one directly: the post's caption, author, and visible metrics on TikTok, Douyin, Xiaohongshu, Instagram, YouTube, and X, its comments, and — on YouTube only — its transcript. Each of those is a paid lookup, each is optional, and each is confirmed on its own before it runs, per [reading the reference from a link](references/reference-lookup.md). A lookup never shows you a frame; framing, motion, and cutting rhythm still come from a file, from screenshots, or from the user.
    
    The subject is the user's product, service, topic, or account. Reuse whatever the conversation already states about it rather than asking again.
    
    Default to a 9:16 vertical canvas, a remake of the same length as the reference, a reference frame for the opening beat plus any others the user marks — with the final count following the rebuild route — and a narration voice matched to short social content. After the rewrite, default to checking that the remake's first 3 seconds carry the hook — the reason to keep watching — rather than restating the reference's opening credits or a self-introduction. Fix that in the still-free shot list before any generation confirmation. Name each default in the confirmation instead of asking about it.
    
    Two facts shape every decision. **Every video generation call must fit the selected live model card's supported duration** — for a single continuous take that bounds the whole clip, and for a segmented rebuild it bounds each unit while the clip itself runs as long as the sequence of units needs. And how many beats actually get animated follows from the chosen rebuild route: one opening frame for a short, low-cut reference that fits inside a single model unit, or a segmented sequence of units — each with its own reference frame — when the reference cuts fast or runs longer than the model allows. Both are stated at the confirmation, not discovered after paying.
    
    For a single continuous take, that same ceiling binds the narration too: the clip has to be at least as long as the spoken track, so the whole script has to read aloud inside it. A segmented rebuild carries no such ceiling on the narration as a whole — the unit split is what lets the clip run past any one model card's ceiling, while the narration still stays one continuous track. Either way, budget the spoken fields while they are still free text: count the read-aloud rate at roughly four to five Chinese characters or two to three English words per second, and cut what does not fit before the shot list is shown for approval — cutting after synthesis costs a second paid call, and discovering an overrun after a video call costs one of the most expensive ones.
    
    Claims split by source. Structure, pacing, and craft are yours to read off the reference. Specifications, prices, results, certifications, and promotions for the user's own subject come from the user. When those are missing, write around them; never produce a plausible figure, because the user is the one who answers for it.
    
    ## Golden path
    
    Segmenting the reference, rewriting it onto the user's subject, choosing the rebuild route, and the gate where the teardown, the shot list, and the rebuild plan get approved together — these genuinely cost nothing. Two calls can land ahead of that gate, and each is disclosed and confirmed on its own, before it runs, in the same shape: the optional social lookup, and — whenever the reference is a video file being read for its actual frames — the `beatra.videos.understand` call inside step 1. Neither is folded into the free stages that follow it, and nothing else is charged before the user has seen the teardown, the shot list, and the rebuild plan, and approved them together.
    
    **Before stage 1, only when the user brings a link and asks for it to be read:** look up the post, and — when the teardown needs them — its comments or its YouTube transcript, per [reading the reference from a link](references/reference-lookup.md). Skip it whenever the user already brought a file, screenshots, or a transcript; the teardown is just as real from those.
    
    1. **Read the reference.** When the reference is a video file whose actual frames still need reading, that reading is paid — billed per admitted input-video second, and capped at 50 MiB and 360 seconds of input video, a fixed tool limit that rejects anything past it before any charge is made — and it is confirmed on its own before it runs, exactly like the optional lookup above: state both limits, read the live per-second price from `beatra.models.list` (capability `video_to_text`) and quote that, never a number from memory, and say plainly that the teardown can still run at no cost from screenshots, a transcript, or the user's own account of it instead. Only once the user agrees, and the file is confirmed to sit inside both limits, make one `beatra.videos.understand` call, with `response_format` set to `json`, to pull the whole visual read in a single pass — never one call per question, since each call re-bills the entire clip. **Rescale before using any of it:** the model's own reported duration is wrong, so read the material's real duration from its own metadata and scale every returned timing against that, never against what the model claims. Dialogue never comes from this call — the vision model has no audio track to hear, so pull dialogue from its own four-tier source ladder instead, never from a guess the vision model makes about sound. Fill the four tables in [reading the reference](references/teardown.md).
    2. **Rewrite it onto the user's subject.** Keep the evidence table's line count and its per-line timing budget, and the shot table's shot count and functional sequence; replace the content itself. Write each beat as two separate fields — what is on screen, and what is said — because a merged field cannot be shot. For a single continuous take, budget the spoken fields against the selected live model card's duration ceiling and cut them until they fit; a segmented rebuild does not bind the whole script to that same ceiling, since the unit split is what absorbs a reference longer than one model card allows. Screen the copy as described in [rewriting onto your subject](references/remake-plan.md).
    3. Read the live `text_to_image` and `text_to_speech` cards with `beatra.models.list`, and select a voice with `beatra.voices.list`. Also read the live card for whichever video capability the shoot call will actually use — `image_to_video` for `beatra.videos.animate`, `frames_to_video` for `beatra.videos.interpolate`, `reference_to_video` for `beatra.videos.generate_from_references` on a segmented rebuild's unit built from ordered references, and `video_extend` whenever a single shot must be continued past the unit ceiling — because that capability's supported duration, not any other capability's, is what decides how the clip gets split into generation units. Do this before the shot list is signed off.
    4. **Choose the rebuild route.** The clip's row count, whether it has a hard cut, and the selected model's duration ceiling first rule out one route outright whenever they can; only when both routes remain structurally possible does it come down to asking the user directly whether they edit video themselves, per [three rebuild routes](references/rebuild-routes.md).
    5. **Show the teardown, the shot list, and the rebuild plan together, and get them approved.** This is the artifact the rest of the run is built from, and it is free to revise. Settle the route and the unit count here and state them plainly, spelling out the chain that produced them — this model, therefore this route, therefore this many units, therefore roughly this much. For a single continuous take, the spoken script has to fit the card's longest supported duration before this approval, because nothing later can make an over-long narration fit; a segmented rebuild is not bound by that same ceiling for the script as a whole, since the unit split — not the narration — is what absorbs a reference longer than the card allows.
    6. **Confirm preparation.** Show which beats become frames, the 9:16 canvas and what changing it later would cost, the selected ready voice from `beatra.voices.list` — or, when the user chose to clone one instead, the live `voice_clone` price and its own stable request ID — the current estimate, and a stable request ID for every planned paid call.
    7. **Source the reference frames, then generate.** Take each one from what the user uploads for this run or from what they already have in their own library first; fall back to `beatra.images.generate` only once neither tier has anything usable, and never generate a reference image for a physical product — a generated product shot is never that product. Synthesize the narration once for the whole clip with `beatra.speech.synthesize`, then read the actual returned duration, size, and MIME type.
    8. **Show the real materials.** Display the frames and play the narration whenever the host can access them, and report the true duration. Distinguish returned task facts from media the host could not inspect.
    9. **Show the video admission card, then run the paid generation.** Admit the duration first: for a single continuous take, the smallest whole second at or above the real narration length, supported by the selected live model card — never lower it to reach the ceiling; shorten the spoken fields and resynthesize instead, which is the cheapest call in the run. For a segmented rebuild, admit each unit's own duration from its slice of the shot table against that same card instead, not from the whole narration. Then show the chosen route, the call or calls it makes, the approved reference frame or frames, the narration, the duration — audio-led for a single continuous take, or each unit's own table-derived duration for a segmented rebuild — the provisional live estimate, the fact that the standard signup credit usually cannot start this video, and what happens if the balance is short. Planning, comparison, or "make the clip" is not approval; approved frames or narration do not authorize the video. Do not create a video `client_request_id` or submit until the user confirms they have topped up or already have enough credits for this estimate. Run the generation per [three rebuild routes](references/rebuild-routes.md) — one call for a single continuous take, or one call per unit for a segmented rebuild, keeping the per-unit ledger from [remake workflow](references/workflow.md) whenever there is more than one unit — poll every task with `beatra.tasks.get` to terminal, deliver the result accordingly, and review what you can actually see.
    
    For a single continuous take, select the video model explicitly rather than leaving it to `auto`: only some models on this capability accept supplied narration, and one that does not will discard it. Which capability that is follows from the call — `image_to_video` for `beatra.videos.animate`, `frames_to_video` for `beatra.videos.interpolate` — and the test is that the card admits the narration alongside whichever frames that call supplies, never one fixed input combination, since the two capabilities advertise different frame inputs. Those two are also the only calls a single continuous take makes: `beatra.videos.generate_from_references` has no driving-audio input at all, so a subject or product lock on this route is held by the reference frame, built from the user's own asset, that the call animates. A segmented rebuild's units carry no narration into the video call at all — the narration is delivered as its own track, which the user aligns in their own editor from the edit list's timecodes — so this requirement does not narrow which model a unit can use; still select each unit's model explicitly rather than `auto`.
    
    The canvas is decided by the first reference frame generated, so choosing it late means producing every paid artifact again.
    
    ## Decisions that require confirmation
    
    Confirm before spending: any reference lookup on its own, before anything else, whenever one is run at all; the `beatra.videos.understand` read of the reference's actual frames on its own, before it runs, whenever the reference is a video file; then the frame set and the narration together with every one of their priced calls — including a `beatra.voices.clone` call whenever the user chooses to clone a voice instead of picking a ready one free from `beatra.voices.list`; then the paid generation itself — one video call for a single continuous take, or one call per unit for a segmented rebuild, where a unit built from ordered references makes `beatra.videos.generate_from_references` instead of `beatra.videos.animate` or `beatra.videos.interpolate`, and a shot continued past the unit ceiling makes `beatra.videos.extend`. That last confirmation comes after the user has seen the accessible frames and heard the narration, because that work costs the most.
    
    Also confirm, rather than deciding alone: a canvas other than 9:16, a beat count that departs from the reference, a claim about the user's subject that they have not verified, and any change after an artifact is approved. Each changed argument is new paid work with a new request identifier and fresh approval.
    
    When the user asks for the reference's own footage, music, or on-screen person to be reproduced rather than its structure, say what this route does produce — an original clip built on the same structure — and continue from there.
    
    ## Execution
    
    Invoke every remote Beatra tool only through the bundled `scripts/mcp_client.py`, with the tool name as the CLI argument and its arguments as JSON on standard input:
    
    ```text
    printf '%s' '{"capability":"text_to_image"}' | python3 scripts/mcp_client.py call beatra.models.list
    printf '%s' '{"capability":"text_to_speech"}' | python3 scripts/mcp_client.py call beatra.models.list
    printf '%s' '{"capability":"image_to_video"}' | python3 scripts/mcp_client.py call beatra.models.list
    printf '%s' '{"capability":"frames_to_video"}' | python3 scripts/mcp_client.py call beatra.models.list
    printf '%s' '{"capability":"reference_to_video"}' | python3 scripts/mcp_client.py call beatra.models.list
    printf '%s' '{"capability":"video_extend"}' | python3 scripts/mcp_client.py call beatra.models.list
    printf '%s' '{"capability":"voice_clone"}' | python3 scripts/mcp_client.py call beatra.models.list
    printf '%s' '{"language":"zh-CN"}' | python3 scripts/mcp_client.py call beatra.voices.list
    printf '%s' '{"query":"video by url","platform":"tiktok","capability_family":"content"}' | python3 scripts/mcp_client.py call beatra.social.tools.search
    ```
    
    Do not configure or call a host Beatra Connector, and do not use REST/OpenAPI as a fallback. Give each logical paid request one stable opaque `client_request_id` and submit it exactly once.
    
    ## Delivery and review
    
    Deliver the teardown, the approved shot list and rebuild plan, every frame as a delivered still, the narration, and — per the chosen route — either the one finished video artifact, or the segment sources, the single continuous narration track, captions, and the timecoded edit list. For every generation task, deliver its task ID, the returned artifact links, the resolved model, the returned dimensions and duration, and `billing.net_charged_credits`. A reference lookup is reported differently — the returned payload, its task ID, the terminal status, and `billing.net_charged_credits`, with no resolved model, dimensions, or duration to report — per [reading the reference from a link](references/reference-lookup.md). Report only facts the task actually returned.
    
    When the host can view or play the returned media, check that each frame or segment matches the beat it was written for, that the narration is present and finishes cleanly, and that the clip or the segments fit the canvas. State which media details could not be inspected instead of inferring them from task metadata.
    
    After the teardown is delivered and the user stops before the remake, or after the remake is delivered, offer at most one next step in the conversation, as [next step](references/next-step.md) describes: a talking-avatar video made from the rewritten script of a talking-head reference, or original commercial-use music for a product remake.
    
    ## Recovery
    
    Record each task ID immediately and poll only that task. `queued` and `running` mean wait. If a create response is lost, resubmit only the identical frozen payload under the same identifier; if a task ID is lost, list tasks for that capability and match candidates against your own ledger before any retry — except for a reference lookup, which has no capability to list by and is matched on its saved `operation_key`, arguments, and `schema_hash`. Redoing one frame reuses the other artifacts unchanged; under a segmented rebuild, redo only the failed unit and keep the per-unit ledger described in [remake workflow](references/workflow.md). On `insufficient_balance`, relay the returned message, keep the top-up URL inside the balance error exact, and retry the same frozen `client_request_id` only after the user says they have topped up.
    
    ## Account balance
    
    When the user asks how many credits remain or whether a live estimate fits,
    call `beatra.wallet.get`. When they ask what was charged, call
    `beatra.wallet.ledger`. Both are read-only. Do not invent an account-balance or
    top-up tool. Do not make `wallet.get` a required step before every paid submit.
    
    When a model card comes back carrying a `top_up` block, relay its tiers as the
    card lists them and in that order. Do not rank them, do not talk one down, and
    do not pick one for the user. Which tier suits them is their call, made on
    the wallet page with the whole list in front of them. Never quote a tier from
    memory.
    
    ## References by task
    
    - Choosing R1 or R2 by clip length, cut density, the model ceiling, and whether the user edits video themselves: [three rebuild routes](references/rebuild-routes.md)
    - What this route borrows from the reference and what it must never carry over, checked before any generation call runs: [the six red lines](references/compliance.md)
    - Reading a reference from a link, what each lookup costs, and how its results are attributed: [reading the reference from a link](references/reference-lookup.md)
    - How the three source layers combine, how the model's timings get rescaled against the real duration, and how the four evidence-and-scoring tables get filled: [reading the reference](references/teardown.md)
    - Carrying the structure onto a new subject, writing paired visual and spoken fields, choosing the mode and its locks, and taking reference frames from real assets before generation: [rewriting onto your subject](references/remake-plan.md)
    - Exact payloads, what each confirmation freezes, polling, redoing one stage or one unit, the per-unit ledger, recovery, and cancellation: [remake workflow](references/workflow.md)
    - After a delivered teardown or remake, choosing and offering one next step: [next step](references/next-step.md) and [offering one next step](references/next-step-offers.md)
    - First install or expired authorization: [installation and authentication](references/installation-and-auth.md)
    - Non-billable package registration: [installation registration](references/installation-registration.md)
    - Task polling, artifacts, and result fields: [tasks and results](references/tasks-and-results.md)
    - Balance, validation, and structured errors: [billing, errors, and recovery](references/billing-errors-and-recovery.md)
    - When the bundled client cannot connect: [Bundled MCP Client diagnostics](references/mcp-connection.md)
    - Updates and security: [updates and security](references/updates-and-security.md)
    - Removing the package or shared credentials: [uninstall and disconnect](references/uninstall-and-disconnect.md)
    
    ## Updates and security
    
    This Skill runs only the files installed with it and leaves them unchanged while
    it runs; it never downloads or executes other code. It talks to Beatra's official
    services over HTTPS, and a file you choose to upload goes only to the one-time
    upload address Beatra issues for it.
    
    Once a day at most, the bundled client reads Beatra's public version list. When
    the store or tool you installed from has a newer version, it prints one line with
    the command that updates it there. Updating stays your choice, through that store
    or tool. See [updates and security](references/updates-and-security.md).
    
  • skills/viral-video-teardown-remake/scripts/authorize.py61 KBf1133730bfd1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/viral-video-teardown-remake/scripts/mcp_client.py86 KBe147a8728ae6upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/viral-video-teardown-remake/scripts/uninstall.py13 KBbb352c897c36upstream ↗
    #!/usr/bin/env python3
    """Uninstall one Beatra Skill package without stranding the shared connection.
    
    The device connection (~/.beatra) is shared by every installed Beatra skill.
    Removing one skill must therefore never touch the shared credential while any
    other skill still uses it — even when the user asks for a complete removal.
    Only when this device's skill inventory says nothing else is left does the
    credential revoke itself and the local state leave with it.
    
    Every uncertain situation resolves to "keep the connection": a wrongly kept
    credential idles out server-side after 15 days and can be revoked from the
    Console at any time, while a wrongly revoked one breaks every remaining skill.
    
    This script never deletes the package directory it runs from — it reports the
    directory so the calling agent can remove it as the final step.
    """
    
    from __future__ import annotations
    
    import argparse
    import json
    import os
    import sys
    import urllib.error
    import urllib.request
    from pathlib import Path
    from typing import Any, Callable
    
    sys.dont_write_bytecode = True  # never leave __pycache__ inside the installed Skill
    
    REVOKE_PATH = "/oauth/device/revoke"
    PACKAGE_SLUG = "viral-video-teardown-remake"
    PACKAGE_DISPLAY_NAME = "Viral Video Teardown Remake"
    PACKAGE_VERSION = "0.4.3"
    HTTP_USER_AGENT = f"Beatra-Skill/{PACKAGE_SLUG}/{PACKAGE_VERSION}"
    
    #: Everything the connection owns inside ~/.beatra. Removal unlinks exactly
    #: these and the update records below, then removes each directory only if it
    #: is empty — the script never recursively deletes a directory it does not
    #: fully understand.
    _STATE_FILES = (
        "credentials.json",
        "installation.json",
        "host.json",
        "skills.json",
        "registrations.json",
        "network.json",
        "balance-holds.json",
        "pending_authorization.json",
        ".authorize.lock",
    )
    
    #: The per-install records in ~/.beatra/updates/<id>/: the version check,
    #: install source and registration, and a domestic channel's update lock. Only
    #: these names leave; an interrupted update's transaction stays, and so does
    #: every directory that still holds something.
    _UPDATE_RECORD_FILES = ("state.json", "source.json", "registration.json", "update.lock")
    _UPDATE_RECORD_DIGITS = frozenset("0123456789abcdef")
    
    PostRevoke = Callable[[str, str], int]
    
    
    class _RejectRedirectHandler(urllib.request.HTTPRedirectHandler):
        def redirect_request(
            self,
            _request: urllib.request.Request,
            _file_pointer: Any,
            code: int,
            _message: str,
            _headers: Any,
            _new_url: str,
        ) -> None:
            raise RuntimeError(f"Beatra revocation refused HTTP redirect ({code})")
    
    
    def _revoke_url(state_dir: Path) -> str:
        """Revoke over this computer's recorded network route. Uninstall never asks
        Beatra which route to use: revocation is best effort, and the record it
        would write is about to be removed."""
    
        import mcp_client  # the bundled client beside this file owns the route
    
        return f"{mcp_client.route_api_origin(mcp_client.current_route(state_dir))}{REVOKE_PATH}"
    
    
    def _default_post_revoke(token: str, url: str) -> int:
        request = urllib.request.Request(
            url,
            data=b"",
            headers={
                "Accept": "application/json",
                "Authorization": f"Bearer {token}",
                "User-Agent": HTTP_USER_AGENT,
            },
            method="POST",
        )
        opener = urllib.request.build_opener(_RejectRedirectHandler())
        try:
            with opener.open(request, timeout=30) as response:
                return int(response.status)
        except urllib.error.HTTPError as exc:
            return int(exc.code)
        except urllib.error.URLError as exc:
            raise RuntimeError("Beatra authorization service is unreachable") from exc
    
    
    def _own_skill_root() -> Path | None:
        """The installed package root this script runs from, when knowable."""
        try:
            return Path(__file__).resolve().parent.parent
        except NameError:
            return None
    
    
    def _load_inventory(state_dir: Path) -> tuple[list[dict[str, Any]] | None, str]:
        """Return (entries, state) where state names why entries may be None."""
    
        path = state_dir / "skills.json"
        if not path.exists():
            return None, "inventory_missing"
        try:
            value = json.loads(path.read_text(encoding="utf-8"))
        except (OSError, ValueError):
            return None, "inventory_unreadable"
        loaded = value.get("skills") if isinstance(value, dict) else None
        if not isinstance(loaded, list):
            return None, "inventory_unreadable"
        return [entry for entry in loaded if isinstance(entry, dict)], "ok"
    
    
    def _device_token(state_dir: Path) -> str | None:
        path = state_dir / "credentials.json"
        try:
            value = json.loads(path.read_text(encoding="utf-8"))
        except (OSError, ValueError):
            return None
        token = value.get("access_token") if isinstance(value, dict) else None
        if not isinstance(token, str) or not token:
            return None
        return token
    
    
    def _provably_deleted(install_path: str) -> bool:
        """True only when the entry's directory is verifiably gone.
    
        "Not currently visible" is not "uninstalled": an unmounted volume, a
        permission-restricted parent, or any stat error must count the skill as
        alive — the rule resolves every uncertainty to keeping the connection.
        Only a clean missing entry under a reachable parent is proof of removal.
        """
    
        try:
            os.stat(install_path)
            return False
        except FileNotFoundError:
            pass
        except OSError:
            return False
        parent = os.path.dirname(install_path.rstrip("/\\")) or os.sep
        try:
            os.stat(parent)
        except OSError:
            return False
        return True
    
    
    def _remove_update_records(state_dir: Path) -> None:
        updates = state_dir / "updates"
        try:
            if updates.is_symlink() or not updates.is_dir():
                return
            records = [
                child
                for child in updates.iterdir()
                if len(child.name) == 24
                and set(child.name) <= _UPDATE_RECORD_DIGITS
                and not child.is_symlink()
                and child.is_dir()
            ]
        except OSError:
            return
        for record in records:
            for name in _UPDATE_RECORD_FILES:
                try:
                    (record / name).unlink(missing_ok=True)
                except OSError:
                    pass
            try:
                record.rmdir()
            except OSError:
                pass
        try:
            updates.rmdir()
        except OSError:
            pass
    
    
    def _remove_local_state(state_dir: Path) -> None:
        for name in _STATE_FILES:
            try:
                (state_dir / name).unlink(missing_ok=True)
            except OSError:
                pass
        _remove_update_records(state_dir)
        try:
            state_dir.rmdir()
        except OSError:
            pass
    
    
    def uninstall(
        *,
        state_dir: Path | None = None,
        skill_root: Path | None = None,
        post_revoke: PostRevoke = _default_post_revoke,
        dry_run: bool = False,
    ) -> dict[str, Any]:
        """Apply the last-skill rule and return a machine-readable decision."""
    
        state_dir = (state_dir or Path.home() / ".beatra").expanduser()
        root = skill_root or _own_skill_root()
        resolved_root = str(Path(root).expanduser().resolve()) if root is not None else None
    
        result: dict[str, Any] = {
            "package": PACKAGE_SLUG,
            "dry_run": dry_run,
            "delete_next": resolved_root,
        }
    
        if not state_dir.is_dir():
            # Nothing local to retire; the package files are all that is left.
            result.update({"decision": "disconnected", "revoked": False, "reason": "no_local_state"})
            return result
    
        if resolved_root is None:
            result.update({"decision": "keep_connection", "reason": "unknown_install_path"})
            return result
    
        try:
            entries, inventory_state = _load_inventory(state_dir)
            if entries is None:
                # No trustworthy inventory means no proof this is the last skill —
                # the connection stays, and the 15-day idle expiry backstops it.
                result.update({"decision": "keep_connection", "reason": inventory_state})
                return result
    
            survivors: list[dict[str, Any]] = []
            for entry in entries:
                if (
                    entry.get("slug") == PACKAGE_SLUG
                    and entry.get("install_path") == resolved_root
                ):
                    continue  # the package being uninstalled
                install_path = entry.get("install_path")
                if isinstance(install_path, str) and install_path and _provably_deleted(install_path):
                    continue  # verifiably removed outside this flow — self-heal
                survivors.append(entry)
        except Exception:  # noqa: BLE001 -- any surprise resolves to keeping the
            # connection; a crash here must never read as permission to revoke.
            result.update({"decision": "keep_connection", "reason": "inventory_error"})
            return result
    
        if survivors:
            # The inventory is deliberately not rewritten here: this package's own
            # entry disappears through the provably-deleted check once the agent
            # finishes removing the directory, so an interrupted uninstall leaves
            # a still-installed skill visible rather than silently forgotten.
            result.update(
                {
                    "decision": "keep_connection",
                    "reason": "other_skills_still_installed",
                    "remaining_skills": [
                        {"slug": entry.get("slug"), "platform": entry.get("platform")}
                        for entry in survivors
                    ],
                }
            )
            return result
    
        if dry_run:
            result.update({"decision": "disconnected", "revoked": False, "reason": "dry_run"})
            return result
        token = _device_token(state_dir)
        revoked = False
        revoke_state = "no_credential"
        if token is not None:
            try:
                status = post_revoke(token, _revoke_url(state_dir))
                if status == 200:
                    revoked = True
                    revoke_state = "revoked"
                elif status == 401:
                    # The server no longer recognises this token; the local copy
                    # is worthless either way, but nothing was confirmed revoked.
                    revoke_state = "not_recognized"
                else:
                    # Reached but refused (rate limit, server error): keep every
                    # local file so a retry — or a Console revoke followed by a
                    # rerun — can still finish the job cleanly.
                    result.update(
                        {
                            "decision": "revoke_retry",
                            "revoked": False,
                            "reason": f"http_{status}",
                        }
                    )
                    return result
            except RuntimeError:
                revoke_state = "unreachable"
        token = None
        _remove_local_state(state_dir)
        result.update({"decision": "disconnected", "revoked": revoked, "reason": revoke_state})
        return result
    
    
    def main() -> int:
        parser = argparse.ArgumentParser(
            description=f"Uninstall the {PACKAGE_DISPLAY_NAME} Skill from this device"
        )
        parser.add_argument(
            "--dry-run",
            action="store_true",
            help="Report the decision without revoking or changing any file.",
        )
        args = parser.parse_args()
        result = uninstall(dry_run=args.dry_run)
        print(json.dumps(result, ensure_ascii=False, indent=2))
        if args.dry_run:
            print("Dry run: nothing was changed. Run without --dry-run to uninstall.")
            return 0
        if result["decision"] == "keep_connection":
            print(
                "The shared Beatra connection stays in place"
                + (
                    " because other installed skills still use it."
                    if result.get("reason") == "other_skills_still_installed"
                    else " because this device's skill inventory could not prove it is unused."
                )
            )
        elif result["decision"] == "revoke_retry":
            print(
                "Nothing was changed: the Beatra server refused the revocation just now. "
                "Run this script again shortly, or revoke the device in the Beatra "
                "Console and rerun to finish removing local state."
            )
            return 0
        elif result.get("revoked"):
            print("The Beatra device authorization is revoked and local state is removed.")
        else:
            print(
                "Local state is removed. The server-side authorization could not be "
                "confirmed revoked from here; it expires after 15 days of inactivity "
                "and can be revoked in the Beatra Console at any time."
            )
        if result.get("delete_next"):
            print(f"Finish by deleting the package directory: {result['delete_next']}")
        return 0
    
    
    if __name__ == "__main__":
        sys.exit(main())
    
  • skills/viral-video-teardown-remake/references/billing-errors-and-recovery.md4.8 KB4492c70c65d8upstream ↗
    # Billing, errors, and recovery
    
    Every generation tool consumes Beatra credits and creates an asynchronous task.
    Use one logical request identity across transport uncertainty so recovery cannot
    accidentally create or charge a duplicate task.
    
    ## Submit a billable request
    
    1. Assemble the final generation arguments.
    2. Generate one opaque `client_request_id`.
    3. Submit exactly once.
    4. Store both `client_request_id` and the returned `task_id`.
    5. Poll with `beatra.tasks.get`; do not resubmit while the task is queued or
       running.
    
    The prepaid amount accepted with the request can be an estimate. A successful
    task is settled against authoritative measured usage. Read the terminal
    `usage` and `billing` fields, and report net credits as
    `billing.net_charged_credits`. Do not promise that the initial estimate
    is the final charge.
    
    ## Run a batch
    
    When one request becomes many paid calls (a list of items, a loop, or a
    script):
    
    1. Before the first paid call, price the whole batch from the live prices
       (`beatra.models.list`, or `beatra.social.tools.get` for social data) and
       tell the user the estimated total.
    2. Let the first `insufficient_balance` stop the whole batch. Do not go on to
       the next item; report which items finished and which did not.
    3. Resume only the unfinished items, and only after the user says they have
       topped up. A refused item keeps its `client_request_id` and arguments.
    
    ## Recover an uncertain response
    
    - If no response arrived, make an identical retry with the same
      `client_request_id` and exactly the same generation arguments.
    - If any prompt, input artifact, model, output setting, or other generation
      argument changes, treat it as new work and use a new `client_request_id`.
    - If the task ID was lost, use `beatra.tasks.list` before considering a retry.
    - If remote execution failed, report the terminal error. Start changed or newly
      requested work only with a new request ID.
    
    ## Handle structured failures
    
    - HTTP 401 authentication failure: do not replay the paid call automatically.
      Run `python3 scripts/authorize.py` and follow its output
      until it prints `Beatra is ready`, then recover with the original request
      identity and unchanged arguments.
    - Timeout, DNS/TLS, HTTP 429, HTTP 5xx, or another transport failure: preserve
      the credential. If delivery of a paid call is uncertain, retry only with the
      same `client_request_id` and exactly the same arguments after connectivity
      recovers.
    - Insufficient scope: explain that the active connection lacks required access;
      run `python3 scripts/authorize.py --force` only after the
      user explicitly chooses to reconnect the full Beatra authorization. Never ask
      for a media-specific grant.
    - Insufficient balance (error code `insufficient_balance`): relay the returned
      message to the user — it already carries the facts that matter: nothing was
      charged, the top-up link, credits take effect immediately, and the same
      request can be retried as-is. Translate into the user's language but keep
      the URL exactly as returned. Stop all remaining paid work, including the
      rest of a batch, and do not retry until the user says they have topped up.
      A successful task can also leave a negative balance when actual measured
      usage exceeded the estimate; the output remains valid, but new billable
      work must wait for a top-up.
    - After that refusal, `scripts/mcp_client.py` holds further calls to the same
      tool on this computer: it answers them with the same message and sends
      nothing (`details.local_hold`). Its `details.agent_note` names the balance
      check that lifts the hold once the user says they have topped up. If the user
      chose a cheaper request instead, run that cheaper call once with
      `--recheck-balance`. Never put `--recheck-balance` in a loop or script.
    - Idempotency conflict: the request identity was reused with different
      arguments. Do not retry it. Keep the original task if it exists, or use a new
      `client_request_id` only for user-approved changed work.
    - Rate or concurrency limit: honor the returned retry delay, then retry the
      exact same arguments with the same request identity. Do not create a
      replacement task.
    - Validation failure or model incompatibility: call `beatra.models.list` for current
      constraints, correct the invalid arguments, and use a new
      `client_request_id` because the generation inputs changed.
    - Upload expiration, MIME mismatch, or byte-length mismatch: request a fresh
      grant and upload the unchanged file again. Never reuse a consumed or expired
      grant.
    - Remote execution failure: preserve the Beatra error code and task ID;
      report only the failure classification and billing/refund fields returned by
      Beatra. Do not infer a different cause or promise a refund that is not shown.
    
    Never expose authentication tokens, complete private prompts, or sensitive
    input content while explaining recovery.
    
  • skills/viral-video-teardown-remake/references/compliance.md4.0 KBb699b20d37ebupstream ↗
    # The six red lines
    
    This route borrows the structure of someone else's video. Structure is the only thing
    it borrows. The six rules below get checked before any generation call runs, not after
    the fact.
    
    ## 1. Labelling AI-generated content is the user's obligation
    
    Labelling AI-generated content is a legal obligation in the places this package
    operates, and it falls on the user, not on this package. **This package does not stamp
    a label onto the deliverable on the user's behalf.** Say so plainly, so the user does
    not assume the deliverable already satisfies the obligation, and tell them clearly that
    meeting it — before or at the moment they publish — is theirs to do.
    
    If the selected video model exposes a `watermark` option, that is a different thing: a
    model watermark the provider burns into the generated video, not a legal AI-content
    label. Do not present accepting or enabling it as satisfying the user's labelling
    obligation.
    
    ## 2. Deduplication is not reuploading
    
    Washing someone's original commerce video and reposting it under a different account is
    a violation, not a derivative work. This package does not do that.
    
    What it reuses is **structure only** — where the hook sits, what each beat is for, the
    shape of the timing. It never reuses the reference's footage, its music, or the person
    who appears on camera in it.
    
    When a user asks for the original's footage, its music, or its on-screen person to be
    carried over rather than rebuilt, say plainly what this route does produce instead — an
    original clip built on the same structure — and continue the run from there.
    
    ## 3. Treat every frame of the reference as unsafe to feed back in
    
    Measured, not assumed, for Douyin: the play address this package can reach for a Douyin
    post reports `has_watermark` as true, and there is no clean version to fetch instead —
    see [reading the reference from a link](reference-lookup.md). Other platforms have not
    been measured the same way, but a platform-served copy carrying a visible or embedded
    mark is an ordinary risk, not a Douyin-specific one, so treat a downloaded reference
    frame from any platform as unsafe to feed back in unless the source is proven clean.
    
    So a frame of the reference must never enter any generation call's reference input,
    on any platform. Looking at those frames for your own analysis — reading a shot, timing
    a cut — is fine. Feeding them into a model is not: whatever mark sits in the input gets
    learned into the output, not filtered out of it.
    
    ## 4. Likeness
    
    The subject lock's reference image has to come from the user themselves, or from
    material the user has already cleared to use.
    
    **Never pull a frame out of the reference clip to use as a subject lock.** The person on
    screen in the reference is not the user. That is someone else's face, and how well the
    frame would work is beside the point.
    
    ## 5. Advertising law
    
    The per-line evidence table's on-screen-keyword column collects the reference's prices,
    discounts, figures, and promises. Go through that column again once the rewrite starts:
    absolute superlatives, efficacy promises, and price promises found there must not carry
    across onto the user's own video unchanged. The same screening in
    [rewriting onto your subject](remake-plan.md) — superlatives, efficacy claims, prices —
    applies here too, to whatever came from the reference and not only to what the user
    wrote fresh.
    
    The user's own specifications, prices, results, certifications, and promotions can only
    come from the user. When one of those is missing, write the beat around it. **Never
    invent a plausible-looking number to fill the gap** — the user is the one who answers
    for whatever the video claims, not this package.
    
    ## 6. Platforms judge reuploads on their own terms
    
    Even a remake that reuses structure alone, and nothing else, can still trip a platform's
    duplicate-content detection — the platform does not see the same intent this package
    does. Tell the user about that risk plainly, and advise making the picture, the voice,
    and the pacing of the remake genuinely different from the reference, not just the
    product name.
    
  • skills/viral-video-teardown-remake/references/installation-and-auth.md9.3 KB149c77b01f1aupstream ↗
    # Installation and authentication
    
    Use this reference when Beatra is newly installed, unavailable, or needs its
    authorization recovered. This flow is owned by the Skill and works the same way
    in any agent that can run Python 3.10 or newer and make HTTPS requests. The
    helpers use only the Python standard library; do not install packages for them.
    
    ## Keep one private local identity
    
    The Skill uses two user-only files:
    
    - `~/.beatra/installation.json` contains one stable, non-secret installation
      reference.
    - `~/.beatra/credentials.json` contains the single Device Token.
    
    On POSIX systems the directory must be mode `0700` and both files mode `0600`.
    On Windows the current user must be the only principal granted access through
    the file ACL. Never copy the Device Token into conversation context, stdout,
    stderr, a command argument, an environment variable, a log, a backup, a diff,
    or another file. A completed authorization leaves the token only in
    `~/.beatra/credentials.json`.
    
    ## Ensure Beatra is ready
    
    From the installed `beatra` Skill directory, run:
    
    ```text
    python3 scripts/authorize.py
    ```
    
    Use `python` instead when that is the local Python 3.10+ command. Always run this
    idempotent helper after installing or replacing a Beatra Skill and when
    recovering its connection. It validates the candidate credential with one
    non-billable live MCP request. A valid credential becomes Ready without opening
    the browser, so installing another Beatra package does not require a second
    approval.
    
    When no valid credential exists, or the live MCP endpoint definitively returns
    HTTP 401, the helper:
    
    1. reuses or creates `~/.beatra/installation.json`;
    2. continues an approval that is already open on this computer, or requests a
       new Device Authorization from Beatra. When the user already selected Allow
       on this computer and nothing collected it, Beatra connects at once — no
       second approval;
    3. prints the HTTPS approval link at once and opens it in the user's browser
       (only once for each approval). The URL fragment carries the approval code,
       so the page verifies the code by itself;
    4. waits while it checks every few seconds whether the user selected Allow,
       and keeps checking through brief network failures. One run waits up to
       about 15 minutes; an approval page stays open for up to an hour;
    5. atomically saves the returned Device Token to
       `~/.beatra/credentials.json` without printing an HTTP response body;
    6. validates the new credential with the same non-billable MCP request and
       prints `Beatra is ready` only after it succeeds.
    
    ### Wait for Allow
    
    The user usually needs a minute or more to sign in or create an account before
    selecting Allow. The helper waits for it: leave it running. If your host moves
    the command to the background, let it keep running and do not start a second
    one.
    
    Act on how each run ends:
    
    - `Beatra is ready` — the connection works; continue with the user's request.
    - `BEATRA_AUTH_PENDING` (exit status 3) — the run ended before the user selected
      Allow: the approval page had not been opened yet, the run's wait ran out, or
      the run was stopped. Show the approval link to the user as described below if
      you have not already, and again if the link is different. Run the same command
      at most twice in one turn; it continues the same approval, so the user
      approves only once. When it is still pending after that, deliver what needs
      no connection (below) and stop. When the message says Beatra could not be
      reached, tell the user the connection is being retried instead of asking them
      to approve again.
    - `BEATRA_AUTH_IN_PROGRESS` (exit status 3) — another run on this computer is
      starting an approval right now. Run the same command again in a moment; it
      continues that approval.
    - `Beatra authorization stopped (access_denied)` — the user declined on the
      approval page. A decline is often a mis-click: if the user still wants to
      connect, run the same command again and it opens a new approval page.
    - `Beatra authorization stopped (expired_token)` — the approval page expired
      before the user selected Allow. Tell the user; if they still want to
      connect, run the same command again and share the new approval link.
    
    A run stopped by a timeout or an interrupted tool call counts as one of the
    two runs in the turn: run the same command again once, since it continues the
    approval that is already open, and after a second stop deliver what needs no
    connection and stop.
    
    An approval does not depend on a run being active when the user selects Allow.
    Beatra keeps it, and every Beatra command collects it first: when the user
    writes again after approving, run the helper once (or go on with their
    request) and the connection completes without a second approval. So if the
    user interrupts to ask something else, stop the helper and answer them; and if
    they do not want to connect now, stop waiting — the link stays valid for a
    while.
    
    #### Deliver while the approval is pending
    
    When the approval is still pending at the end of a turn, finish and deliver
    everything in the request that needs no connection, in the format the user
    asked for — the Skill's root names it for each kind of work: the prepared
    text, prompt, lyrics, shot list, or selection criteria. Say in one line that
    the paid step continues on their next message after Allow, because the next
    Beatra command collects the approval. Do not fill the gap with another tool or
    service, and do not name voices, models, prices, or results that no live call
    returned.
    
    When telling the user what to do:
    
    - present the approval page as a link and say the only decision on it is
      selecting Allow;
    - never quote, display, or read out the approval code. It travels inside the
      link fragment, the approval page does not show it, and the user never types
      or compares it — a code surfaced in conversation is noise, not a step;
    - say prominently that a signed-out browser lands on Beatra sign-in first:
      the user signs in or creates their account there, and the approval page
      continues automatically after sign-in;
    - say once that the connection continues automatically after Allow — never
      ask the user to confirm in chat that they approved.
    - on the mainland China network, follow the sign-in and console-link guidance
      in [MCP connection](mcp-connection.md#network-route).
    
    The helper opens no local listener and requires no inbound connection. One
    approval covers image, video, music, speech, upload, model, and task tools.
    
    HTTP 403 or insufficient scope does not prove the credential is invalid. Keep
    the credential and run `python3 scripts/authorize.py --force`
    only when the user explicitly wants to reconnect or switch accounts. A timeout,
    DNS/TLS failure, HTTP 429, or HTTP 5xx is transient: keep the credential, do
    not start Device Authorization, and retry after connectivity recovers.
    
    ### Record where this Skill was installed from
    
    After this Skill first connects, if this conversation shows how this
    Skill was installed — for example an install command or link that names a
    store or site — record it once:
    
    ```text
    python3 scripts/mcp_client.py install-source --guess <source>
    ```
    
    Use one of `website`, `github`, `skillhub`, `skillatlas`, `modelscope`,
    `workbuddy`, `clawhub`, or `other`. If the conversation does not show it,
    skip this and do not ask the user. If the command is not recognized, skip it.
    
    ## Use the bundled MCP client
    
    Every Beatra Skill tool runs through the bundled `scripts/mcp_client.py`, which
    connects to `https://mcp.beatra.ai/mcp`. Do not add, enable, trust, or configure
    a host Beatra Connector. The bundled client reads the shared credential file
    and never accepts the token through argv or the environment:
    
    ```text
    python3 scripts/mcp_client.py verify
    python3 scripts/mcp_client.py tools
    python3 scripts/mcp_client.py call beatra.tasks.list
    ```
    
    The host follows this computer's network route; see [MCP connection](mcp-connection.md).
    
    For `call`, provide the tool arguments as one JSON object on stdin. Do not put
    user content or credentials in the command arguments. The authorization helper
    already performs this verification. Run the explicit `verify` command only for
    diagnostics; it invokes `beatra.tasks.list` with `{}` and is non-billable.
    
    The direct client follows the Streamable HTTP sequence:
    
    1. send `initialize` with the MCP protocol version and client information;
    2. retain an `MCP-Session-Id` response header when the server provides one;
    3. send the `notifications/initialized` notification;
    4. use `tools/list` for discovery and `tools/call` for execution;
    5. include the protocol version, optional session ID, and Device Token bearer
       header on every request.
    
    ## Recover or revoke access
    
    The single Device Token has a sliding 15-day idle lifetime. Every accepted MCP
    use extends that idle deadline without user action. If Beatra returns HTTP 401
    after the token was idle too long or was revoked, run
    `python3 scripts/authorize.py` and act on its output as
    described above; the helper replaces and validates the credential. Do not start another
    authorization for a media-type change and do not delete a credential because of
    a transient connection failure.
    
    The user can revoke a connected agent from the Beatra Console at any time.
    Revocation immediately invalidates the credential. Rerun Device Authorization
    only when the user wants to reconnect that installation.
    
    After first installing or replacing the Skill, start a new agent session when
    the host discovers Skills only at session startup.
    
  • skills/viral-video-teardown-remake/references/installation-registration.md2.0 KB7da7c1c9b57cupstream ↗
    # Installation registration
    
    On first use, and again when the version, agent environment, channel, network
    route, install source or installation reference changes or 24 hours pass, the
    bundled client makes one best-effort, non-billable
    `beatra.installations.register` call for this package. It is the only reporting call
    the Skill makes, it does not replace Device Authorization, it never asks for
    narrower package scopes, and its failure never blocks the user's requested
    task. It records:
    
    - the package, its version, the agent environment (`platform`), and the
      stable installation reference;
    - the distribution channel and locale fixed when the package was built;
    - the network route this computer uses and why (see the MCP connection
      reference);
    - where this copy was installed from, when known: a source file Beatra adds to
      copies it hands to a store or its website, a store client's own record in
      the Skill directory, or the agent's `install-source --guess`;
    - coarse runtime facts: operating system and version, processor architecture,
      Python version, interface language, and time-zone offset.
    
    It never sends user names, file paths, environment variables, prompts, or tool
    details. Beatra uses these fields to understand which stores and networks
    people install from, as its privacy policy describes, and clears the runtime
    facts when the account is deleted.
    
    A per-installation cache in `~/.beatra/updates/` suppresses another
    registration until the version, agent environment, channel, network route, install
    source or installation reference changes, or 24 hours pass. An unknown but well-formed package
    slug is accepted and recorded as unrecognized, so package release never
    depends on a synchronized backend registry deployment.
    
    The `platform` field is the real agent environment, resolved once per process
    from environment signatures (or `~/.beatra/host.json`, written at
    authorization time) — never detected per request. When authorizing manually,
    pass `--platform <environment-name>` to `scripts/authorize.py` if automatic
    detection cannot identify the host.
    
  • skills/viral-video-teardown-remake/references/mcp-connection.md3.3 KB9365c7be5051upstream ↗
    # MCP connection
    
    All Beatra Skill packages use one connection path:
    
    ```text
    scripts/mcp_client.py -> https://mcp.beatra.ai/mcp
    ```
    
    The host follows this computer's network route, described below.
    
    They share the one full-scope Device Token stored in
    `~/.beatra/credentials.json`. Installing or switching packages must not trigger
    another authorization when that credential is already valid. Do not add,
    enable, trust, or configure a host Beatra Connector. Never print or move the
    token into command arguments, environment variables, logs, chat, or another
    package directory.
    
    The bundled client performs MCP `initialize`, retains `MCP-Session-Id` when the
    server returns one, sends `notifications/initialized`, and then uses
    `tools/list` or `tools/call`. Its `verify` command runs the non-billable
    `beatra.tasks.list` operation. It supplies the private `Authorization: Bearer`
    header on every request without exposing its value.
    
    Source attribution: every `tools/call` may carry two optional string
    arguments, `source_package_slug` (this package's slug) and `source_platform`
    (the agent environment, for example `claude-code` or `codex`). The bundled
    client adds them automatically. They are telemetry only: missing values never
    block a call, and the server treats them as `unknown`.
    
    ## Network route
    
    Beatra serves two networks: the international hosts, and the mainland China
    hosts `mcp.beatra.cn`, `api.beatra.cn`, `www.beatra.cn`, `cdn.beatra.cn` and
    `console.beatra.cn`. The saved credential works on both. Packages of the
    mainland China (`cn`) channel always use the mainland hosts and cannot change
    network (`network` shows `"policy":"cn"`). Other packages choose once a day,
    before their first command: the client asks Beatra which network suits this computer,
    in a small request that carries no credential and no installation identity,
    and records the answer in `~/.beatra/network.json`. Approval pages, console and
    top-up links, uploads, and result downloads then follow the chosen network.
    
    ```text
    python3 scripts/mcp_client.py network
    python3 scripts/mcp_client.py network --use auto
    ```
    
    `network` shows the current choice. Only when the user asks for a specific
    network, run `network --use cn` (mainland China) or `network --use ai`
    (international): it first checks that Beatra answers on that network and
    refuses otherwise; packages of the `cn` channel refuse `--use`. If commands start failing to connect after a network was
    chosen this way, run `network --use auto`. A request that failed is never
    resent on the other network; the next command decides again unless a network was chosen with
    `network --use`. A chosen network also keeps the version-list check on it.
    
    On the mainland China network the approval page offers WeChat, phone and email
    sign-in. If the user cannot find their sign-in method, or wants to sign in with
    Google, run `python3 scripts/authorize.py --approval-link ai`: it shows the same
    approval on Beatra's international site, and the network does not change;
    `--approval-link auto` goes back. When you give the user a console or top-up
    link on the mainland network, remind them to sign in the way they did before
    (phone, email, or the same WeChat): scanning with a different WeChat creates a
    separate account. If credits do not appear after a top-up, first check that
    they signed in to the same account.
    
  • skills/viral-video-teardown-remake/references/next-step-offers.md2.9 KB0349e1f019c0upstream ↗
    # Offering one next step
    
    After the user accepts a result, offer one next step that builds on that exact
    result. It is a suggestion the user can ignore, not part of the job they asked
    for. This Skill's own [next step](next-step.md) names the step and when it
    fits.
    
    ## When to offer
    
    Offer only when all of these hold:
    
    - the user has accepted the result: they said it works, asked to download,
      post, print, or send it, or the delivered result passed review and there is
      no revision worth proposing;
    - the conversation is not in the middle of a revision, a batch that is still
      running, an authorization step, task recovery, or an
      `insufficient_balance` error;
    - no next step has been offered earlier in this conversation;
    - [next step](next-step.md) says the step fits this result.
    
    When a revision is still worth proposing, propose the revision instead. A
    revision suggestion and a next step never share one message.
    
    ## How to offer
    
    - One step, in one or two sentences, in the user's language: what they would
      get, made from what they already have, and where they would use it.
    - End with one question the user can answer yes or no. For another Skill, the
      install message follows that question (see below).
    - Before offering an in-place clip, read the `image_to_video` card (a free,
      read-only call; see the animating reference in this Skill). Only for that
      in-place clip, and only when the card carries a `free_first_video` offer,
      say in plain words that it would be the account's free first video. Never
      call a step in another Skill free. Leave every other price, credit, and
      top-up fact to the confirmation card.
    - Offer one step, not a menu, and keep it factual: no "recommended",
      "limited time", or "popular".
    
    If the user declines, does not answer, or moves on, drop it. Offer no next
    step again in this conversation, even after another delivery. A new
    conversation is a new job and may get one offer.
    
    ## Doing it in place
    
    When [next step](next-step.md) marks the step as in place, the user's yes
    starts that step's own free planning here. Its paid call still needs its own
    confirmation card; agreeing to the offer is not approval to spend.
    
    ## Pointing to another Beatra Skill
    
    When the step belongs to another Skill, say in one sentence what that Skill
    makes and what the user would prepare (for example a front-facing photo), ask
    whether they want it, then copy the install message [next step](next-step.md)
    gives for the user's language, unchanged; for a language other than Chinese or
    English, use the English line. It has the Beatra website's form:
    
    ```text
    请安装 <中文名>;需要登录授权时告诉我:https://beatra.ai/skills/<slug>/install.md
    Install <English name> and tell me when I need to sign in: https://beatra.ai/skills/<slug>/install.md
    ```
    
    Every Beatra Skill uses the same Beatra account, so a second Skill normally
    needs no new sign-in. Offering downloads nothing. Install only after the user
    asks, from that link.
    
  • skills/viral-video-teardown-remake/references/next-step.md2.4 KB442bac307c38upstream ↗
    # Next step after a teardown or a remake
    
    Follow [offering one next step](next-step-offers.md). This route has two
    moments for a next step; whichever comes first is the only offer in the
    conversation. Offer nothing when neither condition holds.
    
    ## The teardown is delivered and the remake does not follow
    
    After golden-path step 5 (teardown, shot list, and rebuild plan shown), the
    user stops there: they only wanted the analysis, find the remake too much, or
    end without choosing frames. When the reference is a talking-head clip (one
    person speaking to the camera for most of its length), point to one of these:
    
    - **Talking Avatar & AI Presenter Video.** One front-facing photo plus the
      rewritten narration becomes a talking-avatar video, without a frame for
      every shot. They prepare the photo; the script is already written.
    
      ```text
      请安装 AI数字人口播与虚拟主播视频;需要登录授权时告诉我:https://beatra.ai/skills/talking-avatar-video/install.md
      Install Talking Avatar & AI Presenter Video and tell me when I need to sign in: https://beatra.ai/skills/talking-avatar-video/install.md
      ```
    
    - **Founder IP Avatar Studio, instead, for a recurring series.** The user
      presents their own shop or professional field and plans regular episodes
      (weekly updates, "I am the doctor / the owner"). It clones the user's own
      voice and keeps the same presenter across episodes. They prepare a
      front-facing photo and a short voice sample.
    
      ```text
      请安装 数字人分身·创始人口播;需要登录授权时告诉我:https://beatra.ai/skills/founder-ip-avatar-studio/install.md
      Install Founder IP Avatar Studio and tell me when I need to sign in: https://beatra.ai/skills/founder-ip-avatar-studio/install.md
      ```
    
    ## The remake is delivered and it sells something
    
    The remake is for a business or a product. Point to Short Video BGM Studio:
    an original music track written for this clip's length and pace, owned by the
    user and usable in commercial posts. The remake does not reuse the reference's
    own music (see [the six red lines](compliance.md)), so the remake carries no
    music from the reference; the track is added in the user's editor.
    
    ```text
    请安装 短视频配乐工作室;需要登录授权时告诉我:https://beatra.ai/skills/short-video-bgm-studio/install.md
    Install Short Video BGM Studio and tell me when I need to sign in: https://beatra.ai/skills/short-video-bgm-studio/install.md
    ```
    
  • skills/viral-video-teardown-remake/references/rebuild-routes.md7.2 KB97be2b2b75aaupstream ↗
    # Three rebuild routes
    
    The teardown is done and the rewrite is done. One decision is still open: how the film actually gets built.
    
    The answer is not fixed, but it is total: every clip lands in exactly one of the two routes below, and no clip matches neither or both.
    
    Three structural facts rule out R1 outright, each on its own: table 3 having more than two rows, an obvious hard cut anywhere in table 3, or the selected model's ceiling being smaller than `T`. **Any one of those means R2** — there is nothing left to ask.
    
    Only when none of the three holds — at most two rows, no hard cut, and the ceiling covers the whole clip — are both routes actually available, and there the decisive factor is **whether the user edits video themselves**, asked directly before the route is chosen. A user who edits gets R2's editable segments even though the clip would have fit in one take; a user who does not gets R1's one-click clip.
    
    ## Generation-unit length is a variable, not a constant
    
    Every video generation path on this platform takes an integer duration of 2 through 30 seconds, or `auto`. Which of those values a given model actually supports is not fixed — read it live from `beatra.models.list`.
    
    So how long one generation unit can be is a consequence of the model the user picked, not a constant this reference can state. The same teardown packs into different unit boundaries under different models. **Read the model card before the shot list is signed off**, because it decides everything that follows: which route applies, how many units the clip splits into, and where the boundaries fall.
    
    ## R1 — one continuous take
    
    **When it applies:** table 3 has at most two rows, no hard cut, and the selected model's ceiling is at least `T` — **and** the user says they do not edit video themselves. Typical of a slow talking-head piece or anything shot as a single continuous take.
    
    **How to build it:** build the opening frame from the real-assets-first tiers — plus the closing frame, when both the first and the last frame are locked — and run one call: `beatra.videos.animate` (first frame only) or `beatra.videos.interpolate` (both first and last frames locked) — then `beatra.speech.synthesize` for the narration.
    
    Those two are the whole list on this route, and the reason is that R1 is audio-led: only their requests carry a `driving_audio` track. A subject or product lock here is satisfied **in the reference frame** — the frame comes from the user's own asset and carries the identity, and the call animates that frame — never by swapping in `beatra.videos.generate_from_references`, whose request has no driving-audio field and would leave the finished clip with no narration on it, per [rewriting onto your subject](remake-plan.md).
    
    ## R2 — segmented generation plus an edit list
    
    **When it applies:** table 3 has more than two rows, or it contains an obvious hard cut, or `T` exceeds the selected model's ceiling — any one of those, on its own, is enough. It also applies when none of those hold but the user says they do edit video themselves.
    
    **How to build it:**
    
    1. Repack table 3 into a unit sequence, landing unit boundaries on table 3's shot boundaries by preference; only when a single shot by itself exceeds the ceiling do you cut inside it, and there you use `beatra.videos.extend` to continue within that shot. **`T` divided by the ceiling, rounded up, is only a lower bound on the unit count** — packing whole shots without splitting them will often need more units than that division suggests, because a boundary usually lands before a shot's actual end rather than exactly on the ceiling. Count the units your actual packing produces, and state that count — not the division's result — at the free gate.
    2. Each unit takes its reference frame from the real-assets-first tiers and wears the locks its mode requires. No unit's call carries the narration, so a unit that needs several ordered references to hold a subject or product identity steady runs `beatra.videos.generate_from_references` in place of `beatra.videos.animate` or `beatra.videos.interpolate`, fed those references in order — the mechanism R1 cannot use, and the one this route can.
    3. Generate each unit.
    4. **Synthesize the narration once for the whole clip**, so the voice stays continuous and consistent. **Do not split the audio locally.** Deliver one track, and let the edit list carry each unit's audio timecode so the user can align it in their own editor.
    5. Deliver the segment sources, the single narration track, captions, and a timecoded edit list.
    
    ### Continuity across units, without flattening the cuts
    
    Inside one scene, use the previous unit's last frame as the next unit's first frame. That is one inherited frame, not two, so the call is `beatra.videos.animate`, not `beatra.videos.interpolate` — which needs a genuine required last frame that nothing here supplies — and the picture still carries across the boundary.
    
    At a scene change, **keep the hard cut** and start from a fresh reference frame. Fast cutting is exactly what this genre lives on — smoothing it away in the name of continuity destroys the thing being copied.
    
    ## R3 — segmented generation plus platform compose
    
    R2's first four steps, plus the platform stitching the units into one finished cut.
    
    **This route cannot run today** — the platform has no compose capability. When a user asks for a single publishable file, say plainly what is available instead: R2's segments and edit list. Do not blur this into a promise the platform cannot keep.
    
    ## R2 is not a lesser R3
    
    Do not assume a finished cut beats segments. A user who edits wants an editable project — a welded single file is a liability to them, because changing one shot means rebuilding the whole thing. Segments plus an edit list is what they actually want.
    
    The one-click finished cut is for users who do not edit.
    
    So, whenever the clip's structure leaves both routes open, the route follows **what the user says about their own editing** — asked directly before the route is chosen, never inferred for them, and then stated plainly together with the shot list at the free gate that follows. When the clip's structure rules out one route outright, there is nothing to ask: the surviving route is stated at that same gate, without a question attached to it.
    
    ## That gate is free
    
    Mode, route, the unit sequence, and each unit's locks and reference-frame source are shown together with the shot list, revisable without limit, at no cost.
    
    **The route and the unit count must be settled and stated at this gate.** R1 and R2 differ in final cost by a factor of the unit count, and the route follows from the clip's structure, the selected model's ceiling, and — whenever both remain open — the user's own answer about editing. Spell out the whole chain — this model, therefore this route, therefore this many units (the actual packed count, not the raw division), therefore roughly this much — rather than letting it surface only at the last paid confirmation.
    
    ## Do not make `videos.extend` chaining a main route
    
    Chaining `beatra.videos.extend` needs no new capability and grows one continuous piece, but it cannot produce a hard cut, and its error compounds unit over unit. Keep it to the one job named above: continuing inside a single shot that overruns the ceiling — nothing broader.
    
  • skills/viral-video-teardown-remake/references/reference-lookup.md12 KB7764e7c5f486upstream ↗
    # Reading the reference from a link
    
    The reference usually arrives as something the user already has — a file, screenshots, a
    transcript, their own account of it. This route exists for the shape they reach for
    first: **the link**. When the connection exposes Beatra's public social lookup, a link
    can be read directly.
    
    It is optional and it is paid. A run that never touches it is a complete run, and the
    teardown from screenshots is a real teardown.
    
    ## What this package may look up
    
    Only these operations. Do not invent an `operation_key`, and do not reach for one that
    is not on this list even when `beatra.social.tools.search` returns it.
    
    | Platform | The post itself | Its comments | Credits |
    | --- | --- | --- | --- |
    | TikTok | `social.tiktok.video.get_by_url` | `social.tiktok.video.comments.list` | 6 |
    | Douyin | `social.douyin.video.get_by_url` | `social.douyin.video.comments.list` | 6 |
    | X | `social.twitter.tweet.get` | `social.twitter.tweet.comments.list` | 6 |
    | YouTube | `social.youtube.video.get` | `social.youtube.video.comments.list` | 6 |
    | Instagram | `social.instagram.post.get` | `social.instagram.post.comments.list` | 12 |
    | Xiaohongshu | `social.xiaohongshu.note.video.get`, `social.xiaohongshu.note.image.get` | `social.xiaohongshu.note.comments.list` | **60** |
    
    Plus one transcript operation: `social.youtube.video.captions.get`, **60 credits**,
    YouTube only. No other platform on this list returns a transcript.
    
    Plus two account-level operations, **Douyin only**, used together for the same-account
    comparison below: `social.douyin.user.search` and `social.douyin.user.posts.list`, 6
    credits each.
    
    Prices are what the catalog charges today; read the live price from
    `beatra.social.tools.get` and quote that, not this table.
    
    ## A same-account comparison — Douyin only, two lookups
    
    One video doing well can just be the recommendation algorithm rolling the dice. To tell
    a repeatable method apart from a one-off, the cheapest evidence is the rest of the
    account's output, and on Douyin this route can reach it in two paid steps:
    
    1. **`social.douyin.user.search`** with the creator's name as `keyword` — the same name
       the user already has from watching the reference, never an internal ID they would
       have to go and find. Returns a page of matching users, each carrying its `sec_uid`.
       Confirm this lookup on its own, at its live price, before running it.
    2. **`social.douyin.user.posts.list`** fed that `sec_uid`. Returns one page of the
       account's posts, each with its own `statistics` and `video` metadata; a page this
       size typically comes back as an artifact envelope — handle it per "A lookup delivers
       in one of two shapes" below. Confirm this lookup on its own too, at its own live
       price, separately from the search above — it is a second charge, not bundled into the
       first.
    
    **That is two separate paid lookups, each disclosed and confirmed on its own before it
    runs**, exactly like every other lookup on this page — never one price quoted for both,
    and never the second one run on the strength of the first's approval. Read both prices
    live from `beatra.social.tools.get`; quote no number from memory.
    
    Once the page of posts is in hand, check two things against it: how far this post's
    public metrics sit from the account's median, and whether the same structural beats show
    up in the other posts. Recurrence points to a method; a one-off points to luck.
    
    **This route exists on Douyin only.** No search-by-name operation is whitelisted for
    TikTok, Instagram, YouTube, X, or Xiaohongshu — on those platforms, say plainly that a
    same-account comparison is not available here, rather than implying this route
    generalises.
    
    This whole comparison is optional, and it is the user's call whether the teardown's
    directional judgement needs this anchor badly enough to spend twice more — never run it
    without asking, and never send the user off to hand-collect other posts manually instead
    of running it. When it is skipped — on Douyin by choice, or because the reference is on
    another platform — say so in the teardown report: a single-post sample cannot tell a
    method from a lucky roll, and the report should state that plainly rather than imply
    otherwise.
    
    ## Turning the link into arguments
    
    Each operation takes what a pasted link already contains. Never ask the user for an
    internal ID they would have to go and find.
    
    - **TikTok and Douyin** take the share link as `share_url`. The comments operation needs
      an `aweme_id`, and a canonical link carries it already: it is the numeric segment in
      `tiktok.com/@user/video/<id>` or `douyin.com/video/<id>`. Read it from the link when it
      is there — comments then cost one lookup rather than two. A short or redirecting link
      does not carry it; take it from the post lookup's returned payload instead, and if
      neither yields one, say the comments cannot be read for this link rather than paying
      for a guess.
    - **Xiaohongshu** takes the share link as `share_text`, including an `xhslink` short
      link. Both the video-note and image-note operations accept it; pick by what the link
      actually is, and if that is not yet known, ask the user rather than paying twice.
    - **Instagram** takes the post URL directly as `code_or_url`.
    - **YouTube** needs `video_id` — the `v=` parameter, or the last path segment of a
      `youtu.be` or `/shorts/` link. Captions are the exception: they accept `video_url`
      directly.
    - **X** needs `tweet_id`, the numeric segment after `/status/`.
    
    ## The route
    
    1. Find the operation with `beatra.social.tools.search`. Free.
    2. Inspect it with `beatra.social.tools.get`. Free. Read the arguments and the credit
       price, and copy the `schema_hash` it just returned.
    3. Show the user the `operation_key` and the credit price that `tools.get` just
       returned, in plain words alongside them, and get a clear go-ahead. Then call
       `beatra.social.execute` once with `operation_key`, that `schema_hash`, `arguments`,
       and one `client_request_id`.
    4. Poll with `beatra.tasks.get` until terminal.
    
    One `execute` is one prepaid lookup. **The next page of comments is another `execute`
    and another charge**, not a page token on the same call. One page of comments is enough
    to read the audience; a second page is a new decision for the user.
    
    Public social lookup has no `model` field. On a failure keep `error.code` and read the
    platform wording in `error.message`; do not call `beatra.models.list` and do not offer a
    different model. Do not show `schema_hash` to the user.
    
    If the social tools are not exposed on this connection, say the lookup is not available
    here and read the reference from whatever the user brought. That is the ordinary shape
    of this route, not a degraded one.
    
    The same answer covers a link this route cannot read at all. Only the six platforms in
    the table above have operations; a WeChat Channels, Kuaishou, Bilibili, or Weibo link
    has none. Say so plainly, name the shapes that do work — a file, screenshots, a
    transcript, a description — and never substitute a neighbouring platform's data for the
    one the user actually linked.
    
    Every call on this route goes through the bundled `scripts/mcp_client.py`, exactly as
    the generation calls do. Do not configure or call a host Beatra Connector, and do not
    fall back to REST or OpenAPI.
    
    ## The captions trap
    
    `social.youtube.video.captions.get` costs 60 credits per call, and **calling it with an
    empty `language_code` returns the list of available captions rather than a transcript**.
    That listing call is billed like any other. Pass the language you expect on the first
    call, and only fall back to the empty-code listing when that returns nothing — otherwise
    one transcript costs 120 credits instead of 60.
    
    Say plainly that a transcript is available for YouTube only. On every other platform,
    the spoken track still has to come from the remaining tiers of the four-tier dialogue
    ladder — a transcript the user supplies directly, hard-burned subtitles read from the
    frames, or recorded as missing — never from the video's own audio track, which the
    vision model cannot hear; see [reading the reference](teardown.md) for the full ladder.
    
    ## Confirming it
    
    **Every lookup is confirmed on its own before it runs, without exception.** There is no
    request specific enough to skip the price: the operations on this list range from 6 to
    60 credits, so the same sentence — "read this link for me" — costs ten times more on
    Xiaohongshu than on TikTok, and a transcript costs ten times more than the post it
    belongs to.
    
    State, before the call:
    
    - what is being looked up, in plain words — the post, its comments, or its transcript —
      together with the `operation_key` it maps to;
    - the credit price `beatra.social.tools.get` just returned;
    - how many lookups the plan contains, counting the post, the comments, and the
      transcript as separate charges, and each extra page as one more;
    - that the teardown can run on screenshots or a description at no cost.
    
    Offer the post on its own first. Comments and a transcript are worth their price when
    the teardown needs them, and the user should be the one who decides that.
    
    ## What each lookup adds to the teardown
    
    Keep this straight, because it decides whether a lookup is worth running at all.
    
    - **The post** gives the caption, the author, the visible metrics, and public media URLs.
      It fixes the claims and the call to action, and it dates the reference — a structure
      that worked eighteen months ago is a different bet from one that worked last week.
    - **The comments** give the audience's own words. This is the strongest evidence
      available for *why* it held: what viewers quote back, what they ask, what they object
      to. Use it to name the hook that actually landed and to source objections the remake
      should answer.
    - **The transcript** gives the spoken track verbatim, so the beat table's `Spoken`
      column stops being reconstructed.
    
    None of the three shows you a frame. Framing, motion, on-screen text, and cutting rhythm
    still come from a file the host can open, from screenshots, or from the user. Say which
    is which.
    
    ## A lookup delivers in one of two shapes
    
    A small result comes back inline in the task output. A large one does not: the
    `output` is instead an envelope, `{"delivery": "artifact", "result_artifact": {...}}`,
    and the actual data sits at `result_artifact.url` as CDN-hosted JSON. A single page of
    a creator's posts measured around 630 KB and came back this way.
    
    Handle both shapes. When `delivery` reads `artifact`, fetch `result_artifact.url` and
    parse the JSON it returns — the envelope is not the result, and treating it as one
    means working from a payload that is missing everything.
    
    ## A direct play address expires fast
    
    The post payload's play address carries a `cdn_url_expired` timestamp, and in practice
    it goes stale after roughly 57 minutes.
    
    So: **use a direct address the moment it is fetched, inside the same run that fetched
    it.** Never cache it across sessions, and never write it into a deliverable for the user
    to click later — it will be dead by the time they do. Re-running the teardown later
    means fetching the post again, not reusing the old link.
    
    The same payload carries `has_watermark`. For Douyin it is `true` — the play address
    this route can reach is watermarked, and there is no unwatermarked version to ask for
    instead. That watermark is why the reference footage itself can never be fed into a
    generation call; see [compliance](compliance.md) for what it rules out.
    
    ## Carrying the result into the teardown
    
    Every figure that reaches the report is labelled with where it came from and when.
    
    - A view, like, comment, or share count read from a lookup is marked as looked up, with
      the time it was read. These move; a count quoted without its read time ages badly.
    - Anything the user supplied stays marked as supplied.
    - Anything neither source produced is stated as missing, never estimated from what
      videos like this usually do.
    - **Why it performed well remains inference even with comments in hand.** Comments are
      evidence about what the audience noticed, not proof of what caused the result. Mark
      the read as inference, quote the comments that support it, and say what would confirm
      it — the same structure repeating across other posts by the same account, or a wider
      sample.
    
  • skills/viral-video-teardown-remake/references/remake-plan.md13 KBdfc1e5199a90upstream ↗
    # Rewriting onto your subject
    
    The teardown produced a structure. This stage carries that structure onto the user's own subject and turns it into something that can be shot.
    
    ## What carries over and what does not
    
    Carry over table 2's line count and its per-line timing budget, table 3's shot count and the functional sequence of its shots, and the timing shape. Replace every piece of content.
    
    The most common failure is a remake that keeps the reference's specifics — its numbers, its demonstration, its story — and swaps only the product name. That produces a claim the user cannot stand behind and a video that reads as a copy. Keep the skeleton; rewrite the flesh.
    
    Timing shape means proportion, not exact seconds. If the reference gave 3 seconds of its 30 to the hook, a 12-second remake gives the hook about 1. Hold the ratios, then round to whole seconds.
    
    ## Write each beat as two fields
    
    Every beat gets **on screen** and **spoken** as separate fields. Never merge them.
    
    A merged field cannot be shot: the frame prompt needs the visual with no dialogue in it, and the narration needs the spoken line with no scene description in it. Writing them together means untangling them later, badly.
    
    | Field | Written for | Contains |
    | --- | --- | --- |
    | On screen | The image call | Subject, framing, setting, lighting, motion, any on-screen text — no dialogue |
    | Spoken | The speech call | The exact words in speaking rhythm — no scene description, no stage directions |
    
    Budget the spoken fields against the target length. Natural narration runs roughly four to five Chinese characters, or two to three English words, per second.
    
    What caps the target length depends on how the rebuild will actually be built, and the two routes cap it differently. A single continuous take is one generation call: the clip has to be at least as long as the narration and the selected live model card sets the maximum, so the whole spoken script — every beat added together — has to read aloud inside that live ceiling. A segmented rebuild splits the clip into units, and that split is what absorbs a clip longer than one card allows; the narration stays one continuous track, and the card's ceiling binds each unit's own duration rather than the script as a whole. See [three rebuild routes](rebuild-routes.md) for which route this rebuild takes.
    
    Either way, total the spoken fields at the rate above before the shot list is shown, and cut lines until they fit the target length. Write to that budget rather than trimming after synthesis: a script that merely overruns its target costs a second paid call, and a script that overruns a single continuous take's ceiling stops the run outright, because shortening the video would cut off the ending. Discovering either one after a video call costs one of the most expensive calls in the run.
    
    ## Where the facts come from
    
    Everything the user's remake asserts about the user's own subject comes from the user.
    
    Specifications, prices, materials, ingredients, certifications, awards, before-and-after results, timeframes, and promotional terms are theirs to supply. When one is missing, write the beat around it — a beat can carry a demonstration or a scene instead of a number. Never fill the gap with a plausible-looking figure; the user is the one who answers for it.
    
    What is safe to write without asking: what the subject visibly is and does, how it is used, who it is for, and the feeling the beat should carry.
    
    ## Screen the copy before it becomes a frame or a voice
    
    Run every spoken and on-screen line through three checks while it is still free to change.
    
    **Superlatives and absolutes.** Words claiming top rank, totality, or permanence — best, first, number one, absolute, permanent, national-grade, 100% — are restricted in advertising copy in several markets, and their local-language equivalents carry the same restriction. They are also cheap to replace. Rewrite to the specific thing that is actually true: not "the best cleaning power", but "lifts the mark in one wipe" when the user has seen it do that.
    
    **Efficacy claims.** Health, medical, curative, weight, and safety outcomes need substantiation the user actually holds. Without it, move the line to what the user observed rather than what the product does.
    
    **Prices.** A price stated without its unit, size, or condition invites a complaint. Whenever a number appears, the specification appears with it.
    
    Then read it aloud once. Short sentences. Natural stops. No written-register connectives — the line has to sound like a person talking, because a voice is about to say it.
    
    ## The shot list
    
    Deliver one table the user approves before any generation is paid for. An optional reference lookup, or a `beatra.videos.understand` read of a reference video file, may already have run and been paid for ahead of the teardown; each has its own gate and neither moves this one.
    
    | Column | Contents |
    | --- | --- |
    | # | Beat order |
    | Beat | Its function in this remake, assigned here rather than carried over |
    | Seconds | In and out, contiguous, ending at the target length; the selected live model card's supported duration bounds the whole clip under a single continuous take, and each unit's own slice under a segmented rebuild |
    | On screen | The visual, written so it can become an image prompt as-is |
    | Spoken | The exact words |
    | Note | Anything the shoot needs: on-screen text, a pace change, a sound cue |
    
    Mark which beats become generated frames. How many are actually animated follows the rebuild route: under a single continuous take not every beat needs one — the opening frame governs the finished clip, and the rest are reference material for the user's own shoot — while a segmented rebuild gives every unit in the sequence its own reference frame and its own generation call, per [three rebuild routes](rebuild-routes.md). Say which is which, so the frame count in the confirmation is the frame count they expected.
    
    ## What the remake fixes
    
    The teardown named one weakness in the reference. Say, in one line, how the remake addresses it. That is the difference between matching the reference and beating it, and it is the part the user remembers.
    
    ## Two modes this version builds, and one it does not
    
    Read table 2 for whether the clip carries spoken dialogue, and table 3's subject column for whether the on-screen subject is a person speaking to camera. Those two answers place the clip into one of three shapes — talking head, voiceover, or no dialogue at all.
    
    - **talking head** — dialogue, with the speaker on camera.
    - **voiceover** — dialogue, with no speaker on camera.
    - **no dialogue** — no spoken line at all.
    
    **This version builds only the first two.** Every generation path this route runs always synthesizes and attaches a narration track — the single continuous take is audio-led, and a segmented rebuild still delivers one continuous narration track for the user to align — so a clip with nothing to say has nothing for that track to carry, and there is no path here that skips it.
    
    **When the reference itself has no dialogue at all, say so plainly and stop before offering a third mode.** Do not present "no dialogue" as something this run can build — it cannot, end to end, in this version. Offer the two real choices instead: write a narration for the remake and build it as a voiceover, or treat the request as out of scope for now.
    
    Decide talking head or voiceover once, for the whole clip, before writing a single line, and never mix the two inside one video.
    
    Each mode requires a different set of locks. "Required" and "Advised" name a constraint on the finished clip — a subject, product, or voice identity that must not drift shot to shot, or a picture that must land on a specific last frame — not a specific tool or a specific price; which mechanism satisfies it, and what that mechanism costs, is set out below the table.
    
    | Mode | Reads as | Voice lock | Subject lock | First-and-last-frame lock | Product lock |
    | --- | --- | --- | --- | --- | --- |
    | Talking head | Dialogue, speaker on camera | Required | Required | Optional | Depends on the subject matter |
    | Voiceover | Dialogue, no speaker on camera | Required | Not applicable | Advised | Depends on the subject matter |
    
    ## Four locks, and what satisfies each
    
    - **first-and-last-frame lock** — `beatra.videos.interpolate`. The last frame is required; the first frame and a driving audio track are optional. Billable: it is the video call itself for the unit it locks, disclosed and confirmed at approval gate 2 like any other shoot call.
    - **subject lock** and **product lock** — the mechanism follows the route, because the two routes carry the narration differently.
    
      **Under a single continuous take, the lock lives in the reference frame.** The frame is built from the user's own asset through the real-assets-first tiers below, and `beatra.videos.animate` or `beatra.videos.interpolate` animates that frame — so the identity is held by what the frame carries, while the call still takes the narration as `driving_audio`. Do not reach for `beatra.videos.generate_from_references` here: its request takes a prompt and an ordered `references` list and has no driving-audio field at all, and an unrecognised field is dropped rather than refused, so a take built that way pays for the most expensive call in the run and comes back with no narration on it. There is nothing later that recovers it.
    
      **Under a segmented rebuild, no unit's call carries the narration**, so `beatra.videos.generate_from_references` fits, and it is the mechanism for a unit that needs several ordered image references — drawn from the same real-assets-first tiers below — to hold the identity steady across the unit. It is billable, and it is a video call, not a preparation step: for the unit it locks, it replaces `beatra.videos.animate` or `beatra.videos.interpolate` as the call this route makes. Read the live `reference_to_video` card with `beatra.models.list` before the shot list is signed off, disclose its current price at approval gate 2 alongside the other shoot options, give it its own stable `client_request_id`, and never submit it before the user has confirmed the estimate — the same footing as every other shoot call.
    - **voice lock** — **the default, at no cost, is picking one `status: ready` voice with `beatra.voices.list` and reusing that same voice id for the whole clip.** `beatra.voices.clone` is a separate, optional, billable upgrade for when the user wants a voice built from their own sample instead of a preset — it is never the only way to satisfy this lock, and it is never chosen silently on the user's behalf. Offer the free pick first. If the user asks to clone one instead, read the live `voice_clone` card with `beatra.models.list`, quote its current price, and get the user's explicit confirmation together with `consent_attested: true` — set only once the user attests they hold the rights to clone that sample. Give the clone its own stable `client_request_id`, submit it once, and disclose it at approval gate 1 alongside the frame and narration calls, since the clip's voice has to exist before narration can be synthesized.
    - **length adaptation** — `beatra.videos.extend`, used only when a single continuous shot runs longer than the selected model's supported duration.
    
    ## Reference frames: real assets before anything generated
    
    Take reference images in this order, and do not skip a tier:
    
    1. **What the user uploads for this run** — `beatra.assets.upload`, up to 100 MiB.
    2. **Assets the user already has** — material already sitting in the user's own library.
    3. **Generation** — `beatra.images.generate`, only once neither of the first two tiers has anything usable.
    
    A subject lock's or a product lock's reference images are drawn from these same three tiers — both the single frame a continuous take animates and the ordered references a segmented rebuild's unit feeds into `beatra.videos.generate_from_references` — and the physical-product rule below applies to them exactly as it applies to any other reference frame.
    
    **When the subject matter involves a physical product, its product-lock reference image comes from tier one or tier two only — it is never generated.** A generated product shot is not that product: its packaging, colour, logo, and proportions will all be subtly wrong, and the user usually only discovers this once the cut is finished. Treat this as a hard rule, not a preference.
    
    ## Rewrite losslessly
    
    Change the words. Do not change the skeleton:
    
    - Keep table 2's line count and its per-line timing budget; a swing of up to 15% either way is fine.
    - Keep table 3's shot count and the functional sequence of its shots.
    - Never let the rewritten words contradict what is on screen — a line that says "open the box" over a static product shot is a contradiction, not a rewrite.
    
    Once the rewrite is done, rehearse it against the chosen voice for real timing. If it overruns, **cut spoken words first, not shots** — table 3 has already fixed the shot count.
    
  • skills/viral-video-teardown-remake/references/tasks-and-results.md2.2 KB34977869c667upstream ↗
    # Tasks and results
    
    Generation returns an asynchronous task. Keep its `task_id` and use
    `beatra.tasks.get` to poll it with bounded backoff: wait 2 seconds before the
    first poll, then increase the interval toward 5, 10, and at most 15 seconds.
    Honor `deadline_at` when the task response provides it. Otherwise stop active
    polling after 30 minutes, report the task ID and current status, and explain
    that the user or a later agent session can resume polling the same task.
    
    ## Interpret state
    
    - `queued` and `running` are nonterminal. Continue polling; do not submit a
      replacement generation.
    - `succeeded`, `failed`, and `canceled` are terminal. Stop polling.
    - On success, present returned artifacts, resolved model, actual usage, and
      billing truth. For prepaid work, report `billing.net_charged_credits`; the gross charged value
      may include a supplemental actual-usage debit and the refunded value may
      return an unused request-time estimate.
    - For a settled video task, `usage.video_seconds` is the authoritative
      billable total. When present, `usage.input_video_seconds` and
      `usage.output_video_seconds` are the authoritative components of that total.
      This distinction matters for reference-video generation and video editing,
      where both input and output can be billable. Do not infer either component
      when Beatra returns it as `null`.
    - On failure, preserve the structured error and apply the recovery reference.
    
    Use `beatra.tasks.list` to recover a lost task ID or inspect recent work from
    this connection. Filter only when doing so helps identify the task.
    
    Call `beatra.tasks.cancel` only when the user requests cancellation. Before
    remote execution starts, cancellation stops the task. After remote execution
    starts, Beatra returns `canceled` only when the stop is confirmed. A `409`
    means the task continues: do not promise a stop or refund, do not submit a
    replacement, and continue polling the same task.
    
    Do not infer an artifact URL, completion, usage, or charged credits from
    elapsed time. Return only fields present in Beatra's task response.
    For MCP task reads, prefer the direct `structuredContent.usage` and
    `structuredContent.billing` objects; the complete envelope remains available
    under `structuredContent.task`.
    
  • skills/viral-video-teardown-remake/references/teardown.md8.2 KBa53e9da0b4b1upstream ↗
    # Reading the reference
    
    The teardown draws on three sources, and it keeps them separate because their reliability is not the same.
    
    | Layer | Source | Reliability |
    | --- | --- | --- |
    | Picture semantics — shots, framing, on-screen text | `beatra.videos.understand`, one call, `response_format` set to `json` | High for what it sees; **timings need a rescale before they mean anything** |
    | Dialogue | The four-tier ladder below | Depends on which tier supplied the line |
    | Public metrics and comments | `beatra.social.execute` | A snapshot taken at read time |
    
    **Call `beatra.videos.understand` once, not once per question.** It is billed per second of input video. Four separate questions against the same clip are not four small charges — each one recomputes the whole clip, so four questions cost four times the price of one. Put every field the teardown needs into a single JSON structure and ask for it in one call.
    
    **The call is also capped at 50 MiB and 360 seconds of input video** — a fixed tool limit, checked before the price is even quoted, not something a live card can raise. A reference past either limit is rejected before any charge; check the file against both before proposing the price.
    
    That one call is still a charge, so it is confirmed on its own before it runs, the way the optional lookup is: state both limits, quote the live per-second price read from `beatra.models.list` with capability `video_to_text` rather than a number from memory, and say plainly that the teardown can run at no cost from screenshots, a transcript, or the user's own account of the clip instead. See [remake workflow](workflow.md) for that gate. When the reference arrives in one of those shapes rather than as a video file, this charge never arises at all — fill the tables below from what the user brought, and say which parts you read yourself.
    
    ## Table 1 — duration lock and rescale
    
    Read the clip's real duration, `T`, from the material's own metadata before looking at anything the model returned.
    
    **Never take the duration from the model. Its self-reported duration is wrong.** A probe against a public 56-second Douyin post came back with `total_duration_s: 1.46` — the tool had compressed all nineteen shots' timings into that range while the clip itself ran fifty-six seconds.
    
    The error is not random; it is a clean linear scale, and that makes it fixable:
    
    1. Read the model's `total_duration_s` as `T_reported`.
    2. Compute `k = T / T_reported`, using the real `T` from the material's own metadata — never the model's figure.
    3. Multiply every timing the model returned, every shot's start and end, by `k`.
    4. Check that the rescaled end of the last shot lands on `T`. On the probe clip it landed exactly on 56.00 seconds, with a mean deviation of 0.245 seconds from whole-second boundaries across the rest of the shots.
    
    Table 1 records `T`, `T_reported`, `k`, and that end-of-last-shot check. Every other table's timings depend on this table having run first.
    
    State the precision ceiling out loud: the model samples one frame per second internally, so no rescaled timing is more precise than a second. That is enough for an ordinary clip; a clip with cuts inside the same one-second window will not show them apart, and the teardown should say so rather than let table 3 imply a precision it does not have.
    
    ## Dialogue: a four-tier ladder
    
    **The model cannot hear.** It receives sampled frames, not an audio track, so dialogue never comes from `beatra.videos.understand`. It comes from one of four sources, taken in this order:
    
    1. A transcript the user supplies directly. Highest reliability, no extra cost.
    2. The YouTube captions operation — YouTube only. No other platform this package can reach has an equivalent operation.
    3. Hard-burned subtitles read from the frames. The text itself is real, but there is no precise per-line start and end time behind it — mark these lines **approximate**.
    4. Nothing available. Record the line as missing in table 2. **Never invent a line of dialogue.**
    
    ### Never ask the vision model about sound
    
    On the same probe clip — one that had background music — `beatra.videos.understand` returned `spoken_audio_detected: false`. It has no audio track; that boolean is a guess dressed up as an observation, and here it was a **false negative**, the dangerous kind: acting on it would put the entire rewrite layer on the premise that the clip has no dialogue to work from.
    
    Keep every audio field out of the JSON structure you request, and out of the prompt. Whether the clip has speech, music, both, or neither is answered only by the four-tier ladder above, never by the vision model.
    
    ## Table 2 — per-line script evidence
    
    | Start (s) | End (s) | Duration | Line | On-screen keyword | Source tier |
    | --- | --- | --- | --- | --- | --- |
    
    Two rules, no exceptions:
    
    - **One row per spoken line.** Never merge two lines into one row, and never split one line across two rows.
    - **Never polish the wording.** This table is evidence, not copy — transcribe the line as delivered, awkward phrasing included.
    
    "On-screen keyword" is for a price, a discount, a number, or a promise printed on screen — the things a later compliance pass needs to check. "Source tier" names which of the four tiers above supplied that row, so a reader can tell an exact YouTube caption apart from an approximate burned-in subtitle at a glance.
    
    ## Table 3 — shot master table
    
    | # | Start (s) | End (s) | Cut type | Shot size | Lighting | Subject and emotion | Caption position |
    | --- | --- | --- | --- | --- | --- | --- | --- |
    
    Cover the whole clip: no gap between one shot's end and the next shot's start, no overlap between rows, and every timing already run through the rescale in table 1.
    
    **There is no camera-movement column, and that is deliberate.** On the probe clip, all nineteen shots came back `Static` for camera movement. One frame per second gives the model no inter-frame continuity to read, so a pan, tilt, or push is invisible to it in principle — the field was never observing anything real. A column that returns the same constant value on every row is worse than no column at all, because a downstream reader treats a constant as a real observation instead of noticing it was never measurable. If camera movement matters to the teardown, ask the user, or say plainly that this route cannot get it.
    
    ## Table 4 — observation and attribution
    
    Six dimensions: hook strength, information density, pacing, subject presentation, emotional curve, conversion pull.
    
    **No absolute scores.** For each dimension, write three things:
    
    - **Observation** — what the clip actually does on this dimension, stated as fact.
    - **Evidence** — a row number cited into table 2 or table 3, not a general impression.
    - **Directional judgement** — stronger or weaker than the comparison in hand, never a number.
    
    There is no baseline corpus behind a figure like 8.5 out of 10 for a hook — a number like that is invented precision dressed up as measurement. A same-account comparison gives the directional judgement something concrete to be relative to; on Douyin, two further paid lookups can reach one — see [reading the reference from a link](reference-lookup.md) for the route and its cost, rather than re-deriving that mechanism here. It is optional, and on every other platform it is not available at all. Without a comparison in hand — whether it was skipped by choice or the platform has none — say plainly that the judgement reflects one sample and nothing more.
    
    ## Two limits to state in the deliverable
    
    **Why a clip performed remains an inference, even with comments in hand.** Comments are evidence of what viewers noticed, not proof of what caused the result. Say what would confirm the read — the same structure recurring elsewhere in the account, or a wider sample — rather than presenting the inference as settled.
    
    **The metrics that would actually settle it are not available.** Completion rate and the three-second drop-off are the decisive numbers for judging a hook, and no platform this package reaches exposes either one. Every retention read built from likes, comments, or shares is a weak substitute for those two numbers, not an equivalent to them. State this plainly in the deliverable — otherwise table 4 reads as more certain than the evidence behind it actually is.
    
  • skills/viral-video-teardown-remake/references/uninstall-and-disconnect.md2.7 KB5435c8ecc181upstream ↗
    # Uninstall and disconnect
    
    Use this workflow when the user asks to remove, uninstall, or delete this
    package, or to disconnect this device from Beatra entirely.
    
    ## The one rule
    
    The device connection (`~/.beatra`) is shared by every installed Beatra skill.
    It may only be retired when no other Beatra skill remains on this device — and
    `scripts/uninstall.py` is the only component that can decide that. Never delete
    `~/.beatra` or any file inside it yourself, and never skip the script, even
    when the user asks for a complete removal: if another installed skill still
    uses the connection, the connection must survive this uninstall.
    
    ## Steps
    
    1. Run the bundled decision script first, while the package files still exist:
    
       ```
       python3 scripts/uninstall.py
       ```
    
       `--dry-run` prints the same JSON decision without changing anything or
       contacting the server. Never act on a dry-run report — rerun without the
       flag to actually uninstall.
    
    2. Read the JSON decision it prints:
    
       - `"decision": "keep_connection"` — another installed skill still uses the
         shared connection (`remaining_skills` lists them), or the inventory could
         not prove this is the last one. The credential and `~/.beatra` stay
         untouched. Tell the user which skills keep the connection alive.
       - `"decision": "disconnected"` — this was the last Beatra skill. The script
         has removed the local connection state. `"revoked": true` means the
         server confirmed the revocation; `"revoked": false` means it could not be
         confirmed from here (server unreachable, or the token was no longer
         recognised) — the authorization then expires on its own after 15 days of
         inactivity, and the user can revoke it immediately in the Beatra Console
         under Agents.
       - `"decision": "revoke_retry"` — the server was reached but refused just
         now (for example rate limiting). Nothing was changed. Run the script
         again shortly, or have the user revoke the device in the Beatra Console
         and then rerun it to finish removing local state.
    
    3. After a `keep_connection` or `disconnected` decision, finish by deleting
       only the package directory the script names in `delete_next`. Do not delete
       anything else. (After `keep_connection`, the inventory notices the deleted
       directory by itself — no further bookkeeping is needed.)
    
    ## Disconnecting everything
    
    There is no separate "disconnect all" action. Uninstall each installed Beatra
    skill with its own bundled script; the last one automatically revokes the
    authorization and clears `~/.beatra`. The user can always revoke the device
    from the Beatra Console as well — that invalidates the credential server-side
    immediately, whatever remains on disk.
    
  • skills/viral-video-teardown-remake/references/updates-and-security.md5.9 KB5c0172b54189upstream ↗
    # Updates and security
    
    Since the October 2026 releases, Beatra Skill packages contain no self-updater.
    Earlier releases could replace their own files from Beatra's CDN; that code has
    been removed. Updates now come only from the store or tool you installed the
    Skill from.
    
    ## What runs
    
    Every operation runs one of the bundled scripts: `scripts/mcp_client.py`,
    `scripts/authorize.py`, or `scripts/uninstall.py`. They use only the Python
    standard library. `scripts/authorize.py` opens the Beatra approval page in
    this computer's web browser when approval is still needed. They never
    download, write, or execute other code, and the files of this installed Skill
    stay exactly as installed.
    
    ## Where requests go
    
    Requests use HTTPS and follow this computer's network route, described in
    [MCP connection](mcp-connection.md): the international hosts, or the mainland
    China hosts `mcp.beatra.cn`, `api.beatra.cn`, and `www.beatra.cn`. When you
    choose to upload a local file, it goes only to the one-time upload address
    Beatra issues for that upload. Choosing the network may send a small request
    to the other network, and so may retrying the version list once, unless a
    network was chosen with `network --use`.
    
    ## What is stored on this computer
    
    These files are written under `~/.beatra/`. On POSIX that directory is mode
    0700. Nothing is written inside the installed Skill directory.
    
    - `credentials.json` (POSIX mode 0600), written by `scripts/authorize.py`: the device credential.
    - `installation.json` (POSIX mode 0600), written by `scripts/authorize.py`: the stable installation reference.
    - `host.json` (POSIX mode 0600), written by `scripts/authorize.py`: the agent environment, and a device name when one is known.
    - `network.json` (POSIX mode 0600), written by `scripts/mcp_client.py`: this computer's network route.
    - `skills.json` (POSIX mode 0600), written by `scripts/authorize.py` and `scripts/mcp_client.py`: which Beatra skills are installed here, with the slug, agent environment, install path, and time.
    - `pending_authorization.json` (POSIX mode 0600), written by `scripts/authorize.py`: an approval that is still open. Removed when that approval is collected or discarded.
    - `.authorize.lock` (POSIX mode 0600), written by `scripts/authorize.py` while authorization is in progress, then removed.
    - `balance-holds.json` (POSIX mode 0600), written by `scripts/mcp_client.py`: a local record after a tool is refused for insufficient credits. Removed when no such record remains.
    
    `scripts/mcp_client.py` also keeps one directory per installation under
    `~/.beatra/updates/`. Its name is the first 24 hexadecimal characters of the
    SHA-256 of the resolved installation path, and on POSIX the directory is mode
    0700. The files inside it are POSIX mode 0600:
    
    - `state.json`: the time of the last version check.
    - `registration.json`: the cache of the last installation registration.
    - `source.json`: where this copy was installed from, when that is known.
    
    Replacing one of these files writes a temporary file in the same directory and
    then renames it over the old file.
    
    When `scripts/uninstall.py` decides this is the last Beatra skill on the
    computer, it first asks Beatra to revoke the device credential when one is
    stored. If Beatra refuses, it changes nothing so the run can be repeated.
    Otherwise it unlinks exactly these names in `~/.beatra/`: `credentials.json`,
    `installation.json`, `host.json`, `skills.json`, `registrations.json`,
    `network.json`, `balance-holds.json`, `pending_authorization.json`, and
    `.authorize.lock`. It also unlinks `state.json`, `registration.json`, and
    `source.json` in each installation directory under `~/.beatra/updates/`. It
    then removes each of those directories, `~/.beatra/updates/`, and `~/.beatra/`
    only when that directory is empty. These
    scripts do not create `registrations.json`; uninstall still unlinks that name
    if it is present. The script never deletes the installed Skill directory. It
    names that directory in `delete_next` for the caller to delete. If another
    skill remains, or the inventory cannot prove this is the last one, it leaves
    `~/.beatra/` unchanged.
    
    ## What is reported
    
    Beyond the requests a command makes, the only report is the installation
    registration described in [installation registration](installation-registration.md).
    No prompts, file contents, file paths, or tool-call details are sent with it.
    Each tool call itself names this package and the agent environment (for example
    `claude-code`), as source attribution in [MCP connection](mcp-connection.md)
    describes, so a task can be traced to the Skill that made it.
    
    ## Version notice
    
    At most once every 24 hours, before an ordinary command, the bundled client
    reads Beatra's public version list for this package
    (`/skills/<package>/sources.json` on the site host of the current network). It
    works out from local records which store or tool installed this copy. When that
    place offers a newer version, it prints one line on standard error with the
    command that updates it there. It never installs anything. If the check fails,
    nothing is printed and the command runs as usual. A copy with no such record
    gets no notice.
    
    | Installed with | Update with |
    | --- | --- |
    | ClawHub CLI | `clawhub update <package> --workdir <dir> --dir <skills-dir>` (add `--force` if it reports local changes) |
    | SkillHub CLI | `skillhub install <package> --force --dir <skills-dir>` |
    | GitHub CLI | `gh skill update <package>`, run in the project directory for a project install |
    | skills CLI (GitHub or ModelScope) | `npx skills update <package> -p -y`, run in the project directory; or `npx skills update <package> -g -y` for a global install |
    | WorkBuddy | Update the Skill in WorkBuddy |
    | Beatra website (English packages) | Reinstall from the package's install page |
    
    ## Check by hand
    
        python3 scripts/mcp_client.py update --check
    
    It reports what the store or tool you installed from offers now. It installs
    nothing and leaves the Skill's files unchanged. If `python3` is not the local
    Python command, use the available Python 3.10+ command.
    
  • skills/viral-video-teardown-remake/references/workflow.md29 KB3d3fb7a12a06upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/viral-video-teardown-remake/install-source.json39 B71bdc5669a3bupstream ↗
    {"schema_version":1,"source":"github"}
    
  • skills/viral-video-teardown-remake/manifest.json7.9 KB4a0f10028a38upstream ↗
    {
      "changelog": "The helper shared by all Beatra Skills now runs its connection step at most twice in one turn. While your approval is still pending, the Skill delivers the part of your request that needs no connection and continues the paid step on your next message after Allow.",
      "display_name": "Viral Video Teardown Remake",
      "entry": "SKILL.md",
      "homepage": "https://beatra.ai/skills/viral-video-teardown-remake",
      "icon": "https://beatra.ai/textures/icons/viral-video-teardown-remake-0.4.1.png",
      "localized": {
        "en": {
          "description": "Turn a short video that already worked into your own version. Paste the link and this viral video teardown and short-video remake workflow reads the reference itself on TikTok, Douyin, Xiaohongshu, Instagram, YouTube, or X — caption, author, visible metrics, comments, and on YouTube the full transcript — or work from a file, screenshots, or your own description instead. It breaks the clip into its hook, body beats, and call to action, names the script pattern behind it, scores what carried the performance, then rewrites that structure around your product or topic — delivering a shot list with visuals and narration kept apart, reference frames from your own assets before any are generated, a narration track, and either an animated clip or segmented sources with a timecoded edit list. Use it to study a competitor's viral short, borrow a proven structure for Reels, Shorts, or WeChat Channels, rebuild a benchmark video under your own brand, or turn a saved reference into a content formula you can run again.",
          "display_name": "Viral Video Teardown Remake",
          "summary": "Paste the link or bring the file, break a short video that worked into its hook, beats, and call to action, then rebuild that structure around your own subject as a shot list, beat frames, and narration — delivered as one vertical clip animated from your opening frame, or, when the reference cuts too fast or runs too long for a single take, as segmented sources with captions and a timecoded edit list.",
          "tags": [
            "viral video teardown",
            "short video remake",
            "viral video breakdown",
            "recreate a viral video",
            "competitor video analysis",
            "video hook analysis",
            "short form video script generator",
            "TikTok viral video analysis",
            "video shot list generator",
            "storyboard from a reference video",
            "benchmark video rebuild",
            "short video remake with voiceover",
            "analyze a video from its link",
            "video comment analysis",
            "YouTube transcript to script"
          ],
          "title": "Viral Video Teardown Remake: Break Down a Short and Rebuild It as Yours"
        },
        "ja": {
          "description": "すでに伸びた短尺動画を、あなた自身の一本に作り替えます。参考動画はリンクを貼るだけでも構いません。Douyin(抖音)・TikTok・小紅書・Instagram・YouTube・Xの投稿から、キャプション、投稿者、公開数値、コメントを取得し、YouTubeなら字幕の全文まで取り出せます。手元の動画ファイルやスクリーンショット、ご自身の説明からでも同じように進められます。参考動画を冒頭フック・本編の各展開・締めのCTAへ秒単位で分解し、どの構成パターンに当たるかを判定し、伸びた理由を構造・内容・演出の層に分けて言語化したうえで、その骨格をあなたの商品やテーマへ移し替えます。映像と語りを別々の欄に書き分けた台本兼絵コンテ表、まずご自身の素材を参照フレームとして使い、足りない分だけ生成するカット画像、選んだ声によるナレーション音声、そして動かした動画一本、またはタイムコード付き編集リストを添えた分割済み素材のいずれかを納品します。バズ動画のリメイクを、分解から動画一本まで一つの流れで。競合のショート分析、バズ構成の再現、TikTok・リール・ショート・小紅書向けの企画づくり、保存したままの参考動画を繰り返し使える型に変えたいときに。",
          "display_name": "バズ動画 分解・リメイク",
          "summary": "リンクを貼るか手元の素材を渡すだけ。伸びたショート動画を冒頭フック・本編・締めへ分解し、その構成を自分のテーマに移して、絵コンテ・カット画像・ナレーションまで作ります。カット数が少なく尺がモデルの単発生成上限内に収まれば冒頭カットを動かした縦型動画一本、カットが多い、または尺が上限を超える場合はタイムコード付き編集リストを添えた分割済み素材でお渡しします。",
          "tags": [
            "バズ動画 分析",
            "ショート動画 構成 分解",
            "バズ動画 リメイク",
            "競合 ショート動画 分析",
            "動画 フック 分析",
            "ショート動画 台本 作成",
            "絵コンテ 自動生成",
            "TikTok バズ 構成",
            "縦型動画 制作",
            "参考動画 再現",
            "ショート動画 企画",
            "ナレーション付き ショート動画",
            "動画 リンク 解析",
            "コメント 分析",
            "字幕 抽出"
          ],
          "title": "バズ動画の分解とリメイク:構成を読み解き、自分の一本に作り替える"
        },
        "zh": {
          "description": "把一条已经跑出来的短视频,变成你自己的那一条。参考视频可以是文件、截图或你自己的描述,也可以直接粘一个视频链接——抖音、TikTok、小红书、Instagram、YouTube、X 都能读到标题文案、作者、公开数据和评论区留言;YouTube 还支持字幕提取,拿到整段逐字稿。借助 AI 的爆款短视频拆解与复刻工作流:逐段拆出钩子、中段节奏和转化引导,判定它属于哪一类脚本结构,说清它到底靠什么跑起来,再把这套骨架原样套到你的产品或选题上——交付画面与口播分开写的分镜表、优先取用你自己素材、必要时才生成的参考帧、选定音色的口播配音,以及一条动起来的竖屏短片,或者按分段交付的素材配上带时间码的剪辑清单。适合爆款结构分析、评论分析、爆款拆解、对标爆款、抄爆款结构、二创改写、视频号、抖音、小红书、快手起号找对标,也适合把收藏夹里存了很久的参考视频,变成一套能反复复用的内容公式。",
          "display_name": "爆款视频拆解·短视频复刻",
          "summary": "粘一个视频链接,或者把文件截图交给它:把一条跑出来的短视频拆成钩子、中段和转化引导,再把这套结构套到你自己的选题上,出分镜表、分镜图、口播——镜头简单、时长在单条模型上限内就交付一条由开场画面动起来的竖屏短片,卡点多或时长超限就按分段交付素材,配一条完整口播音轨、字幕和带时间码的剪辑清单。",
          "tags": [
            "爆款视频拆解",
            "爆款短视频拆解",
            "短视频复刻",
            "爆款复刻",
            "对标爆款",
            "视频号爆款拆解",
            "抖音爆款拆解",
            "二创脚本",
            "爆款结构分析",
            "短视频钩子分析",
            "分镜表生成",
            "口播脚本生成",
            "爆款视频",
            "视频链接",
            "评论区",
            "字幕提取",
            "逐字稿",
            "评论分析"
          ],
          "title": "爆款视频拆解·短视频复刻:拆到结构,重做成你的"
        }
      },
      "mcp": {
        "authentication": "device-bearer",
        "credential_file": "~/.beatra/credentials.json",
        "name": "beatra",
        "transport": "streamable-http",
        "url": "https://mcp.beatra.ai/mcp"
      },
      "name": "viral-video-teardown-remake",
      "schema_version": 1,
      "version": "0.4.3"
    }
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/beatra-ai-viral-video-remake-skill-skills-viral-video-teardown-remake.md

// REPO STATS

9 stars
0 open issues
Last commit: 5d ago