Agent skills

This development build uses API voxelite.v1.

Teach the workflow once. Keep the creative loop moving.

These portable skills teach agents how to use the implemented Quantum MCP tools. They cover atomic edits, palette choices, primitive composition, real image inspection and recovery from conflicts.

Install MCP

Install Quantum for Mac in Applications first. The app includes the MCP server. Open your project folder in your host, then choose an install method below. For source builds or a different app location, use the manual configuration with your executable's absolute path.

Cursor

Review and confirm the server in Cursor. The file root is ${workspaceFolder}, your open project folder. View mcp.json for manual setup.

Claude Code

Run from your project directory; "$PWD" sets the file root to that directory.

claude mcp add voxelite -- '/Applications/Voxelite.app/Contents/MacOS/voxelite-mcp' --root "$PWD"

To make the server available across projects, add --scope user after claude mcp add. Its file root still points to the directory where you ran the command.

Codex

Run from your project directory; "$PWD" sets the file root to that directory.

codex mcp add voxelite -- '/Applications/Voxelite.app/Contents/MacOS/voxelite-mcp' --root "$PWD"

Or merge this into ~/.codex/config.toml (or your trusted project's .codex/config.toml). Replace <project dir> with an existing absolute path.

[mcp_servers.voxelite]
command = "/Applications/Voxelite.app/Contents/MacOS/voxelite-mcp"
args = ["--root","<project dir>"]

VS Code

Install in VS Code

Review and confirm the server in VS Code, or run this CLI command. Both use ${workspaceFolder} for the file root, resolved by VS Code in your open project.

code --add-mcp '{"name":"voxelite","command":"/Applications/Voxelite.app/Contents/MacOS/voxelite-mcp","args":["--root","${workspaceFolder}"]}'

View .vscode/mcp.json for manual setup.

Other

For Claude Desktop, Windsurf and other MCP hosts, merge this entry into the host's MCP settings. Preserve existing servers and replace <project dir> with an existing absolute path.

{
  "mcpServers": {
    "voxelite": {
      "command": "/Applications/Voxelite.app/Contents/MacOS/voxelite-mcp",
      "args": [
        "--root",
        "<project dir>"
      ]
    }
  }
}

Install skills

Install all skills from the repository's skills/ directory with the open Agent Skills CLI. This installs workflow instructions; configure MCP above to give them tools.

npx skills add 0x63616c/voxelite

Add --skill <name> for one skill, -g for a global install, or -a claude-code, -a cursor or -a codex to pick an agent. Choose an individual skill.

For a manual install, download the skill folders or use a repository checkout. Copy each skills/<name>/ folder into .cursor/skills/, .claude/skills/, or ~/.codex/skills/. Install, update and removal notes.

What you get

MCP gives your agent voxel editing tools, palettes, real PNG renders, and project save/export. Skills teach it to compose, inspect and refine a model. Each standalone server owns its own session; save .voxl files before disconnecting. To edit the live native canvas, copy the connection configuration from the app.

Verify it works

Restart or reconnect your host and list its MCP tools.
Call voxelite_capabilities_get with {}. Expect API voxelite.v1, an epoch and available document IDs.
Confirm the installed skills appear in your host, then ask it to use voxelite-workflow for your first model.

Choose a skill

voxelite-palettes

Choose, create or apply Voxelite palettes with readable material roles and stable slot mappings, without unintended recoloring.

npx skills add 0x63616c/voxelite --skill voxelite-palettes

Read skill instructions

voxelite-primitives

Build Voxelite subjects from integer primitive masses, mirrored boxes and bounded explicit voxel batches for curved shapes.

npx skills add 0x63616c/voxelite --skill voxelite-primitives

Read skill instructions

voxelite-render-review

Inspect real Voxelite MCP renders from multiple angles, identify spatial flaws, and verify repairs at a consistent document revision.

npx skills add 0x63616c/voxelite --skill voxelite-render-review

Read skill instructions

voxelite-workflow

Create or refine voxel art through Voxelite MCP, with atomic edits, visual review, named versions and portable exports.

npx skills add 0x63616c/voxelite --skill voxelite-workflow

Read skill instructions

Give it a first brief

Use the Quantum workflow to build a warm brass lantern within 32 × 32 × 32 cells. Save a blockout version, inspect iso/front/right/back renders, repair the handle silhouette, then save .voxl and GLB.

The render-review skill uses voxelite_render for real PNG feedback. There is no screenshot-named MCP tool in this build. Primitive guidance also stays within today's catalog: boxes and explicit voxel batches, without invented cylinder or ellipsoid calls.

Know when it worked

The agent should report the model revision, views it actually inspected, and saved output paths. A successful render call is not visual inspection, and exporting an image is not saving a project. These distinctions are part of every workflow.

All documentation Start building