Topview

View saved version →

---
name: canvas-agent-workflows
description: Use when the user explicitly requests Topview Canvas creation or accepts a Canvas recommendation for timelines, reusable scene assets, storyboards, whiteboards or 3D workflows. Preserve narrative coverage and continuity. Ordinary image and video requests use direct-creation.
---

# Canvas Agent Workflows

Achieve a complete Canvas creation goal in one agent task. Business rules live here; atomic MCP writes live in `$operate-topview-canvas`.

### Plugin version / upgrade

When the user asks whether the Topview plugin is up to date, which version is installed, or asks to upgrade/reinstall the plugin, call `topview_check_plugin_update` first. Use its returned `downloadUrl` and host-specific `upgradePrompt` verbatim — never invent a CloudFront URL or substitute a host marketplace command. After a successful upgrade, call `topview_ack_plugin_update` with `action=upgraded`; if the user declines, call it with `action=dismissed`.

## Canvas-first creative gate

This gate applies only after the user explicitly requests Canvas or accepts the recommendation to use it. Ordinary image/video generation and image editing use `$direct-creation` without creating a Canvas.

1. Resolve the target Canvas, or create one when the user asks for a new project. If no target is known and multiple existing projects plausibly match, let the user choose.
2. Obtain `get_topview_canvas_web_link` and open its official browser link, or return that link when host navigation is unavailable. Board and Canvas management use the existing website. Legacy embed tools remain compatible but are not the default delivery path.
3. Only after the Canvas is visible, create nodes, submit Canvas-owned image/video/music work, or open the whiteboard / 3D surface. Keep the project visible throughout so the user can inspect, select, rearrange, edit, or use **Use in chat** while the Agent continues.
4. If the matching Canvas is already visibly open in the current flow, reuse it and do not create a duplicate UI result.

For an accepted Canvas workflow, keep dependent generation attached to that Canvas. The cross-shot narration exception remains `topview_generate_voice` because Canvas currently has no TTS capability; import its result back into the selected Canvas.

## Skill boundaries

| Skill | Owns |
| --- | --- |
| `$operate-topview-canvas` | MCP tools, V2 generation contract, paid generation approval mode (`confirm_each_submit` / `autonomous`), observational revision, layout, Group composition, local-media bridge, capability-first + universal duration planning, Timeline, auth |
| `$canvas-agent-workflows` | Workflow routing, orchestration runtime, workflow-specific single-task gates, Scene creative contract, typed references, quality gates, DAG completion |
| `$direct-creation` | Ordinary standalone image/video generation and image editing, delivered in chat and archived to Board |
| `$marketing-studio` | Research / marketing data stages that may precede a Canvas workflow |

## Progressive reads

**Mandatory before planning:**

1. [references/workflow-routing.md](references/workflow-routing.md) — lock the Original Goal Contract, then pick exactly one primary workflow.
2. [references/generation-stage-machine.md](references/generation-stage-machine.md) — Plan Ledger, Safe Parallel Policy, recovery (no Canvas revision cursor).
3. The selected file under [references/workflows/](references/workflows/).

**Conditional (read only when the stage needs it):**

- `$operate-topview-canvas` `references/generation-planning.md` + [references/duration-and-task-assembly.md](references/duration-and-task-assembly.md) — before freezing paid task counts / duration splits.
- `$operate-topview-canvas` `references/seedance-2.5.md` — when the selected exact live video model is Seedance 2.5; lock `auto` / `edit` / `extend` intent before prompt authoring or submits.
- [references/reference-resolution.md](references/reference-resolution.md) — before any cons

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 19 — file references are metadata, not package contents.

View saved version →

---
name: direct-creation
description: Use when the user wants to create an image, edit an image, or generate a video in the conversation, without explicitly requesting a Canvas. Deliver the result card and save the creation context in a personal Board.
---

# Direct image and video creation

Ordinary image/video requests use standalone creation tasks. No Canvas, project
selection, or Board selection is required. The server assigns the personal
Codex Creations Board across conversations. Only send boardId when the user
explicitly chooses another Board.

1. Preserve the requested deliverable and verbatim prompts when requested.
2. Discover current model configuration with topview_get_generation_config. Use
   the model ID and supported ratio, resolution, duration and reference inputs.
   Do not invent support or silently switch to a text-only task when references
   are required. This creation contract currently supports text_to_image,
   image_edit, text_to_video and image_to_video.
3. Resolve reference media to authorized durable Topview references. Do not submit
   local file paths, guessed IDs or expiring preview links. If import is needed,
   call topview_prepare_creation_upload, PUT the file bytes to its uploadUrl, then use its storageKey with topview_import_board_asset. For image references, pass that storageKey as inputImageS3Path. The server rejects arbitrary storage paths. Do not use the general OpenAPI upload endpoint for this scoped upload contract.
