Your First Inventory

This guide walks you through creating an inventory from scratch: connecting an empty Git repository, adding your first skill, and publishing it.

Prerequisites

• aiman installed (Installation)
• Git configured
• An empty repository created on GitHub or another Git host

The repository must be completely empty — no README, no .gitignore, no other files. AIM will create the internal structure.

1. Connect the repository

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

AIM clones the repository and creates a base structure:

skills/
mcp/
aim.yaml
.gitignore

An SSH address requires a configured key. For a public repository you can use an HTTPS address: https://github.com/you/aim-loadout.git.

2. Create a skill

A skill (Skill Item) is a Markdown file in the skills/ directory. One file, one skill.

Create the file skills/git-commit.md:

---
name: git-commit
description: Writes commit messages following Conventional Commits
targets:
  - claude-code
---

# Role

You help write commit messages.

For each request:
- use Conventional Commits format: `type(scope): message`;
- write in English;
- keep the first line under 72 characters;
- if the change is non-trivial, add a body explaining the reason.

The name field must match the filename without .md. The targets field restricts the skill to specific AI environments — if omitted, the skill is applied to all detected environments. For the full list of fields and accepted values, see Inventory Format.

You can create multiple skills before the first push — add the files you need to skills/, then move on to the next step.

3. Apply locally

aiman apply

AIM reads the contents of skills/ and writes the skills to the AI environment configuration files. Changes take effect the next time the agent starts. aiman apply publishes nothing — changes remain on your machine only.

4. Publish

aiman push

AIM validates the inventory, creates a commit, and pushes it to the remote repository. You don't need separate git add, git commit, and git push commands — aiman push handles all of that. It works with an empty repository — no prior Git history is required.

To review what will change before publishing:

aiman status

---

What's next

• Inventory Format — full specification for Skill Item and MCP Item
• Repository Structure — what is stored where
• Getting Started — the full scenario including multi-machine sync
• Workflows — common inventory workflow patterns