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

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

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

bash

aiman add skill path/to/skill.md

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

bash

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

Из stdin:

bash

cat skill.md | aiman add skill -

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

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

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

bash

aiman add mcp path/to/server.yaml

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

bash

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

Из stdin:

bash

cat server.yaml | aiman add mcp -

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

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

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

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

bash

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

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

bash

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

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

Cursor не хранит скиллы нативно — --from cursor всегда вернёт пустой результат.

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

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

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

bash

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

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

bash

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

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

bash

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

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

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

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

bash

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

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

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

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

bash

$EDITOR skills/review-code.md
aiman apply

Что делает apply:

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

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

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

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

bash

aiman status
aiman push

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

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

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

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

text

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 и отправляет его в удалённый репозиторий. После публикации он показывает состав опубликованных изменений:

text

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

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

bash

aiman push --dry-run

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

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

bash

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

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

text

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

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

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

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

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

bash

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

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

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

bash

aiman sync --force

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

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

text

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

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

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

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

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

Задача	Команда
Добавить скилл из файла	`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 status`
Опубликовать готовый инвентарь	`aiman push`
Применить опубликованный инвентарь на машине	`aiman sync`
Проверить окружение и конфиги	`aiman doctor`

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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