MDA Open Spec: One .mda Source for SKILL.md, AGENTS.md, MCP-SERVER.md and CLAUDE.md

The four-file drift problem MDA was written to solve

The README states the problem in the first person: the author kept shipping the same skill four times, once as SKILL.md for agentskills.io runtimes, once as AGENTS.md for the AAIF ecosystem, once as MCP-SERVER.md with a sidecar JSON, and once as CLAUDE.md. Same content, four frontmatter shapes. The stated failure mode is not the initial duplication but what happens a month later, when a paragraph edited in SKILL.md never reaches AGENTS.md and the four files become four slightly different instruction files.

That is a maintenance problem with a specific shape. The content is identical; only the wrapper differs. A compiler that owns the wrapper and leaves the content alone is the correct fix, and that is what MDA claims to be. The audience is narrow and identifiable: people publishing skills or agent instruction documents to more than one runtime, who have already felt the drift. If you target one runtime, the premise does not apply to you and the rest of the project is overhead.

What mda compile actually emits

The pipeline in the README is a single source file going through mda compile into four outputs. SKILL.md is emitted inside a directory named after the skill, alongside scripts/, references/ and assets/. MCP-SERVER.md gets a sidecar file, mcp-server.json. AGENTS.md and CLAUDE.md are emitted as flat files. The README describes the result as drop-in compatible, meaning the compiled artifacts are meant to load in the target runtimes without further editing.

The compatibility claim is scoped. Five SKILL.md runtimes are listed as verified end-to-end with reproducible install kits in compat/: Claude Code, Codex CLI, OpenCode, Hermes Agent and OpenClaw. Compiled AGENTS.md artifacts are said to 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. Note the hedge on that second list: documentation level is weaker than the end-to-end verification claimed for the five SKILL.md runtimes, and the README does not spell out what the difference means in practice. That is the first thing to test against your own target.

Three optional additions on top of standard Markdown

MDA adds rich YAML frontmatter, typed footnote relationships, and cryptographic identity. All three are optional, and the README is explicit that a .mda source carrying only the open-standard name and description fields compiles unchanged into a .md file. That matters for adoption cost: you can start with the compile step alone and add the rest later.

The frontmatter beyond the baseline carries doc-id, version, requires, depends-on, relationships and tags. The README says agent-aware tools use these for routing, dependency resolution and graph traversal, and points at spec/v1.0/02-frontmatter.md and spec/v1.0/10-capabilities.md. The dependency graph is typed: requires and depends-on are separate keys, and the README gives the example of depending on another skill at version ^1.2.0 with a content digest attached. That is a shape a JSON Schema can validate, which is the point of putting it in frontmatter rather than prose.

Typed footnotes are standard Markdown footnotes whose payload is a JSON object. The relationship types listed are parent, child, related, cites, supports, contradicts and extends. On compile they are mirrored to metadata.mda.relationships in body order. The README's own example of why this matters is the distinction between supports and cites: there is no place in the four standard formats to record that difference, so it ends up in prose where neither an agent nor a reviewer can act on it reliably.

The integrity and signature layer, and where it stops

Every compiled artifact carries a JCS-canonicalized integrity.digest, according to the README. Signed artifacts additionally carry DSSE-enveloped, Sigstore-anchored signatures[] in the frontmatter. The argument for this is stated plainly: 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, because the standard frontmatter shapes have nowhere to put a digest or a signature. The trust decision therefore falls back to trusting the repository.

That is a fair criticism of the status quo. The honest limitation is on the other side. MDA defines where a digest and a signature live and how they are canonicalized. It does not, from anything in the supplied material, provide the verification infrastructure. Sigstore and Rekor are external services; the README mentions a Rekor index as the kind of thing you cannot currently express, which tells you the signing path assumes a transparency log exists and is reachable. Whether an agent runtime performs the verification at load time, or merely carries an unverified signatures[] array in frontmatter, is not answered in the material I have. Tamper-evidence is only as useful as the check someone actually runs. Treat the signing layer as a contract definition, not as a working trust system, until you have confirmed who verifies and when.

Getting it running: the CLI and the spec files

