Repository Structure

An inventory is a plain Git repository.

Top-level structure

<inventory>/
├── skills/
│   └── review-code.md
├── mcp/
│   └── context7.yaml
├── loadouts/
│   └── documentation-work.yaml
├── aim.yaml
└── .gitignore

The loadouts/ directory is optional: a repository without it is fully valid.

Each machine also creates locally:

aim.local.yaml

aim.local.yaml must not be committed to Git.

skills/

One file per Skill Item:

skills/<name>.md

The filename without .md must match the name field in the frontmatter.

A skill can also be stored as a folder — this is how aiman add skill <dir> and aiman import skill write a folder-format skill taken from an AI environment:

skills/<name>/SKILL.md
skills/<name>/references/...

In this case the directory name defines the skill name. See Inventory Format for details.

mcp/

One file per MCP Item:

mcp/<name>.yaml

The file describes the MCP server launch command, arguments, targets, and environment variables.

aim.yaml

Shared inventory config. Stored in Git.

.gitignore

Must at minimum exclude:

aim.local.yaml

aim.local.yaml

Machine-local config:

• AI environment paths;
• hash markers;
• MCP server env variable values.

The file is created by AIM and is not committed.

loadouts/

One file per Loadout Item — a named subset of the inventory:

loadouts/<name>.yaml

Example:

name: Documentation Work
description: Skills and MCP servers for documentation work
targets:
  - claude-code
items:
  - skill:create-spec
  - skill:wpage
  - mcp:context7

Filename convention: kebab-case; the filename is the name field after normalization (spaces → hyphens, lowercase). name: Documentation Work → loadouts/documentation-work.yaml. A mismatch is a warning during aiman push, not an error.

The directory is optional. aiman init does not create it — add it yourself when you need your first loadout.

A loadout is applied with aiman apply --loadout <name> (CLI Reference); field formats and invariants are in the Inventory Format Reference.

Publishing. aiman push validates loadouts/ and publishes these files together with skills/ and mcp/ — no separate git add is needed.