Give your agent the vibevm skill

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 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 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 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 Decision. The integration surface supports a fixed set of MCP-capable coding agents (Claude Code, Claude Code Desktop, Cursor, OpenCode, Codex).

09 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 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-level mcpServers of ~/.claude.json (user) — never settings.json, which only gates .mcp.json servers (enabledMcpjsonServers) and does not define them.

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

13 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

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

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

183. 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 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/<name>/…, .opencode/skills/<name>/…, .agents/skills/<name>/… — the paths PROP-015 §2.6 already resolves).

21 vibe skill list — skills declared by installed packages.

22 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 as vibe 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 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 It grows package discovery: every installed package of kind mcp contributes its [[mcp_server]] entries, written into the target agents' configs with

29 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 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 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).

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