Write One Skill Source, Compile It for Every Major Agent Runtime with MDA

You maintain one skill, but every runtime wants its own wrapper: SKILL.md for agentskills.io runtimes, AGENTS.md for the AAIF ecosystem, MCP-SERVER.md with a JSON sidecar, CLAUDE.md for Claude. Update one, forget the others, and a month later the files have drifted apart. MDA, a 616-star open spec from sno-ai, compiles a single .mda source into all of them.

Why This Skill Matters

MDA is a Markdown superset for agent-facing documents. One .mda source compiles into the .md files every major agent runtime already loads: SKILL.md, AGENTS.md, MCP-SERVER.md (plus an mcp-server.json sidecar), and CLAUDE.md. Five SKILL.md runtimes are verified end-to-end with reproducible install kits in the repo's compat/ directory: Claude Code, Codex CLI, OpenCode, Hermes Agent, and OpenClaw. Compiled AGENTS.md artifacts also drop into the AAIF ecosystem (Codex, Copilot, Cursor, Windsurf, Amp, Devin, Gemini CLI, VS Code, Jules, Factory).

Deduplication is only half the pitch. Standard frontmatter has nowhere to put a content digest or a signature, so the trust decision falls back to a feeling about the repo. MDA carries a JCS-canonicalized integrity digest and DSSE-enveloped, Sigstore-anchored signatures[] in the frontmatter itself, so both the agent at load time and the human at review time can verify the artifact in hand.

On top of standard Markdown, .mda adds three optional things: rich YAML frontmatter (doc-id, version, requires, depends-on, relationships, tags), typed footnote relationships (parent, child, related, cites, supports, contradicts, extends), and the cryptographic identity above. A source with only the open-standard frontmatter compiles unchanged into a .md — adopt as much or as little as you need.

Installation

The reference CLI ships as the npm package @markdown-ai/cli; the installed binary is mda. Install it globally, or run it without installing:

npm install -g @markdown-ai/cli
# or, without installing:
npx @markdown-ai/cli --help

The current release is candidate v1.0.0-rc.3.

Real Workflow: Ship One Skill to Claude Code and Codex

1. See the whole pipeline in one command. npx -y @markdown-ai/cli demo writes mda-demo/hello.mda plus SKILL.md, AGENTS.md, MCP-SERVER.md, and mcp-server.json outputs, each with a sha256 integrity digest.
2. Author a source. mda init code-review --out code-review.mda scaffolds the file; edit the name, description, metadata, and body.
3. Validate before compiling:

mda validate code-review.mda

4. Compile with integrity, targeting only the runtimes you ship to:

mda compile code-review.mda --target SKILL.md AGENTS.md --out-dir out --integrity

5. Validate and verify the emitted artifacts, not just the source:

mda validate out/SKILL.md --target SKILL.md
mda validate out/AGENTS.md --target AGENTS.md
mda integrity verify out/SKILL.md --target SKILL.md

The same flow has an agent mode: append --json — the CLI manual recommends it for almost every command — and you get stable ok, artifacts, diagnostics, and nextActions fields for scripts and CI gates.

Tips

• Start with open-standard frontmatter only. Everything MDA adds is optional; a .mda that carries just name and description compiles into a plain, valid .md.
• The three authoring modes — agent-written, human-written, compiled — are judged against the same JSON Schema 2020-12 target and the same conformance suite. There is no second code path for agent output.
• Keep the CLI out of your runtime. The README positions @markdown-ai/cli as an authoring, CI, and agent-side checking tool; runtime libraries should keep their own lightweight loaders and verifier hooks.
• Licensing is split: CC-BY-4.0 for the spec content, Apache-2.0 for schemas and tooling.

When Not to Use This

The README's own "Status, honestly" section is the boundary. v1.0 ships the contract, not the ecosystem: a bundled signature verifier is not shipped yet, a dependency resolver and central artifact registry do not exist yet, and no 2026 multi-agent harness is known to route through metadata.mda.requires. The spec also does not target Cursor MDC, Windsurf rules, Continue, Aider, or *.instructions.md — those still need parallel maintenance. And if you ship one skill to one runtime, a plain SKILL.md is simpler than a compiler.

See the leaderboard for more skills.