mdm

The markdown management CLI. No telemetry · Fully open source.

📖 Full documentation: sethcarney.github.io/mdm - install guide, complete command reference, and per-command guides.

Why mdm?

Managing markdown across multiple agentic coding tools is more painful than it should be. Keeping CLAUDE.md, copilot-instructions.md, .cursorrules, and friends consistent and up to date is tedious enough on its own. Add in installing first- and third-party skills and context files, versioning them, pulling updates, and auditing them for prompt injection risks and hidden characters, and it becomes a real maintenance burden.

mdm is a fast, security-focused markdown management CLI written in Go, designed to solve exactly these problems:

• 43 harnesses supported out of the box, including Claude Code, Cursor, Cline, GitHub Copilot, Gemini CLI, Codex, and 37 more.
• One source of truth for instruction files. mdm rules link makes AGENTS.md the canonical file and symlinks each harness's expected filename to it.
• Skills from anywhere. Install from GitHub, GitLab, arbitrary URLs, local paths, or the skills.sh registry.
• Reproducible installs. Repos can commit an mdm.lock with their recommended skills, agent definitions, knowledge bundles, and plugins so new teammates run mdm install once and onboard with whatever harness they prefer.
• Security-focused by default. Every install runs a deterministic local scan for hidden characters and prompt-smuggling patterns, and mdm skills audit checks for updates and OSV security advisories.
• Knowledge bundles. mdm knowledge installs, validates, and updates Open Knowledge Format (OKF) bundles for AI harnesses.
• Agent Plugins. mdm plugins installs, validates, and updates Agent Plugins - portable packages of skills and MCP servers - and wires their MCP servers into each harness's config.
• Agent definitions. mdm agents installs subagent persona files (e.g. Claude Code subagents) into each harness that supports them.
• No telemetry, fully open source.

Prefer a UI? There's also a VS Code extension.

Install

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/sethcarney/mdm/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/sethcarney/mdm/main/install.ps1 | iex

Both installers place the binary in ~/.local/bin/mdm and will warn if that directory isn't in your PATH.

To install to a different directory, set INSTALL_DIR before running:

INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/sethcarney/mdm/main/install.sh | bash

Dev container

mdm is published as a Dev Container Feature, so a repo can declare it instead of scripting an install:

"features": {
  "ghcr.io/sethcarney/mdm/mdm:1": {}
}

The feature installs the release binary for the container's architecture to /usr/local/bin/mdm, verified against the release checksums - no Go toolchain needed in the image. Pin a release with {"version": "2.0.0"}, and pair it with "postCreateCommand": "mdm install -y" to restore everything in mdm.lock on create. See src/mdm/README.md for the full options.

Usage

mdm install                Restore everything mdm.lock records (skills, agents, knowledge, plugins)

mdm rules link             Set up AGENTS.md as source of truth and symlink harness files
mdm rules status           Show the state of all harness instruction files
mdm rules unlink           Remove symlinks created by mdm rules link

mdm skills add <package>   Add a skill from GitHub or URL
mdm skills cherry-pick     Fork third-party skills into ./skills as your own
mdm skills remove          Remove installed skills
mdm skills list            List installed skills
mdm skills find [query]    Search the registry
mdm skills update          Update installed skills
mdm skills audit           Check installed skills for updates and security advisories
mdm skills init [name]     Scaffold a new skill
mdm skills install         Restore skills, then agent definitions, from mdm.lock
mdm skills sync            Sync skills from node_modules

mdm knowledge add <source>  Install an OKF knowledge bundle into ./knowledge/
mdm knowledge list          List installed bundles (also: remove · update · validate · init · install)

mdm plugins add <source>   Install an Agent Plugin: link skills, wire MCP servers
mdm plugins list           List installed plugins (also: remove · update · validate · init · install)

mdm harnesses list         Show the configured harnesses for the current scope
mdm harnesses add          Add harnesses to the configured default install list
mdm harnesses remove       Remove harnesses (and their unique skill / instruction files)

mdm agents add <source>    Install agent definitions into your harnesses
mdm agents list            List installed agent definitions (also: remove · update · install)

mdm doctor                 Check installed skills and project markdown for health issues
mdm migrate                Fold v1 lock files into mdm.lock / mdm-state.json
mdm bug                    Open a prefilled bug-report form (nothing is sent automatically)
mdm upgrade                Upgrade the mdm CLI binary

Run mdm --help for the full command reference. See docs/rules.md for a detailed walkthrough of the mdm rules flow.

[!NOTE] Upgrading from v1 or an earlier v2 build: the AI tool is now a harness. mdm agents (which managed the configured tool list) is mdm harnesses, and --agent / -a on the skills, plugins, rules and cherry-pick commands is --harness. mdm agents now installs agent definitions, and mdm agents add <name> no longer configures a tool: use mdm harnesses add <name>. There is no alias, so an old script fails rather than doing something else. mdm.lock written by the earlier build is read as before.

