cmx — Package Manager for Curated Agentic Context

cmx manages the lifecycle of agents and skills for AI coding assistants — versioning, installation, updates, and distribution.

What are agents and skills?

What cmx does

• Source management — register git repositories or local directories as artifact sources (plugin marketplaces)
• Install & update — install agents and skills globally or per-project, track versions and checksums
• Status tracking — see what's installed, what's outdated, what's deprecated
• LLM-powered diff — use AI to analyze differences between installed and source versions
• Cross-platform — works with Claude Code, GitHub Copilot, Cursor, Windsurf, and Gemini CLI

Quick example

# Add a source marketplace
cmx source add guidelines https://github.com/svetzal/guidelines

# Search across all sources
cmx search python

# Browse a specific source
cmx source browse guidelines

# Install an agent globally
cmx agent install python-craftsperson

# Install all available agents
cmx agent install --all

# Check what needs updating
cmx outdated

# See an LLM-powered analysis of changes
cmx agent diff rust-craftsperson

# Update everything
cmx agent update --all

Installation

Homebrew (macOS and Linux)

brew tap svetzal/tap
brew install cmx

From GitHub Releases

Download the latest binary for your platform from GitHub Releases.

Extract and place cmx somewhere on your PATH:

tar xzf cmx-darwin-arm64.tar.gz
sudo mv cmx /usr/local/bin/

From source

git clone https://github.com/svetzal/context-mixer2.git
cd context-mixer2
cargo install --path .

Verify installation

cmx --version

Quick Start

1. Add a source

Sources are git repositories (or local directories) that contain agents and skills. Register one:

# From a git URL
cmx source add guidelines https://github.com/svetzal/guidelines

# Or from a local directory
cmx source add my-agents ~/Work/my-agents

You can also add Anthropic's official skills:

cmx source add anthropic-skills https://github.com/anthropics/skills

2. Browse available artifacts

cmx source browse guidelines

This shows all agents and skills in the source, with versions and deprecation status.

3. Install artifacts

# Install a single agent
cmx agent install python-craftsperson

# Install from a specific source
cmx agent install guidelines:python-craftsperson

# Install all available agents
cmx agent install --all

# Install into the current project (instead of globally)
cmx agent install python-craftsperson --local

4. Check status

# See everything installed
cmx list

# Check what's outdated
cmx outdated

5. Update

# Update a specific agent
cmx agent update python-craftsperson

# Update all tracked agents
cmx agent update --all

Where artifacts get installed

By default, cmx installs to Claude Code's global directories:

Sources

Sources are plugin marketplace repositories — git repos or local directories containing agents and skills.

Adding sources

# Git repository (cloned automatically)
cmx source add team https://github.com/acme/agent-standards

# Local directory
cmx source add guidelines ~/Work/guidelines

Listing sources

cmx source list

Browsing a source

cmx source browse guidelines

Shows all agents and skills with their versions. Deprecated artifacts are marked with ⛔.

Updating sources

Git-backed sources are automatically updated when stale (>60 minutes since last fetch) during browse, install, and outdated operations.

To explicitly update:

# Update a specific source
cmx source update guidelines

# Update all git-backed sources
cmx source update

Removing sources

cmx source remove guidelines

For git-backed sources, this also deletes the local clone.

Marketplace format

cmx supports two source formats:

1. Marketplace repos — contain .claude-plugin/marketplace.json listing plugins with their agents and skills. Compatible with Claude Code's native plugin system.

2. Simple repos — any directory with .md agent files and skill directories containing SKILL.md. cmx auto-discovers these by walking the tree.

See Marketplace Structure for details on creating your own.

Searching

Search across all registered sources for agents and skills by keyword.

Usage

cmx search <keyword>

The search matches against both artifact names and descriptions (case-insensitive).

Example

$ cmx search python
  Name                    Type   Version  Source            Description
  ----------------------  -----  -------  ----------------  -----------
  python-craftsperson     agent  1.3.1    guidelines        Use this agent when writing, reviewing...
  uv-python-craftsperson  agent  1.3.1    guidelines        Use this agent when writing, reviewing...

2 result(s) found.

