Give your agent the vibevm skill

Your 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 status vibe skill list --quiet

The 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](../glossary/index.xml#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.

Two 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.

vibe 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.

1. See the plan first; nothing is written:

vibe mcp status --path hello-vibe Detected 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.md

2. 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.md

3. 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.

Packages 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.

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.

The skill of this manual, `vibevm-docs`, arrives the same way once the manual is in the machine [store](../glossary/index.xml#store).

A package of the `mcp` kind delivers a server built from its own code, such as the discipline tools of a language [family](../glossary/index.xml#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.

Every 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.

`vibe mcp upgrade` refreshes existing integrations to the shape shipped by the current binary after a vibe upgrade; it creates nothing new.

`vibe mcp uninstall` removes vibe's entry and skill and leaves every foreign entry in place; `vibe skill uninstall` strips only the skills vibe projected.

Cursor 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.