Getting Started

From installation to your first applied inventory in a few minutes.

Prerequisites

• Git installed and configured
• At least one supported AI environment: Claude Code, Cursor, or Codex CLI

1. Install aiman

Follow the instructions for your OS: Installation.

Verify the installation:

aiman --version
aiman doctor

doctor shows the detected AI environments and anything that needs attention. If something is wrong, see Troubleshooting.

2. Prepare an inventory repository

An inventory is a plain Git repository where your skills and MCP servers are stored. AIM reads it and applies the contents to your AI environments.

No repository yet? Create an empty repository on GitHub or another Git host and copy the URL — you'll need it in the next step. AIM will create the internal structure automatically.

Have a repository with skills? aiman init will create aim.yaml and connect the repository automatically. Make sure the skills in the skills/ folder are valid Skill Items with correct frontmatter — otherwise aiman apply and aiman sync will skip them. See repository structure for details.

3. Connect the repository

aiman init git@github.com:you/aim-loadout.git

Here git@github.com:... is an SSH address. SSH requires a configured key and is required for private repositories. For a public repository you can use an HTTPS address: https://github.com/you/aim-loadout.git.

If you don't pass --path, the command will prompt for a local clone path — the default is a directory named after the repository in the current folder. Press Enter to accept the suggested path or type a different one. To specify a path upfront: aiman init git@github.com:you/aim-loadout.git --path ~/projects/aim-loadout.

If the repository is empty, AIM creates a base structure:

skills/
mcp/
aim.yaml
.gitignore

If the repository was already initialized by AIM, it will be reconnected and you'll be prompted to run aiman sync.

4. Sync the inventory

aiman sync

AIM fetches the published state from Git and applies skills and MCP servers to your AI environments. If an MCP server requires API keys or other secrets, AIM will prompt for them interactively — the values are saved locally and never stored in Git.

5. Create or edit a skill

Open a skill in your editor:

$EDITOR skills/my-skill.md

Minimal skill file format:

---
name: my-skill
description: A short skill description
targets:
  - claude-code
---

The skill prompt text — a role explanation, task description, or instructions for the AI agent.

name must match the filename without .md. The targets field is optional — without it, the skill is applied to all detected AI environments. Full format: Inventory Format.

Apply changes locally without publishing:

aiman apply

Check the skill in your AI environment. You may need to restart the agent session for changes to take effect — most AI environments read skills at startup. Repeat the edit → apply → restart cycle until ready.

6. Publish

aiman status   # shows unpublished changes
aiman push     # validates, commits, and pushes to the remote repository

7. Sync on another machine

On a new machine, install aiman, then:

aiman init git@github.com:you/aim-loadout.git
aiman sync

The published skills and MCP servers will be applied immediately after sync.

---

What's next

• Concepts — what inventory, skills, and adapters are
• Workflows — common scenarios
• Repository Structure — the full inventory format
• CLI Reference — all commands