# sno-ai/mda: One .mda Source Compiles to SKILL.md, AGENTS.md, MCP-SERVER.md and CLAUDE.md

> MDA Open Spec is a Markdown superset that compiles a single source file into the agent-facing documents four runtimes already load, with JSON Schema validation and Sigstore-anchored signatures in the frontmatter. It is for teams maintaining the same skill across multiple agent runtimes.

**sno-ai/mda** — 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.

- Repository: https://github.com/sno-ai/mda
- Website: https://mda.sno.dev
- Stars: 617 · Forks: 32
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/sno-ai-mda

## The four-file drift problem MDA was written to end

The README opens with the author's own account: the same skill shipped 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, once as CLAUDE.md. Same content, four frontmatter shapes. Update one and forget the others, and the README's claim is that a month later the four files have "quietly drifted into four slightly different instruction files."

The audience is narrow and specific: people who publish agent-facing documents into more than one runtime. If you only ever write a CLAUDE.md, the compiler adds a build step and a schema to maintain for no fan-out benefit. The project's value proposition is proportional to how many targets you actually emit.

## What the compiler actually emits, and in what shape

The README shows the pipeline as a single source moving through a deterministic compile step. The output is not one file but a directory: `<name>/SKILL.md` alongside `scripts/`, `references/` and `assets/`, plus `AGENTS.md`, plus `<name>/MCP-SERVER.md` with an `mcp-server.json` sidecar, plus `CLAUDE.md`. The README describes the result as "drop-in compatible," meaning the emitted files are meant to be consumed unchanged by the runtimes that expect them.

On top of standard Markdown, MDA adds three optional layers. Rich YAML frontmatter carries `doc-id`, `version`, `requires`, `depends-on`, `relationships` and `tags` in addition to the baseline `name` and `description`. Typed footnote relationships use standard Markdown footnotes whose payload is a JSON object with one of `parent`, `child`, `related`, `cites`, `supports`, `contradicts` or `extends`, mirrored to `metadata.mda.relationships` in body order at compile time. Cryptographic identity is a JCS-canonicalized `integrity` digest plus DSSE-enveloped, Sigstore-anchored `signatures[]`. The README states all three are optional, and that a `.mda` source carrying only the open-standard frontmatter compiles unchanged into a `.md`.

## Installing the CLI and compiling a first source

The repository is a pnpm workspace. The root `package.json` names the package `markdown-for-agent` at version 1.0.0 under Apache-2.0, and its scripts build the CLI from the `apps/cli` workspace. The README does not give a single global install command, so the reproducible path from the repository layout is to clone and build from source:

```bash
pnpm install
pnpm cli:build
```

The `cli:build` script runs `pnpm -C apps/cli build`. The README's pipeline diagram labels the compile step simply as `mda compile`, invoked against a `<name>.mda` source. After a compile you should see the emitted directory tree the README documents: a `<name>/` folder containing `SKILL.md` with `scripts/`, `references/` and `assets/`, a top-level `AGENTS.md`, a `<name>/MCP-SERVER.md` with its `mcp-server.json` sidecar, and a `CLAUDE.md`.

The repository ships worked examples under `examples/`, split into `examples/skill-md/` and `examples/source-only/`. Those directories are the fastest way to see what a valid source looks like before writing your own, since the README itself does not walk through a full source file. The `spec/v1.0/` directory holds the normative documents the README cites for each feature: `02-frontmatter.md` and `10-capabilities.md` for frontmatter, `03-relationships.md` for footnotes, `08-integrity.md` and `09-signatures.md` for the cryptographic layer. The `schemas/` directory at the repository root holds the JSON Schemas that validate all of it.

## Where the specification is still ahead of the ecosystem

The README is unusually candid about this. It says the two long-form documents in `docs/v1.0/` "call out current ecosystem gaps inline." A specification can define a `depends-on` field with a version range and a content digest, but that only pays off when a consuming runtime reads the field and acts on it. The README's own framing is that the information previously had "nowhere to put it, so it sits in prose, where neither agents nor humans can act on it reliably." Moving it into validated frontmatter is a necessary step, not a sufficient one.

