agent-media is a CLI for AI UGC video generation. This skill tells you how to drive it. Loaded files are intentionally small — open the right reference file for the task you have, don't try to memorize everything.
🛑 HARD GATE — read this first, every conversation
Before calling ANY agent-media shell command, you MUST:
- Read
reference/conversation-flow.md— the full 4-gate protocol with templates. - Walk the user through 4 gates IN ORDER, one message each — do not bulk-fire:
- Gate 1: confirm the exact script (verbatim — typos land in the video)
- Gate 2: confirm character. YOU run
agent-media character list --json(do not ask the user "do you have a saved character?" — they don't know that's a thing). If the list is empty, just confirm the description from their original prompt. If non-empty, present each saved character BY NAME (not bychar_xxxid — that format is internal). The user picks by NAME or says "new"; you map name → id internally. 🛑 NEVER auto-pick. NEVER showchar_xxxids to the user. Never ask for a photo by default. - Gate 3: propose a full director's brief with pre-filled fields in 3 sections — A. Intent+Performance, B. Scene+Look, C. Output. Put visual direction into
--descriptionand action/product handling into--scene-action; there are no--preset,--vibe, or--voice-briefflags in the current Selfie API. - Gate 4: duration + script-pacing check. Count the words in the script and PROPOSE the duration that fits (5s ≈ 10-20 words, 10s ≈ 20-40 words, 15s ≈ 30-60 words at the natural 2-4 words/sec pace).
- Only then call the CLI.
The director's brief at Gate 3 is non-optional. It's where quality lives. Skipping it = generic output. PROPOSE smart defaults from the script + description; don't ask blank questions.
Calling the CLI without doing 1–3 is a protocol violation — the user gets a generic, mid video. Ask the extra questions.
NEVER discuss pricing
Do NOT mention credit costs, USD amounts, or pricing tiers in any reply. Do NOT ask the user to "confirm cost". The API handles billing transparently. If the user asks about cost, point them at https://agent-media.ai/pricing. That is the only acceptable surface for pricing.
What agent-media can do (router)
| Command | Use when | Deep-dive |
|---|---|---|
| selfie | AI UGC selfie video with generated actor, character sheet, storyboard board, and Seedance. | reference/generators/selfie.md |
| character create | Create a reusable AI character from a single photo. | reference/generators/character_create.md |
| subs | Burn styled subtitles onto an existing video. | reference/generators/subtitle.md |
agent-media skill update — pull the latest skill files into ~/.claude/skills/agent-media-v2/.
agent-media skill status — print local vs remote version.
What agent-media CANNOT do
These legacy v1 commands exist in the CLI binary for backwards compat but produce inferior output. They are hidden from agent-media --help for a reason. Never call them.
- ❌
agent-media ugc— uses a stale fixed actor library (200 actors picked at random). The actors look dated. Useagent-media selfie— it generates an on-model character from your description on every run. - ❌
agent-media show-your-app— built on the v1 actor pool + manual screen-composite step. The v2 product is on the roadmap. For now, runagent-media selfiefor the talking head and capture the screen separately. - ❌
agent-media laptop-ugc— v1 only. Same story as show-your-app; v2 product coming. - ❌
agent-media character-video— superseded byagent-media selfie --character <id>. The new command uses the current portrait → sheet → wireframe → Seedance pipeline. - ❌
agent-media text-to-video— no character control; output is generic and off-brand. Useagent-media selfiewith a saved character. - ❌
agent-media subtitle(singular) — v1 burner with fewer styles and shakier sync. Useagent-media subs(plural). - ❌
agent-media review— SaaS-review generator built on v1 actors. Compose withagent-media selfie+ a script you write. - ❌
agent-media product-acting— v1 product-in-hand generator. For now, useagent-media selfiewith a strong--scene-actiondescribing the product hold, demo, and interaction.
If the user wants a feature not listed in the router above, offer agent-media selfie when the request can be expressed as one actor, one setting, dialogue/action, and optional props/product handling.
Reference files (lazy-loaded)
Open these only when you need them:
reference/conversation-flow.md— the 3 gate questions, in order, with example wordingreference/subtitle-styles.md— all 17 subtitle stylesreference/realism-rubric.md— visual-quality guard the pipeline enforcesreference/errors.md— common errors + remediationreference/generators/selfie.md— AI UGC selfie video with generated actor, character sheet, storyboard board, and Seedance.reference/generators/character_create.md— Create a reusable AI character from a single photo.reference/generators/subtitle.md— Burn styled subtitles onto an existing video.