Рабочие циклы

Добавление скилла из файла

Чтобы добавить готовый навык в инвентарь:

aiman add skill path/to/skill.md

Если файл с таким именем уже существует в инвентаре с другим содержимым:

aiman add skill path/to/skill.md --overwrite    # перезаписать
aiman add skill path/to/skill.md --name new-name  # сохранить под другим именем

Из stdin:

cat skill.md | aiman add skill -

После добавления запустите aiman push, чтобы опубликовать изменение.

Добавление MCP-сервера из файла

Чтобы добавить конфигурацию MCP-сервера в инвентарь:

aiman add mcp path/to/server.yaml

Если файл с таким именем уже существует в инвентаре с другим содержимым:

aiman add mcp path/to/server.yaml --overwrite    # перезаписать
aiman add mcp path/to/server.yaml --name new-name  # сохранить под другим именем

Из stdin:

cat server.yaml | aiman add mcp -

Если входной файл содержит поля value в блоке env, AIM автоматически переносит их в aim.local.yaml и не записывает в mcp/<name>.yaml. Это гарантирует, что секреты не попадут в Git.

После добавления запустите aiman push, чтобы опубликовать изменение.

У меня уже всё настроено: aiman import

Частый случай первого запуска: на машине уже стоят скиллы и MCP-серверы в Claude Code, Cursor или Codex — их не нужно переносить по одному вручную.

aiman import

Без флагов команда сканирует все три среды и печатает план — что нашла, что можно перенести, где конфликт. Ничего не пишет:

Scanned: ~/.claude, ~/.codex, ~/.cursor — no network requests, nothing leaves this machine
Claude Code   1 skill, 1 MCP server
Codex   nothing found
Cursor   nothing found

found: 2 occurrences → 2 unique items

ready to import: 2
  mcp:context7
  skill:review-code

Run: aiman import --yes to import 2 items and store 1 local MCP value
Nothing will change until --yes is used. No AI environment or remote repository is touched.

Посмотрели план глазами — выполните его:

aiman import --yes

imported: 2
  mcp:context7
  skill:review-code
Stored 1 local MCP value in aim.local.yaml (never published)
Next: aiman apply to deliver, aiman push to publish

Дальше — обычный цикл: aiman push, чтобы опубликовать.

Ограничить скан одной средой можно через повторяемый --from:

aiman import --from codex

Если один и тот же элемент найден в нескольких средах с разным содержимым — план покажет его в категории conflicts, ничего не запишет и не выберет вариант по порядку обхода. Разрешить такой конфликт — точечно, тем же aiman import skill|mcp <name> --from <env>, что и раньше.

Полная модель — occurrence, unique item, три слоя кандидата, три типа конфликта — в Концепциях; полный контракт команды и флагов — в Справочнике CLI.

Импорт скилла из AI-среды

Импорт пишет только в активный репозиторий инвентаря. Если он ещё не подключён, команда завершится ошибкой no active inventory repository; run 'aiman init' first, не создав ничего в текущей директории — сначала выполните aiman init <url> или aiman switch <path>.

Если навык уже установлен в одной из AI-сред, его можно импортировать напрямую:

aiman import skill hello --from claude-code
aiman import skill review-code --from codex

Посмотреть содержимое без записи:

aiman import skill hello --from claude-code --print

Поддерживаемые источники: claude-code, cursor, codex.

Скилл переносится целиком: если в среде он лежит папкой (<name>/SKILL.md плюс references/, скрипты), в инвентарь попадают и SKILL.md, и все ресурсные файлы, включая исполняемый бит скриптов — он сохраняется и при переносе в инвентарь, и при последующей установке в AI-среду.

После добавления запустите aiman push, чтобы опубликовать изменение.

Импорт MCP-сервера из AI-среды

Если MCP-сервер уже настроен в одной из AI-сред, его можно импортировать напрямую:

aiman import mcp context7 --from claude-code
aiman import mcp jira --from cursor

Посмотреть содержимое без записи:

aiman import mcp context7 --from claude-code --print

Импортировать и установить все три AI-среды как целевые:

aiman import mcp context7 --from claude-code --targets all

Поддерживаемые источники: claude-code, cursor, codex.

AIM читает живую конфигурацию указанной среды, извлекает дескриптор MCP-сервера и применяет env-strip: реальные значения env-переменных записываются в aim.local.yaml, в инвентарь и Git попадают только дескрипторы без секретов. Дескрипторы env-переменных сортируются по имени, поэтому повторный импорт неизменённого сервера не даёт лишних диффов в Git.

Импортировать можно только stdio-серверы — те, у которых в конфигурации среды задан command. Сервер, объявленный через "type": "http", "type": "sse" или голый "url", не импортируется: команда завершается ошибкой с причиной и ничего не пишет в инвентарь.

Если сервер с таким именем уже есть в инвентаре с другим содержимым, команда завершится с ошибкой. Для перезаписи используйте --overwrite:

aiman import mcp context7 --from claude-code --overwrite

После добавления запустите aiman push, чтобы опубликовать изменение.