4. Call topview_quote_creation. The quote is authoritative for current credits,
   free generation count and shortfall. It creates no generation or Canvas.
5. If canSubmit is false, show requiredCredits, availableCredits and
   shortfallCredits, with the returned nontransactional entitlement information
   link. Do not substitute checkout, purchase or upgrade URLs. Offer changes to
   specifications only as options; never silently reduce the user's request.
6. Submit with topview_submit_creation when the concrete quoted scope is
   authorized. Respect an already approved budget; ask only when the quote
   exceeds it or payment scope is unresolved. Reuse the same idempotencyKey for
   transport retries. Never manufacture a new key to bypass an uncertain result.
7. Poll topview_show_creation using creationId. Preserve every batch item,
   including failures and uncertain submissions. Show the native result card;
   a one-output result needs no batch selector.
8. Report completion only for confirmed successful outputs. The card provides
   Recreate, Download and Open in Topview. Recreate requests a fresh quote and
   creates a new version; it does not overwrite the original.

Save only creation prompts, parameters, references and result relationships.
Never upload the entire conversation. Filenames and Board bindings are assigned
by the server; do not invent or reserve them through model text.

## Mixed and multi-prompt batches

For several deliverables with different prompts, including mixed images and
videos, call topview_quote_creation_batch with one item per independently
specified prompt/type/model. A batch supports up to 12 items; split larger
requests into bounded batches without dropping any item. Use count only for
multiple variations of the same prompt and settings.

Review every returned quote and its credit requirement. Shared credits and free
allowances are not reserved by quotes; do not promise that free quota applies
independently to every item. Submit the approved quotes using
topview_submit_creation_batch, retaining each quoteId/idempotencyKey pair.
A transport error or submission_unknown is not proof of failure: retry only the
same pair, never manufacture replacement quotes or keys. Report quote changes,
shortfalls and failures per item; no automatic paid upgrade or replacement.

Deliver all creation IDs together through topview_show_creations, including
pending and failed creations. This read-only tool returns a mixed inline gallery
with every result, pro

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: marketing-studio
description: Plan and execute Topview Marketing Studio workflows for ecommerce market research, product analysis, listing and content optimization, TikTok Shop operations, Amazon operations, Shopee operations, YouTube or Instagram creator discovery, audience analysis, outreach, and campaign reporting. Use when a user asks for a marketing strategy, platform-specific research, creator campaign, content plan, product selection, trend analysis, or an operational review.
---

# Marketing Studio

Route each request to the smallest relevant bundled playbook, verify data and tool availability, and produce an evidence-backed marketing deliverable.

### Skill feedback

If this task used Topview MCP tools, immediately before the final user reply follow the installed Topview plugin's shared `references/skill-feedback.md` once with `skillName="marketing-studio"`. Diagnose whether this Skill or its Topview MCP contract should improve using the current task context; this is best-effort guidance, never a blocking Hook.

### Plugin version / upgrade

When the user asks whether the Topview plugin is up to date, which version is installed, or asks to upgrade/reinstall the plugin, call `topview_check_plugin_update` first. Use its returned `downloadUrl` and host-specific `upgradePrompt` verbatim — never invent a CloudFront URL or substitute a host marketplace command. After a successful upgrade, call `topview_ack_plugin_update` with `action=upgraded`; if the user declines, call it with `action=dismissed`.

## Workflow

1. Identify the platform, market, objective, time window, product or category, and requested output.
2. Run `python3 scripts/search_catalog.py "<request>"` from this skill directory, or inspect [references/catalog.md](references/catalog.md), to select at most three matching playbooks.
3. Read [references/compatibility.md](references/compatibility.md), then read only the domain reference returned by the catalog:
   - [references/ecommerce.md](references/ecommerce.md) for shared routing, reviews, and durable outputs.
   - [references/amazon.md](references/amazon.md) for Amazon research and optimization.
   - [references/tiktok-shop.md](references/tiktok-shop.md) for TikTok Shop research, content, affiliate, ads, and live operations.
   - [references/influencer.md](references/influencer.md) for YouTube and Instagram creator workflows.
   - [references/shopee.md](references/shopee.md) for Shopee market, product, shop, brand, and keyword analysis.