The published entry point is @markdown-ai/cli, released as v1.1.7 on 2026-05-26. The README shows mda compile as the command that turns a source into the four outputs, and the diagram names the source pattern as <name>.mda. Beyond that, the supplied material does not include the full command line, so flags, output directory selection and any verify subcommand are not something I can state here.

The specification is versioned and split by concern under spec/v1.0/: 02-frontmatter.md, 03-relationships.md, 08-integrity.md, 09-signatures.md and 10-capabilities.md are the files the README cites. Those are where the schema-level detail lives, and they are the right place to start if you need to know exactly which frontmatter keys are required versus optional, or how the footnote payload is validated. The homepage is mda.sno.dev, and the README points to longer documents under docs/v1.0/ that trace each claim back to a spec section and call out ecosystem gaps inline. Read those before committing, since they are the project's own account of where the surrounding ecosystem does not yet meet the spec.

Release-candidate status is the adoption constraint

The latest spec release is v1.0.0-rc.4, dated 2026-05-26, described as five runtimes verified. The prior two releases were v1.0.0-rc.3 (reference CLI published) and the CLI line at v1.1.7. The README's own badge still points at v1.0.0-rc.3, which is a small inconsistency but a useful signal about how fast the documents trail the releases.

A release candidate is a real constraint, not a formality. The spec files are versioned under spec/v1.0/, which means the frontmatter keys, the relationship vocabulary and the integrity field layout are all still subject to change before 1.0.0 lands. If you compile artifacts that other people load, a spec revision can invalidate the digests you have already published, because the digest is computed over canonicalized content that includes the frontmatter. Plan for regeneration, and keep the compiled outputs in version control so a diff shows you what a spec bump changed rather than discovering it in a runtime.

Where a single-target project should look instead

The obvious alternative is not another compiler. It is a plain Markdown file plus a small build script, or a templating step in whatever CI you already run. If you only ship CLAUDE.md, a Jinja or Handlebars template that injects shared sections into a Markdown body gets you the deduplication without adopting a spec, a schema and a signing story. The difference in approach is that MDA defines a document format with a validation contract and a canonicalization rule; a template just concatenates strings. You pay for the contract in spec surface area, and you get typed relationships and a reproducible digest in return.

If you need dependency metadata specifically, and not the multi-target compile, a package manifest you already have (package.json, a lockfile) can express versioned dependencies without a new frontmatter dialect. MDA's value over that is putting the dependency next to the document it describes, in a file the runtime loads anyway. That is a genuine advantage for agent-facing docs and a genuine duplication of what your build system already tracks. Pick based on whether the agent needs to resolve the dependency at load time or whether your CI resolves it before the artifact ships.

Licence and the cost of keeping up

The repository is Apache-2.0. That is a permissive licence with an explicit patent grant and a requirement to preserve notices and state changes, which matters if you redistribute compiled artifacts or vendor the CLI. It does not require you to open your own skill sources. None of this is legal advice; if you are embedding the compiler in a product, have someone read the LICENSE file rather than a review.

Maintenance cost has two components. The first is the compile step itself, which is small if you keep your sources in the same repository as the artifacts and regenerate on change. The second is spec churn while the project sits at v1.0.0-rc.4. Every frontmatter or canonicalization revision can change the digest of every artifact you have published, which turns a spec upgrade into a signing event across your whole document set. That cost is proportional to how many artifacts you sign and how many consumers check the signature. If nothing verifies the signature, the churn buys you nothing.

Editorial conclusion

Adopt MDA if you already maintain more than one of SKILL.md, AGENTS.md, MCP-SERVER.md or CLAUDE.md by hand and have felt them drift, and if you can accept a v1.0.0 release candidate as your build dependency. Do not adopt it if you ship to a single runtime, or if the Sigstore path is the reason you are interested, because signature verification depends on infrastructure the spec documents but does not itself provide. Verify three things first: that mda compile against your own source produces byte-stable output across two runs, that the emitted frontmatter still loads in each runtime you target, and that your reviewers can actually resolve a signer identity rather than just seeing a signatures[] array they cannot check.

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. sno-ai/mda on GitHub