Локальная итерация: edit -> apply -> test

Используйте aiman apply, когда хотите проверить изменение до публикации.

$EDITOR skills/review-code.md
aiman apply

Что делает apply:

• читает локальные skills/ и mcp/;
• валидирует элементы;
• применяет валидные элементы в обнаруженные AI-среды;
• не делает commit;
• не обращается к remote;
• не обновляет published_hash и synced_hash.

Этот цикл подходит для разработки навыков: правка, применение, проверка в AI-инструменте, повторная правка. Большинство AI-сред читают навыки при старте сессии — после aiman apply перезапустите сессию агента, чтобы изменения подхватились.

Контекстное переключение: apply --loadout

Когда инвентарь разрастается, не каждый навык нужен в каждой задаче. Loadout — именованное подмножество инвентаря — позволяет держать в AI-средах только релевантный набор.

Опишите набор в loadouts/<name>.yaml:

# loadouts/documentation-work.yaml
name: Documentation Work
description: Навыки и MCP для работы с документацией
items:
  - skill:create-spec
  - skill:wpage
  - mcp:context7

Посмотрите план и примените:

aiman apply --loadout documentation-work --dry-run
aiman apply --loadout documentation-work

Применение декларативное: среды приводятся ровно к набору loadout. Элементы инвентаря вне loadout удаляются из сред (D в составе изменений), файлы вне инвентаря не затрагиваются. Всегда начинайте с --dry-run — он показывает, что именно будет удалено:

[dry-run] would apply loadout "Documentation Work" — 4 changes to 1 environment (claude-code):
  A skills/create-spec.md   (new in all environments)
  D skills/review-code.md   (would remove from all environments)
  M skills/wpage.md   (differs in all environments)
  A mcp/context7.yaml   (new in all environments)

Вернуться к полному набору — обычный aiman apply или aiman sync.

Чтобы loadout был доступен на других машинах, его нужно опубликовать — aiman push проверяет файлы loadouts/ и публикует их вместе с остальным инвентарём:

aiman push

Обновление remote без выхода из loadout: пин

aiman sync по умолчанию — транспорт полного инвентаря: он применяет весь инвентарь и расширяет среду обратно до полного набора, даже если до этого вы сузили её через apply --loadout. Для разовой синхронизации это можно обойти паттерном sync → apply --loadout <name>, но при частых обновлениях remote придётся повторять его каждый раз.

Если вы работаете в узком loadout продолжительное время — например, несколько дней занимаетесь только документацией — и хотите, чтобы sync сам применял именно этот набор, закрепите loadout пином:

aiman apply --loadout documentation-work --pin

Пин — это сохранённое состояние в глобальном конфиге, а не разовое действие: он остаётся активным между запусками CLI, пока вы не смените его явно. Пока пин установлен, aiman sync вместо полного инвентаря декларативно приводит среды к набору пинованного loadout — так же, как apply --loadout <name>, включая удаление элементов вне набора:

aiman sync

applying loadout "documentation-work" (pinned)
synced: 67451fc · 2 skills, 1 MCP server → 1 environment
  A skills/create-spec.md   (new in all environments)
  M skills/wpage.md   (updated in all environments)

Проверить, какой loadout закреплён сейчас, можно через aiman status — поле Pinned loadout: показывает его имя или none.

Чтобы вернуться к полному инвентарю и снять пин одним действием:

aiman apply --default

Чтобы просто снять пин, ничего не применяя (например, если вы хотите вручную выбрать следующий loadout):

aiman apply --unpin

Если пин указывает на loadout, которого больше нет (переименовали, удалили, или switch привёл к репозиторию без такого имени), sync останавливается с ошибкой вместо тихого отката к полному набору:

error: pinned loadout "documentation-work" not found in inventory

Снимите пин (aiman apply --unpin или --default) или восстановите loadout под ожидаемым именем — подробнее в Устранении проблем.

aiman switch на другой репозиторий инвентаря всегда снимает пин безусловно, даже если в новом репозитории есть loadout с таким же именем — заново закрепите его через apply --loadout <name> --pin, если нужно.

Подробнее о том, чем пин отличается от разового apply --loadout <name> — в Концепциях. Полное описание флагов и вывода — в Справочнике CLI.

Публикация: status -> push

Когда локальное изменение готово:

aiman status
aiman push

status показывает позицию репозитория относительно origin/main, состояние AI-сред и список изменений в skills/, mcp/ и loadouts/.

status — сетевая команда: перед расчётом позиции она выполняет Git fetch, поэтому позиция отражает фактическое состояние remote, а не устаревший локальный ref. Короткая задержка на fetch — ожидаемое поведение. Подробнее о том, почему это отличается от git status — в Концепциях.

TODO: добавить спиннер во время fetch

Пример вывода при наличии неопубликованных изменений:

Repository:   git@github.com:you/aim-loadout.git
Position:     2 commits ahead of origin/main
Environments: needs sync (2 commits not applied)

Changes not yet published (origin/main → working tree):
  A skills/new-skill.md
  M skills/existing.md

  run aiman push to publish

