Skip to main content

​
MDA Open Spec

The current normative version is MDA Open Spec v1.0, release candidate v1.0.0-rc.3. This page is a guided index into the spec. The authoritative text lives in spec/v1.0/. Mintlify links go to GitHub; clone or download the repo if you need offline access.

​
What MDA is

A portable, structured metadata format for AI-agent artifacts. A single .mda source compiles to byte-equivalent .md outputs that drop into every major agent ecosystem: SKILL.md, AGENTS.md, CLAUDE.md, and MCP-SERVER.md. The wedge: cross-runtime portability + machine-readable dependency graph + open-extensible capability declarations. Cryptographic identity (Sigstore-anchored signatures) is an enabler that makes enterprise adoption viable, not the wedge itself.

​
Design priority order

Every MDA design decision follows P0 > P1 > P2:
  • P0 — AI-agent authorability. An LLM with only this Open Spec in context MUST be able to produce conforming output.
  • P1 — Human authorability. A human with a text editor, standard hashing tools, and a DSSE-capable signing path MUST be able to produce conforming output.
  • P2 — Tooling convenience. Reference implementations are convenience, not requirement.
Normative statement: spec/v1.0/00-overview.md §0.5.

​
Three authoring modes

MDA artifacts MAY be produced in any of three equivalent ways:
  1. Agent mode — an AI agent writes the .md directly (primary near-term use case).
  2. Human mode — a human writes the .md directly with standard tooling.
  3. Compiled mode — an author writes a .mda source; the MDA compiler emits one or more .md outputs.
See spec/v1.0/00-overview.md §0.6 and docs/create-sign-verify-mda.md for the human and agent-author paths.

​
Spec sections

​
Companion artifacts

  • JSON Schemas — schemas/ — frontmatter-source, frontmatter-skill-md, frontmatter-agents-md, frontmatter-mcp-server-md, relationship-footnote, mda-trust-policy, plus _defs/ for integrity, signature, requires, depends-on, version-range, metadata-namespaces, mda-keys.
  • Conformance suite — conformance/ — positive and negative fixtures bound to spec rule IDs in manifest.yaml. Runner: node scripts/validate-conformance.mjs.
  • Examples — examples/ — source-only/, skill-md/ (additional target examples land alongside reference-implementation maturity).
  • Vendor namespace registry — REGISTRY.md — vendor namespaces, standard requires keys, reserved Sigstore OIDC issuers, reserved Rekor instances, reserved DSSE payload-type values.
  • Create, sign, and verify guide — docs/create-sign-verify-mda.md — practical human and agent-author flow without the MDA CLI.
  • Reference implementation — apps/cli/ — TypeScript, npm: @markdown-ai/cli. Architecture spec: apps/cli/IMPL-SPEC.md.

​
Governance

MDA is an independent project. It actively serves AAIF (Linux Foundation Agentic AI Foundation) governed targets — AGENTS.md and MCP-SERVER.md — as first-class compile destinations. MDA does not seek to join AAIF in v1.0. See spec/v1.0/00-overview.md §0.8.

​
Versioning

  • Patch releases (v1.0.1, v1.0.2, …) deliver editorial fixes and reference-implementation maturity. They do not change the conformance contract.
  • Pre-release cycle. The current release candidate is v1.0.0-rc.3. The final v1.0.0 lands when the reference implementation passes 100% conformance.
  • Minor releases (v1.1.0) are not pre-planned. They emerge from observed adoption.
  • Major releases (v2.0.0) ship breaking changes in a new directory; previous versions remain immutable at their canonical URLs.
See spec/v1.0/00-overview.md §0.9.

​
What v1.0 doesn’t ship

The current release-candidate contract is defined. The consumer-side ecosystem that enforces or routes through that contract is mostly nascent. For the truthful gap, see What v1.0 doesn’t ship. For the long-form value framing, two documents go deeper. Both trace every claim back to a section of the spec, and both call out current ecosystem gaps inline:

​
License

This document set is licensed under CC-BY-4.0. Schemas and tooling are licensed under Apache-2.0.