Install mdedit agent skills

Start with the four-skill catalog. Choose one transport for the agent doing the work:

CLI-backed is the portable default and requires mdedit-cli 0.4.0 or newer.
MCP-backed is recommended when a verified host plugin already configures the hosted mdedit MCP server.

Channel status

Channel	Status	What remains
Portable Agent Skills	Release candidate	CLI-backed skills generated for the open Agent Skills format. Public installation begins with mdedit-cli 0.4.0.
ChatGPT and Codex plugin	Release candidate	Package and live workflow qualification are complete; directory submission and publication remain human-gated.
Claude Code plugin	Release candidate	The package validates locally; production OAuth and marketplace publication remain release gates.
Cursor plugin	Planned	A generated candidate package exists, but IDE and CLI authentication and upstream acceptance are not yet verified.
Gemini CLI extension	Planned	A generated API-key candidate exists; OAuth compatibility and public extension distribution remain unverified.

Only channels marked Available should be presented as one-click public installs. Release-candidate and planned channels below document their intended commands and remaining requirements without implying marketplace availability.

Recommended setup by host

Host	Recommended setup	Current gate
ChatGPT and Codex	Install the official mdedit plugin after its directory listing is marked Available. Until then, use the portable CLI-backed skills where the host supports Agent Skills.	Human listing submission, publication, and public install verification.
Claude Code	Prefer the mdedit plugin and its MCP-backed skills after production OAuth is verified. The CLI-backed skills in `.claude/skills` are the release-candidate fallback.	Production OAuth and marketplace end-to-end evidence.
Cursor	Prefer the official plugin after publication; use `mdedit skill install --target cursor` for local CLI-backed evaluation.	IDE and CLI authentication verification plus upstream acceptance.
Gemini CLI	Prefer the official extension after publication; use `mdedit skill install --target gemini` for local CLI-backed evaluation.	OAuth compatibility and public extension verification.
Other compatible agents	Use portable Agent Skills with the CLI-backed default.	The host must support the Agent Skills format and allow `mdedit-cli` execution.

Perplexity remains part of the broader MCP connector roadmap, not the native Skills parity matrix.

Portable Agent Skills

After mdedit-cli 0.4.0 and the public artifacts are released, compatible Agent Skills installers can discover the catalog and four raw skill files from mdedit.ai:

npx skills add https://mdedit.ai

The public index is https://mdedit.ai/.well-known/skills/index.json. Its SKILL.md files are CLI-backed and declare mdedit-cli as a compatibility requirement.

Install with mdedit-cli

The native installer defaults to all four CLI-backed skills, project scope, and .agents/skills:

mdedit skill list
mdedit skill install
mdedit skill doctor

Choose individual skills, transport, scope, or host directory explicitly:

mdedit skill show revise-mdedit-document --via mcp
mdedit skill install save-mdedit-document revise-mdedit-document --via cli
mdedit skill install --via mcp --target claude --scope user
mdedit skill install publish-mdedit-document --via mcp --target cursor
mdedit skill install --via mcp --target gemini

Target	Project directory	User directory
`agents`	`.agents/skills`	`~/.agents/skills`
`claude`	`.claude/skills`	`~/.claude/skills`
`cursor`	`.cursor/skills`	`~/.cursor/skills`
`gemini`	`.gemini/skills`	`~/.gemini/skills`

Installations are atomic and idempotent. Each installed skill has mdedit ownership metadata and a content checksum. The installer refuses to overwrite an unowned or edited skill without --force; uninstall removes only unchanged mdedit-owned files.

Authenticate the transport

CLI-backed skills

Interactive browser OAuth is release-gated. Where enabled, use:

mdedit auth login
mdedit auth status

For CI or hosts without browser OAuth, create a scoped key in API Keys, then use MDEDIT_API_KEY or mdedit config login --api-key <key>. See the full CLI authentication reference.

MCP-backed skills

Host plugins connect to https://mcp.mdedit.ai/mcp. Use browser OAuth only in hosts where the production flow is marked verified. Other supported runtimes can use a scoped API key following MCP authentication. Do not put an API key in a committed plugin or skill file.

Update or change variants

Run the same install command after upgrading mdedit-cli. An unchanged mdedit-owned installation updates in place; an edited copy stops for review.

npm install -g mdedit-cli@latest
mdedit skill doctor --via cli
mdedit skill install --via cli

Switching from CLI-backed to MCP-backed instructions is explicit:

mdedit skill doctor --via mcp --target claude
mdedit skill install --via mcp --target claude

Uninstall

mdedit skill uninstall
mdedit skill uninstall publish-mdedit-document --target cursor
mdedit skill uninstall --scope user --target claude

If a skill changed after installation, uninstall leaves it in place. Review the local changes and remove it manually only if you intend to discard them.

Migrate legacy instructions

Older CLI releases appended a monolithic mdedit section to CLAUDE.md, wrote .cursor/rules/mdedit.mdc, or appended Copilot instructions. New releases never mutate those files. Diagnose them with:

mdedit skill doctor --format json

Review and remove a reported legacy block manually, then install the focused skills in the host’s native skill directory. doctor does not rewrite or delete host instructions.

Troubleshooting

Symptom	What to do
`unowned` or `modified` collision	Inspect the existing skill. Use `--force` only when installing and only if replacement is intentional.
`stale` in `doctor`	Upgrade the CLI and rerun the matching `install --via ...` command.
Authentication denied	Verify the selected transport, active CLI profile or MCP connection, and the scopes listed in the skill catalog.
Ambiguous workspace or document	Supply the exact returned workspace and document identity; do not guess from names.
Publish result has no public URL	Treat the operation as unsuccessful and do not construct an `mded.it` URL.
Marketplace install is unavailable	Check the channel matrix above. Planned and release-candidate packages are intentionally not advertised as available.

For CLI command behavior, see CLI. For public visibility semantics, see Public links and publishing.

Skill catalog Overview