Концепции

Loadout

Loadout — метафора продукта: полный патронташ разработчика, работающего с AI-инструментами. В него входят навыки, MCP-серверы и настройки, которые делают AI-среды готовыми к работе.

Команда aiman sync — быстрая перезарядка этого патронташа на новой машине.

В будущем loadout также станет технической сущностью: именованным подмножеством инвентаря, например Documentation Work или Architecture Work. В текущем MVP такой возможности нет: AIM применяет весь валидный инвентарь целиком.

Inventory

Inventory (инвентарь) — Git-репозиторий с файлами, которые AIM применяет в AI-среды пользователя.

В текущей модели инвентарь содержит:

• skills/ — навыки;
• mcp/ — MCP-серверы;
• aim.yaml — общий конфиг;
• .gitignore — как минимум исключает aim.local.yaml;
• aim.local.yaml — локальный файл на каждой машине, не хранится в Git.

Library Item

Library Item — единица инвентаря. В текущем MVP есть два типа: Skill Item и MCP Item.

Кандидатом на место в инвентаре становится сущность, которую AI-среды приняли как промышленный стандарт: у неё есть устоявшийся формат, её поддерживают несколько производителей, и её можно перенести между средами без существенных изменений. Такая сущность имеет смысл как переносимый актив — её стоит хранить централизованно и применять через адаптеры.

Skill Item

Skill Item — Markdown-инструкция для AI-среды.

Файл хранится как skills/<name>.md:

---
name: review-code
description: Проведи code review с фокусом на корректность
targets:
  - claude-code
  - cursor
tags:
  - review
---

# Role

...

После применения AIM устанавливает навык в формат, ожидаемый конкретной AI-средой.

Навык может храниться в виде папки (skills/<name>/SKILL.md) с дополнительными справочными файлами — например agent-patterns.md или examples.md. В этом случае AIM копирует всю папку целиком. Подробнее — в Справочнике формата инвентаря.

MCP Item

MCP Item — YAML-описание MCP-сервера:

name: context7
description: Документация библиотек через MCP
command: npx
args:
  - -y
  - "@upstash/context7-mcp"
targets:
  - claude-code
  - cursor
  - codex
env:
  - name: API_KEY
    description: API key
    required: true

Значения env-переменных не хранятся в Git. AIM запрашивает их локально и сохраняет в aim.local.yaml.

Потенциальные будущие типы

По мере того как AI-среды договариваются о новых стандартах, в инвентарь могут войти дополнительные типы.

Инструкция субагента. Claude Code уже поддерживает инструкции для субагентов. Когда этот формат примут Codex CLI и Cursor, он может стать самостоятельным Library Item.

Системная инструкция проекта / директории. Claude Code хранит её в CLAUDE.md, Codex — в AGENTS.md, Cursor читает оба файла. Эти инструкции уже де-факто конвергируют к схожему формату. В перспективе AIM сможет хранить такую инструкцию как единый актив и при sync распределять её по средам через адаптеры.

В текущем MVP ни один из этих типов не реализован. Library Item — это только Skill Item или MCP Item.

Сбор инвентаря

Прежде чем управлять инвентарём, его нужно наполнить. AIM поддерживает два способа добавления элементов.

aiman add — из локального файла или stdin:

aiman add skill cool-skill.md
cat prompt.md | aiman add skill -

aiman add mcp jira.yaml
cat jira.yaml | aiman add mcp -

aiman add skill принимает и путь к папочному скиллу (или его SKILL.md) — в этом случае в инвентарь копируется вся папка: SKILL.md и все файлы-references рядом с ним.

При добавлении MCP-сервера AIM автоматически извлекает реальные значения env-переменных из файла и сохраняет их в aim.local.yaml — в инвентарь (и в Git) попадают только дескрипторы без секретов.

aiman import — из установленной AI-среды:

aiman import skill review-code --from claude-code
aiman import skill my-prompt --from codex

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

При импорте MCP-сервера AIM читает живую конфигурацию AI-среды, применяет env-strip и записывает дескриптор в mcp/<name>.yaml. Реальные значения env-переменных при этом попадают в aim.local.yaml, но не в Git.

После добавления элемент появляется в локальном инвентаре (skills/<name>.md или mcp/<name>.yaml). Для публикации используйте aiman push.

Подробнее о конкретных командах и флагах — в Справочнике CLI.

Adapter

Adapter — часть AIM, которая знает формат конкретной AI-среды.

Адаптер отвечает за:

• обнаружение базовой директории AI-среды;
• сканирование навыков при aiman import skill — адаптер знает, где AI-среда хранит навыки;
• сканирование MCP-конфигурации при aiman import mcp — адаптер читает живой конфиг среды;
• установку Skill Item;
• запись MCP-сервера в нужный JSON или TOML-конфиг.

Поддерживаемые среды:

• Claude Code;
• Cursor;
• Codex CLI.

apply, push и sync

aiman apply применяет текущее локальное рабочее дерево без Git-операций. Это внутренний цикл разработки навыка.

aiman push валидирует инвентарь, делает commit и отправляет изменения в удалённый репозиторий. Это публикация.

aiman sync получает опубликованное состояние из Git и применяет его в локальные AI-среды. Это перенос на другую машину или обновление текущей.

Состав изменений в результате

Все три команды после строки результата показывают состав изменений — что именно добавлено (A), изменено (M) или удалено (D):

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

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

Для навыков состав изменений вычисляется сравнением содержимого. Для MCP-серверов он пока не вычисляется (см. Известное ограничение в справочнике).

Почему aiman status обращается к remote

aiman status отвечает на вопрос «что в моём инвентаре изменилось относительно опубликованного состояния». Этот вопрос по определению включает состояние remote, поэтому перед расчётом позиции команда выполняет Git fetch.

Это осознанное отличие от локального git status, который к сети не обращается: его вопрос — только о локальном рабочем дереве. У aiman status нет «честного» локального ответа — без fetch позиция строилась бы по устаревшему ref и могла бы вводить в заблуждение. Поэтому короткая задержка на fetch — ожидаемое поведение, а не сбой. Если remote недоступен, status не зависает: позиция показывается как unknown (remote unreachable), а команда завершается успешно.

aim.local.yaml

aim.local.yaml создаётся на каждой машине отдельно и не попадает в Git.

В нём хранятся:

• пути к AI-средам;
• hash-метки последнего успешного push и sync;
• локальные значения env-переменных MCP-серверов.

Hash-метки информационные: они помогают объяснить состояние, но безопасность push и sync опирается на состояние Git.

---

Дальше

• Рабочие циклы — сбор, публикация и синхронизация инвентаря.
• AI-среды — поддерживаемые адаптеры и пути обнаружения.
• Структура репозитория — полный формат инвентаря.
• Справочник CLI — все команды.