Agent Media V2

agent-media, Claude skill

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.

Not on the CLI? Use the connector instead

This skill drives the local agent-media CLI. If the CLI is not installed, or you are Claude on the web, where you cannot run shell commands, connect over the hosted MCP connector instead: one URL, browser sign-in, no API key.

https://api.agent-media.ai/mcp

Claude (web or desktop): Settings → Connectors → Add custom connector. Claude Code: claude mcp add --transport http agent-media https://api.agent-media.ai/mcp. Full guide: https://agent-media.ai/connect. Over MCP the surface is different from the CLI: the connector lists generate_video, generate_image, generate_audio, quote, list_models, list_characters, get_run_status, upload_image and rate_run: you write the prompt, pick the model and the video mode (text, image-to-video with first_frame, reference with refs / video_refs / audio_refs) yourself (see the public skill at public-skill/skills/agent-media/SKILL.md). After submitting you MUST call get_run_status to get the finished URL.

🛑 HARD GATE, read this first, every conversation

Before calling ANY agent-media shell command, you MUST:

1. Read reference/conversation-flow.md, the full 4-gate protocol with templates.
2. Walk the user through 4 gates IN ORDER, one message each, do not bulk-fire:
   • Gate 1: confirm duration first with script-pacing guidance (2-4 words/sec). Propose a fit: 5s ≈ 10-20 words, 10s ≈ 20-40 words, 15s ≈ 30-60 words.
   • Gate 2: confirm the exact script (verbatim, typos land in the video), or confirm scene_action + --background-music when there is no speech.
   • Gate 3: 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 by char_xxx id, that format is internal). The user picks by NAME or says "new"; you map name → id internally. 🛑 NEVER auto-pick. NEVER show char_xxx ids to the user. Never ask for a photo by default.
   • Gate 4: 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 --description and action/product handling into --scene-action. The shot composition and energy are inferred from the brief; you can OPTIONALLY pin them with --shot-preset and --vibe, or override the realism defaults with --camera-locked / --phone-in-frame / --polish (rare, only when the user explicitly asks for a stable shot, a phone-in-hand composition, or a different polish look).
3. Only then call the CLI.

The director's brief at Gate 4 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 to 3 is a protocol violation, the user gets a generic, mid video. Ask the extra questions.

Choosing the video engine

Both selfie and crazy-look take an engine: seedance-2.0 (DEFAULT) or seedance-2.5. Leave it alone unless the user asks for the newest or sharpest model, 2.5 is a premium tier, so it is opt-in, never your default choice. Do not raise it unprompted, and do not discuss what either tier costs (see below).

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)

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. Use agent-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, run agent-media selfie for 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 by agent-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. Use agent-media selfie with a saved character.
• ❌ agent-media subtitle (singular), v1 burner with fewer styles and shakier sync. Use agent-media subs (plural).
• ❌ agent-media review, SaaS-review generator built on v1 actors. Compose with agent-media selfie + a script you write.
• ❌ agent-media product-acting, v1 product-in-hand generator. For now, use agent-media selfie with a strong --scene-action describing 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 4 gate questions, in order, with example wording
• reference/subtitle-styles.md, all 17 subtitle styles
• reference/realism-rubric.md, visual-quality guard the pipeline enforces
• reference/errors.md, common errors + remediation
• reference/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.
• reference/generators/crazy_look.md, Silent extreme close-up reaction clip with a static caption overlay ("the crazy look").