Concepts

Loadout

In AIM, the word "loadout" has two meanings: a product one and a technical one.

The loadout metaphor is a developer's complete toolkit for working with AI tools. It includes skills, MCP servers, and settings that make AI environments ready to use. aiman sync is the quick reload of that toolkit on a new machine. Hence the product name: AIM Loadout.

A technical loadout is a named subset of the inventory for context-specific work, such as Documentation Work or Architecture Work. It is stored as loadouts/<name>.yaml and applied with aiman apply --loadout <name> declaratively: AI environments are brought to exactly the loadout's set, within the items the inventory knows about. Inventory items outside the loadout are removed from environments; files created by hand or by another tool are never touched.

Meaning	What it covers	Command
Loadout metaphor	the entire inventory	aiman sync, aiman apply
Technical loadout	a named subset of the inventory	aiman apply --loadout <name>

aiman apply without --loadout operates in the virtual Default loadout mode: the entire valid inventory. Its behavior is additive — it installs and updates items, but never removes anything from environments. aiman sync has no --loadout flag at all — it is the transport for the full inventory — but its apply behavior depends on whether a pin is active: without a pin it is additive, just like apply without --loadout; with an active pin it declaratively brings environments to the pinned loadout's set, just like apply --loadout <name>.

For the context-switching scenario, see Workflows; for the file format, see the Inventory Format Reference.

Pinned loadout

apply --loadout <name> is a one-off action: it brings AI environments to the loadout's set once and remembers nothing. The next aiman sync expands environments back to the full inventory, because by default sync has no idea which set you chose with apply.

A pin is persisted state built on top of the same loadout mechanism: the name of the pinned loadout is stored in the global user config (~/.config/aim/config.yaml, field loadout) and stays active across CLI runs until explicitly cleared. While a pin is set, aiman sync declaratively brings environments to the pinned loadout's set instead of additively applying the full inventory — the same way as apply --loadout <name>, including removing items outside the set.

	apply --loadout <name>	apply --loadout <name> --pin
What happens	applies the set once	applies the set and remembers it as the active pin
What the next sync sees	knows nothing about the choice — applies the full inventory	applies the same loadout instead of the full inventory
Where it's stored	nowhere — the effect only lives in AI environments	in the global config, as loadout: <name>
How to clear it	nothing to clear — the next sync already applies the full set	aiman apply --unpin or aiman apply --default

The pin is controlled by apply flags:

• apply --loadout <name> --pin — apply and pin;
• apply --default — apply the full inventory and clear the pin in one action;
• apply --unpin — clear the pin without applying anything.

aiman status shows the active pin in the Pinned loadout: field. aiman switch to a different inventory repository unconditionally clears the pin, even if the new repository has a loadout with the same name — only one global pointer is stored per machine, not a separate pin per repository.

If the pin points to a loadout that no longer exists (renamed, deleted, or switch moved to a repository without a loadout of that name), sync stops with the error pinned loadout "X" not found in inventory instead of silently falling back to the full inventory — so the mismatch never goes unnoticed. This is a separate check from loadout "X" not found in loadouts/, which apply --loadout returns when no pin is involved.

For the full description of flags, conflicts, and output, see the CLI Reference; for the usage scenario, see Workflows.

Inventory

The inventory is a Git repository containing the files that AIM applies to your AI environments.

In the current model, the inventory contains:

• skills/ — skills;
• mcp/ — MCP servers;
• loadouts/ — named subsets of the inventory (optional);
• aim.yaml — shared config;
• .gitignore — at minimum excludes aim.local.yaml;
• aim.local.yaml — a local file on each machine, not stored in Git.

Library Item

A Library Item is a single unit of the inventory. In the current MVP, there are two types: Skill Item and MCP Item.

An entity becomes a candidate for the inventory when AI environments have adopted it as an industry standard: it has an established format, multiple vendors support it, and it can be moved between environments without significant changes. Such an entity makes sense as a portable asset — worth storing centrally and applying through adapters.

Skill Item

A Skill Item is a Markdown instruction for an AI environment.

The file is stored as skills/<name>.md:

---
name: review-code
description: Code review focused on correctness
targets:
  - claude-code
  - cursor
---

# Role

...

When applied, AIM installs the skill in the format expected by the specific AI environment.

A skill can also be stored as a folder (skills/<name>/SKILL.md) with additional reference files — for example agent-patterns.md or examples.md. In that case, AIM copies the entire folder. See the Inventory Format Reference for details.

MCP Item

An MCP Item is a YAML description of an MCP server:

name: context7
description: Library documentation via MCP
command: npx
args:
  - -y
  - "@upstash/context7-mcp"
targets:
  - claude-code
  - cursor
  - codex
env:
  - name: API_KEY
    description: API key
    required: true

