Visual Sandbox Skills and Claude plugin

Everything an AI agent needs to generate media with Visual Sandbox: the knowledge packs that teach it how to prompt each model, and the plugin that gives it the tools to run them.

This repository is two things at once.

A Claude Code plugin. .claude-plugin/ + .mcp.json at the root ship the skills, four slash commands, and the hosted MCP server as one install:

claude plugin marketplace add visualsandbox/skills
claude plugin install visual-sandbox@visual-sandbox

That adds the visual-sandbox MCP server at https://visualsandbox.com/mcp. The first tool call opens a browser, you press Approve, and it is connected. No token to copy. Then /image a red bicycle in the rain works straight away.

A skill library for the vsb CLI. Each skill is a single SKILL.md (plus optional references/) with YAML frontmatter the agent runtime reads to decide when the skill applies. The CLI embeds them in its binary and vsb setup writes them to ~/.claude/skills/.

Both surfaces do the same work. The vsb trunk skill opens with Two ways to run, which sends an agent holding MCP tools to the MCP reference and everyone else to the CLI.

Commands the plugin adds

The MCP tools

list_models, get_model, estimate_cost, generate, get_job, list_jobs, list_voices, upload_media, list_sandbox_items, get_selection, read_sandbox_docs, write_sandbox_doc, create_design, get_design, update_design, move_layer, export_design, list_presets, get_preset, get_balance, top_up, list_skills, get_skill, the video edit tools, the asset library and brand themes (search_assets, update_asset, list_themes, get_theme, update_theme, extract_theme), film projects (create_film_project, get_film_project, update_film_project, list_film_projects, assemble_film), render_html_video, render_html_image and submit_feedback — one for each vsb command. Add the server on its own, without the plugin:

claude mcp add --transport http visual-sandbox https://visualsandbox.com/mcp

Every generation is charged to the connected account. Nothing is free.

Skills

Install

# One-shot install of the binary + default skill bundle + auth
curl -fsSL https://visualsandbox.com/install.sh | sh
vsb setup

vsb setup writes the default bundle (vsb, vsb-presets, vsb-image, vsb-image-prompting, vsb-video, vsb-audio) into ~/.claude/skills/ so Claude Code finds them in every project. Pass --project to install into ./.claude/skills/ instead (committable, per-project, shared via git).

# Skills only — skip auth (re-run after editing locally)
vsb setup --skills-only

# Pick individual skills
vsb skills install nano-banana
vsb skills install ugc-people --project

# Refresh installed skills to the latest version baked into the binary
vsb skills update

Agents working with vsb should follow cli-install.md for the full install playbook — covers PATH issues, token recovery, and the first-run verify.

Other agents

The same repository installs in other agents. Each one reads its own file at the root, and every file names the one server, https://visualsandbox.com/mcp.

Planned: the film pyramid

Every skill above answers one question: how do I run this model well? None of them answers what comes first — what am I making, and what should the shot be?

docs/film-pyramid.md plans six skills that sit above the model, from an idea down to a finished cut, and says how they hand work to each other. The first one, vsb-film, is built as one skill that holds the whole flow. The split into tiers is still a plan.

Layout

skills/
├── <name>/
│   ├── SKILL.md          # frontmatter + body
│   └── references/        # optional supporting docs
├── index.json             # sha256 + bytes per file (generated)

How the CLI consumes this

vsb embeds these skills directly into the binary at build time — every release ships a snapshot of skills/, sha256-verified against index.json. vsb setup / vsb skills install write from the embedded bundle with zero network calls.

Power users can opt into the live registry instead of the embedded copy:

vsb skills install nano-banana --remote
# or for the whole session:
VSB_SKILLS_REMOTE=1 vsb setup --skills-only

Remote mode pulls from https://raw.githubusercontent.com/visualsandbox/skills/main/skills/, caches in ~/.vsb/skills-cache/, and verifies sha256 against the live index.json. Pin to a tag, branch, or sha with VSB_SKILLS_REF=v0.3 vsb setup --skills-only.

Contributing

Edits land in skills/<name>/SKILL.md. After editing locally:

bun run gen

That regenerates skills/index.json with fresh sha256s. The CI workflow in .github/workflows/index.yml also regenerates the index on every push to main, so manual runs are mainly for previewing the diff before opening a PR.

License

Proprietary. You may install the skills into your own agents and use them with Visual Sandbox. See LICENSE for the full terms.