Thanks to visit codestin.com
Credit goes to mda.sno.dev

Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mda.sno.dev/llms.txt

Use this file to discover all available pages before exploring further.

Until now, you shipped the same agent-facing skill four times. Once as SKILL.md for the 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, forget the others, and a month in, the four files have quietly drifted into four slightly different instruction files. You write one .mda. The compiler emits the rest. 
                ┌─────────────────────────┐
                │   <name>.mda  (source)  │   ← MDA superset
                └────────────┬────────────┘
                             │  mda compile
                             ▼
   ┌─────────────────────────────────────────────────────────┐
   │ <name>/SKILL.md     (+ scripts/, references/, assets/)  │
   │ AGENTS.md                                               │
   │ <name>/MCP-SERVER.md  (+ mcp-server.json sidecar)       │
   │ CLAUDE.md                                               │
   └─────────────────────────────────────────────────────────┘
                       drop-in compatible

​
Three additions, all optional

.mda adds three things on top of standard Markdown.

Rich frontmatter

Beyond the open-standard name and description baseline, MDA carries doc-id, version, requires, depends-on, relationships, and tags. Agent-aware tools use these for routing, dependency resolution, and graph traversal.

Typed footnote relationships

Standard Markdown footnotes whose payload is a JSON object: parent, child, related, cites, supports, contradicts, extends. Mirrored to metadata.mda.relationships in body order on compile.

Cryptographic identity

A JCS-canonicalized integrity digest plus DSSE-enveloped, Sigstore-anchored signatures[]. The compiled .md carries reproducible tamper detection without bolting it on later.
A .mda source with only the open-standard frontmatter compiles unchanged into a .md. Use as much or as little of MDA as your project needs.

​
Three authoring modes

MDA artifacts may be produced three ways. They’re equivalent under validation.
  1. Agent mode — an AI agent writes the .md directly. The primary near-term use case.
  2. Human mode — a human writes the .md directly, then adds integrity and signs it with a DSSE-capable signing path.
  3. Compiled mode — an author writes a .mda source; the MDA compiler emits one or more .md outputs.
Whichever path you take, the artifact is judged against the same JSON Schema 2020-12 target schema and the same conformance suite. There’s no second code path for “this came from an agent.”

​
Where the value lands

One source, many runtimes

A compiled SKILL.md loads in Claude Code, OpenCode, OpenAI Codex, Hermes, OpenClaw, skills.sh, Cursor, and Windsurf. A compiled AGENTS.md lands in Codex CLI, Copilot, Cursor, Windsurf, Amp, Devin, Gemini CLI, VS Code, Jules, and Factory.

Machine-readable graph

metadata.mda.depends-on declares dependencies with version ranges and digest pins. metadata.mda.relationships mirrors the body’s typed footnote graph. Tools traverse explicit edges instead of inferring from prose.

Structured capabilities

metadata.mda.requires declares runtime, tools, network, packages, model, and cost-hints so a harness can decide activation, eviction, and routing without parsing description prose.

Verifiable trust at load

Sigstore OIDC keyless signing by default, with a did:web air-gap fallback. Reproducible tamper detection. The conformance runner enforces signatures[].payload-digest == integrity.digest byte-for-byte.

​
Status, honestly

v1.0 ships the contract, not the entire ecosystem around it. What works today: you author a .mda, compile it to one or more conforming .md outputs, and validate them against the target JSON Schemas and the conformance suite. What’s still being built: a bundled signature verifier, a working dependency resolver, a central artifact registry, a graph indexer, harnesses that route through requires. The .mda you write today still produces conforming .md outputs that load in every runtime listed above. For the truthful gap, see What v1.0 doesn’t ship. For the long version of the value proposition, the AI-agent-side core value and human-author-side core value documents trace every claim back to a section of the spec.

​
Next

Quickstart

Author a minimal .mda and compile it to a SKILL.md in under five minutes.

Architecture

The three additions, the parsing flow, and how a compiled .md stays drop-in compatible.

Specification

The normative spec entry point, with links to every §.

Examples

Worked .mda examples covering common authoring patterns.