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

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

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 state of managed files. push validates the inventory, creates a commit, and pushes it to the remote repository.

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.

Protecting against lost changes

sync is blocked if local changes might be overwritten.

aiman sync
# error: local changes detected ...

Options:

• publish changes via aiman push;
• manually save or discard local changes;
• use aiman sync --force if you can afford to lose the local changes.

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