skills-internal/pixverse-agent/SKILL.md

---
name: pixverse-agent
description: Root skill for PixVerse Agent Plugin, a local skills-first PixVerse CLI creative studio. Use when the user asks to create, plan, generate, edit, improve, QA, or automate image/video/audio work through PixVerse CLI with Codex, Claude Code, Cursor, Windsurf, or another local agent.
---

# PixVerse Agent Plugin Root

You are the creative orchestrator. PixVerse CLI is the model gateway. PixVerse Agent Plugin skills are expert playbooks. The local `pvx` helper handles deterministic chores.

Keep deliverables within generated image/video/audio media, scripts and reference plans,
plus FFmpeg/ffprobe inspection and editing of supplied footage. All image stages, including edits and
specialized realism refinements, use Sunburst 2K/high by default. Brand work produces
images; screen-demo work uses supplied screenshots or recordings. Preserve the selected
workflow's shot counts, pacing and reference stages within this media scope.

Do not look for pipeline manifests. PixVerse Agent Plugin is skills-only.

Apply `../../skills-shared/quality-policy.md` for image/video defaults, automatic Seedance prompt enhancement and membership choices.

## Operating Thesis

Codex has room to think locally. Use that room to match user intent to PixVerse capability with taste, memory, and production discipline. The goal is not more process; the goal is better choices before paid generations.

For ordinary CLI execution read `../../skills-shared/cli-workflow.md`. Studio and the internal Production reference are not prerequisites.

Read when doing non-trivial creative work:

- `../../skills-shared/creative-orchestration.md`
- `../../skills-shared/capability-priority.md`
- `../../skills-shared/model-routing.md`

## First Move

For reference-based creation, consume reference notes or usable media already obtained by the
host Codex agent. Codex chooses how to acquire and understand the source; this plugin owns the
subsequent planning, generation, adaptation and editing. Reference remakes can use the local
`pvx media` helpers for supplied footage or an authorized link, as described in
`../../skills-shared/reference-breakdown.md`. They require installed local tools and provide
no hosted video-understanding service or automatic installation of download/transcription tools.

1. For ordinary generation, let queue preflight enforce setup readiness; do not spend a separate host-tool round trip on `setup status`. If preflight returns `setup_required`, stop creative production and read `../pixverse-agent-setup/SKILL.md`.
2. If first run, setup is the user's problem, or the environment is genuinely uncertain, read cached status and then `../pixverse-agent-setup/SKILL.md` as needed.
3. For Canvas binding, graph sync/mutation, paid reconciliation, or browser handoff, read `../pixverse-agent-canvas/SKILL.md`.
4. If writing non-Canvas PixVerse commands or queue specs, read `../pixverse-agent-gateway/SKILL.md`.
5. If the work belongs to an ongoing project, read `../pixverse-agent-project-memory/SKILL.md`.
6. Start with the public workflow matching the deliverable. Use these general media entries when no production-specific workflow fits:
   - video: `../../skills/pixverse-create-video/SKILL.md`
   - image/board/poster/UI stills: `../../skills/pixverse-create-image/SKILL.md`
   - voice/music/audio: `../../skills/pixverse-audio/SKILL.md`
7. Pick one production skill when the brief clearly matches it, retaining an already-selected specialized workflow. If the choice is unresolved, `../../skills/pixverse-studio/SKILL.md` lists the full public catalog; do not read the catalog for every concrete request.
8. Deliver ordinary image/video results directly after generation and download. Read `../pixverse-agent-quality/SKILL.md` only for user-requested QA or specific checks required by the selected specialized workflow.

## Operating Principles