Environment variable values are not stored in Git. AIM prompts for them locally and saves them in aim.local.yaml.

Potential future types

As AI environments agree on new standards, additional types may be added to the inventory.

Sub-agent instruction. Claude Code already supports sub-agent instructions. When Codex CLI and Cursor adopt this format, it could become a standalone Library Item.

Project/directory system instruction. Claude Code stores this in CLAUDE.md, Codex in AGENTS.md, and Cursor reads both. These instructions are already converging to a similar format. In the future, AIM could store such an instruction as a single asset and distribute it across environments via adapters on sync.

Neither type is implemented in the current MVP. A Library Item is only a Skill Item or an MCP Item.

Collecting inventory

Before managing inventory, you need to populate it. AIM supports two ways to add items.

aiman add — from a local file or 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 also accepts a path to a folder skill (or its SKILL.md) — in that case, AIM copies the entire folder into the inventory: SKILL.md plus all reference files alongside it.

When adding an MCP server, AIM automatically extracts real env variable values from the file and saves them to aim.local.yaml — only descriptors without secrets end up in the inventory (and in Git).

aiman import — from an installed AI environment:

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

aiman import writes only to the active inventory repository: without a connected repository, the command fails and asks you to run aiman init instead of creating files in the current directory.

When you import a skill that the environment stores as a folder (<name>/SKILL.md with resource files), the whole folder is transferred into the inventory — the same way aiman add skill <dir> handles it.

When importing an MCP server, AIM reads the live configuration of the AI environment, applies env-strip, and writes the descriptor to mcp/<name>.yaml. The real env variable values go to aim.local.yaml, not to Git. Only stdio servers (those with a command field) are imported; AIM does not transfer servers that use an HTTP/SSE transport.

After adding, the item appears in the local inventory (skills/<name>.md or mcp/<name>.yaml). To publish, run aiman push.

For details on specific commands and flags, see the CLI Reference.

Adapter

An adapter is the part of AIM that knows the format of a specific AI environment.

An adapter is responsible for:

• discovering the AI environment's base directory;
• scanning skills during aiman import skill — the adapter knows where the environment stores skills;
• scanning MCP configuration during aiman import mcp — the adapter reads the live environment config;
• installing a Skill Item;
• writing an MCP server entry to the appropriate JSON or TOML config.

Supported environments:

• Claude Code;
• Cursor;
• Codex CLI.

apply, push, and sync

aiman apply applies the current local working tree without any Git operations. This is the inner development loop for a skill.

aiman apply --loadout <name> is the context-specific variant of apply: it brings AI environments to exactly the named subset of the inventory, including removing inventory items outside the loadout (see Loadout).

aiman push validates the inventory, creates a commit, and pushes changes to the remote repository. This is publishing.

aiman sync fetches the published state from Git and applies it to local AI environments. This is how you transfer inventory to another machine or update the current one. Without a pin, sync applies the full inventory additively; with an active pin, it declaratively brings environments to the pinned loadout's set, just like apply --loadout <name>.

Change delta in the result

All three commands show a change delta after the result line — what was added (A), modified (M), or deleted (D). For push, D always means a file removed from the inventory. For apply, it appears only with --loadout and means an item removed from an AI environment. For sync, what D means depends on context: in the git delta (what changed in the published inventory) it means a deleted file, while in pinned mode a second, separate block is printed — the delta of what was applied to environments, where D means the same thing as in apply --loadout (see CLI Reference):

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

Note the distinction between two numbers here. The counters on the result line (21 skills) represent the operation volume: how many items were applied in total. The block below is the change delta: what is new or different. 21 skills means 21 skills total, not 21 changes. If nothing changed, the block is omitted — only the result line is printed.

For skills, the delta is computed by comparing file content. For MCP servers, delta is not yet computed (see the Known limitation in the reference).

Why aiman status fetches from remote

aiman status answers the question "what in my inventory has changed relative to the published state." That question inherently includes the remote state, so the command runs a Git fetch before calculating the position.

This is a deliberate difference from git status, which never touches the network: its question is only about the local working tree. aiman status has no honest local-only answer — without a fetch, the position would be calculated against a stale ref and could be misleading. The short fetch delay is expected behavior, not a bug. If the remote is unreachable, status does not hang: the position is shown as unknown (remote unreachable) and the command exits successfully.

aim.local.yaml

aim.local.yaml is created separately on each machine and is not stored in Git.

It stores:

• paths to AI environments;
• hash markers from the last successful push and sync;
• local env variable values for MCP servers.

Hash markers are informational: they help explain the current state, but the safety of push and sync relies on Git state, not these markers.

---

What's next

• Workflows — collecting, publishing, and syncing inventory.
• AI Environments — supported adapters and discovery paths.
• Repository Structure — the full inventory format.
• CLI Reference — all commands.