The compatibility claim is also bounded. Five SKILL.md runtimes are described as verified end-to-end with reproducible install kits in `compat/`: Claude Code, Codex CLI, OpenCode, Hermes Agent and OpenClaw. The AAIF list is longer (Codex, Copilot, Cursor, Windsurf, Amp, Devin, Gemini CLI, VS Code, Jules, Factory) but the README qualifies it as dropping in "at the documentation level," and mentions skills.sh as a 2026 SKILL.md consumer at the same level. Documentation-level compatibility is a weaker claim than the end-to-end verification given to the five. If your runtime is not among the five with a `compat/` kit, treat the drop-in promise as untested for your case.

The release picture is also worth reading carefully. The most recent release listed is v1.1.7 of `@markdown-ai/cli` on 2026-05-26, and the README's own release badge still points at v1.0.0-rc.3. The spec itself is at v1.0.0-rc.4, described as "five runtimes verified." A release candidate for the specification alongside a numbered CLI release is a normal split, but it means the spec is not yet declared 1.0 final. The last push to the repository was on 2026-05-26.

## The alternative: hand-maintained per-runtime files

The real alternative is what the README's author was doing before writing this: keep four hand-edited files and a checklist. That approach has no build step, no schema, no pnpm workspace, and no new file extension to explain to contributors. It also has no mechanism to detect drift, which is the failure the README describes from experience.

A second alternative is generating the per-runtime files with a bespoke script or a general templating tool. That gets you single-source authoring, but it does not get you a published JSON Schema, typed relationship footnotes, or the `integrity` digest and `signatures[]` layer. The difference is not the fan-out; a template can do fan-out. The difference is that MDA defines what goes in the frontmatter and validates it, so the output is checkable by something other than the script that produced it. Whether that matters depends on whether anyone downstream needs to verify the artifact rather than trust the repository it came from. The README puts the trust question directly: the standard frontmatter shapes have nowhere to put a digest or signature, so the decision "quietly falls back to 'we trust the repo, somehow.'"

## Licence and the cost of tracking a release candidate

The repository is Apache-2.0, and the root `package.json` declares the same. Apache-2.0 permits commercial use and modification and includes a patent grant, which matters for a specification you may want to embed in a product. It also requires that you preserve the licence and attribution notices in redistributed copies. This is a description of the licence text, not legal advice; if you plan to relicense compiled artifacts or bundle the CLI, read the LICENSE file and the NOTICE requirements yourself.

Upgrade cost is dominated by the release-candidate status of the specification. The spec is at v1.0.0-rc.4 while the CLI is at v1.1.7, so the two version lines move independently. A change to the frontmatter schema or the relationship vocabulary between release candidates would invalidate sources you have already written, and because the frontmatter is validated against JSON Schema in `schemas/`, a schema change surfaces as a validation failure rather than silent drift. That is the better failure mode, but it is still work. The `CHANGELOG.md` at the repository root is where the project records what moved between releases; the README does not document a migration path between spec versions, so check the changelog before upgrading the CLI across a spec boundary.

## Conclusion

Adopt sno-ai/mda if you maintain the same skill across several agent runtimes and have felt the four files drift apart. Do not adopt it if you only ship one target file: the compiler earns its keep through fan-out, not through single-file authoring. Before committing, verify that the runtimes you actually load skills into appear in the compat/ directory with a reproducible install kit, and check whether the release you install is the v1.0.0 release candidate or the v1.1.7 CLI line, since the README's badge still points at v1.0.0-rc.3.

## FAQ

### What is sno-ai/mda?

It is a Markdown superset for agent-facing documents, described in the README as "one source, many targets." A single .mda file compiles into SKILL.md, AGENTS.md, MCP-SERVER.md with a sidecar JSON, and CLAUDE.md.

### How do I install the MDA CLI?

The README does not give a global install command. The repository is a pnpm workspace whose root package.json defines a cli:build script that runs pnpm -C apps/cli build, so the documented path from the repository layout is to install dependencies and build from source.

### Which agent runtimes are verified for sno-ai/mda?

The README states that five SKILL.md runtimes are 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 at the documentation level.

## Sources

- [License: Apache-2.0](https://github.com/sno-ai/mda/blob/main/LICENSE)
- [Project website](https://mda.sno.dev)
- [README](https://github.com/sno-ai/mda/blob/main/README.md)
- [Releases](https://github.com/sno-ai/mda/releases)
- [sno-ai/mda on GitHub](https://github.com/sno-ai/mda)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sno-ai-mda