MDA Open Spec 🧩 Skill Open source

What it does

MDA (Markdown for Agent) is an open specification and reference CLI for writing agent-facing documents once and compiling them into the several .md shapes different runtimes expect. Today a skill often ships four times, as SKILL.md, AGENTS.md, MCP-SERVER.md and CLAUDE.md, with the same body and four different frontmatter shapes that quietly drift apart. With MDA you write one .mda source and the compiler emits the rest, drop-in compatible. It also adds what those formats cannot express: a content digest for tamper detection and optional Sigstore-anchored signatures, so both the agent loading a document and the human reviewing it can make a real trust decision about the artifact in hand.

What is inside

• The normative MDA Open Spec (frontmatter, typed footnote relationships, integrity, signatures, capabilities, conformance) with JSON Schemas and a conformance suite
• A .mda superset that stays valid Markdown: rich frontmatter (doc-id, version, requires, depends-on, relationships, tags), typed relationship footnotes, and a JCS-canonicalised integrity digest plus DSSE/Sigstore signatures, all optional
• A TypeScript reference CLI (@markdown-ai/cli, the mda binary) to init, validate, compile, sign, verify and integrity-check artifacts, usable by humans and as an agent-side gate

Works with

Compiled SKILL.md outputs are verified against Claude Code, Codex CLI, OpenCode, Hermes and OpenClaw; compiled AGENTS.md also drops into the AAIF ecosystem (Codex, Copilot, Cursor, Windsurf, Amp, Devin, Gemini CLI and others).

How to install

npm install -g @markdown-ai/cli
mda --help

Or run without installing:

npx -y @markdown-ai/cli demo

Maintenance and safety

Spec content is CC-BY-4.0; schemas, tooling and reference code are Apache-2.0. The project is candid about scope: v1.0 ships the contract (author, compile, validate), while a bundled signature verifier, dependency resolver, registry and graph indexer are still being built, and it does not yet target Cursor MDC, Windsurf rules or *.instructions.md. The CLI touches no network unless you ask it to.

Who should use it

Authors and teams who maintain the same skill or instruction file across multiple agent runtimes and are tired of keeping four copies in sync, especially those who want tamper-evidence and signer attribution built into the format.