Inventory Format

Skill Item

Path:

skills/<name>.md

Example:

---
name: create-spec
description: Write a concise technical specification for a developer
targets:
  - claude-code
  - cursor
tags:
  - planning
---

# Role

...

Fields:

Field	Required	Description
name	yes	Skill identifier; must match the filename
description	no	Short skill description
targets	no	List of AI environments; if not set, applied to all detected environments
tags	no	User-defined tags

The Markdown body after the frontmatter must not be empty.

Folder Skill

A Skill Item can also be stored as a folder:

skills/<name>/SKILL.md
skills/<name>/agent-patterns.md   # optional reference files
skills/<name>/delegation.md
skills/<name>/examples.md

SKILL.md is the primary skill file with frontmatter and body. The other files in the folder are reference materials that can be mentioned in SKILL.md via @mention. When the skill is installed, the entire folder is copied to the AI environment.

Priority: if both skills/<name>.md and skills/<name>/SKILL.md exist at the same time, the flat file (<name>.md) takes precedence.

Limitation: apply --dry-run and delta calculation compare only the hash of SKILL.md. Changes to reference files inside the folder are not reflected in the change delta.

MCP Item

Path:

mcp/<name>.yaml

Example:

name: context7
description: Library documentation via MCP
command: npx
args:
  - -y
  - "@upstash/context7-mcp"
targets:
  - claude-code
  - cursor
  - codex
env:
  - name: UPSTASH_REDIS_REST_URL
    description: Upstash Redis store URL
    required: true
    example: https://example.upstash.io

Fields:

Field	Required	Description
name	yes	MCP server identifier
description	yes	Short description
command	yes	Launch command
args	yes	Argument list; may be empty
targets	yes	List of AI environments
env	yes	List of environment variables; may be empty

Env variable

Field	Required	Description
name	yes	Variable name
description	yes	Variable purpose
required	yes	Whether a value is required at apply time
example	no	Example value

Env variable values are not stored in the MCP Item. They are set locally and saved in aim.local.yaml.

Targets

Supported values:

• claude-code;
• cursor;
• codex.