ui2v Skill

UI2V 是面向 AI 工作流的 视频动效资源库。它帮助用户发现、安装、复用和分享 HyperFrames 动效包；实际的视频创作、预览和渲染由 HyperFrames 完成。

For project positioning, README copy, npm copy, website copy, or launch/promo text, read references/positioning.md.

Mental model

HyperFrames authoring -> package folder -> ui2v login -> ui2v motion publish -> ui2v.com

Layer	Tool
Author / preview / render	HyperFrames (/hyperframes and related skills)
Search / install / publish / sync	ui2v CLI (npm package @ui2v/cli, bin ui2v)

Do not use the abandoned @ui2v/cli@1.x JSON render/preview stack (doctor, validate, preview, render, animation.json, @ui2v/core, @ui2v/engine, @ui2v/producer). The current @ui2v/cli package is the registry client.

Task routing

Use this skill for registry work and CLI/package maintenance:

• Publish/share/install/search a motion on ui2v.com → use this skill and the ui2v CLI.
• Fix or extend the UI2V CLI → inspect packages/ui2v/src/cli, update focused tests, then run the repo verification commands below.
• Fix registry package metadata or a publish failure → read references/package-format.md and references/publish.md.
• Update website, README, npm, or promo copy → read references/positioning.md; keep package references as npm @ui2v/cli, bin command ui2v, and npx command npx @ui2v/cli@latest ....
• Clean project structure → read references/cleanup.md; remove or route away from legacy JSON renderer examples/scripts; do not present them as current UI2V capabilities.
• Prepare or explain a release → read references/release.md; verify versions, tests, build, and npm copy.

Route away from this skill when the user is not doing registry work:

• Make / edit / preview / render a video composition → use HyperFrames skills, not this CLI.
• Old JSON ui2v projects → do not revive the old JSON toolchain. Migrate to a HyperFrames package, then publish with ui2v.

CLI version gate

Before publish/install/sync that depends on current CLI behavior:

ui2v --cli-version
npm view @ui2v/cli version

• Missing CLI → install: npm install -g @ui2v/cli@latest (or bun install -g @ui2v/cli)
• Behind latest → ui2v upgrade (alias self-update), or npm install -g @ui2v/cli@latest
• Under --no-input, ui2v upgrade only prints the install command and exits non-zero when outdated

npm view is metadata only. Do not upgrade as a routine first step unless the CLI is missing, too old for the task, broken, or the user asks for latest.

From this monorepo before publishing:

cd packages/ui2v && bun run build && node bin/ui2v.js --cli-version

Monorepo development workflow

For CLI source changes in this repository:

bun install
bun run build
bun run test
bun run --filter "@ui2v/cli" verify
node packages/ui2v/bin/ui2v.js --help
node packages/ui2v/bin/ui2v.js --cli-version

Prefer the narrowest useful test first while iterating:

cd packages/ui2v
bun run test:src
bun run verify:build
bun run test:artifact

Package shape

A motion folder must include:

• registry-item.json with type: "hyperframes:block"
• Entry composition HTML (index.html or listed composition file)
• Optional assets/, README.md, thumbnail

Details: references/package-format.md.

Positioning

When introducing the project, use this core message:

让 AI 帮你发现、安装和分享 UI2V 视频动效资源：
搜索并安装现成动效，发布原创作品，让动画像依赖一样轻松复用。

Do not call UI2V a renderer. Keep the boundary crisp:

• HyperFrames creates, previews, and renders motion.
• UI2V distributes completed motion packages through search, install, publish, sync, and inspect workflows.

Publish flow

ui2v login
ui2v motion publish ./my-motion --version 1.0.0
# optional: ui2v sync

Aliases: ui2v skill publish, legacy ui2v publish.

Full checklist: references/publish.md.

Release flow

For npm release preparation, use references/release.md. Do not publish or bump versions casually; first confirm the requested version and run local verification.

Common registry commands

ui2v search "logo sting"
ui2v install <slug>
ui2v list
ui2v update --all
ui2v explore
ui2v inspect <slug>
ui2v upgrade

Install command shown on the site: npx @ui2v/cli@latest install <slug>.

Troubleshooting cookbook

• CLI not found → install @ui2v/cli, then confirm ui2v --cli-version.
• Outdated CLI → run ui2v upgrade or npm install -g @ui2v/cli@latest.
• Auth failure → run ui2v login; for automation use ui2v login --token clh_... only when the user provides a token.
• Publish rejects version → ensure --version is valid semver and is newer than the published release.
• Missing entry HTML → check index.html, first files[] composition path, or {name}.html.
• Manifest validation failure → check type: "hyperframes:block", dimensions, duration, and files[] using references/package-format.md.
• Render/preview request appears → stop using UI2V commands and route to HyperFrames.