Searching across multiple sources

Search scans every registered source. If you have both your team's marketplace and Anthropic's skills registered, results from all sources appear together:

$ cmx search pdf
  Name           Type   Version  Source            Description
  -------------  -----  -------  ----------------  -----------
  canvas-design  skill  -        anthropic-skills  Create beautiful visual art in .png and .pdf...
  pdf            skill  -        anthropic-skills  Use this skill whenever the user wants to do...

2 result(s) found.

Auto-update

Search triggers auto-update for stale git-backed sources (>60 minutes since last fetch) to ensure results are current.

After finding what you need

Install directly from the search results:

cmx skill install anthropic-skills:pdf

Installing Artifacts

Install a single artifact

cmx agent install python-craftsperson
cmx skill install skill-creator

If the artifact exists in multiple sources, cmx will ask you to disambiguate:

cmx agent install guidelines:python-craftsperson

Install all available

cmx agent install --all
cmx skill install --all

This installs every artifact from registered sources that isn't already tracked in the lock file with a matching version.

Local vs global install

By default, artifacts install globally (~/.claude/agents/ or ~/.claude/skills/).

Use --local to install into the current project:

cmx agent install python-craftsperson --local

This installs to .claude/agents/ in the current directory.

What happens on install

1. The artifact is copied to the appropriate platform directory
2. A SHA-256 checksum is computed
3. The version (if present in frontmatter) is recorded
4. An entry is written to the lock file with source, checksum, version, and timestamp

Listing & Status

List installed artifacts

# Everything
cmx list

# Agents only
cmx agent list

# Skills only
cmx skill list

The list view shows a table with status indicators:

Global agents:
  Name                        Installed  Source      Available
  --------------------------  ---------  ----------  ---------
  python-craftsperson         1.3.1      guidelines  1.3.1      ✅
  rust-craftsperson           1.0.0      guidelines  2.0.0      ⚠️
  clojure-craftsperson        -          guidelines  1.0.1      ⚠️
  skill-writing               1.0.0      guidelines  1.0.0      ⛔
  my-custom-agent             -          -           -

Status indicators

Check what's outdated

cmx outdated

Shows only artifacts that need attention — outdated, untracked, or changed in the source. Includes artifacts on disk that match a source but were never installed through cmx.

Updating Artifacts

Update a single artifact

cmx agent update python-craftsperson
cmx skill update skill-creator

This reinstalls the artifact from its original source, updating the lock file with the new version and checksum.

Update all tracked artifacts

cmx agent update --all
cmx skill update --all

Updates every artifact in the lock file that has a different checksum than the current source version.

Adopting untracked artifacts

If you have agents or skills installed on disk that weren't installed through cmx (e.g., manually copied), use install --all to adopt them:

cmx agent install --all

This will install (and track) every source artifact that isn't already in the lock file with a matching version — including ones already on disk.

Diffing with LLM Analysis

cmx can use an LLM to analyze differences between your installed artifact and the source version.

Usage

cmx agent diff python-craftsperson
cmx skill diff blog-image-generator

If the artifacts are identical (checksums match), cmx reports "up to date" without calling the LLM.

When differences exist, cmx sends both versions to the configured LLM and returns a concise analysis covering:

1. What capabilities or behaviors were added, removed, or changed
2. Whether the update is significant or cosmetic
3. A recommendation on whether to update

Example output

Comparing python-craftsperson (agent)
  Installed (global): unversioned
  Source (guidelines): 1.3.1

Analyzing differences...

The only difference is the addition of version metadata in the
frontmatter. No behavioral changes. Update is safe but optional.

Works with untracked artifacts

diff works on any installed artifact that has a matching source — even ones not tracked in the lock file. It finds the file on disk and compares directly.

LLM configuration

See Configuration to set up the LLM gateway and model.

Configuration

cmx stores configuration in ~/.config/context-mixer/config.json.

View current settings

cmx config show

LLM Gateway

The diff command uses an LLM for analysis. By default, cmx uses OpenAI with the gpt-5.4 model.

Set the gateway

# OpenAI (default) — uses $OPENAI_API_KEY
cmx config gateway openai

