Concepts

Loadout

Loadout is the product metaphor: 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.

In the future, a loadout will also become a technical entity: a named subset of the inventory, such as Documentation Work or Architecture Work. This is not available in the current MVP — AIM applies the entire valid inventory as a whole.

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;
• 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
tags:
  - review
---

# Role

...

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

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 -

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 --dry-run

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.

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 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.

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.