MDA: one source for SKILL.md and AGENTS.md
MDA
The mda CLI compiles one .mda file into ready SKILL.md, AGENTS.md and MCP-SERVER.md files and validates them against JSON Schema.
- 621 ★ on the repository
- Last commit
Extended access
Why this level
- The `mda compile` command writes files into the chosen folder, and `mda integrity compute --write` changes the header of the source file
- Running through npx executes the package code from npm, and signing talks to external Sigstore services
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/mdaDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The `mda compile` command writes files into the chosen folder, and `mda integrity compute --write` changes the header of the source file
- Running through npx executes the package code from npm, and signing talks to external Sigstore services
This is third-party code. Review the repository files before installing.
What it does
MDA is an open specification of extended Markdown for documents that agents read. The author names the problem: one skill has to be kept in SKILL.md, AGENTS.md, MCP-SERVER.md and CLAUDE.md, and the copies drift apart over time. With MDA you write one `.mda` file and the compiler emits the rest. On top of the standard `name` and `description` fields, MDA adds optional ones: a document ID, a version, dependencies, tags and typed relationships between documents written as footnotes. Tamper protection comes from a content digest written into the header, and signed artifacts can carry Sigstore signatures. All extensions live under the `metadata.mda` key, so an ordinary `.mda` with only standard fields compiles almost unchanged. The reference implementation, the `@markdown-ai/cli` package with the `mda` command, can create a starter, validate sources and outputs, compile, and compute and verify digests. JSON output is made for agents: it carries the `ok`, `exitCode`, `diagnostics` and `nextActions` fields, so an agent does not have to parse text. Compatibility with Claude Code, Codex CLI, OpenCode, Hermes Agent and OpenClaw is confirmed by install kits in the `compat` folder.
Who it is for. For authors of skills and agent instructions who publish the same content for several runtimes and want to check it in CI.
Good fit when
- One skill must ship as SKILL.md and AGENTS.md and the copies should not drift apart over time
- CI needs to confirm that SKILL.md matches the schema: `mda validate out/SKILL.md --target SKILL.md`
- An agent edits instruction documents itself, and its result should pass a `--json` check before a build
- You need a content digest to notice that a skill file was changed after publication
- Skills depend on each other, and those dependencies with versions should be recorded in machine-readable form
Not a fit when
- You need a single SKILL.md for one agent: the compiler then gives no gain
- You need Cursor MDC rules, Windsurf rules or Aider: version 1.0 covers only the agentskills.io and AAIF formats
- You need ready signature verification, a dependency resolver or a registry: version 1.0 does not have them yet
- You need a library inside an application: the authors advise using the CLI for authoring, CI and checking, and keeping your own loaders at runtime
Example request
Create hello.mda, check it with `mda validate`, compile it into SKILL.md and AGENTS.md in the out folder and verify the digest of the result.Limitations
The release is still a candidate: v1.0.0-rc.3, and the final 1.0.0 will land when the CLI passes the full conformance suite. The specification describes four targets, but the CLI help allows source, SKILL.md, AGENTS.md and MCP-SERVER.md, so compilation to CLAUDE.md is not claimed yet. A digest shows that content changed but does not prove who wrote it.
There is no bundled Sigstore signature verifier: you combine a JCS canonicalization library with DSSE signing tools. There is also no dependency resolver, central registry or relationship graph indexer. According to the authors, no known agent harness routes tasks by the `requires` field yet.
Whether npm and Sigstore services are reachable from Russia was not checked for this card. The code is under Apache-2.0 and the specification text under CC-BY-4.0.
How to disable. For a global install run `npm uninstall -g @markdown-ai/cli`; running through `npx` leaves nothing behind. Generated files live in the folder named by the `--out-dir` flag and are deleted in the usual way. Your `.mda` sources stay yours: without the compiler you can turn them into ordinary SKILL.md files by hand.
FAQ
What is MDA and how does .mda differ from SKILL.md?
MDA is a layer over Markdown with an extended header, typed relationships in footnotes and a content digest. A `.mda` file is the source, and the compiler emits SKILL.md, AGENTS.md and MCP-SERVER.md from it. If the source has only the standard `name` and `description` fields, the output is nearly identical to it.
How do I compile .mda into SKILL.md and AGENTS.md?
Run `mda compile hello.mda --target SKILL.md AGENTS.md --out-dir out --integrity`. Then check the results with `mda validate out/SKILL.md --target SKILL.md` and `mda integrity verify out/SKILL.md --target SKILL.md`.
How can I see mda working without setup?
The `npx -y @markdown-ai/cli demo` command creates an mda-demo folder with hello.mda and ready SKILL.md, AGENTS.md, MCP-SERVER.md and mcp-server.json with digests. It refuses to overwrite an existing mda-demo folder.
How should an agent use mda?
Add `--json`: the response carries `ok`, `command`, `exitCode`, `summary`, `artifacts`, `diagnostics` and `nextActions`. Continue while `ok` is true and the exit code is 0, read `diagnostics[0].code` before the text and write outputs to a temp folder first.
What is not ready in MDA yet?
There is no bundled signature verifier, dependency resolver, artifact registry or relationship graph indexer. Version 1.0 also does not target Cursor MDC, Windsurf rules, Continue, Aider or instructions.md files.
Discussion
No questions or reviews yet.
Related
CLI toolsA skills library that gives coding agents a development process: brainstorming, planning, TDD, subagents and code review
Skills for real engineers by Matt Pocock
Skills For Real Engineers
Small composable skills for engineering with agents: plan grilling, TDD, bug diagnosis, code review and architecture
Karpathy-inspired Claude Code guidelines
Karpathy-Inspired Claude Code Guidelines
Four principles in one CLAUDE.md against common LLM coding mistakes: silent assumptions, overengineering, drive-by edits
A plugin and skill that makes the agent write minimal code: reuse, stdlib and native platform features come first
GitHub toolkit for spec-driven development: the specify CLI adds agent commands and skills to a project, from principles to implementation
Garry Tan's skill suite that turns Claude Code into a virtual team: product, architecture, design, review, QA and shipping
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| MDA: one source for SKILL.md and AGENTS.md (this entry) | no | 621 | |
| agnix | yes | 457 | a linter for finished CLAUDE.md, AGENTS.md, SKILL.md, hooks and MCP configs that compiles nothing |
| Caliber | no | 1,310 | creates and maintains context files for coding agents based on the project state |
README in short
The main document explains why a single source for several formats is needed and shows the compile diagram with compatible runtimes. It then describes three additions to Markdown: extended frontmatter, typed relationships and cryptographic identity, and three authoring modes: by an agent, by a human and by the compiler. It gives a minimal pdf-tools.mda example, the specification's table of contents and the list of JSON schemas. A status block lists what version 1.0 already delivers and what is still missing.