# Give your agent the vibevm skill {#root} @status:doc/work @audience:user [p01] 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. [p02] ```prompt 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. ``` - needs: 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 outcome: `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 - assert: `vibe mcp status` - assert: `vibe skill list --quiet` ## What happens {#what-happens} [p03] 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. > [p04] 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. > > [p05] 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. > [p06] 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. > > > [p07] 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. > > > [p08] **Decision.** The integration surface supports a fixed set of MCP-capable > coding agents (Claude Code, Claude Code Desktop, Cursor, OpenCode, Codex). > > > [p09] **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: > > [p10] 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. > [p11] **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 > `/.mcp.json` (project) and the top-level `mcpServers` of > `~/.claude.json` (user) — **never `settings.json`**, which only > *gates* `.mcp.json` servers (`enabledMcpjsonServers`) and does not > define them. > > > [p12] **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.json` appends 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. > > > [p13] **Decision.** For agents that support a skill manifest (Claude Code, > OpenCode, Codex — not the JSON-config-only Cursor / Claude Code Desktop), > `vibe mcp install` also writes a `SKILL.md` describing how to use vibevm > through the MCP tools. > > ## By hand {#by-hand} [p14] 1. See the plan first; nothing is written: [p15] ```sh vibe mcp status --path hello-vibe ``` ```output Detected agents: claude, claude-desktop, opencode, codex → would-create mcp claude (project) → /work/hello-vibe/.mcp.json (file does not exist yet) → would-update mcp claude (user) → /.claude.json (mcpServers/vibevm differs) → would-update mcp claude-desktop (user) → /AppData/Roaming/Claude/claude_desktop_config.json (mcpServers/vibevm absent) → would-create mcp cursor (project) → /work/hello-vibe/.cursor/mcp.json (file does not exist yet) → would-create mcp cursor (user) → /.cursor/mcp.json (file does not exist yet) → would-create mcp opencode (project) → /work/hello-vibe/opencode.json (file does not exist yet) → would-update mcp opencode (user) → /.config/opencode/opencode.json (mcp/vibevm differs) → would-update mcp codex (user) → /.codex/config.toml ([mcp_servers.vibevm] absent) → would-create skill claude (project) → /work/hello-vibe/.claude/skills/vibevm/SKILL.md → would-update skill claude (user) → /.claude/skills/vibevm/SKILL.md → would-create skill opencode (project) → /work/hello-vibe/.opencode/skills/vibevm/SKILL.md → would-update skill opencode (user) → /.config/opencode/skills/vibevm/SKILL.md → would-create skill codex (project) → /work/hello-vibe/.agents/skills/vibevm/SKILL.md → would-create skill codex (user) → /.agents/skills/vibevm/SKILL.md ``` [p16] 2. Install for every detected agent, or for one with `--agent claude`, `--agent codex`, `--agent opencode`, `--agent cursor`, `--agent claude-desktop`: [p17] ```sh vibe mcp install --auto --yes --dry-run --path hello-vibe ``` ```output → would mcp claude (project) → /work/hello-vibe/.mcp.json (file does not exist yet) → would mcp opencode (project) → /work/hello-vibe/opencode.json (file does not exist yet) → would skill claude (project) → /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) → /work/hello-vibe/.opencode/skills/vibevm/SKILL.md → would skill codex (project) → /work/hello-vibe/.agents/skills/vibevm/SKILL.md ``` [p18] 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. ## Skills that packages bring {#skills-from-packages} [p19] 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. > [p20] **Decision.** Installing a skill into an agent is a **projection**: read the > declared skill body from the package (in `vibedeps/…` 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//…`, `.opencode/skills//…`, > `.agents/skills//…` — the paths PROP-015 §2.6 already resolves). > > > [p21] **`vibe skill list`** — skills declared by installed packages. > > > [p22] **`vibe skill install [--agent …] [--scope project|user|both] [] […]`** > — 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 as `vibe mcp install` (PROP-015 §2.7). > > [p23] ```sh vibe skill list --path hello-vibe ``` ```output → 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. ``` [p24] The skill of this manual, `vibevm-docs`, arrives the same way once the manual is in the machine [store](../glossary/index.xml#store). ## Servers that packages bring {#servers-from-packages} [p25] 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. > [p26] Registering a server schedules package code execution at agent-session > start; building its binary compiles package code. > > [p27] 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. > [p28] It grows package discovery: every installed package of kind > `mcp` contributes its `[[mcp_server]]` entries, written into the target > agents' configs with > > > [p29] 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; > > > [p30] 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 `` block convention of the boot files, > applied to agent configs. > > > [p31] One trust model, two > verbs: registration inherits PROP-025's consent gate verbatim — > `org.vibevm` packages are allow-listed; any other origin requires the > explicit `--assume-yes` (or is refused with the recipe naming that > exact flag). > > > [p32] `vibe mcp status` reports each declared server's artifact state > (an unbuilt artifact registers fine and fails at agent launch — the > recipe names `vibe bin build `); > > ## Edge cases and rules {#edge-cases} [p33] `vibe mcp upgrade` refreshes existing integrations to the shape shipped by the current binary after a vibe upgrade; it creates nothing new. [p34] `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. > [p35] **`vibe skill uninstall …`** — the inverse; strips only vibevm-projected > skills, leaves foreign skill dirs untouched. > > [p36] 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.