mda: one Markdown superset for four agent runtime wrappers
MDA Open Spec — a Markdown superset for agent-facing documents. One .mda source compiles to drop-in SKILL.md, AGENTS.md, MCP-SERVER.md, and CLAUDE.md. JSON Schema validated, with typed dependency graph, footnote relationships, and Sigstore-anchored signatures. For agentskills.io and AAIF runtimes.
At a glance
- What is it?
- MDA Open Spec is a TypeScript project that compiles a single .mda source into SKILL.md, AGENTS.md, MCP-SERVER.md and CLAUDE.md, adding typed dependency edges and Sigstore-anchored signatures in frontmatter while keeping every extension optional.
- Who is it for?
- mda is worth a trial if you already publish the same instructions to several agent runtimes and your wrappers have drifted, because the compiler plus the integrity fields attack the same duplication that produced the drift. Do not expect it to solve provenance you do not have: a DSSE envelope and a Sigstore signature only mean something if an identity in the chain can be verified at load time, and the documentation collected here shows no install command for the CLI at all.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 173 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- sno-ai/mda616 ★ · +0
| Repository | 2026-09-11 | 2026-11-15 |
|---|---|---|
| sno-ai/mda | 616 | 616 |
0 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
One .mda source compiles into four runtime wrappers
The problem MDA starts from is duplication with a long fuse. The same skill gets shipped once as `SKILL.md` for the agentskills.io runtimes, once as `AGENTS.md` for the AAIF ecosystem, once as `MCP-SERVER.md` with a JSON sidecar, and once as `CLAUDE.md`. The content matches and the frontmatter shape does not, because every runtime has its own opinion about what belongs at the top of a file. Update one wrapper, forget the others, and a month later four instruction files quietly disagree with each other. MDA replaces the four files with one `<name>.mda` source and a `mda compile` step. The output layout is not uniform, and that is worth noticing before you wire it into a build. The `SKILL.md` target becomes a `<name>/` directory with `scripts/`, `references/` and `assets/` beside it, and the `MCP-SERVER.md` target keeps its own folder plus an `mcp-server.json` sidecar, while `AGENTS.md` and `CLAUDE.md` are emitted as flat files. Two targets are trees, two are single documents.
Five runtimes verified in compat/, ten more reached by documentation
Compatibility is claimed at two very different strengths, and the difference decides how much you should test yourself. Five SKILL.md runtimes are verified end to end with reproducible install kits kept in `compat/`: claude-code, codex-cli, opencode, hermes and openclaw. Those are the ones where an install kit exists to inspect. The compiled `AGENTS.md` output is aimed at a longer list that names Codex, Copilot, Cursor, Windsurf, Amp, Devin, Gemini CLI, VS Code, Jules and Factory, and the documentation adds skills.sh and other 2026 SKILL.md consumers at the documentation level only. Read that as one verified tier and one asserted tier. The release notes for v1.0.0-rc.4 use the same wording, five runtimes verified, which is a candid label: the project is telling you which number it stands behind. The `compat/` tree is therefore the part of the repository to read first if you are deciding whether your own runtime is covered.
integrity.digest and signatures[] moved out of prose and into frontmatter
The second gap MDA targets is quieter than file drift. None of the four standard frontmatter shapes has anywhere to put a content digest or a signature, so the trust decision about an agent-facing file collapses into trusting the repository it came from. The agent loading `SKILL.md` cannot check that the bytes match what the author wrote, and the curator reviewing `AGENTS.md` cannot tell whose hands touched the file between merge and load. MDA puts a JCS-canonicalized `integrity.digest` and DSSE-enveloped, Sigstore-anchored `signatures[]` in the frontmatter itself. Canonicalization is what makes the digest reproducible across runs, the DSSE envelope is the signed wrapper, and Sigstore is the transparency anchor behind it. The README makes the point with a claim you can now actually write down: a file signed by a given identity at a given Rekor index. Both the agent at load time and the human at review time check the artifact in hand instead of a feeling about the repo. The spec text lives in `spec/v1.0/08-integrity.md` and `spec/v1.0/09-signatures.md`.
Footnotes carry typed edges and frontmatter carries the dependency graph
The third addition moves relationships out of sentences. A typed relationship is an ordinary Markdown footnote whose payload is a JSON object, and the allowed types are `parent`, `child`, `related`, `cites`, `supports`, `contradicts` and `extends`. On compile those relationships are mirrored into `metadata.mda.relationships` in body order, so the compiled document keeps both the human-readable footnote and the machine-readable edge. The distinction the project cares about is `supports` versus `cites`, which in prose are the same sentence to a reader and different facts to a graph. The YAML frontmatter carries the other half of the graph: `doc-id`, `version`, `requires`, `depends-on`, `relationships` and `tags`, beyond the open-standard `name` and `description` baseline. Agent-aware tools use those fields for routing, dependency resolution and graph traversal, and they are what lets a document state that it needs another skill at version `^1.2.0` with a given content digest. The details sit in `spec/v1.0/03-relationships.md`, `spec/v1.0/02-frontmatter.md` and `spec/v1.0/10-capabilities.md`.
Every MDA extension is optional, and so is the format
The design constraint that makes adoption cheap is also the one that limits the payoff. All three additions are optional, and a `.mda` source that carries only the open-standard frontmatter compiles unchanged into a `.md` file. Nothing in the compilation step requires you to adopt integrity digests, typed footnotes or the dependency fields, which means a team can start with the compiler alone and add trust metadata later without a migration. The tradeoff is that the interesting parts are opt-in, so two projects using the same format can still produce artifacts with wildly different guarantees. The README states the boundary plainly: use as much or as little of MDA as the project needs. The same section notes that everything new is optional because the Markdown body still renders and the standard fields still load, which is the compatibility story in one sentence. Validation is the other half of the bargain, and it is claimed as strict: the project describes it as catching almost-conformant artifacts before they ship.
The root manifest says 1.0.0 while the newest release is @markdown-ai/cli 1.1.7
The version numbers in this repository do not line up, and anyone pinning a dependency needs to know which file to trust. The root `package.json` is named `markdown-for-agent` and carries version 1.0.0. The release history is a different set of names: v1.1.7 published as `@markdown-ai/cli` 1.1.7, plus two release candidates for the spec itself, v1.0.0-rc.4 labelled as five runtimes verified and v1.0.0-rc.3 labelled as the reference CLI published. Three of the releases carry the same date, 2026-05-26, which is also the date of the last push. So the published artifact appears to be a scoped CLI package while the repository root is the spec workspace, and no release tag matches the root version 1.0.0. The root scripts support that reading: `dev2main` shells out to a script, and `cli:build` and `cli:test` both delegate into `apps/cli`, which is where the compiler actually lives. The project also hosts documentation at mda.sno.dev, separate from the repository.
pnpm overrides pull vite 6 over the vite 5 the manifest pins
Inside the same root manifest sits a contradiction worth flagging before you install anything. `vite` is declared in devDependencies as the exact version 5.4.21, while the `pnpm.overrides` block demands `vite` `>=6.4.2`. The override wins on install, so the number written in devDependencies does not describe what lands in your tree. The same block handles a long security-flavoured list of floors, including `tar` `>=7.5.11`, `minimatch` `>=3.1.3`, `qs` `>=6.15.2`, `axios` `>=1.15.2`, `express` `>=4.21.0`, `cookie` `>=0.7.0`, `postcss` `>=8.5.10` and `esbuild` `>=0.25.0`, and it also repeats a floor for `js-yaml`. Alongside them sit runtime dependencies that have little to do with compiling Markdown, such as `react-tweet`, `basic-ftp`, `smol-toml` and `undici`, which suggests the root manifest carries weight for the apps and documentation workspaces rather than for the compiler alone. For a reviewer, the practical point is that `vite` in devDependencies is a stale label, and the overrides block is the real dependency policy.
The authoring-modes section stops after its first entry
One gap should be stated rather than papered over. The README opens a section on three authoring modes, saying that MDA artifacts may be produced three ways and that the three are equivalent under validation, and then the text breaks off partway through the first numbered entry. The other two modes are not described in the copy available here, so this page does not name them. What is missing from that section is also missing from the rest: no install command for the CLI appears anywhere in the documentation collected, so the entry points on offer are the site, the release tags and the root scripts. Elsewhere the repository is unusually well organised for a spec project. There are `spec/`, `schemas/`, `conformance/`, `compat/`, `apps/`, `docs/` and `types/` directories, a `SPEC.md`, a `REGISTRY.md`, a `SECURITY.md`, an `llms.txt`, and eight translations of the README under `docs/readme/`. The `examples/` tree splits into `skill-md/` and `source-only/`, which is a compact demonstration of the optionality claim.
Editorial conclusion
mda is worth a trial if you already publish the same instructions to several agent runtimes and your wrappers have drifted, because the compiler plus the integrity fields attack the same duplication that produced the drift. Do not expect it to solve provenance you do not have: a DSSE envelope and a Sigstore signature only mean something if an identity in the chain can be verified at load time, and the documentation collected here shows no install command for the CLI at all. Check mda.sno.dev and the release tags first, read spec/v1.0/08-integrity.md and spec/v1.0/09-signatures.md before trusting the digest story, and confirm that the five verified runtimes under compat/ include the ones you actually ship to.
Frequently asked questions
What does mda compile from, and what does it produce?
One .mda source compiles into SKILL.md with scripts, references and assets beside it, a flat AGENTS.md, an MCP-SERVER.md with an mcp-server.json sidecar, and a CLAUDE.md.
Does an mda document have to carry a Sigstore signature?
No. All three MDA additions are optional, and a source with only the open-standard frontmatter compiles unchanged into a .md file, so the integrity fields are something you opt into.
Which agent runtimes has mda verified end to end?
Five SKILL.md runtimes, with reproducible install kits under compat/: claude-code, codex-cli, opencode, hermes and openclaw. Compiled AGENTS.md output is aimed at a wider group including Codex, Copilot, Cursor, Windsurf, Amp, Devin, Gemini CLI, VS Code, Jules and Factory.
How does mda record a dependency between two documents?
YAML frontmatter carries doc-id, version, requires, depends-on, relationships and tags, and footnote payloads are typed as parent, child, related, cites, supports, contradicts or extends, mirrored on compile into metadata.mda.relationships.
How do I install the mda command line tool?
The documentation collected for this page shows no install command. The entry points it gives are the site mda.sno.dev, the releases v1.1.7, v1.0.0-rc.4 and v1.0.0-rc.3, and the root package.json scripts cli:build and cli:test, which build and test the CLI in apps/cli.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/sno-ai-mda)Star history chart for your README
[](https://hysenlabs.com/projects/sno-ai-mda)Was this useful?