Формат инвентаря

Skill Item

Путь:

skills/<name>.md

Пример:

---
name: create-spec
description: Написать лаконичное ТЗ для разработчика
targets:
  - claude-code
  - cursor
---

# Role

...

Поля:

Поле	Обязательно	Описание
name	да	Идентификатор навыка; должен совпадать с именем файла
description	да	Короткое описание навыка; без него навык считается невалидным и не применяется
targets	нет	Список AI-сред, ограничивающий доставку навыка; см. ниже

Тело Markdown после frontmatter не должно быть пустым.

targets ограничивает доставку. Поле влияет на применение на всех путях — apply, sync, apply --loadout и pinned sync. Если поле отсутствует или список пуст, навык применяется во все обнаруженные AI-среды — это поведение по умолчанию. Если список непустой, навык устанавливается только в перечисленные среды из числа обнаруженных.

Это отличается от MCP Item, где targets обязателен: пустой список у MCP Item — ошибка валидации, у Skill Item — «применить везде». Асимметрия осознанная: превращение поля в обязательное сломало бы существующие инвентари, где навыки заведены без targets.

Имена сред в targets не валидируются: опечатка (например, claud-code) не даёт ошибки — навык просто не попадёт ни в одну среду.

Folder Skill

Skill Item может храниться в виде папки:

skills/<name>/SKILL.md
skills/<name>/agent-patterns.md   # опциональные справочные файлы
skills/<name>/delegation.md
skills/<name>/examples.md

SKILL.md — основной файл навыка с frontmatter и телом. Остальные файлы в папке — справочные: их можно упомянуть в SKILL.md через @mention. При установке навыка папка целиком копируется в AI-среду.

Приоритет: если одновременно существуют skills/<name>.md и skills/<name>/SKILL.md, используется плоский файл (<name>.md).

Для папочного навыка name берётся из имени директории, а не из frontmatter; description и непустое тело в SKILL.md обязательны так же, как у плоского навыка.

Ограничение: apply --dry-run и расчёт дельты сравнивают только хеш SKILL.md. Изменения в справочных файлах папки не отображаются в составе изменений. По той же причине aiman add skill <dir> и aiman import skill считают навык already identical, если SKILL.md не изменился, — изменения только в справочных файлах в инвентарь не переносятся.

Ограничение: права доступа к файлам не сохраняются ни при добавлении в инвентарь, ни при установке в AI-среду — все файлы записываются как 0644. Исполняемый бит скриптов внутри папочного навыка теряется.

MCP Item

Путь:

mcp/<name>.yaml

Пример:

name: context7
description: Документация библиотек через MCP
command: npx
args:
  - -y
  - "@upstash/context7-mcp"
targets:
  - claude-code
  - cursor
  - codex
env:
  - name: UPSTASH_REDIS_REST_URL
    description: URL Redis-хранилища Upstash
    required: true
    example: https://example.upstash.io

Поля:

Поле	Обязательно	Описание
name	да	Идентификатор MCP-сервера
description	нет	Короткое описание
command	да	Команда запуска
args	да	Список аргументов, может быть пустым
targets	да	Список AI-сред
env	да	Список env-переменных, может быть пустым

Env variable

Поле	Обязательно	Описание
name	да	Имя переменной
description	нет	Назначение переменной
required	да	Требовать значение при применении
example	нет	Пример значения

Значения env-переменных не хранятся в MCP Item. Они задаются локально и сохраняются в aim.local.yaml.

Loadout Item

Путь:

loadouts/<name>.yaml

Пример:

name: Documentation Work
description: Навыки и MCP для работы с документацией
targets:
  - claude-code
items:
  - skill:create-spec
  - skill:wpage
  - mcp:context7

Поля:

Поле	Обязательно	Описание
name	да	Человекочитаемый идентификатор loadout
description	нет	Назначение набора; при отсутствии — предупреждение
items	да	Непустой список ссылок skill:<name> или mcp:<name>
targets	нет	Ограничение допустимых AI-сред применения loadout

Инварианты:

• items не может быть пустым;
• каждая ссылка имеет префикс skill: или mcp: и непустое имя;
• каждый skill:<name> существует как skills/<name>.md или skills/<name>/SKILL.md;
• каждый mcp:<name> существует как mcp/<name>.yaml;
• имя файла — нормализация поля name (пробелы → дефисы, нижний регистр); несовпадение — предупреждение.

Формат и ссылочная целостность проверяются при aiman push. aiman apply --loadout останавливается на первой ошибке формата; ссылка на исчезнувший или невалидный элемент инвентаря при применении даёт предупреждение, элемент пропускается.

Пересечение targets

targets на уровне loadout — ограничение допустимых сред (whitelist), а не селектор доставки:

• targets указан — loadout применяется только в перечисленные среды из числа обнаруженных;
• targets не указан — ограничения на уровне loadout нет, действует item-level targets каждого элемента;
• loadout-level и item-level targets совмещаются как пересечение: элемент применяется в среду, только если она допустима на обоих уровнях. Это верно и для MCP Item (targets обязателен), и для Skill Item (targets опционален; отсутствие или пустой список на item-level не сужает пересечение — действует только loadout-level ограничение).

Два уровня ограничений ведут себя по-разному при удалении. Среда, отсечённая loadout-уровневым targets, в план не входит и не изменяется вовсе. Среда, оставшаяся в плане, приводится к желаемому набору целиком — поэтому элемент (навык или MCP-сервер), входящий в loadout, но не перечисливший эту среду в своём item-level targets, будет из неё удалён, если он там установлен. Для навыка это происходит только на declarative-пути (apply --loadout, pinned sync): на аддитивных путях (sync, apply без --loadout) навык только устанавливается в допустимые среды и никогда не удаляется, даже если targets впоследствии сузили.

Targets

Поддерживаемые значения:

• claude-code;
• cursor;
• codex.