4. Check whether the required data source exists among the tools exposed by the unified `topview` MCP. Use a matching Topview tool when available. Otherwise use user-provided exports or authoritative public sources, state the limitation, and never fabricate private platform metrics.
5. Separate evidence, inference, and recommendation. Include source dates, market or region, currency, units, and material exclusions. Do not convert missing evidence into a precise score.
6. Produce the requested deliverable. Prefer a compact table for comparisons and an owner, date, and action list for operational plans.
7. Obtain explicit user approval before publishing content, spending money, contacting creators, generating paid media, or changing external state.

## Routing rules

- Prefer one platform-specific playbook plus one shared playbook. Do not load every reference.
- Ask for a product or category, region, and date window only when their absence would materially change the result.
- Treat Amazon, TikTok Shop, Shopee, YouTube, and Instagram as distinct data contracts; do not silently substitute one platform's evidence for another.
- Use uploaded private reports before public estimates when the user asks about their own store, ads, inventory, costs, or conversion.
- Do not expose Marketing Studio internal credentials, environment paths, release metadata, or private workspace data.

## Source status

This development bundle contains 29 Topview-authored repository playbooks. It i

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 11 — file references are metadata, not package contents.

View saved version →

---
name: operate-topview-canvas
description: List, create, open, and manage Topview Canvas projects; place nodes with an orderly layout protocol; run Canvas-owned generation via capabilities → V2 submit → refresh; assemble and export Timeline videos through the unified remote Topview MCP.
---

# Operate Topview Canvas

Use the plugin's `topview` MCP server as the Canvas data and action boundary. It is the same remote MCP connection used by other Topview skills.

Apply this skill only when Canvas was explicitly requested or its recommendation
accepted. Ordinary image/video creation and image editing use `$direct-creation`.
For this release, open the official link from `get_topview_canvas_web_link` in
the browser. This browser default supersedes the legacy host-specific embedded
opening rules below; those tools remain available for compatibility.

### Skill feedback

If this task used Topview MCP tools, immediately before the final user reply follow the installed Topview plugin's shared `references/skill-feedback.md` once with `skillName="operate-topview-canvas"`. Diagnose whether this Skill or its Topview MCP contract should improve using the current task context; this is best-effort guidance, never a blocking Hook.

### Plugin version / upgrade

When the user asks whether the Topview plugin is up to date, which version is installed, or asks to upgrade/reinstall the plugin, call `topview_check_plugin_update` first. Use its returned `downloadUrl` and host-specific `upgradePrompt` verbatim — never invent a CloudFront URL or substitute a host marketplace command. After a successful upgrade, call `topview_ack_plugin_update` with `action=upgraded`; if the user declines an upgrade prompt, call it with `action=dismissed`.

For multi-stage Canvas creation workflows (replication, ecommerce, short film, social, element editing, research→generate), use `$canvas-agent-workflows` on top of this skill. This skill stays the atomic MCP / V2 / layout / Timeline contract (no Agent-facing Canvas revision CAS).

Contract reference for parameters and text envelopes: [`references/canvas-mcp-api.md`](references/canvas-mcp-api.md).  
Layout algorithms and default sizes: [`references/node-layout.md`](references/node-layout.md).  
Generic Group composition: [`references/node-groups.md`](references/node-groups.md).  
Capability-first planning and universal duration splits: [`references/generation-planning.md`](references/generation-planning.md).  
Seedance 2.5 task-mode and prompt contract: [`references/seedance-2.5.md`](references/seedance-2.5.md).
Local files → durable upload sources: [`references/local-media-bridge.md`](references/local-media-bridge.md).

## Calling principles

1. **Read text first**: success and business-failure fields are in `content[0].text`. Use `structuredContent` when present. Business failures often set `isError=true` while HTTP stays 200.
2. **Observational revision only**: successful Canvas responses may include `revision` for observability. Do **not** send `expectedRevision` on node mutations, generation submit, or generation refresh. Do **not** chain revisions, keep a revision cursor, or take `max(revision)` after a parallel wave for the next write. Do **not** call `get_topview_canvas_state` solely to obtain a revision. Do **not** request `fields=["revision"]` — `revision` is always present on the state root when returned and is **not** a filterable field. Do **not** claim `sinceRevision` exists. Do **not** teach Canvas `REVISION_CONFLICT` recovery via fresh `expectedRevision` (Timeline ETag conflict is separate — see Timeline).
3. **Safe Parallel Policy** (same Agent turn; **wait-all** before the next turn): prefer parallel only when **all** hold — (a) same DAG layer and no reading peer outputs (`nodeId` / `taskId` / `mediaRef` / `shortCode`) from this wave; (b) distinct targets / `parentId` / `sceneNodeId` / tasks — **never** same-target concurrent writes; (c) distinct `commandId` per paid intent, params frozen from capa

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 8 — file references are metadata, not package contents.