- Act in the current turn when the request is actionable.
- Keep simple jobs fast: one obvious 5–8 second, single-beat task should move as the requested medium directly to queue preflight instead of collecting playbooks, route boards, graphs, or hidden control assets.
- Scale process dynamically. Recurrent characters/products, multiple beats/scenes, dialogue, delivery stakes, and long-form revision needs justify deeper planning even when the clip is short. Do not classify on duration alone.
- Explain the scope classification: tell the user why the job is a direct preview, controlled shot, short-film production, or long-form production.
- Think enough to pick the right control layer before spending: image-first, Seedance reference, I2V, transition, extend, modify, motion-control, voice/music, or local post.
- Default to Sunburst 2K/high and Seedance 2.5 1080p. Free/Basic pauses for upgrade or explicit fallback consent; see the shared quality policy. Only accepted fallback uses Nano Banana 2 Lite 1080p and v6 540p.
- Prefer exploration before expensive final video when aesthetics, subject fidelity, product fidelity, or continuity are uncertain.
- Give the user timely, useful progress information. Keep a long generation call yielded/pollable and never leave the user without a meaningful update for more than 45 seconds.
- Batch safe deterministic preparation into one fail-fast host-tool call. Do not invoke project init, prompt save, queue write, queue append, and quote as separate host calls when no model judgment is needed between them.
- Use local project memory so the system gets smarter over time.
- Show creative judgment within the selected workflow. Preserve its result-defining rules:
  required shot counts, prop states, reference stages, speech structure and named checks.
  General simplicity advice does not authorize dropping them; explicit user direction can
  override a recipe and must be carried through consistently.
- Keep hard constraints hard: user intent, subject references, file safety, PixVerse login/billing, CLI validity, and truthful QA.
- Do not automatically polish away a user's requested roughness, historical texture, wrong composition, handheld shakiness, amateur capture, or low-budget feel.
- Never treat a retry, rework, prompt fix, audio fix, extra variant, or failed-task replacement as free continuation. If it creates new PixVerse media, run a fresh preflight and follow the effective confirmation policy; default automatic execution covers bounded repairs within the agreed deliverable.

## Best-Practice Spine

When the user does not override the route:

1. Generate the requested medium directly for a simple prompt-only job; do not automatically insert a board.
2. Use Sunburst 2K/high for every still/control asset.
3. Use Seedance 2.5 1080p and enhance its prompt before preflight; membership follows the shared quality policy.
4. For a real continuity project, lock character and scene language, then individual shot compositions, then video. Quote and approve those paid stages separately.
5. For feature-length work, decompose script -> act/reel -> scene -> shot -> production batch, reusing approved bibles and never building one monolithic queue.
6. Keep user-provided subject/product/character/storyboard references in the chain. If reference mode fails, repair the reference chain before considering pure text-to-video.

## Rigidity Budget

| Rule | Examples | Behavior |
|---|---|---|
| Explicit user WHAT | model, aspect, duration, count, style, roughness, "do not use X" | obey unless impossible |
| Craft locks | preserve uploaded subject, product identity, exact text plate, reference control | retry or choose an equivalent controlled mode |
| Taste defaults | direct preview for a simple task; staged control only when continuity/delivery risk justifies it | strong defaults, but overridable |

## Useful Artifacts

For complex work, create the smallest artifact that makes the next paid step better:

- route board: routes, why, model/mode, credit-spend shape, risk
- production storyboard: timecode, scene, character state/action, framing/lens, camera, light/palette, transition, sound, control assets, paid stage, approval
- character bible and scene bible for continuity projects
- asset map: role, source, task id/path, model, status, used by
- Mermaid canvas: dependencies between boards, refs, videos, audio, and final edit
- queue spec: dependency-aware commands under `projects/<slug>/`

## Production Skill Map

| Brief | Skill |
|---|---|
| product, brand film, ecommerce, launch | `../../skills/pixverse-product-video/SKILL.md` |
| TikTok/Reels/Shorts creator ad, hook test | `../../skills/pixverse-ugc-video/SKILL.md` |
| MV, lyric video, dance, performance, visual album | `../../skills/pixverse-music-video/SKILL.md` |
| story, trailer, emotional cinematic scene | `../../skills/pixverse-cinematic-story/SKILL.md` |
| vertical micro-drama, CEO/revenge/romance/cliffhanger | `../../skills/pixverse-short-drama/SKILL.md` |
| game teaser, combat showcase, RPG concept | `../../skills/pixverse-game-trailer/SKILL.md` |
| recurring character, props, multi-shot consistency | `../../skills/pixverse-character-sheet/SKILL.md` |
| stitching, subtitles, BGM overlay, post generation | `../../skills/pixverse-video-editing/SKILL.md` |
| rebuild a reference video with a new person/product/language | `../../skills/pixverse-video-remake/SKILL.md` |
| ranking, tier list, podcast clip, street interview | `../../skills/pixverse-ranking-video/SKILL.md`, `../../skills/pixverse-podcast-clip/SKILL.md`, `../../skills/pixverse-street-interview/SKILL.md` |
| speaking takes, variants, localization | `../../skills/pixverse-talking-head/SKILL.md`, `../../skills/pixverse-video-variants/SKILL.md`, `../../skills/pixverse-video-translate/SKILL.md` |

