# Дайте агенту навык vibevm {#root} @status:doc/work @audience:user [p01] Ваш агент работает лучше, когда знает, что такое vibe и как его вызывать. Эта страница кладёт короткий файл с инструкцией туда, где агент его читает, а для агентов, которые это поддерживают, запускает сервер, к которому агент обращается напрямую. [p02] ```prompt Подключи vibe ко всем агентам для кода, установленным на этой машине, для проекта VibeVM в текущей папке: установи навык vibevm и запись MCP-сервера, затем покажи мне, что записано и для каких агентов. ``` - needs: vibe в `PATH`; проект с `vibe.toml` в текущей папке; хотя бы один поддерживаемый агент: Claude Code, Claude Desktop, Cursor, OpenCode или Codex outcome: `vibe mcp status` показывает актуальную запись сервера и навык для каждого обнаруженного агента; следующая сессия агента в этом проекте знает команды vibe и может спрашивать о пакетах проекта - assert: `vibe mcp status` - assert: `vibe skill list --quiet` ## Что происходит {#what-happens} [p03] Агент выполняет `vibe mcp install --auto --yes`. vibe обнаруживает агентов на машине и записывает для каждого две вещи. Первая — запись в конфигурации агента, которая запускает `vibe mcp serve` как сервер, к которому агент может обращаться. Вторая — файл [навыка](../glossary/index.xml#skill), `SKILL.md`, который учит агента командам vibe и тому, когда ими пользоваться. Обе записи трогают только запись vibevm в каждой конфигурации; всё остальное в этих файлах остаётся как было. Команда идемпотентна: второй запуск сообщает о каждой неизменившейся записи как о неизменившейся. > [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] Это работает благодаря двум поверхностям. `vibe mcp serve` — сервер Model Context Protocol, который отдаёт любому агенту состояние проекта, выведенное из лока, в виде инструментов, а команды `vibe mcp` подключают его к собственной конфигурации каждого агента и пишут его `SKILL.md`. Набор агентов фиксирован: Claude Code, Claude Code Desktop, Cursor, OpenCode и Codex. Каждый глагол идемпотентен на матрице «агент и область», предлагает `--dry-run` и спрашивает перед записью. > [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 пишет в тот файл, который каждый агент действительно читает при обнаружении: для Claude Code это `.mcp.json` в проекте или таблица серверов верхнего уровня в `~/.claude.json`, и никогда файл настроек, который их только ограничивает. Он вставляет или обновляет свою единственную запись и сохраняет каждый чужой ключ в его порядке, так что большая конфигурация дополняется, а не переписывается; удаление вычищает только запись vibe. Для агентов с папкой навыков, Claude Code, OpenCode и Codex, он также пишет `SKILL.md` о том, как пользоваться vibe через инструменты. > [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} [p14] 1. Сначала посмотрите план; ничего не записывается: [p15] Example `mcp-status` is copied from the source page at projection time. [p16] 2. Установите для всех обнаруженных агентов или для одного: `--agent claude`, `--agent codex`, `--agent opencode`, `--agent cursor`, `--agent claude-desktop`: [p17] Example `mcp-install` is copied from the source page at projection time. [p18] 3. Выберите область: `--scope project` пишет в папки агентов внутри проекта, `--scope user` — в вашу домашнюю конфигурацию, `--scope both` — в обе. Без проекта в текущей папке пользовательская область выбирается за вас. ## Навыки, которые приносят пакеты {#skills-from-packages} [p19] Пакеты могут объявлять собственные навыки, и пакет может быть любого вида: flow приносит навык-чеклист, языковое руководство — навык обхода, руководство — навык чтения. `vibe skill list` показывает, что объявляют установленные пакеты, а `vibe skill install` проецирует их в папки навыков агентов. Установка навыка — это проекция файла, который пакет уже несёт, а не второй механизм доставки. > [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] Example `skill-list` is copied from the source page at projection time. [p24] Навык этого руководства, `vibevm-docs`, приходит тем же путём, как только руководство оказывается в машинном [хранилище](../glossary/index.xml#store). ## Серверы, которые приносят пакеты {#servers-from-packages} [p25] Пакет вида `mcp` доставляет сервер, собранный из его собственного кода, например инструменты дисциплины языкового [семейства](../glossary/index.xml#family). `vibe mcp install` регистрирует такие серверы в конфигурациях агентов рядом с сервером самого vibe, с путём к собранному бинарнику; `vibe mcp status` сообщает, собран ли каждый и актуален ли он. Зарегистрировать сервер — значит, что агент будет запускать код этого пакета в начале сессии, поэтому регистрация спрашивает согласия, как установка. > [p26] Registering a server schedules package code execution at agent-session > start; building its binary compiles package code. > > [p27] Каждый установленный пакет вида `mcp` вносит свои серверы в одну и ту же регистрацию, и она относится к проекту, потому что серверы проекта принадлежат его закоммиченной конфигурации. В JSON-файле vibe держит маленький список `vibevm.managed` с именами записей, которыми владеет, так что переустановка переписывает только их и никогда не трогает сервер, который вы добавили сами. Ворота согласия те же, что у бинарников: пакеты группы `org.vibevm` в белом списке, любому другому происхождению нужен `--assume-yes`. `vibe mcp status` говорит, собран ли бинарник каждого сервера. > [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} [p33] `vibe mcp upgrade` после обновления vibe приводит существующие интеграции к форме, которую несёт текущий бинарник; ничего нового он не создаёт. [p34] `vibe mcp uninstall` удаляет запись и навык vibe и оставляет каждую чужую запись на месте; `vibe skill uninstall` вычищает только навыки, которые спроецировал vibe. > [p35] **`vibe skill uninstall …`** — the inverse; strips only vibevm-projected > skills, leaves foreign skill dirs untouched. > > [p36] Cursor и Claude Desktop принимают запись сервера, но папок навыков у них нет; vibe сообщает, что навык для них пропущен, а не выдумывает место.