# Ollama (local)
cmx config gateway ollama

Set the model

# OpenAI models
cmx config model gpt-5.4

# Ollama models
cmx config gateway ollama
cmx config model qwen3.5:27b

Environment variables

Writing Agents

An agent is a single .md file with YAML frontmatter that provides curated guidance for a tech stack.

Minimal agent

---
name: python-craftsperson
description: |
  Use this agent when writing, reviewing, or maintaining Python code.
model: sonnet
---

You are an expert Python developer...

Required fields

Optional cmx fields

Agent body

The markdown body after the frontmatter closing --- becomes the agent's system prompt. Write it in second person ("You are...").

File naming

The file name (without .md) becomes the artifact name used by cmx. For example, python-craftsperson.md → artifact name python-craftsperson.

Writing Skills

A skill is a directory containing a SKILL.md file with YAML frontmatter, plus optional supporting files.

Directory structure

my-skill/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Optional: automation scripts
├── references/           # Optional: detailed documentation
└── examples/             # Optional: templates, samples

Minimal skill

---
name: my-skill
description: What this skill does and when to use it.
---

# My Skill

Instructions for the AI agent...

Required fields

Optional cmx fields

Follows the Agent Skills specification

cmx skills follow the Agent Skills specification, making them compatible with Claude Code, GitHub Copilot, Cursor, and other AI coding assistants.

Directory naming

The directory name becomes the artifact name. For example, skills/blog-image-generator/SKILL.md → artifact name blog-image-generator.

Marketplace Structure

A marketplace is a git repository that distributes agents and skills. cmx supports the Claude Code plugin marketplace format and a simple fallback.

Plugin marketplace (recommended)

Add a .claude-plugin/marketplace.json to your repo. This is compatible with Claude Code's native plugin system.

cmx supports three plugin declaration styles within marketplace.json, matching the formats used across Anthropic's own repositories.

Format 1: Explicit agents/skills arrays

Best when you want precise control over which artifacts are exposed:

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json
├── agents/
│   ├── python-craftsperson.md
│   └── typescript-craftsperson.md
├── skills/
│   ├── blog-image-generator/
│   │   └── SKILL.md
│   └── code-review/
│       └── SKILL.md
└── README.md

{
  "name": "my-marketplace",
  "owner": { "name": "Your Name" },
  "plugins": [
    {
      "name": "my-plugin",
      "description": "Description of this collection",
      "source": "./",
      "agents": [
        "./agents/python-craftsperson.md",
        "./agents/typescript-craftsperson.md"
      ],
      "skills": [
        "./skills/blog-image-generator",
        "./skills/code-review"
      ]
    }
  ]
}

Paths in agents and skills arrays are resolved relative to the repository root.

Format 2: Source path without explicit arrays

Best when each plugin lives in its own subdirectory. cmx walks the directory to discover artifacts automatically:

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json
├── plugins/
│   ├── code-review/
│   │   ├── reviewer.md
│   │   └── review-skill/
│   │       └── SKILL.md
│   └── commit-tools/
│       └── committer.md
└── README.md

{
  "name": "my-marketplace",
  "owner": { "name": "Your Name" },
  "plugins": [
    {
      "name": "code-review",
      "description": "Automated code review",
      "source": "./plugins/code-review"
    },
    {
      "name": "commit-tools",
      "description": "Git commit workflows",
      "source": "./plugins/commit-tools"
    }
  ]
}

When no agents/skills arrays are present, cmx resolves the source path and walks that directory to find .md agents and SKILL.md skills.

Format 3: Remote source objects (not yet supported)

The official Claude Code plugin format also supports remote sources (url, github, git-subdir, npm). cmx recognizes these entries and emits a warning. Future versions may add support for fetching remote plugin sources.

{
  "plugins": [
    {
      "name": "some-plugin",
      "source": {
        "source": "url",
        "url": "https://github.com/example/plugin.git",
        "sha": "a1b2c3d4..."
      }
    }
  ]
}

Scanning priority

1. If agents/skills arrays exist on a plugin entry, cmx uses them directly.
2. If only a source path string is present, cmx walks that directory.
3. If source is an object (remote), cmx warns and skips.

