JLugagne mct — Claude Agent & Skill Package Manager
mct manages Claude agent and skill markdown files distributed through Git repositories called markets. No central registry. No server. Just Git.
Core Concepts
| Term | What it is |
|---|---|
| Market | A Git repo containing agent/skill .md files in agents/ and/or skills/ |
| Entry | A single .md file (agent or skill) from a market |
| Ref | Unique entry ID: market/path/to/file.md |
| Profile | A directory grouping within a market (e.g. mymarket/dev/go) |
| Drift | Local modifications to an installed file (detected via MD5 checksum) |
| Managed skill | A skill auto-installed as a dependency of an agent |
State files (never edit manually):
- Config:
~/.config/mct/config.yml - Checksums:
~/.cache/mct/mct.checksums.json - Sync state:
~/.cache/mct/mct.state.json - Market clones:
~/.cache/mct/{market-name}/
Global Flags
--config path to config file
--cache cache directory
--offline disable all network operations
--verbose detailed log output
--quiet suppress output except errors
--no-color disable ANSI colors
--ci non-interactive mode
Most commands also support --json for machine-readable output.
Markets
Register and manage Git repositories as markets.
mct market add <name> <url> # Register a Git repo as a market
--branch string branch to track (default: main)
--trusted skip breaking-change confirmation prompts
--read-only index only, never install from it
--no-clone register without cloning immediately
mct market list # List all registered markets (alias: mct markets)
mct market info <name> # Detailed market info (entries, last sync, etc.)
mct market rename <old> <new> # Rename a market
mct market set <name> <key> <val> # Update a market property
mct market remove <name> # Unregister a market
--force skip installed-entries check
--keep-cache keep the local clone
Market names must be kebab-case, 2–64 characters.
Installing & Removing Entries
mct add <ref> # Install an entry (alias: mct install)
--pin <sha> pin to a specific commit SHA
--no-deps skip auto-installing required skills
--dry-run preview without making changes
--accept-breaking accept breaking-change flag without prompt
mct remove # Remove an installed entry
--ref <ref> (required)
mct add automatically installs skill dependencies listed in the entry's frontmatter requires_skills field, and marks them as managed by the agent.
Sync & Updates
mct refresh # Fetch latest from all markets (no local changes)
mct update # Apply pending upstream changes to installed files
--ref <ref> only update this entry
--market <name> filter to one market
--dry-run
--agents-only / --skills-only
--all-keep keep all local changes
--all-delete discard all local changes
--all-merge merge all changes
--accept-breaking
mct sync # refresh + update in one step
--market, --dry-run, --accept-breaking, --all-merge
Status & Drift
mct check # Show status of all installed entries (alias: mct status)
--market <name> filter
--short one-line summary
Status indicators:
| Symbol | Meaning |
|---|---|
ok |
Clean — up to date, no local changes |
up |
Update available (no local changes) |
~ |
Drift — locally modified, no update |
! |
Both drift and update available |
x |
Deleted from upstream |
+ |
New in registry (not installed) |
o |
Orphaned — market removed |
? |
Unknown state |
Search & List
mct search <query> # BM25 full-text search across all markets
--limit int max results (default: 10)
--type agent|skill
--market <name> scope search to a single market
--category <cat>
--installed / --not-installed
--include-deleted
mct list # List all installed entries
Results are grouped by profile. Use --market to narrow results when multiple markets are registered.
Version Pinning & Diff
mct pin --ref <ref> --sha <sha> # Lock entry to a specific commit
mct diff --ref <ref> # Open external difftool: local vs. upstream
Pruning Deleted Entries
When an upstream entry is deleted it becomes tombstoned (still exists locally, flagged as deleted).
mct prune
--ref <ref> specific entry
--all-keep keep all locally (stop tracking)
--all-remove delete all locally
Import / Export
Portable JSON format for sharing setups across machines.
mct export [file] # Export all markets + installed profiles to JSON
# (omit file to write to stdout)
mct import <file> # Import markets and entries from JSON
--dry-run preview without changes
--yes auto-confirm adding markets not registered locally
(without --yes, unknown markets are skipped in --json
mode, or prompted interactively otherwise)
Configuration
mct config get [key] # Show config value(s)
mct config set <key> <value>
Settable keys: ssh_enabled, local_path, conflict_policy, drift_policy, difftool, stale_after, namespace_dirs.
Other Commands
mct init # Initialize mct in the current project
mct conflicts # Show all conflicts (ref collisions, dep issues)
mct sync-state # Print raw sync state for all markets
mct index # Index operations
--bench measure indexing performance
--dump dump index as JSON
mct tui # Interactive terminal UI (bubbletea)
mct lint [dir] # Check a local directory as a market (default: current dir)
# Reports profile count, agent/skill counts, and issues:
# error invalid/missing frontmatter, unknown type
# warn missing README.md, missing tags, empty profile
Entry Frontmatter Reference
Fields mct reads from .md files in markets:
---
description: "..." # required: short description
author: "..." # optional
breaking_change: true # optional: flag for breaking changes
deprecated: true # optional
requires_skills: # optional: skill dependencies
- file: skills/go-test.md
pin: abc123 # optional: pin this dep to a SHA
---
Fields mct injects when installing (do not add these manually — mct will reject the file):
mct_ref: mymarket/dev/go/agents/go-developer.md
mct_version: "abc1234 2024-01-15"
mct_market: mymarket
mct_installed_at: "2024-01-15T10:30:00Z"
Market Repository Layout
A market is a Git repo with this structure:
<namespace>/<profile>/
README.md # optional but recommended — frontmatter: tags, description
agents/
my-agent.md
skills/
my-skill.md
Example: dev/go-hexagonal/agents/go-architect.md → ref mymarket/dev/go-hexagonal/agents/go-architect.md
See MARKET.md in this repo for the full market authoring guide.