feat: rewrite video-translate skill with v3 API (hardened)

[davidchou-heygen]

Supersedes #43 (with @kenchung's blessing).

Contains @kenchung's full v3 rewrite (3 commits) plus one follow-up commit from end-to-end testing. Bundling them so the entire video-translate v3 ships as one reviewable change against master.

What @kenchung's commits ship (382b03c, f14e0a0, 3199516)

• New video-translate skill built on the v3 API (POST /v3/video-translations)
• Content-type routing: maps talking-head, podcast, music-video, and corporate content to optimal flag combinations instead of exposing raw boolean toggles
• Precision mode default-on, first-time user detection, source quality guardrails, speaker count validation
• Languages fetched from API (no hardcoded table)
• Discriminated-union video field for source routing (URL / asset upload / existing asset ID)
• URL sanity check (HEAD request) before submission, with local-upload fallback

What the hardening commit adds (badc217)

Eight fixes found by running the skill end-to-end against real translations:

Install path

• Move skills/video-translate/ → video-translate/ to match heygen-avatar/ and heygen-video/ layout
• Register video-translate in setup's SKILLS array

Skill content

• Interactive intake — ask one question at a time, extract from first message, propose sensible defaults
• API key resolution from ~/.heygen/config (mirrors parent SKILL.md's 3-source order)
• Soak-then-tight polling — 5-min silent soak, then 30s polls until terminal
• Backgrounded bash polling — replaces broken Agent subagent path (subagents can't inherit Bash approvals in Claude Code)
• Upfront approval-count warning before launching N background polls
• Narrate-before-each-Bash rule — one sentence about why before every shell call
• Markdown-link-wrapped delivery — flag emoji header + view-online link + [Download .mp4] + [SRT] · [VTT]
• Shell hygiene section — env vars don't persist across Bash calls (inline auth load every time), zsh "no matches found" = unquoted glob, don't burn approvals on diagnostics
• Fix \$status zsh read-only collision in poll script template
• Correct languages endpoint response shape: real API returns { languages: string[] }, not { data: [{ code, name }] }
• Correct dashboard URL pattern: /videos/{id} not /video-translate/{id}

Test plan

• Run ./setup from a fresh checkout — verify video-translate symlinks into ~/.claude/skills
• Submit a translation end-to-end — verify one approval per language, no foreground polling, deliverable renders with clickable links
• Verify the language list query returns successfully on first call (no jq path error)
• Verify View online link opens the correct dashboard page

After merge

• @kenchung to close feat: rewrite video-translate skill to opinionated v3 API #43
• I'll close fix: harden video-translate from end-to-end testing #45 (the interim PR I had stacked on Ken's branch) when this lands

[kenchung]

Review

Domain content is genuinely strong — content-type profiles, soak-then-tight polling, narrate-before-bash, ${status}-vs-st zsh fix, signed-URL markdown wrapping. Most operationally savvy of the three skills.

But this PR was authored against an older repo shape, and master changed materially in the last 24 hours (PR #77 self-containment + PR #79 feat!: eliminate root SKILL.md + PR #80 Codex .app.json). A handful of mechanical fixes are required before merge. ~30 min of work.

Must-fix

1. Skill name should be heygen-translate, not video-translate.
For consistency with siblings heygen-avatar and heygen-video. PR description even says David moved the dir to repo root "to match heygen-avatar/ and heygen-video/ layout" — same logic applies to the name itself. Rename: directory, frontmatter name:, setup SKILLS array entry, any manifest paths.

2. allowed-tools will break the skill at runtime. video-translate/SKILL.md:5 lists only mcp__heygen__*. The skill is heavily Bash-driven (curl, polling loops, jq, asset uploads). Claude Code will deny every shell call. Match siblings: Bash, WebFetch, Read, Write, mcp__heygen__*.

3. Missing version: frontmatter line with # x-release-please-version marker.
Both siblings have version: 3.1.0 # x-release-please-version at line 2. Without it, release-please will never bump this skill's version.

4. .cursor-plugin/plugin.json not updated. The skills array is still ["./heygen-avatar/", "./heygen-video/"]. Cursor users won't see the new skill until it's added: ["./heygen-avatar/", "./heygen-video/", "./heygen-translate/"].

5. release-please-config.json not updated. Add an extra-files entry for heygen-translate/SKILL.md so release-please bumps the version on conventional commits touching the skill.

Suggestions

6. Description missing "NOT for" clause + chain signals. Both siblings have a "NOT for" list (e.g., heygen-video says "NOT for: cinematic b-roll, video translation, TTS-only"). And add chain signals to heygen-avatar / heygen-video where overlap exists — translated talking-head output naturally chains to heygen-video for re-render, or heygen-avatar for voice-clone identity.

7. Missing canonical H2 sections. Both siblings have named ## Files & Paths, ## Language Awareness, ## UX Rules H2s (with the meta-content migrated in via PR #79). The substance is covered by the skill's intake/narrate/Bash-hygiene rules — just needs the canonical H2 labels + a Files & Paths table for ~/.heygen/config, signed-URL temp dirs, asset uploads.

8. Missing argument-hint: in frontmatter. Siblings have it (e.g., [topic_or_script] [--avatar avatar_id]). Add the equivalent for translate inputs.

What's good

• Domain rules (soak-then-tight polling, content-type profiles, narrate-before-bash, upfront approval-count warning, backgrounded-bash for discovery) are real operational learnings.
• No ../ references, no calls to deleted root files — already conforms to the post-#79 self-contained pattern in spirit.
• Single 635-line SKILL.md is tight; no need to split into references/ yet.
• Auth + shell hygiene sections are strong.

Verdict

Request changes. Items 1-5 are blocking (rename, runtime break, version anchor, plugin manifest, release-please config). 6-8 are nice-to-have for consistency with the post-#79 pattern. Once 1-5 land, this is a strong third skill in the stack.

[eve-builds]

Closing as superseded by #82 (merged at 89d28b99 on 2026-05-13). The heygen-translate skill is now on master under the post-#79 independent-skill structure, with verified-against-live-API proofreads docs, full MCP+CLI side-by-side coverage, and David's auth-gate / duration-question / open-ended-language improvements from #86 incorporated. Thanks for the original draft — it kept the skill on the queue.