Give your agent the vibevm skill
01Your agent works better when it knows what vibe is and how to call it. This page puts a short instruction file where the agent reads it, and, for agents that support it, starts a server the agent can query directly.
Wire vibe into every coding agent installed on this machine, for the VibeVM project in the current folder: install the vibevm skill and the MCP server entry, then show me what was written and for which agents.vibe on the PATH; a project with vibe.toml in the current folder; at least one supported agent installed: Claude Code, Claude Desktop, Cursor, OpenCode or Codex
vibe mcp status shows an up-to-date server entry and skill for each detected agent; the next agent session in this project knows the vibe commands and can query the project's packages
vibe mcp statusvibe skill list --quiet
What happens
03The agent runs vibe mcp install --auto --yes. vibe detects the agents present on the machine and writes two things for each. The first is an entry in the agent's configuration that starts vibe mcp serve as a server the agent can query. The second is a skill file, SKILL.md, that teaches the agent the vibe commands and when to use them. Both writes touch only the vibevm entry of each configuration; anything else in those files is left alone. The command is idempotent: a second run reports every unchanged entry as unchanged.
04 spec: Registration writes touch ONLY the target…
Registration writes touch ONLY the target agent's config files and only managed entries; server processes receive the project root as cwd and NO secrets from vibe.
05Two surfaces make this work. vibe mcp serve is a Model Context Protocol server that exposes the project's lock-derived state to any agent as tools, and the vibe mcp commands wire it into each agent's own configuration and write the agent's SKILL.md. The set of agents is fixed: Claude Code, Claude Code Desktop, Cursor, OpenCode and Codex. Every verb is idempotent over the agent-and-scope matrix, offers --dry-run and asks before writing.
06 spec: A Model Context Protocol server (vibe…
A Model Context Protocol server (vibe mcp serve) that exposes the
project's lockfile-derived state to any MCP-speaking agent as callable
tools — so the agent queries package identity and pulls subskill content
on demand instead of guessing from the file tree.
07 spec: An agent-integration command family (vibe mcp…
An agent-integration command family (vibe mcp install and friends)
that wires that server into each agent's own configuration and writes a
per-agent skill manifest, so an operator runs one command instead of
hand-editing five different config files.
08 spec: Decision: The integration surface supports…
Decision. The integration surface supports a fixed set of MCP-capable coding agents (Claude Code, Claude Code Desktop, Cursor, OpenCode, Codex).
09 spec: Decision: The agent-integration command family…
Decision. The agent-integration command family is a coherent
lifecycle over the (agent × scope) matrix, every verb idempotent and
every mutating verb offering --dry-run and a confirmation:
10vibe writes into the file each agent really reads for discovery, for Claude Code .mcp.json in the project or the top-level servers table of ~/.claude.json, and never a settings file that only gates them. It upserts its one entry and preserves every foreign key in its order, so a large configuration is appended to, not rewritten; uninstalling strips only vibe's entry. For the agents with a skill folder, Claude Code, OpenCode and Codex, it also writes a SKILL.md on how to use vibe through the tools.
11 spec: Config path
Config path — resolved per (agent, scope), cross-platform. The path must be the file the agent actually reads for MCP discovery, not merely a settings file it happens to own. For Claude Code that is<project>/.mcp.json(project) and the top-levelmcpServersof~/.claude.json(user) — neversettings.json, which only gates.mcp.jsonservers (enabledMcpjsonServers) and does not define them.
12 spec: Merge discipline
Merge discipline — installing upserts vibevm's one entry under the section key and preserves every foreign key, and their order: the JSON writer round-trips order-preserving (serde_json/preserve_order), so a merge into a large~/.claude.jsonappends rather than re-alphabetising the operator's whole file. Uninstalling strips only vibevm's entry and leaves the rest. The operator's other MCP servers and unrelated config survive every operation.
By hand
141. See the plan first; nothing is written:
vibe mcp status --path hello-vibeDetected agents: claude, claude-desktop, opencode, codex
→ would-create mcp claude (project) → <TMP>/work/hello-vibe/.mcp.json (file does not exist yet)
→ would-update mcp claude (user) → <HOME>/.claude.json (mcpServers/vibevm differs)
→ would-update mcp claude-desktop (user) → <HOME>/AppData/Roaming/Claude/claude_desktop_config.json (mcpServers/vibevm absent)
→ would-create mcp cursor (project) → <TMP>/work/hello-vibe/.cursor/mcp.json (file does not exist yet)
→ would-create mcp cursor (user) → <HOME>/.cursor/mcp.json (file does not exist yet)
→ would-create mcp opencode (project) → <TMP>/work/hello-vibe/opencode.json (file does not exist yet)
→ would-update mcp opencode (user) → <HOME>/.config/opencode/opencode.json (mcp/vibevm differs)
→ would-update mcp codex (user) → <HOME>/.codex/config.toml ([mcp_servers.vibevm] absent)
→ would-create skill claude (project) → <TMP>/work/hello-vibe/.claude/skills/vibevm/SKILL.md
→ would-update skill claude (user) → <HOME>/.claude/skills/vibevm/SKILL.md
→ would-create skill opencode (project) → <TMP>/work/hello-vibe/.opencode/skills/vibevm/SKILL.md
→ would-update skill opencode (user) → <HOME>/.config/opencode/skills/vibevm/SKILL.md
→ would-create skill codex (project) → <TMP>/work/hello-vibe/.agents/skills/vibevm/SKILL.md
→ would-create skill codex (user) → <HOME>/.agents/skills/vibevm/SKILL.md162. Install for every detected agent, or for one with --agent claude, --agent codex, --agent opencode, --agent cursor, --agent claude-desktop:
vibe mcp install --auto --yes --dry-run --path hello-vibe → would mcp claude (project) → <TMP>/work/hello-vibe/.mcp.json (file does not exist yet)
→ would mcp opencode (project) → <TMP>/work/hello-vibe/opencode.json (file does not exist yet)
→ would skill claude (project) → <TMP>/work/hello-vibe/.claude/skills/vibevm/SKILL.md
→ would skill claude-desktop (project) → (no skill loader) (agent `claude-desktop` has no project-scope skill loader)
→ would skill opencode (project) → <TMP>/work/hello-vibe/.opencode/skills/vibevm/SKILL.md
→ would skill codex (project) → <TMP>/work/hello-vibe/.agents/skills/vibevm/SKILL.md183. Choose the scope: --scope project writes into the project's own agent folders, --scope user into your home configuration, --scope both into both. Without a project in the current folder the user scope is chosen for you.
Skills that packages bring
19Packages can declare skills of their own, for any kind of package: a flow that ships a checklist skill, a language guide that ships a sweep skill, a manual that ships a reading skill. vibe skill list shows what the installed packages declare, and vibe skill install projects them into the agents' skill folders. Installing a skill is a projection of a file the package already carries, not a second delivery mechanism.
20 spec: Decision: Installing a skill…
Decision. Installing a skill into an agent is a projection: read the declared skill body from the package (invibedeps/…once installed) or an external source authenticated by the package's matching lock record, and write it into each target agent's skill directory in that agent's own convention (.claude/skills/<name>/…,.opencode/skills/<name>/…,.agents/skills/<name>/…— the paths PROP-015 §2.6 already resolves).
21 quote from the specification
vibe skill list — skills declared by installed packages.
22 spec: vibe skill install [--agent …] [--scope…
vibe skill install [--agent …] [--scope project|user|both] [<pkgref>] [<skill>…]— project skills into agents. Default: all declared skills; narrow with explicit skill names or a pkgref. Idempotent,--dry-run, confirm (or--assume-yes), per-(agent, scope) report — the same lifecycle and merge discipline asvibe mcp install(PROP-015 §2.7).
vibe skill list --path hello-vibe → wal-status [flow:wal] → agents: all — Read the project WAL end to end and emit a ten-line orientation: phase, attention items, next step; warn on staleness
1 skill(s) declared.24The skill of this manual, vibevm-docs, arrives the same way once the manual is in the machine store.
Servers that packages bring
25A package of the mcp kind delivers a server built from its own code, such as the discipline tools of a language family. vibe mcp install registers such servers in the agents' configurations beside vibe's own, with the path of the built binary; vibe mcp status reports whether each is built and current. Registering a server means the agent will run that package's code at session start, so registration asks for consent like an install does.
26 spec: Registering a server schedules package code…
Registering a server schedules package code execution at agent-session start; building its binary compiles package code.
27Every installed package of the mcp kind contributes its servers to the same registration, which is project-scoped, because a project's servers belong in its committed configuration. In the JSON file vibe keeps a small vibevm.managed list naming the entries it owns, so a re-install rewrites only those and never touches a server you added yourself. The consent gate is the one binaries use: packages of the org.vibevm group are allow-listed, every other origin needs --assume-yes. vibe mcp status says whether each server's binary is built.
28 spec: It grows package discovery: every installed…
It grows package discovery: every installed package of kindmcpcontributes its[[mcp_server]]entries, written into the target agents' configs with
29 spec: Registration is PROJECT-scope only (the {project_root}…
Registration is PROJECT-scope only (the
{project_root} substitution demands a project, and a project's
servers belong in its committed config), and every project-scope
agent config is JSON — so no TOML sidecar form exists;
30 spec: a managed sidecar: a top-level "vibevm"…
a managed sidecar: a top-level"vibevm": { "managed": [...] }object in the JSON config names the entries vibevm owns (never a key INSIDE a server entry — hosts validate entry shapes), so re-installs rewrite ONLY vibevm-managed entries and operator-owned servers are never touched — the<vibevm>block convention of the boot files, applied to agent configs.
31 spec: One trust model, two verbs: registration…
One trust model, two verbs: registration inherits PROP-025's consent gate verbatim —org.vibevmpackages are allow-listed; any other origin requires the explicit--assume-yes(or is refused with the recipe naming that exact flag).
32 spec: vibe mcp status reports each declared…
vibe mcp statusreports each declared server's artifact state (an unbuilt artifact registers fine and fails at agent launch — the recipe namesvibe bin build <name>);
Edge cases and rules
33vibe mcp upgrade refreshes existing integrations to the shape shipped by the current binary after a vibe upgrade; it creates nothing new.
34vibe mcp uninstall removes vibe's entry and skill and leaves every foreign entry in place; vibe skill uninstall strips only the skills vibe projected.
35 spec: vibe skill uninstall …
vibe skill uninstall … — the inverse; strips only vibevm-projected
skills, leaves foreign skill dirs untouched.
36Cursor and Claude Desktop take the server entry but have no skill folders; vibe reports the skill as skipped for them rather than inventing a place.