Workflows

Adding a skill from a file

To add a ready-made skill to your inventory:

aiman add skill path/to/skill.md

If a file with that name already exists in the inventory with different content:

aiman add skill path/to/skill.md --overwrite    # overwrite
aiman add skill path/to/skill.md --name new-name  # save under a different name

From stdin:

cat skill.md | aiman add skill -

After adding, run aiman push to publish the change.

Adding an MCP server from a file

To add an MCP server configuration to your inventory:

aiman add mcp path/to/server.yaml

If a file with that name already exists in the inventory with different content:

aiman add mcp path/to/server.yaml --overwrite    # overwrite
aiman add mcp path/to/server.yaml --name new-name  # save under a different name

From stdin:

cat server.yaml | aiman add mcp -

If the input file contains value fields in the env block, AIM automatically moves them to aim.local.yaml and does not write them to mcp/<name>.yaml. This ensures secrets never end up in Git.

After adding, run aiman push to publish the change.

Importing a skill from an AI environment

If a skill is already installed in one of your AI environments, you can import it directly:

aiman import skill hello --from claude-code
aiman import skill review-code --from codex

Preview the content without writing:

aiman import skill hello --from claude-code --print

Supported sources: claude-code, cursor, codex.

Cursor does not store skills natively — --from cursor always returns an empty result.

After adding, run aiman push to publish the change.

Importing an MCP server from an AI environment

If an MCP server is already configured in one of your AI environments, you can import it directly:

aiman import mcp context7 --from claude-code
aiman import mcp jira --from cursor

Preview the content without writing:

aiman import mcp context7 --from claude-code --print

Import and set all three AI environments as targets:

aiman import mcp context7 --from claude-code --targets all

Supported sources: claude-code, cursor, codex.

AIM reads the live configuration of the specified environment, extracts the MCP server descriptor, and applies env-strip: real env variable values are written to aim.local.yaml, while only descriptors without secrets go to the inventory and Git.

If a server with that name already exists in the inventory with different content, the command fails. To overwrite, use --overwrite:

aiman import mcp context7 --from claude-code --overwrite

After adding, run aiman push to publish the change.

Local iteration: edit → apply → test

Use aiman apply when you want to test a change before publishing.

$EDITOR skills/review-code.md
aiman apply

What apply does:

• reads local skills/ and mcp/;
• validates items;
• applies valid items to detected AI environments;
• does not commit;
• does not contact the remote;
• does not update published_hash or synced_hash.

This cycle is intended for skill development: edit, apply, check in your AI tool, edit again. Most AI environments read skills at session start — after aiman apply, restart the agent session to pick up the changes.

Publishing: status → push

When a local change is ready:

aiman status
aiman push

status shows the repository position relative to origin/main, the state of AI environments, and the list of changes in skills/ and mcp/ that have not yet been published.

status is a network command: it runs a Git fetch before calculating the position, so the result reflects the actual remote state rather than a stale local ref. A short fetch delay is expected behavior. See Concepts for the reasoning.

TODO: add a spinner during fetch

Example output when there are unpublished changes:

Repository:   git@github.com:you/aim-loadout.git
Position:     2 commits ahead of origin/main
Environments: needs sync (2 commits not applied)

Changes not yet published (origin/main → working tree):
  A skills/new-skill.md
  M skills/existing.md

  run aiman push to publish

push validates the inventory, creates a commit, and pushes it to the remote repository. After publishing, it shows the delta of what was published:

published: 96e091b · 19 skills, 1 MCP server
  M skills/review-code.md
  A mcp/jira.yaml

push --dry-run shows the publish plan without writing to Git:

aiman push --dry-run

Moving to another machine: init → sync

On a new machine:

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

sync runs a Git fetch, verifies history, fetches the published state, and applies it to the local AI environments. After applying, it shows the delta of incoming changes:

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

The counters on the result line are the operation volume (total applied); the block below is the change delta. If nothing came in from remote, the block is omitted.

Protecting against lost changes

sync does not block on untracked files unless they conflict by name with a file being introduced from remote. New uncommitted skills and MCP descriptors in skills/ and mcp/ are preserved as long as their names do not clash with incoming remote files.

If a name collision is detected, sync stops and lists the conflicting files. At that point you have three options:

• publish the conflicting file so it becomes part of the remote state:

aiman push
aiman sync

• rename or move the file manually, then retry aiman sync;
• apply the published state and permanently delete the conflicting files:

aiman sync --force

Warning: sync --force permanently deletes conflicting files from the working tree. This cannot be undone.

--force never deletes files silently: before applying the state, AIM prints a list of what was removed:

discarded untracked files (--force):
  skills/draft.md
  mcp/local-only.yaml
synced: 67451fc · 21 skills, 1 MCP server → 3 environments

History states

After fetch, AIM distinguishes several situations:

State	Behavior
Local is already equal to remote	apply inventory without reset
Local is behind remote	fast-forward reset and apply
Local has unpublished commits	stop and ask for aiman push
History has diverged	stop and ask for manual Git recovery

When to use which command

Task	Command
Add a skill from a file	aiman add skill <file>
Add an MCP server from a file	aiman add mcp <file>
Import a skill from an AI environment	aiman import skill <name> --from <env>
Preview a skill without writing	aiman import skill <name> --from <env> --print
Import an MCP server from an AI environment	aiman import mcp <name> --from <env>
Preview an MCP descriptor without writing	aiman import mcp <name> --from <env> --print
Test a local skill without publishing	aiman apply
See what has changed	aiman status
Publish the ready inventory	aiman push
Apply published inventory on a machine	aiman sync
Check environment and configs	aiman doctor