FAQ
Answers to the most common questions about working with AIM Loadout.
Getting started
Do I need GitHub? Can I use a different Git host or a private repository?
GitHub is not required. The inventory is a plain Git repository, and AIM works with any Git host: GitLab, Bitbucket, self-hosted Gitea, or anything else. Private repositories are supported — use SSH with a configured key for access.
Can I start with a completely empty repository?
Yes. If the repository is empty, aiman init will create the base structure inside it: skills/ and mcp/ directories, aim.yaml, and .gitignore. You do not need to populate the repository manually before initialization. See Your First Inventory for a walkthrough.
What does aiman init do if the repository is not empty?
If the repository was already initialized by AIM, aiman init reconnects it and prompts you to run aiman sync. If the repository contains existing skill files, AIM classifies them as adoptable — you can bring them into the correct format. Files without valid frontmatter are skipped by aiman apply and aiman sync. For format details, see Inventory Format.
Skills and inventory
Can I use one inventory across multiple machines?
Yes. This is the primary use case for AIM. After aiman push on one machine, run aiman init <url> and aiman sync on another — skills and MCP servers will be applied automatically. See Getting Started for a walkthrough.
If I have multiple AI tools (Claude Code + Cursor) — will a skill be applied to both?
It depends on the targets field in the skill. If targets is not set, the skill is applied to all AI environments detected on the machine. If targets is set (for example, only claude-code), the skill goes only to that environment. For the full list of supported values, see Inventory Format.
Can I copy skills from somewhere else?
Yes. Copy or create skill files in the skills/ directory of your inventory, then run aiman apply to apply them locally and aiman push to publish. Each file must follow the Skill Item format — it must have valid YAML frontmatter with a name field that matches the filename without .md.
Do I need to restart the AI agent after aiman apply?
Most AI environments read skills at session start, not in real time. After aiman apply, restart the agent session for changes to take effect. This behavior depends on the specific AI environment.
Configuration and environments
Where are secrets (API keys for MCP servers) stored? Do they go into Git?
No. Secret values are stored in aim.local.yaml — a file on your machine that AIM automatically excludes from Git via .gitignore. Only the MCP server description — variable names and their purpose — goes into the repository, never the actual values. See Security and Limits for details.
AIM can't find my AI environment — what should I do?
Run aiman doctor — it shows which environments were found and which paths AIM looks at. If the environment is not found, verify it is installed and that its configuration directory exists. Non-standard paths can be set manually in aim.local.yaml. See Troubleshooting for more.
What is aim.local.yaml and why can't I commit it?
aim.local.yaml is the local config for your machine: AI environment paths, sync hash markers, and MCP server env variable values. This file contains machine-specific data and secrets, so it must not go into the shared repository. AIM automatically creates a .gitignore that excludes this file during aiman init. See Repository Structure for details.
Commands
What is the difference between aiman apply and aiman sync?
aiman apply applies the current local state of skills/ and mcp/ to AI environments — without contacting the Git remote. aiman sync first fetches the published state from the remote and then applies it locally. Use apply in the edit loop on a single machine; use sync to pull changes from another machine or after a teammate's aiman push.
What is the difference between aiman push and git push?
aiman push is not just git push. The command first validates the inventory, then creates a commit with the managed files, and only then pushes. You do not need to run git add, git commit, and git push separately — aiman push does all of that for you.
Why is aiman push blocked? What does "remote is ahead" mean?
aiman push stops if the remote contains commits that are not present locally. This means someone else (or you from another machine) published changes after your last sync. Run aiman sync to apply the current state, then retry aiman push.
Other
Can I have multiple inventory repositories?
Yes. Use aiman switch <path> to switch between them — the command switches the active repository without re-cloning. AIM's global config stores the path to the currently active repository.
Is AIM Loadout paid?
No. AIM Loadout is an open source project, distributed under the Apache 2.0 license.