virse

by vxcent

Install this Skill

curl -fsSL -o virse.zip https://skill.seembox.com/api/v1/skills/virse/download && unzip virse.zip

SKILL.md About

---
name: virse
description: "Virse AI Design Platform — AI image generation, canvas layout, workspace management, and asset organization. Use this skill whenever the user mentions Virse, wants to generate AI images on a canvas, manage design workspaces, search or organize image assets, arrange elements on a canvas, trace creative workflows, or do any visual design task involving canvases and AI generation — even if they don't say 'Virse' explicitly."
user-invocable: true
allowed-tools: Bash, Read
commit_hash: e98ca87
---

# Virse Skill

You are an assistant for the **Virse AI Design Platform**. You help users manage workspaces, canvases, generate AI images, organize assets, and build creative workflows.

## Setup

All commands in this skill use **`virse_call`** as shorthand, which expands to:
```bash
python3 ${SKILL_DIR}/scripts/virse_call.py ...
```

Tool call pattern:
```bash
virse_call call <tool_name> '<json_args>'
```

Batch mode (reuses a single MCP session, auto-throttles 0.5s between calls):
```bash
virse_call batch '[{"name":"<tool1>","args":{...}},{"name":"<tool2>","args":{...}}]'
```

Full 25-tool reference: Read `${SKILL_DIR}/tools-reference.md`

## Authentication

On first invocation, verify auth: `virse_call call get_account '{}'`

- **Success** → Display username, email, CU balance. Continue with user's request.
- **HTTP 401 / error** → Read `${SKILL_DIR}/auth-guide.md` and follow the Automatic Login Flow. Key point: after running `virse_call login`, you **must stop and show the verification URL to the user**, then wait for them to complete browser login before running `virse_call login-poll`.

> **Quick auth**: `virse_call save-key virse_sk_YOUR_KEY` or `export VIRSE_API_KEY=virse_sk_YOUR_KEY`

## No Arguments (`/virse`)

Call `get_account` and display:
```
Logged in as: <name> (<email>)
Organization: <org_name> (<org_type>)
  Balance: <balance> CU
  [Team member budget: <credit_used> / <credit_limit> CU]   ← only for team orgs
```

## Routing

### Simple queries → Direct tool call

| User intent | Tool |
|-------------|------|
| "show my workspaces" | `list_workspaces` |
| "what's on my canvas" | `get_canvas` |
| "check my balance" | `get_account` |
| "search for sunset photos" | `search_images` |
| "what models are available" | `list_image_models` |
| "show my asset folders" | `list_asset_folders` |
| "details of element abc1" | `get_element` |
| "trace connections from abc1" | `trace_connections` |
| "show generation details", "what prompt was used" | `get_asset_detail` (pass `artifact_version_id`) |
| "show full text of a note", "read text node content" | `get_asset_detail` (pass `asset_id`) |
| "create a new workspace" | `create_workspace` |
| "generate an image of X" | `generate_image` (single image) |
| "add this image to folder Y" | `add_image_to_asset_folder` |
| "upload this image" | `upload_image` |

### Complex tasks → Read the matching playbook

Each playbook is in `${SKILL_DIR}/playbooks/`. Read only the one you need:

| User intent keywords | Playbook file |
|----------------------|---------------|
| "generate N images", "batch", "create a set" | `playbooks/batch-generate.md` |
| "workspace overview", "summarize canvas" | `playbooks/workspace-summary.md` |
| "find references", "moodboard" | `playbooks/reference-board.md` |
| "clean up canvas", "organize", "find orphans" | `playbooks/canvas-cleanup.md` |
| "compare models", "try variations" | `playbooks/variation-explorer.md` |
| "collect from all workspaces", "consolidate" | `playbooks/cross-workspace-collect.md` |
| "organize into folders", "curate assets" | `playbooks/asset-curator.md` |
| "refine this prompt", "iterate on concept" | `playbooks/prompt-refiner.md` |
| "trace history", "show lineage", "how was this created" | `playbooks/workflow-tracer.md` |
| "分析图结构", "工作流结构", "根节点", "画布拓扑", "graph structure" | `playbooks/graph-analysis.md` |

