AAM — Agent Artifact Manager¶
The package manager for AI agent artifacts. Install, share, and deploy skills, agents, prompts, and instructions across every AI platform.
Why AAM?¶
Multi-Platform Deploy¶
Deploy once to Cursor, Claude, GitHub Copilot, and Codex. AAM translates your artifacts into each platform's native format automatically.
Dependency Resolution¶
Automatic dependency management with semver constraints and lock files. If your agent needs a skill, AAM resolves and installs the entire tree.
Local-First¶
Works fully offline with local registries. No server required. Git directories, bare repos, or plain folders all work as registries out of the box.
Package and Share¶
Create, validate, sign, and publish packages to any registry. Share with your team via a private registry or with the world via a public one.
Quick Example¶
A typical workflow from zero to a published and installed package:
# 1. Set up AAM client (config, sources)
aam init
# 2. Create a new package interactively
aam pkg create my-code-review-skill
# 3. Publish to your registry
aam pkg publish --registry file:///home/user/my-registry
# 4. Install a package in any project
aam install @yourname/my-code-review-skill
That is it. The skill is now deployed to your configured platform (Cursor, Claude, Copilot, or Codex) and ready to use.
What Can You Package?¶
AAM manages four types of AI agent artifacts:
| Artifact Type | What It Is | Example |
|---|---|---|
| Skills | Workflow and capability packages containing a SKILL.md with optional scripts, references, and assets. | A code-review skill that walks an agent through a structured review process. |
| Agents | Full agent definitions including system prompts, personality configuration, tool settings, and skill references. | A security-audit agent pre-configured with analysis skills and reporting templates. |
| Prompts | Reusable prompt templates with optional variable placeholders for dynamic content. | A structured bug-report prompt that ensures consistent issue descriptions. |
| Instructions | Platform-specific rules, conventions, and guidelines that shape agent behavior. | Python coding standards that enforce style and architecture decisions. |
Tools & Prerequisites¶
AAM is designed to be lightweight. Install only what you need based on your planned tasks:
Always Required¶
| Tool | Version | Purpose |
|---|---|---|
| Python | 3.11+ | Runtime for AAM |
| pip | 22.0+ | Install the aam package |
For Git Source Workflows¶
| Tool | Version | Purpose |
|---|---|---|
| Git | 2.25+ | Clone and fetch community skill sources |
Required when using aam source add, aam source update, or aam source enable-defaults to manage git-based package sources.
For MCP / IDE Integration¶
| Tool | Version | Purpose |
|---|---|---|
| Cursor, Claude Desktop, VS Code, or any MCP client | Latest | Connect to AAM's MCP server |
AAM ships with a built-in MCP server. No extra install needed --- just configure your IDE to spawn aam mcp serve.
For Package Authoring & Publishing¶
| Tool | Version | Purpose |
|---|---|---|
| Text editor | Any | Edit aam.yaml manifests and artifact files |
| Git | 2.25+ | Version control your packages |
Use aam pkg create or aam pkg init to scaffold packages, then aam pkg publish to share them.
Check your environment
Run aam doctor at any time to verify your setup. It checks Python version, configuration files, registry accessibility, and package integrity.
Get Started¶
Install AAM¶
Install with pip, set your default AI platform, and configure a local registry. Everything you need in five minutes.
Quick Start¶
Create a registry, build a package, publish it, and install it --- all in a single walkthrough.
Your First Package¶
Build a complete package with skills, agents, prompts, and instructions from scratch.
CLI Reference¶
AAM provides a comprehensive CLI organized into command groups. Every command is also available as an MCP tool for IDE agents.
| Command Group | Key Commands | What It Does |
|---|---|---|
| Getting Started | aam init | Set up AAM (platform, default sources) |
| Package Management | aam install, aam search, aam list | Install, search, list, upgrade, and remove packages |
| Package Integrity | aam verify, aam diff | Verify checksums and show diffs for modified files |
| Package Authoring | aam pkg create, aam pkg publish | Create, validate, pack, and publish packages |
| Source Management | aam source add, aam source scan | Manage git-based package sources |
| Registry Management | aam registry init, aam registry add | Create and configure local or remote registries |
| Configuration | aam config set, aam config list | Get and set configuration values |
| Diagnostics | aam doctor | Run health checks on your AAM setup |
MCP Interface¶
AAM ships with a built-in MCP (Model Context Protocol) server that lets AI agents in your IDE manage packages directly --- no terminal required.
Read-Only Tools (17)¶
Search packages, list sources, check configuration, verify integrity, and run diagnostics. Always safe, always available.
Write Tools (12)¶
Install, uninstall, upgrade, and publish packages. Create packages and manage sources. Requires explicit --allow-write opt-in.
Resources (9)¶
Passive data endpoints: installed packages, configuration, registries, source lists, and manifest data. Available to any connected agent.
IDE Integration¶
Works with Cursor, Claude Desktop, VS Code, Windsurf, and any MCP-compatible client. One line of config to connect.
# Start MCP server (read-only, safe for exploration)
aam mcp serve
# Start with full read/write access
aam mcp serve --allow-write
Where to Go Next¶
Tutorials¶
Step-by-step guides for common tasks: packaging existing skills, building packages, and deploying to multiple platforms.
Platform Guides¶
Deploy artifacts to Cursor, Claude Desktop, GitHub Copilot, and OpenAI Codex with platform-specific configuration.
Concepts¶
Understand packages, artifacts, git sources, registries, dependency resolution, and platform adapters.