Wiring Versely skills into Claude Code

A tool tells an agent what it can call. A skill tells it when to call it, in what order, and what to check first. That distinction sounds academic until you watch an agent with tools but no procedure fire a twelve-item generation batch without checking the credit balance, fail on item seven, and leave you with six half-useful assets and no plan.

Versely ships both. The MCP server provides the tools; the skill packs provide the procedures. This is how you get them into Claude Code, and where the line sits between what the agent should own and what should stay in the editor.

What a Versely skill actually is

Each skill is a markdown document with frontmatter, distributed through Vercel Labs' open skills CLI. It declares the tools it is allowed to use, and it contains the operating procedure for one area of work: the endpoints, the required fields, the polling discipline, the failure modes and what to do about each.

The generate pack, for instance, does not just say "you can generate images." It specifies that generation is asynchronous and the agent must poll GET /api/v1/status/:requestId rather than looking for the asset anywhere else, because that endpoint is scoped to a single request and will not race. It specifies a credit check before dispatch. It maps the whole error ladder: 401 means the key is invalid, 402 means insufficient credits and the agent should tell you the balance and the estimate rather than retrying, 403 means the key is missing a scope, 429 means read X-RateLimit-Reset and back off, 500 means retry once after ten seconds.

That is the part worth caring about. An agent improvising against an unfamiliar API will retry a 402 five times. An agent following a procedure stops and tells you the balance.

Eight packs ship: generate, slideshow, movie, ugc, music, social, analytics and content-pipeline. The pipeline pack chains the others into complete flows rather than covering an area of its own, and it opens with a budget step, because a multi-step pipeline that dies at step six has already spent the credits from steps one through five. The skills page lists what each one covers.

The install, and what each command actually touches

One command does all three pieces:

npx @versely/cli setup

That runs, in order:

1. npx skills add AI-XLabs-Innovation/versely-skills, which installs the skill packs.
2. A browser sign-in that mints a long-lived API key and stores it at ~/.versely/config.json, readable only by your user.
3. An MCP install that writes the Versely server into every detected agent's config, with your key attached.

If you prefer to run the pieces separately, or you already have a key:

npm install -g @versely/cli
versely auth login          # or: versely auth login --key vsk_xxx
versely install             # or: versely install --agent claude-code

For Claude Code, versely install writes an entry into ~/.claude.json under mcpServers.versely: an HTTP server pointed at https://mcp.versely.studio/mcp, with an Authorization: Bearer header carrying your key. Cursor gets the same entry in its own MCP config. Claude Code, Cursor and Codex are the named targets, and the CLI detects a much longer tail of agents beyond them — run it with no --agent flag and it wires whatever it finds. The CLI page has the full command list.

Restart the agent afterwards. It does not reload MCP config in place, and this is the single most common reason a correct install appears not to have worked. After the restart you should see mcp__versely__* tools and /versely-* skills available.

Verify without guessing:

versely status

It prints the auth line, showing a masked key and whether it came from ~/.versely/config.json or the VERSELY_API_KEY environment variable, then a per-agent line reading not detected, detected, not connected, or connected. Three distinct states, and each has a different fix.

What the agent can do once it is wired

The genuinely useful pattern is not "generate an image from my editor." It is that generation becomes a step inside work the agent was already doing, with the surrounding context already in its head.

A few that hold up in practice:

• Assets from the thing you are building. The agent has read your product copy, your component names and your empty states. Asking for the illustrations for those empty states is a one-sentence instruction against context it already has, rather than a brief you have to write from scratch in another tab.
• Fan-out comparisons. The image and video endpoints accept an array for model, so one request can put the same prompt through several named models and return a request id per model. The agent can dispatch that and lay the results out for you side by side.
• Batch dispatch with a real pre-flight. Reading a prompt list out of a file, costing the run, checking the balance, dispatching, polling, and writing the result URLs somewhere is exactly the shape of work an agent with Bash access does well and a human does tediously.
• Glue. Generate, then rename, sort, convert, commit. The last three steps are the ones that make people abandon a generation workflow, and they are the agent's native territory.

What it is bad at is taste. The agent cannot tell you which of four takes has the right energy, and any workflow where the answer to "is this good" is load-bearing needs a human looking at output rather than at status JSON. Briefing an agent instead of writing prompts is a good primer on how to phrase the parts it can own.

Where the line sits between agent and editor

The clean split is not by task type. It is by whether the loop has a person in it.

Work	Where it belongs	Why
Dispatching many generations	Agent	Repetitive, scriptable, no judgement per item
Choosing between takes	Editor	Someone has to actually watch them
Assembling a timeline	Editor	Trims and timing are judged, not specified
Renaming, sorting, uploading output	Agent	Pure glue
Client review and approval	Editor	Needs a link a non-technical person can open
Re-rendering a locked structure with new footage	Either	Structure is fixed, so nobody needs to judge it

The editor earns its half of that table through one structural property: it is EDL-based. The timeline is a description you re-render rather than a file you overwrite, preview: true returns a free 480p pass gated by a short per-user cooldown, and the final export is charged once regardless of how many clips are on the timeline. That means the expensive part of editing is generation, not iteration, and iteration is the part a human should be doing anyway. The video editing pages cover the timeline model.

The failure mode to avoid is asking an agent to do the cut. You end up describing timing in prose, which is slower than dragging a clip and worse at the thing that actually matters. Let it produce the material and handle everything after export. Let the editor own the middle.

When it does not work

Symptom	Cause	Fix
No mcp__versely__* tools	Agent not restarted	Restart it
versely status shows not signed in	No key on disk or in env	versely auth login
Agent shows detected, not connected	Skills installed, MCP not wired	versely install --agent claude-code
401 on every call	Key revoked or replaced	Re-login, then versely install again to rewrite the header
Agent not detected at all	Config path missing	versely install --agent '*' to force

The 401 row is the one that catches people twice. The key is copied into the agent's config at install time, so revoking and reminting a key means re-running versely install to push the new one. versely auth login on its own updates the CLI's store and nothing else.

For teams, the thing to settle before rollout is not the install but the spending policy, since an agent with a key can spend credits without a confirmation dialog in front of it. Guardrails for agent-run brand content covers budgets and approval gates.

FAQ

Do I need both the skills and the MCP server?

They do different jobs, and the useful setup has both. MCP gives the agent callable tools. Skills give it the procedure for using them properly, including the credit pre-flight and the polling and error rules. Skills alone can still work through Bash and curl if a key is in the environment, since the packs declare Bash and Read as their allowed tools, but you lose the typed tool surface. MCP alone works too, and the agent improvises the procedure, which is exactly the part you do not want improvised.

Does the agent share my normal credit balance?

Yes. One balance across every surface, topped up by the same subscriptions and credit packs. There is no separate agent wallet, no API-only plan and no free allowance anywhere, so an agent run draws down the same credits an in-app generation would. The agent page covers what it can do; billing is unchanged by which door the request came through.

Is this different from connecting Versely to the Claude desktop app?

Same server, different install path. In a chat client you paste the connector URL into settings and sign in there. The CLI exists because a terminal agent needs the config written to a file on disk, and doing that for each agent by hand is error-prone. Generating from Claude over MCP covers the chat-client route, and the MCP page has the connector URL.

How do I remove it cleanly?

versely uninstall strips the Versely entry from every agent config, or --agent claude-code to target one. versely auth logout clears the stored key separately. Both are safe to run repeatedly, and neither touches the skill packs, which are managed by the skills CLI that installed them.