push валидирует инвентарь, создаёт commit и отправляет его в удалённый репозиторий. Если в репозитории есть loadouts/, валидируются и loadout-файлы: формат и ссылочная целостность items (сломанная ссылка блокирует публикацию). После публикации он показывает состав опубликованных изменений:

published: 96e091b · 19 skills, 1 MCP server
  M skills/review-code.md
  A mcp/jira.yaml

push --dry-run показывает план публикации без записи в Git:

aiman push --dry-run

Перенос на другую машину: init -> sync

На новой машине:

aiman init git@github.com:you/aim-loadout.git
aiman sync

sync выполняет Git fetch, проверяет историю, получает опубликованное состояние и применяет его в локальные AI-среды. После применения он показывает состав прилетевших изменений:

synced: 67451fc · 21 skills, 1 MCP server → 3 environments
  M skills/commit-message.md
  A skills/refactor-helper.md

Счётчики строки результата — это объём операции (всего применено), а блок ниже — состав изменений. Если из remote ничего не прилетело, блок не печатается.

Вторая машина: sync -> import -> push

Если на новой машине AI-среды уже были настроены раньше (например, скиллы и MCP-серверы стояли локально ещё до перехода на AIM), рекомендуемый цикл — sync, затем discovery, затем push:

aiman init git@github.com:you/aim-loadout.git
aiman sync             # подтянуть то, что уже опубликовано с других машин
aiman import           # план: что из уже установленного ещё не в инвентаре
aiman import --yes     # перенести найденное
aiman push              # опубликовать

Правила сходимости для этого цикла:

• portable-элемент, уже опубликованный с другой машины, после sync не дублируется — discovery увидит его как already in inventory, даже если тот же скилл или MCP-сервер стоит и в локальной AI-среде;
• при этом отсутствующее локальное значение MCP env (aim.local.yaml не синхронизируется через Git) discovery всё равно заполнит — значения env всегда локальны для каждой машины и импортируются на ней отдельно;
• если та же новая среда независимо импортировала элемент до того, как он был опубликован с первой машины, обычный guard push/sync остановит гонку на второй машине — опубликуйте сначала с первой, затем sync на второй.

Защита от потери изменений

sync не блокируется, если в skills/, mcp/ или loadouts/ есть неотслеживаемые файлы — при условии, что они не конфликтуют по имени с файлами из remote. Новый навык или loadout, ещё не закоммиченный, сохранится.

Если неотслеживаемый файл совпадает по имени с файлом из remote, sync останавливается и выводит список конфликтующих файлов:

aiman sync
# error: untracked file conflicts with remote: skills/review-code.md

Варианты действий:

• опубликовать конфликтующий файл через aiman push;
• переименовать или переместить файл вручную;
• применить опубликованное состояние с удалением конфликтующих файлов:

aiman sync --force

Внимание: sync --force безвозвратно удаляет конфликтующие файлы. Используйте только если их потеря допустима.

--force не удаляет файлы молча: перед применением состояния AIM выводит список того, что удалил:

discarded untracked files (--force):
  skills/draft.md
  mcp/local-only.yaml
synced: 67451fc · 21 skills, 1 MCP server → 3 environments

Защита покрывает skills/, mcp/ и loadouts/: неотслеживаемый файл в любой из этих директорий либо сохраняется, либо явно попадает в список конфликтов.

Состояния истории

После fetch AIM различает несколько ситуаций:

Состояние	Поведение
Local уже равен remote	применить инвентарь без reset
Local отстаёт от remote	fast-forward reset и применить
Local содержит неопубликованные commit'ы	остановиться и попросить aiman push
История разошлась	остановиться и попросить ручное восстановление Git

Когда использовать какую команду

Задача	Команда
Посмотреть, что можно перенести из уже настроенных AI-сред	aiman import
Перенести всё безопасное из плана discovery	aiman import --yes
Добавить скилл из файла	aiman add skill <file>
Добавить MCP-сервер из файла	aiman add mcp <file>
Импортировать скилл из AI-среды	aiman import skill <name> --from <env>
Просмотреть содержимое скилла без записи	aiman import skill <name> --from <env> --print
Импортировать MCP-сервер из AI-среды	aiman import mcp <name> --from <env>
Просмотреть MCP-дескриптор без записи	aiman import mcp <name> --from <env> --print
Проверить локальный навык без публикации	aiman apply
Применить именованное подмножество инвентаря	aiman apply --loadout <name>
Посмотреть план loadout до применения	aiman apply --loadout <name> --dry-run
Опубликовать новый или изменённый loadout	aiman push
Закрепить loadout, чтобы sync применял его вместо полного инвентаря	aiman apply --loadout <name> --pin
Проверить, какой loadout закреплён	aiman status
Вернуться к полному инвентарю и снять пин	aiman apply --default
Снять пин, ничего не применяя	aiman apply --unpin
Посмотреть, что изменено	aiman status
Опубликовать готовый инвентарь	aiman push
Применить опубликованный инвентарь на машине	aiman sync
Проверить окружение и конфиги	aiman doctor