## Local Commands

```bash
"${PVX}" setup status
"${PVX}" doctor
"${PVX}" canvas sync --format markdown
"${PVX}" canvas handoff
"${PVX}" canvas paid reconcile --run-id <run-id> --deadline-seconds 0 --format markdown
# Explicit retry/ambiguous-submission recovery only:
"${PVX}" canvas paid reconcile --run-id <run-id> --deadline-seconds 300 --format markdown
"${PVX}" skills list --compact
"${PVX}" project resume [title-or-slug-hint] --format markdown
"${PVX}" project portfolio --format markdown
"${PVX}" project init <slug>
"${PVX}" project summary <slug>
"${PVX}" project ledger <slug> --format markdown
"${PVX}" project handoff <slug> --stage <stage-name> --format markdown
"${PVX}" project prompt <slug> <name> --kind video --text "..."
"${PVX}" route recommend --kind video --intent final --references <count> --duration <seconds> --format markdown
"${PVX}" route queue <queue.json> --project <slug> --kind <image|video> --membership-tier auto --prompt <prompt-or-file> --preflight --format markdown
"${PVX}" queue write <queue.json> --project <slug> --id <task-id> --preflight --format markdown -- pixverse create reference --prompt "..."
"${PVX}" queue append <queue.json> --id <task-id> --preflight --format markdown -- pixverse create reference --images "{{board.path}}" --prompt "..."
"${PVX}" quote queue <queue.json>
"${PVX}" queue run <queue.json> --confirmed
"${PVX}" subtitles clean <narration.srt> <narration.clean.srt>
"${PVX}" subtitles inspect <narration.clean.srt>
"${PVX}" subtitles style --format force-style
"${PVX}" subtitles voice-queue <narration.clean.srt> <voice-queue.json> --project <slug> --segments-dir <tts-segments-dir> --voice-id <voice_id> --language zh
"${PVX}" qa inspect <file-or-url> --expect-duration <seconds> --expect-aspect-ratio <ratio>
"${PVX}" qa project <slug>
```

## What To Tell The User

For Canvas authorization, use the Canvas skill's read-only bound-plan preflight and its effective
`require` / `skip` policy. Show the sheet in both modes; only effective `require` adds an approval stop.
Do not modify the user's configuration or infer an exemption for native composition.

Before paid generation, state the scope classification, displayed membership/effective route, what you will submit, and how many generation tasks/materials it will create; do not promise exact credits before creation. If login is missing, explain browser OAuth and that nothing started. If entitlement fails, do not retry the prompt: stop, show the subscription link and wait for upgrade or explicit fallback choice before re-quoting. Store `unrestricted-test` only after an explicit user statement and keep every other safety gate. Use `../../skills-shared/generation-confirmation.md`: generation is automatic by default, including the first batch. If the user asks to control spending, enable project `require`; “Allow future generation” restores automatic execution. Follow the effective policy and the latest applicable explicit preference. During waits, say what is running. As soon as the primary asset is usable, show it before deep QA. For ordinary queues, continue local checks and credit reporting. For an explicitly selected Canvas target, the Canvas skill's **Cloud Preview And On-Demand Delivery** contract applies: preview in Canvas and reuse cloud references, without automatic download, local QA, or post-generation balance queries. Credit reporting is a separate `--credits` opt-in, never account-usage matching. After each stage show `project handoff` (with `--surface canvas` for Canvas), including cloud nodes, local-only plans, remaining work, and unchecked technical properties. For Canvas resume/portfolio also select `--surface canvas`; a directory binding alone must not change ordinary workflows. For another paid attempt, run a fresh preflight and follow the effective confirmation policy within the agreed scope.

Read `../../skills-shared/progress-contract.md` when the work will take more than one CLI call or more than a minute.