Simple directory (fallback)

Without marketplace.json, cmx walks the entire tree looking for:

• .md files with frontmatter containing name and description → agents
• Directories containing SKILL.md with frontmatter → skills

This works for quick setups but the marketplace format is preferred for explicit control and Claude Code compatibility.

Registering with cmx

# As a git source
cmx source add my-marketplace https://github.com/you/my-marketplace

# As a local directory
cmx source add my-marketplace ~/Work/my-marketplace

Compatibility

A marketplace registered with cmx can also be used directly with Claude Code:

/plugin marketplace add https://github.com/you/my-marketplace

Versioning

cmx tracks artifact identity with two complementary mechanisms.

Checksums (automatic)

SHA-256 checksums are always computed — no author effort required. They detect that something changed, but not what or how significant.

Versions (opt-in)

Add a version field to your frontmatter:

---
name: python-craftsperson
description: ...
version: 1.3.1
model: sonnet
---

Versions communicate significance of changes. Use semantic versioning:

• Major (2.0.0) — significant rewrites, changed philosophy or approach
• Minor (1.1.0) — new capabilities, added guidance
• Patch (1.0.1) — small fixes, formatting, metadata updates

How they work together

Design principle: checksums are free and always present; versions are opt-in and add human-meaningful context when authors choose to provide them.

Deprecation

Mark agents or skills as deprecated when they should no longer be used.

Frontmatter fields

All three fields are progressive — use as many as apply:

---
name: skill-writing
version: 1.0.0
deprecated: true
deprecated_reason: Superseded by Anthropic's skill-creator
deprecated_replacement: skill-creator
description: ...
---

How it surfaces

In source browse

Skills:
  blog-image-generator  v1.0.0
  skill-writing  v1.0.0  ⛔ DEPRECATED: Superseded by skill-creator (use skill-creator instead)

In list

The status column shows ⛔ instead of ✅, even if the installed version matches the source.

In outdated

Deprecated artifacts appear in the outdated list so users know to take action.

Best practices

• Include actionable instructions in deprecated_reason — tell users how to get the replacement
• If the replacement is in a different source, include the cmx source add command in the reason
• Set deprecated_replacement only if the replacement is installable via cmx

Command Reference

Source management

Agent management

Skill management

Same commands as agent, using cmx skill instead of cmx agent.

Aggregate commands

Configuration

Frontmatter Reference

Agent frontmatter

---
name: python-craftsperson
description: |
  Use this agent when writing, reviewing, or maintaining Python code.
version: 1.3.1
model: sonnet
deprecated: true
deprecated_reason: Replaced by python-craftsperson-v2
deprecated_replacement: python-craftsperson-v2
---

Skill frontmatter (SKILL.md)

---
name: blog-image-generator
description: Generate images for blog posts.
version: 1.0.0
---

marketplace.json

{
  "name": "marketplace-id",
  "owner": { "name": "Author", "email": "author@example.com" },
  "metadata": { "description": "...", "version": "1.0.0" },
  "plugins": [{
    "name": "plugin-id",
    "description": "...",
    "source": "./",
    "agents": ["./agents/my-agent.md"],
    "skills": ["./skills/my-skill"]
  }]
}

Lock File

cmx records installed state in JSON lock files.

Locations

Format

{
  "version": 1,
  "packages": {
    "python-craftsperson": {
      "type": "agent",
      "version": "1.3.1",
      "installed_at": "2026-03-20T10:30:00Z",
      "source": {
        "repo": "guidelines",
        "path": "agents/python-craftsperson.md"
      },
      "source_checksum": "sha256:abc123...",
      "installed_checksum": "sha256:abc123..."
    }
  }
}

Fields

How checksums are used

• source_checksum vs current source — detects upstream changes
• installed_checksum vs current file — detects local edits
• Both match at install time, then drift independently

Platform Paths

cmx currently installs to Claude Code directories by default. Future versions will support additional platforms.

Supported platforms

Current default

cmx v2.0.0 installs to Claude Code paths only. The agent and skill formats follow the Agent Skills specification, which is supported by all platforms listed above.