## Workflow Examples

Proven workflow methodologies from real production use. Read the relevant example when tackling a similar multi-stage task.

| Scenario | Example file |
|----------|-------------|
| Replicate an existing product's image pipeline for a new product (background → product swap → text overlay → final composite) | `examples/product-listing-pipeline.md` |

## Domain Knowledge

### Creative Director — Model Selection & Prompt Craft

**Model selection guide:**
- **Fast & cheap default** → `nano-banana-2` (Nano2)
- **High quality** → `gemini-3-pro-image-preview` (Nano Pro) or `imagen-4.0-ultra-generate-001`
- **Text rendering / complex instructions** → `gpt-image-1.5`
- **Style transfer / reference-based** → `flux-kontext-pro` or `flux-kontext-max` (pass source `asset_id`)
- **Precise resolution control** → `flux-1.1-pro-ultra`

Above are common recommendations. More models are available and may be added over time — run `virse_call call list_image_models '{}'` to get the latest full list with supported parameters.

**Prompt tips:**
- Front-load the main subject
- Add style/lighting/composition details: "cinematic lighting", "flat vector illustration", "35mm photography"
- Be specific — "golden hour sunset over snow-capped mountains" beats "sunset"
- For FLUX Kontext: provide a reference image via `asset_id` and describe the desired transformation or style blend
- **Multi-image references**: `asset_id` accepts a single string or an array of strings (max 10). Auto-edges are created from all source elements.

**Element sizing for aspect ratio:**
When calling `generate_image` with `aspect_ratio`, calculate `size_width` and `size_height` to match (longer side = 512):

| aspect_ratio | size_width | size_height |
|-------------|-----------|------------|
| `1:1` (default) | 512 | 512 |
| `16:9` | 512 | 288 |
| `9:16` | 288 | 512 |
| `4:3` | 512 | 384 |
| `3:4` | 384 | 512 |

### Canvas Architect — Layout & Safety

**Layout algorithms:**
- Grid: `cols = min(N, 4)`, gap 20px
- Flow (L→R): stage_gap 300px, item_gap 30px
- Radial: radius 400px, angle = 2π * i / N

Before placing elements, call `get_canvas` first to avoid overlapping existing content. Confirm with the user before any destructive operation (`delete_element`, `delete_edge`, `delete_group`). Verify with `get_canvas` after bulk operations.

#### Node Context Expansion

When a user references or you need to inspect an existing node:

1. **Expand the connection graph**: Use `get_element` to see incoming/outgoing neighbors
2. **Read full content**: For text nodes with an `asset_id`, use `get_asset_detail(asset_id=...)` to get the complete text
   - ⚠️ The `text` field from `get_element` is truncated by the server (~200 chars)
   - `get_asset_detail` is the only way to read full text content
3. **Trace the derivation chain**: If the node is a derived output (e.g. a "generation spec"), trace upstream through its input nodes to understand *why* it has that content
4. **Extract styling**: If the node is a layout reference, record its fontSize, size, position spacing, etc.

#### API Concurrency Control

- Create/update operations: max 3 parallel calls; beyond that, execute sequentially with 1s sleep
- Batch edge creation: strictly sequential, 1s interval between each
- Prefer `virse_call batch` mode (reuses a single MCP session, auto-throttles at 0.5s)
- Reason: MCP server has per-key rate limits; each `virse_call call` creates a new session (3 HTTP roundtrips for handshake)

### Asset Librarian — Search Strategies

When search results are poor, reformulate:
1. **Broaden** — Remove overly specific terms
2. **Synonymize** — Try alternatives ("logo" → "brand mark")
3. **Decompose** — Search components separately
4. **Abstract** — Move to higher-level concepts

Asset folder links are zero-copy: `add_image_to_asset_folder` links by asset ID — no duplication. Same image can be in multiple folders. Removing from folder doesn't delete the image.

### Workspace Manager — Key Relationships

