📝 MDA Open Spec — Markdown for Agent

A Markdown superset for agent-facing documents. One source, many targets — compile into the .md files every major agent runtime already loads. Tamper-evident at load — every artifact carries a reproducible content digest, and signed artifacts carry Sigstore-anchored signatures, so neither the agent loading the doc nor the human reviewing it has to trust an unsigned blob.

Read in other languages: English · 中文 · Deutsch · Español · Français · Русский · 한국어 · 日本語 · हिन्दी

What MDA is

Until now, you shipped the same skill four times. Once as SKILL.md for the agentskills.io runtimes. Once as AGENTS.md for the AAIF ecosystem. Once as MCP-SERVER.md with a sidecar JSON. Once as CLAUDE.md. Same content, four frontmatter shapes. Update one, forget the others, and a month in, the four files have quietly drifted into four slightly different instruction files.

You write one .mda. The compiler emits the rest.

                ┌─────────────────────────┐
                │   <name>.mda  (source)  │   ← MDA superset
                └────────────┬────────────┘
                             │  mda compile
                             ▼
   ┌─────────────────────────────────────────────────────────┐
   │ <name>/SKILL.md     (+ scripts/, references/, assets/)  │
   │ AGENTS.md                                               │
   │ <name>/MCP-SERVER.md  (+ mcp-server.json sidecar)       │
   │ CLAUDE.md                                               │
   └─────────────────────────────────────────────────────────┘
                       drop-in compatible

Compatibility

Write your skill once. It drops into every major agent runtime — unchanged.

Five SKILL.md runtimes verified end-to-end with reproducible install kits in compat/. Compiled AGENTS.md artifacts also drop into the AAIF ecosystem (Codex, Copilot, Cursor, Windsurf, Amp, Devin, Gemini CLI, VS Code, Jules, Factory), and at the documentation level into skills.sh and other 2026 SKILL.md consumers.

And those four files can't say who signed them. The agent loading SKILL.md has no way to verify the content matches what you wrote, and the curator reviewing AGENTS.md has no way to know whose hands have been on it between merge and load. The standard frontmatter shapes have nowhere to put a content digest or a signature, so the trust decision quietly falls back to "we trust the repo, somehow."

MDA carries a JCS-canonicalized integrity.digest and DSSE-enveloped, Sigstore-anchored signatures[] in the frontmatter itself. Both sides — the agent at load time and the human at review time — can make a real trust decision against the artifact in hand, not against a feeling about the repo. Tamper-evidence and signer verification ship in the contract, not as a later bolt-on.

.mda adds three things on top of standard Markdown. All of them optional.