Концепции

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-средой.

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 -

При добавлении 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 --dry-run

При импорте 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-среды. Это перенос на другую машину или обновление текущей.

aim.local.yaml

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

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

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

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

---

Дальше

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