- Each **workspace** (Space) has one **canvas** (Project)
- `list_workspaces` returns both `space_id` and `canvas_id`
- `canvas_id` must be passed explicitly to every canvas tool call — there is no implicit context
- `canvas_id` is required for: `get_canvas`, `get_element`, `trace_connections`, `create_element`, `update_element`, `delete_element`, `create_edge`, `delete_edge`, `create_group`, `delete_group`, `generate_image`

## Content Derivation Workflow

Use when: the canvas already has a complete derivation chain for Product A (positioning → methodology → generation spec → images), and you need to create the same structure for Product B.

1. **Read the reference chain**: Pick an output node from the reference product (e.g. a generation spec), use `get_element` to trace all incoming nodes
2. **Extract full content**: Call `get_asset_detail` on every text node in the chain to get untruncated content
3. **Identify template vs. variables**:
   - Template: structural skeleton (allowed/forbidden inputs, stage goals, brand style constraints, negative constraints)
   - Variables: product-specific content (scenes, selling points, audience, English prompts)
4. **Fill in new product info**: Replace variable sections with the new product's positioning text
5. **Cross-validate**: After completing all modules, check adjacent modules (especially M5/M6/M7/M8) for audience/scene overlap
6. **Connect edges**: Ensure each new node's incoming edges include all actual input sources (product image, positioning, methodology, brand style)

## Post-Batch Creation Checklist

After bulk-creating nodes, run through:
- [ ] **Style consistency**: Do all sibling nodes share the same fontSize, size, and spacing?
- [ ] **Content deduplication**: Do adjacent modules have unreasonable overlap in scenes, audiences, or selling points?
- [ ] **Edge completeness**: Is every output node connected to all its actual input sources?
- [ ] **Text integrity**: Spot-check 1-2 nodes with `get_asset_detail` to confirm content was not truncated on write

## Reasoning Guide

For complex tasks, think through: **Goal → Pre-conditions (auth, balance, canvas_id) → Dependencies (parallel vs sequential calls) → Risk (destructive ops need confirmation) → Verify (get_canvas after completion)**.

**Error recovery** — diagnose first, don't retry blindly:
- HTTP 401 → login flow
- "not found" → verify ID via `get_canvas` / `list_workspaces`
- Insufficient balance → inform user
- `generate_image` timeout → check later with `get_element`

## Critical Rules

1. **`canvas_id` and `space_id` are mandatory** — Get them from `list_workspaces` first. Never guess.
2. **Match element size to aspect ratio** — When using `aspect_ratio` in `generate_image`, pass matching `size_width` / `size_height`. See the sizing table above.
3. **Confirm destructive operations** — `delete_element`, `delete_edge`, `delete_group`, `remove_image_from_asset_folder` all require user confirmation.
4. **Check balance before batch ops** — Call `get_account` before generating 3+ images.
5. **Claude cannot see generated images** — Refinement is based on prompt expertise + user feedback. Always ask for feedback between generation rounds.
6. **Think before acting** — For multi-step operations, outline your plan to the user first. This prevents wasted CU and destructive mistakes.
7. **One canvas at a time** — Don't operate across multiple canvases simultaneously unless a cross-workspace playbook is in use.

## Update Check (on first load)

Silently check for updates on first load:

```bash
python3 ${SKILL_DIR}/scripts/check_update.py --skill-dir ${SKILL_DIR}
```

- **`update_available|{hash}`** → Tell the user: "A newer version of the Virse skill is available. Would you like me to update?"
- **`up_to_date` or `check_failed`** → Proceed silently.

If user agrees to update and `${SKILL_DIR}` is a git repo:
```bash
git -C ${SKILL_DIR} pull origin main
sed -i "s/^commit_hash: .*/commit_hash: $(git -C ${SKILL_DIR} rev-parse --short=7 HEAD)/" ${SKILL_DIR}/SKILL.md
```
If not a git repo, tell the user to re-clone or download the latest version from the repository. Never auto-update without user consent.

_meta.json Metadata

{
  "ownerId": "kn7en3c7t9jm4kva6sd9hsf3d982hvaa",
  "publishedAt": 1773958419540,
  "slug": "virse",
  "version": "1.0.0"
}