agents и подключение
~/.agents — общая настройка всех ИИ-агентов машины. Навык, правило или MCP-сервер вы описываете один раз, а каждый подключённый ИИ-агент видит его на своём обычном месте.
Что лежит в ~/.agents
У каждого вида элементов один формат — формат agents. Он не принадлежит ни одному ИИ-агенту: где есть открытый стандарт, это стандарт (SKILL.md, AGENTS.md, mcpServers), а для хуков, субагентов и команд — общее ядро со словами agents и разделы расширений по ИИ-агентам.
| Путь | Вид | Страница |
|---|---|---|
skills/<навык>/SKILL.md | навыки | Навыки |
agents/*.md | субагенты | Субагенты и команды |
commands/*.md | пользовательские команды | Субагенты и команды |
AGENTS.md | файл инструкций | Файл инструкций |
mcp.json | MCP-серверы | MCP-серверы |
plugins.json | записи плагинов | Плагины |
hooks.json | хуки | Хуки |
.env | значения секретов | MCP-серверы |
Подключение
agentsync claude onИмя ИИ-агента — имя из каталога ИИ-агентов или его синоним: claude и claude-code называют одну программу. Аккаунт, вход и сервер не нужны: подключение работает без сети.
Каждый вид элементов ИИ-агент получает одним из двух способов:
- Ссылкой — навыки, файл инструкций, а также субагенты и команды, которым перевод не нужен. Правка в
~/.agentsсразу видна ИИ-агенту, повторятьonне нужно. - Переводом — MCP-серверы, плагины, хуки, а также субагенты и команды, которым нужен перевод.
onвписывает их в формате ИИ-агента, и машина помнит, какие записи и файлы вписала она. Изменения этих видов доходят до ИИ-агента после повторногоon.
Вид, который ИИ-агент не понимает, пропускается. Это не отказ.
Вывод
ИИ-агент codex видит из agents: субагенты, файл инструкций, MCP-серверы.
Пропущены виды, которых ИИ-агент не понимает: пользовательские команды, плагины, субагенты writer.Если переменной секрета нет ни в окружении, ни в ~/.agents/.env, а ИИ-агент её не раскрывает, вывод называет и её:
Переменные секрета вписаны как есть, их значения нет в окружении и ~/.agents/.env: GITHUB_TOKEN.Что получает каждый ИИ-агент
| Вид | Claude Code | Codex | Gemini CLI | Grok Build | Остальные |
|---|---|---|---|---|---|
| Навыки | ~/.claude/skills | ~/.codex/skills | ~/.gemini/skills | ~/.grok/skills | свой каталог навыков |
| Субагенты | ~/.claude/agents | ~/.codex/agents, только read-only | ~/.gemini/agents | ~/.grok/agents | Copilot: ~/.copilot/agents; Cursor: ~/.cursor/agents, только readonly |
| Команды | ~/.claude/commands | — | ~/.gemini/commands, TOML | читает ~/.agents/commands сам | — |
| Файл инструкций | ~/.claude/CLAUDE.md | ~/.codex/AGENTS.md | ~/.gemini/GEMINI.md | — | — |
| MCP-серверы | ~/.claude.json | ~/.codex/config.toml | ~/.gemini/settings.json | ~/.grok/config.toml | — |
| Плагины | ~/.claude/settings.json | — | — | — | — |
| Хуки | ~/.claude/settings.json | ~/.codex/hooks.json | ~/.gemini/settings.json | ~/.grok/hooks/agentsync.json | GitHub Copilot: ~/.copilot/hooks/agentsync.json |
CLAUDE_CONFIG_DIR и CODEX_HOME переносят домашнюю папку Claude Code и Codex; подключение их учитывает. Полный список ИИ-агентов и их каталогов: Каталог ИИ-агентов.
Занятое имя
Если у ИИ-агента уже есть собственная папка или файл с именем элемента ~/.agents (например, свой CLAUDE.md или навык grill-me), on сначала создаёт снимок ИИ-агента в его хранилище и переносит туда эту папку целиком, затем ставит ссылку. Прежнюю папку возвращает agentsync revert <ии-агент>.
Собственные элементы ИИ-агента с другими именами остаются у него и в ~/.agents не переходят.
Повторное подключение
Повторный on синхронизирует ИИ-агента с текущим ~/.agents:
- убирает ссылку на элемент, которого в
~/.agentsбольше нет; - убирает свою запись MCP, плагина или хука, которой в
~/.agentsбольше нет; - вписывает новые записи.
Одноимённую чужую запись MCP, плагина или хука on заменяет и запоминает прежнюю. off её возвращает.
Отключение
agentsync claude off- Ссылки на
~/.agentsуходят из всех мест ИИ-агента, в том числе ссылки на удалённые элементы. - Из файлов настроек уходят только записи, которые вписал
on. Заменённые чужие записи возвращаются. - Собственные файлы ИИ-агента и сам
~/.agentsостаются. - Без ссылок и своих записей команда ничего не меняет и не падает.
Собственный файл, который on убрал в снимок ради ссылки, возвращает agentsync revert <ии-агент>.
Отказ подключения
Эти причины проверяются до изменения файлов, поэтому при отказе домашняя папка ИИ-агента не меняется.
| Пояснение | Что сделать |
|---|---|
В agents нечего показать. | Положите в ~/.agents хотя бы один элемент. |
ИИ-агента «…» нет в каталоге ИИ-агентов. | Проверьте имя по каталогу. |
| Два навыка с одним именем папки | Переименуйте одну из папок в ~/.agents/skills. |
Секрет в файле <путь>. | Замените значение переменной секрета ${NAME}. |
Система не разрешила создать ссылку… | На Windows включите режим разработчика (Параметры → Для разработчиков) или запустите команду от администратора. |
Если подключение обрывается на середине, оно возвращает домашнюю папку ИИ-агента к состоянию до попытки.
ИИ-агенты, которые читают ~/.agents сами
Cline, Warp, Zed, Droid и ещё несколько ИИ-агентов читают навыки прямо из ~/.agents/skills. Для них on навыки не трогает, а off отказывает: отключить их нельзя.
ИИ-агенты не зависят друг от друга
ИИ-агент получает элементы ~/.agents только своим подключением, а не через файлы другого ИИ-агента. Grok Build по умолчанию читает и навыки, MCP и хуки Claude Code и Cursor ([compat.claude], [compat.cursor] в ~/.grok/config.toml). Тогда один элемент ~/.agents дошёл бы до Grok дважды. Поэтому agentsync grok on выставляет false для ключей видов, которые Grok получает из ~/.agents (skills, mcps, hooks), и запоминает прежние значения. Остальные ключи таблиц остаются. agentsync grok off возвращает прежние значения.
Публикация и откат ~/.agents
agentsync record
agentsync push
agentsync revert agentsПубликуется и хранится на сервере именно каталог ~/.agents (карточка agents). Снимок не берёт ~/.agents/.env. Применение публикации agents точно заменяет ~/.agents: подробно в Применение.