Skills or MCP tools: instructions and callables

A skill is not a tool. MCP tools are the callables an agent can invoke. Skills are the instructions that tell it when to invoke them, in what order, and what to check first. Treating those as the same install step is how you end up with an agent that can generate a video and still retries a 402 five times.

Versely ships both layers on purpose. The hosted MCP server at https://mcp.versely.studio/mcp exposes generation as tools. The eight skill packs in AI-XLabs-Innovation/versely-skills are markdown procedures the agent loads when your request matches their descriptions. Installing one without the other is valid. Installing both is the setup that actually behaves.

Two different objects

An MCP tool is a function with a name, a schema, and a side effect. Once the connector is live, the agent sees mcp__versely__* entries in its tool list and can call them the way it calls any other tool: pick arguments, wait for a result, continue the turn. There is no procedure inside the tool for "check the balance first" or "this error means stop." The callable does the work you asked. It does not decide whether you should have asked.

A Versely skill is a folder with a SKILL.md. The frontmatter names it (versely-generate, versely-slideshow, and so on), describes when to use it, and lists the tools the skill is allowed to use. Every pack currently declares Bash and Read. The body is the operating procedure: which endpoint, which required fields, how to poll, and what each status code means. The generate pack, for instance, specifies that generation is asynchronous and the agent must poll GET /api/v1/status/:requestId rather than fishing through the media library, because that endpoint is scoped to a single request. It maps the error ladder: 401 is a bad key, 402 is insufficient credits, 403 is a missing scope, 429 means read X-RateLimit-Reset and back off, 500 means retry once after ten seconds.

That is a different kind of object. The tool is the verb. The skill is the runbook.

	Skills	MCP tools
What it is	A markdown procedure the agent loads	A callable with a schema
What it answers	When, in what order, what to check	What can be invoked right now
Auth it needs	A key in the environment, or MCP already connected	A connector session, or a key written into the agent config
Failure mode without the other	Agent can curl the API but has no typed tools	Agent can call tools and improvises the procedure
Install	npx skills add AI-XLabs-Innovation/versely-skills	Connector URL, or versely install

The skills page and the MCP page are the two product surfaces for those layers. They are tabs on the same setup, not alternatives.

What each one actually does in a turn

Watch a request like "generate a 9:16 product clip, then caption it, then schedule it to Instagram tomorrow."

MCP alone. The agent sees tools it can call. It may generate the clip. It may skip the credit check. It may poll the wrong status endpoint. It may treat a 402 as a retryable blip. It may post before the video URL exists. None of that is the tool's fault. The tool did what it was asked. The missing piece is the procedure that would have refused to ask.

Skills alone. The packs tell the agent the endpoints, the polling cadence, and the error ladder. They are allowed to use Bash, so a key in VERSELY_API_KEY is enough for the agent to curl https://api.versely.studio. You get the runbook. You lose the typed tool surface: argument names, required fields, and the client's own confirmation UI for a tool call. It works. It is also how you discover that the agent passed image_url to an endpoint that wanted images: [...].

Both. The skill fires because the request matched "create visual content" plus a later caption and a schedule. It names the generate path, then the caption path, then social posting. The MCP tools are how those steps actually run. The skill is why the agent checks credits before the first generate, polls until completed or failed, and does not retry a 402.

The useful mental model: MCP is capability. Skills are discipline. Capability without discipline spends credits. Discipline without capability works, but you are back to pasting curl into a chat.

When to reach for which

Reach for MCP when the agent needs to do something in Versely during a conversation. Adding the connector in a chat client is the whole install: paste https://mcp.versely.studio/mcp, sign in, generate. That is the right layer if you already know the procedure and you just want the tools in the session. It is also the right layer if you work in Claude's connector UI rather than a terminal agent.

Reach for skills when the agent needs to know the job. Credit pre-flight, polling the right status endpoint, not mixing /generate/video with /movie/:id/status, not treating Suno's taskId as a FAL requestId. Those are not things an agent invents reliably from an OpenAPI guess. They are written down in the packs on purpose.

Reach for both in any terminal agent you use more than once. The CLI exists to make that the default rather than a three-step ritual: npx @versely/cli setup installs the skills, mints a key, and writes the MCP server into every detected agent. versely install is the MCP half if the skills are already on disk.

A third door, which is not a substitute for either layer, is the in-app agent. That surface already has the procedures baked into the product. You do not install skills there. You also do not get them in Cursor by opening the web app.

Installing both is the point

People ask "skills or MCP?" as if it were a platform choice, the way they ask CLI or API. It is not. The CLI, MCP, or API decision is about who initiates the request. Skills versus MCP tools is about what the agent has in context once a request has started.

The combinations that actually occur:

1. Chat client, MCP only. Fine for exploration. You are in the loop. If the agent skips a credit check you see the 402 and you stop it.
2. Terminal agent, skills only. Fine if you already have VERSELY_API_KEY exported and you are comfortable with the agent shelling out to curl. You are missing typed tools.
3. Terminal agent, MCP only. The common failure. Tools appear, the agent looks competent, and the first batch has no pre-flight.
4. Terminal agent, both. The intended setup. Skills decide the path. MCP executes it.

npx skills add AI-XLabs-Innovation/versely-skills is the skills-only command. It uses Vercel Labs' skills CLI and writes into whichever agents that CLI knows about. It does not mint a key and it does not write an MCP config. If you run it and then wonder why the agent cannot generate, you installed instructions and no callable.

The connector URL is the MCP-only command. It does not install skills. If you paste it into Claude and then wonder why the agent retries a 402, you installed callables and no runbook.

The command that does both in one pass is npx @versely/cli setup. That is the one to run on a laptop you actually work on. The unpack of what it writes, including versely install --agent claude-code and the three versely status states, is in wiring Versely skills into Claude Code.

Restart the agent after either install. MCP config is not reloaded in place. A correct install that still shows no mcp__versely__* tools is almost always a process that has been running since before the write.

FAQ

Can I use skills without connecting MCP?

Yes. Each pack lists Bash and Read as allowed tools, and the procedures are written as curl against https://api.versely.studio with Authorization: Bearer $VERSELY_API_KEY. Export the key, or store it at ~/.versely/config.json via versely auth login, and the agent can follow the runbook without a single MCP tool. You lose the typed schema. You keep the polling rules and the error ladder.

Can I use MCP without installing skills?

Yes, and it is the default in a chat client's connector UI. The agent will call whatever mcp__versely__* tools it can see. For a one-shot "make an image of X" that is enough. For anything with a credit check, a poll, or a second step, you are betting the agent improvises the same procedure the skill already wrote down.

Why does the CLI install both if they are separate layers?

Because the failure mode of installing one is silent. Skills without MCP look installed and then fail at the first generate unless a key is already in the environment. MCP without skills looks connected and then spends credits without a pre-flight. npx @versely/cli setup makes the working combination the default so you do not have to remember the distinction on day one. You still can install them separately later. The layers stay separate. The installer is allowed to be opinionated.

Do skills replace the in-app agent?

No. The in-app agent is a product surface with its own routing. Skills are for coding agents on your machine: Claude Code, Cursor, Codex, and the rest of the list the CLI detects. Same catalog, same credit balance, same rule that every generation costs credits. Different place the procedure lives.