[!NOTE] mdm harnesses remove openclaw and your ./skills/ directory. OpenClaw's project skills directory is skills/ - the same place many projects keep hand-written skills. Removing the harness deletes only what mdm installed there: the skills its lock records and the symlinks it created. A cherry-picked fork (which carries an .mdm-origin.json marker) and any hand-written skill the lock does not record are left in place. Every other harness uses a dot-prefixed or shared directory. See Troubleshooting.

Every install path - skills, agent definitions, knowledge bundles and plugins - runs a deterministic local hidden-character scan over markdown files before copying or symlinking content, and each exposes --allow-hidden-chars to override it deliberately. See docs/security/hidden-character-scan.md for the exact checks and bypass policy.

mdm agents add additionally refuses any directory a source declares for itself (an agentsDirs entry in .claude-plugin/marketplace.json) that would leave the source tree - a parent escape, a rooted path, or a directory that resolves through a symlink to somewhere else on your disk. Such an entry is dropped silently; the source's legitimate directories still install.

When installing from a git source, mdm restricts git to the https and ssh transports. This blocks git's ext::/fd:: local-command transports, which would otherwise let a repository source string - including one replayed from a checked-in mdm.lock - execute arbitrary commands. See docs/security/git-transport-restrictions.md for the rationale and the full allow/deny list.

How skills land in your repo, and what to commit

mdm skills add writes one canonical copy of each skill to .agents/skills/<name> and gives every harness you install to a relative symlink from its own skills directory (.claude/skills/<name>, .cursor/skills/<name>, and so on) back to that copy. Harnesses that read .agents/skills natively get no link at all.

Symlink is the default because the canonical directory is the only place the content lives. Installing to five harnesses does not mean five copies of the same files, an update touches one directory and every harness sees it at once, and there is never a question of which harness's copy is the current one.

Copy mode exists for tools that do not follow symlinks, such as sandboxed harnesses that refuse to traverse links, or a machine where symlinks cannot be created. Pass --copy once:

mdm skills add owner/repo --copy

The mode is a switch on the whole scope, not a property of one skill. --copy records installMode: copy in mdm.lock (or in the global state file with -g), converts the installs already in that scope to real directories, and every later add, update, and install in the scope copies without the flag. --symlink switches back the same way: it turns the copied installs into links again and records symlink mode, so the lock never needs editing by hand.

If a symlink cannot be created, mdm copies that install instead of failing, on the spot and per install. The usual cause is Windows without Developer Mode or the symlink privilege. Nothing is recorded: the scope stays in symlink mode, so the next mdm install or mdm skills update tries to link again. The install summary says which harnesses got copies and prints a warning to that effect. If copies are what you want on that machine, run with --copy once to record it; mdm doctor also reports a scope whose files are copies while its lock does not say so.

Do not commit the skills mdm manages. Commit mdm.lock and let mdm install regenerate the rest, the way a package lock is committed and the package directory is not:

• The content is duplicated. One skill is the canonical directory plus a link or a full copy per harness. Committing it puts the same files into your repository at two or more paths, and in copy mode that is a complete copy per harness, all of which have to agree.
• Remote skills drift. A skill from a GitHub, GitLab, or URL source is pinned by source and ref in mdm.lock. Once its files are committed, the repository has its own copy that nothing keeps in step with that ref: an update rewrites the files under a reviewer who cannot tell a local edit from an upstream change, and a local edit is silently lost on the next update. The lock is the record of what was installed; the files are its output.
• Symlinks do not travel well. Git stores a symlink as a path, and a checkout on a machine that cannot create symlinks leaves a text file where the link was. Regenerating from the lock on each machine avoids the problem.

Ignore the canonical directory and each harness's skills directory. This repository's own .gitignore is the shape to follow:

.agents
.claude/*
!.claude/settings.json

Add a line per harness you install to; mdm harnesses list shows the configured ones. Two things do belong in the repository: skills you write yourself, and forks made with mdm skills cherry-pick, which land in ./skills/ precisely so they can be committed and edited as your own. See docs/skills/add.md for the full install-mode rules and docs/skills/cherry-pick.md for forks.

Agent definitions

mdm agents writes agent definitions the same way - a canonical copy plus a link or a real copy per harness, governed by the same scope-wide install mode - and the same "commit mdm.lock, not the files it produces" rule applies. But --copy and --symlink no longer describe every file in the scope. GitHub Copilot's own copy, and any install that crosses formats (a markdown definition installed to Codex, or a Codex TOML definition installed to a markdown harness), are real files regardless of which mode the scope records. See docs/agent-artifacts.md for exactly which harnesses that covers and why.

GitHub Copilot's .github/agents is the one harness directory mdm writes into that is not meant to be ignored by default: GitHub documents it as the way to share agents through the repository, so mdm always writes a real file there, never a symlink. If your team does not want that, .github/agents can be gitignored on its own line while the rest of .github - workflows, CODEOWNERS, copilot-instructions.md - stays tracked:

.github/agents

Do that and the drift warning above still applies to it: the content duplicates what mdm.lock already pins, so it should come from mdm agents install or mdm agents update, not a hand edit.

Development

make build    # compile to ./mdm
make test     # run all tests
make install  # install to $GOPATH/bin
go run . --help

See .vscode/launch.json for VS Code debug configurations.