# 📝 MDA Open Spec — Markdown fĂŒr Agenten > Eine Markdown-Erweiterung fĂŒr agentenseitige Dokumente. **Eine Quelle, viele Ziele** — kompiliere in genau die `.md`-Dateien, die jede gĂ€ngige Agent-Runtime ohnehin lĂ€dt. **Manipulationssicher beim Laden** — jedes Artefakt trĂ€gt einen reproduzierbaren Inhalts-Digest, und signierte Artefakte tragen Sigstore-verankerte Signaturen, sodass weder der ladende Agent noch der prĂŒfende Mensch einem unsignierten Blob blind vertrauen muss. [![Latest release](https://img.shields.io/badge/release-v1.0.0--rc.3-blue)](https://github.com/sno-ai/mda/releases/tag/v1.0.0-rc.3) [![License](https://img.shields.io/github/license/sno-ai/mda)](https://github.com/sno-ai/mda/blob/main/LICENSE) [![Docs](https://img.shields.io/badge/docs-mda.sno.dev-3b82f6)](https://mda.sno.dev) [![GitHub stars](https://img.shields.io/github/stars/sno-ai/mda?style=flat&color=yellow)](https://github.com/sno-ai/mda/stargazers) **In anderen Sprachen lesen:** [English](../../README.md) · [äž­æ–‡](README.zh-CN.md) · **Deutsch** · [Español](README.es.md) · [Français](README.fr.md) · [РуссĐșĐžĐč](README.ru.md) · [한ꔭ얎](README.ko.md) · [æ—„æœŹèȘž](README.ja.md) · [à€čà€żà€šà„à€Šà„€](README.hi.md) ## Was MDA ist Bislang hast du dieselbe Skill viermal ausgeliefert. Einmal als `SKILL.md` fĂŒr die agentskills.io-Runtimes. Einmal als `AGENTS.md` fĂŒr das AAIF-Ökosystem. Einmal als `MCP-SERVER.md` mit einem Sidecar-JSON. Einmal als `CLAUDE.md`. Gleicher Inhalt, vier Frontmatter-Formen. Du aktualisierst eine, vergisst die anderen, und einen Monat spĂ€ter sind aus den vier Dateien klammheimlich vier leicht unterschiedliche Anweisungsdateien geworden. Du schreibst eine `.mda`. Der Compiler liefert den Rest. ![Eine .mda-Quelle wird ĂŒber eine deterministische Pipeline zu SKILL.md, AGENTS.md, MCP-SERVER.md und CLAUDE.md kompiliert](../../images/hero-compile-pipeline.png) ``` ┌─────────────────────────┐ │ .mda (source) │ ← MDA superset └────────────┬────────────┘ │ mda compile â–Œ ┌─────────────────────────────────────────────────────────┐ │ /SKILL.md (+ scripts/, references/, assets/) │ │ AGENTS.md │ │ /MCP-SERVER.md (+ mcp-server.json sidecar) │ │ CLAUDE.md │ └─────────────────────────────────────────────────────────┘ drop-in compatible ``` Und diese vier Dateien können nicht sagen, wer sie signiert hat. Der Agent, der `SKILL.md` lĂ€dt, hat keine Möglichkeit zu prĂŒfen, ob der Inhalt dem entspricht, was du geschrieben hast, und der Kurator, der `AGENTS.md` durchsieht, weiß nicht, durch wessen HĂ€nde sie zwischen Merge und Laden gegangen ist. Die ĂŒblichen Frontmatter-Formen haben keinen Platz fĂŒr einen Inhalts-Digest oder eine Signatur, also fĂ€llt die Vertrauensentscheidung stillschweigend auf „Wir vertrauen dem Repo, irgendwie." MDA trĂ€gt einen JCS-kanonisierten `integrity.digest` und DSSE-verpackte, Sigstore-verankerte `signatures[]` direkt im Frontmatter selbst. Beide Seiten — der Agent beim Laden und der Mensch beim Review — können eine echte Vertrauensentscheidung anhand des konkreten Artefakts treffen, nicht anhand eines BauchgefĂŒhls zum Repo. Manipulationssicherheit und Signer-Verifikation gehören zum Vertrag, nicht zu einem nachtrĂ€glichen Anbau. ![Drei MDA-Erweiterungen oberhalb von Standard-Markdown: reichhaltiges Frontmatter, typisierte Footnote-Beziehungen, signierte IdentitĂ€t](../../images/three-additions.png) `.mda` fĂŒgt drei Dinge auf Standard-Markdown hinzu. Alle davon optional. 1. **Reichhaltiges YAML-Frontmatter.** Über die offene Standardbasis aus `name` und `description` hinaus trĂ€gt MDA `doc-id`, `version`, `requires`, `depends-on`, `relationships` und `tags`. AgentenfĂ€hige Tools nutzen sie fĂŒr Routing, AbhĂ€ngigkeitsauflösung und Graph-Traversierung. Siehe [`spec/v1.0/02-frontmatter.md`](../../spec/v1.0/02-frontmatter.md) und [`spec/v1.0/10-capabilities.md`](../../spec/v1.0/10-capabilities.md). 2. **Typisierte Footnote-Beziehungen.** Standard-Markdown-Fußnoten, deren Payload ein JSON-Objekt ist: `parent`, `child`, `related`, `cites`, `supports`, `contradicts`, `extends`. Beim Kompilieren in der Reihenfolge des Body-Texts nach `metadata.mda.relationships` gespiegelt. Siehe [`spec/v1.0/03-relationships.md`](../../spec/v1.0/03-relationships.md). 3. **Kryptografische IdentitĂ€t.** Ein JCS-kanonisierter `integrity`-Digest plus DSSE-verpackte, Sigstore-verankerte `signatures[]`. Die kompilierte `.md` trĂ€gt reproduzierbare Manipulationserkennung, ohne dass sie nachtrĂ€glich draufgeschnallt werden muss. Siehe [`spec/v1.0/08-integrity.md`](../../spec/v1.0/08-integrity.md) und [`spec/v1.0/09-signatures.md`](../../spec/v1.0/09-signatures.md). Eine `.mda`-Quelle, die nur das offene Standard-Frontmatter verwendet, kompiliert unverĂ€ndert in eine `.md`. Nutze so viel oder so wenig MDA, wie dein Projekt braucht. ## Warum es das gibt Die ehrliche Version. Ich habe immer wieder dieselbe Skill viermal ausgeliefert. Gleicher Inhalt, vier Verpackungen. Jede Runtime hatte ihre eigene Meinung darĂŒber, welches Frontmatter oben hingehört und was als herstellerspezifisch gilt. Beim dritten oder vierten Mal, als ich einen Absatz zwischen `SKILL.md` und `AGENTS.md` herauskopierte und dann zusah, wie sie auseinanderdrifteten, fing ich an, das hier zu schreiben. Die Sache ist, die Duplikation ist nicht das Schlimmste. Das Schlimmste ist, was du in keinem dieser Formate ausdrĂŒcken kannst. Du kannst nicht sagen „diese Skill hĂ€ngt von jener ab, Version `^1.2.0`, mit diesem Inhalts-Digest." Du kannst nicht sagen „diese Datei wurde von dieser IdentitĂ€t bei diesem Rekor-Index signiert." Du kannst nicht sagen „die Beziehung zwischen diesem Dokument und jenem ist `supports`, nicht `cites`." Es gibt keinen Ort fĂŒr diese Information, also landet sie im Fließtext, wo weder Agenten noch Menschen verlĂ€sslich darauf reagieren können. MDA bringt diese Dinge ins Frontmatter und in die Fußnoten, in Formen, die ein JSON Schema validieren kann. Der Markdown-Body rendert weiterhin. Die Standardfelder werden weiterhin geladen. Alles Neue ist optional. Das ist die ganze Idee. FĂŒr die ausfĂŒhrliche Version gehen zwei Dokumente tiefer. Beide fĂŒhren jede Behauptung auf einen Spec-Abschnitt zurĂŒck und benennen aktuelle LĂŒcken im Ökosystem direkt im Text. Lies sie, wenn du entscheidest, ob du MDA einsetzen willst. - [**`docs/v1.0/ai-agent-core-value.md`**](../../docs/v1.0/ai-agent-core-value.md) — fĂŒnf Punkte, zugeschnitten auf Runtimes, Harnesses, Validatoren und Dispatcher. Was MDA einem Agenten beim Laden gibt: strukturiertes `requires` fĂŒr typisierten Dispatch, verifizierbares Vertrauen beim Laden, maschinenlesbare Graphkanten, dateinamenbasiertes Target-Dispatch mit einem einzigen Lookup und denselben Validierungsvertrag fĂŒr agentenerstellte und compilergenerierte Ausgabe. - [**`docs/v1.0/human-curator-user-core-value.md`**](../../docs/v1.0/human-curator-user-core-value.md) — sechs Punkte, zugeschnitten auf die Menschen, die agentenseitige Anweisungsbibliotheken schreiben und kuratieren. Was MDA einem Autor beim Ausliefern gibt: eine Quelle in mehrere Ökosysteme, Manipulationssicherheit und Publisher-Zurechnung, maschinenlesbarer AbhĂ€ngigkeitsgraph und Versions-Pinning, LLM-vermitteltes Authoring, ohne das Frontmatter jeder Runtime einzeln lernen zu mĂŒssen, geringere (nicht null) Vendor-Lock-in und strenge Validierung, die fast-konforme Artefakte vor dem Ausliefern abfĂ€ngt. ## Drei Autorenmodi MDA-Artefakte können auf drei Wegen entstehen. Sie sind unter Validierung gleichwertig. 1. **Agent-Modus** — ein KI-Agent schreibt die `.md` direkt. Der primĂ€re Anwendungsfall in nĂ€chster Zeit. 2. **Human-Modus** — ein Mensch schreibt die `.md` direkt, ergĂ€nzt Integrity und signiert ĂŒber einen DSSE/Rekor-fĂ€higen Signaturpfad. 3. **Compiled-Modus** — ein Autor schreibt eine `.mda`-Quelle; der MDA-Compiler erzeugt eine oder mehrere `.md`-Ausgaben. Welchen Weg du auch nimmst, das Artefakt wird gegen dasselbe JSON Schema 2020-12-Zielschema und dieselbe Conformance-Suite gemessen. Es gibt keinen zweiten Codepfad fĂŒr „das hier kam von einem Agenten." Siehe [`docs/create-sign-verify-mda.md`](../../docs/create-sign-verify-mda.md) fĂŒr die manuellen und agentenerstellten Pfade ohne die Referenz-CLI sowie [`spec/v1.0/00-overview.md §0.5–§0.6`](../../spec/v1.0/00-overview.md) fĂŒr die normative Festlegung von PrioritĂ€t und Modi. ## Minimales Beispiel `pdf-tools.mda`: ```yaml --- name: pdf-tools description: Extract PDF text, fill forms, merge files. Use when handling PDFs. metadata: mda: doc-id: 38f5a922-81b2-4f1a-8d8c-3a5be4ea7511 title: PDF Tools version: "1.2.0" tags: [pdf, extraction] --- # PDF Tools 
 ``` Kompiliert zu `pdf-tools/SKILL.md`. Die Quelle sitzt bereits in der strikten Zielform, mit jedem MDA-erweiterten Feld unter `metadata.mda.*` verschachtelt — der Compile ist also im Wesentlichen ein Rename. Weitere ausgearbeitete Beispiele findest du in [`examples/`](../../examples/) und [`docs/mda-examples/`](../../docs/mda-examples/). ## KompatibilitĂ€t Eine kompilierte `SKILL.md` ist von den wichtigsten agentskills.io-v1-Konsumenten ladbar: - **Claude Code** — https://code.claude.com/docs/en/skills - **OpenCode** — https://opencode.ai/docs/skills/ - **OpenAI Codex** — https://developers.openai.com/codex/skills - **Hermes Agent** — https://hermes-agent.nousresearch.com/docs/user-guide/features/skills - **OpenClaw** — https://docs.openclaw.ai/tools/skills - **skills.sh / Skills Directory** — https://www.skillsdirectory.com/ - **Cursor**, **Windsurf** und weitere SKILL.md-Konsumenten aus 2026 Eine kompilierte `AGENTS.md` landet im AAIF-konformen Ökosystem (der Agentic AI Foundation der Linux Foundation): Codex CLI, GitHub Copilot, Cursor, Windsurf, Amp, Devin, Gemini CLI, VS Code, Jules, Factory. Herstellerspezifische Erweiterungen leben unter reservierten `metadata..*`-Namespaces. Loader lesen nur ihren eigenen Namespace, und Konsumenten dĂŒrfen ein Dokument nicht allein deshalb ablehnen, weil es einen unregistrierten Namespace trĂ€gt. Siehe [`REGISTRY.md`](../../REGISTRY.md) fĂŒr das Namespace-Register, die Standard-`requires`-SchlĂŒssel, reservierte Sigstore-OIDC-Issuer und reservierte DSSE-`payload-type`-Werte. ## Die Open Spec Die normative MDA Open Spec liegt unter [**SPEC.md**](../../SPEC.md) → [`spec/v1.0/`](../../spec/v1.0/). - [§00 Übersicht](../../spec/v1.0/00-overview.md) — Begriffe, RFC 2119, PrioritĂ€t P0 > P1 > P2, drei Autorenmodi, Governance, Versionierung - [§01 Quelle und Ausgabe](../../spec/v1.0/01-source-and-output.md) - [§02 Frontmatter](../../spec/v1.0/02-frontmatter.md) - [§03 Relationships](../../spec/v1.0/03-relationships.md) — Fußnoten + `depends-on` + Versions-/Digest-Pinning - [§04 Plattform-Namespaces](../../spec/v1.0/04-platform-namespaces.md) - [§05 Progressive Disclosure](../../spec/v1.0/05-progressive-disclosure.md) - [§06 Zielschemata](../../spec/v1.0/06-targets/) — `SKILL.md`, `AGENTS.md`, `MCP-SERVER.md`, `CLAUDE.md` - [§07 Conformance](../../spec/v1.0/07-conformance.md) - [§08 Integrity](../../spec/v1.0/08-integrity.md) - [§09 Signatures](../../spec/v1.0/09-signatures.md) — Sigstore OIDC als Default, did:web als Fallback - [§10 Capabilities](../../spec/v1.0/10-capabilities.md) — `metadata.mda.requires` - [§11 Implementer's Guide](../../spec/v1.0/11-implementer-guide.md) (informativ) - [§12 Sigstore-Tooling-Integration](../../spec/v1.0/12-sigstore-tooling.md) (informativ) - [§13 Trusted Runtime Profile](../../spec/v1.0/13-trusted-runtime.md) — ProduktionsprĂŒfung und Trust Policy JSON Schemas liegen in [`schemas/`](../../schemas/) — `frontmatter-source`, `frontmatter-skill-md`, `frontmatter-agents-md`, `frontmatter-mcp-server-md`, `relationship-footnote`, `mda-trust-policy`, plus geteilte `_defs/` fĂŒr `integrity`, `signature`, `requires`, `depends-on` und `version-range`. Conformance-Fixtures und der Validation-Runner liegen in [`conformance/`](../../conformance/) (`node scripts/validate-conformance.mjs`). ## Referenzimplementierung Die TypeScript-CLI liegt in [`apps/cli/`](../../apps/cli/) (npm-Paket: `@markdown-ai/cli`). Die Architektur-Spec ist [`apps/cli/IMPL-SPEC.md`](../../apps/cli/IMPL-SPEC.md). Die CLI reift ĂŒber die `v1.0.0-rc.N`-Tags. Das finale `1.0.0` landet, wenn die CLI 100 % der Conformance-Suite besteht. ![v1.0 liefert den Vertrag — Schemata, Conformance und Compiler — Verifier, Resolver, Registry, Graph-Indexer und Runtime-Routing sind kĂŒnftige Ökosystem-Arbeit](../../images/status-contract-and-ecosystem.png) ## Stand der Dinge — ehrlich v1.0 liefert den **Vertrag**, nicht das gesamte Ökosystem drumherum. **Was heute funktioniert:** du kannst eine `.mda` schreiben, sie zu einer oder mehreren konformen `.md`-Ausgaben kompilieren und sie gegen die Ziel-JSON-Schemata sowie die Conformance-Suite validieren. **Was noch gebaut wird:** - Ein gebĂŒndelter Verifier fĂŒr Signaturen ist noch nicht ausgeliefert. Operatoren kombinieren aktuell eine JCS-Bibliothek mit DSSE/Rekor-fĂ€higen Sigstore-Signatur- und Verifikationswerkzeugen. - Ein funktionierender Dependency-Resolver und ein zentrales Artefakt-Register existieren noch nicht. - Ein Graph-Indexer, der `metadata.mda.relationships` konsumiert, ist nicht ausgeliefert. - Es ist kein 2026er Multi-Agent-Harness bekannt, das heute ĂŒber `metadata.mda.requires` routet. - v1.0 deckt die agentskills.io- und AAIF-Teilmenge ab. Es zielt nicht auf Cursor MDC, Windsurf-Rules, Continue, Aider oder `*.instructions.md`. Diese brauchen weiterhin parallele Pflege. Die `.mda`, die du heute schreibst, erzeugt nach wie vor konforme `.md`-Ausgaben, die in jeder oben gelisteten Runtime laden. Die Teile fĂŒr Verifikation, Auflösung und Graph-Traversierung sind in Arbeit. Was v1.0 einfriert, ist der Vertrag, der es erlaubt, sie ohne weitere Verhandlung zu bauen. FĂŒr die vollstĂ€ndige LĂŒcke zwischen Spec und konsumentenseitigem Ökosystem siehe [`docs/v1.0/what-v1.0-does-not-ship.md`](../../docs/v1.0/what-v1.0-does-not-ship.md). Genau diese Unterscheidung — zwischen einem ehrlichen Spec-Freeze und einem Marketing-Freeze — versucht dieses Projekt zu wahren. ## Mitwirken BeitrĂ€ge sind willkommen. GrĂ¶ĂŸere Änderungen an der Open Spec oder am Vendor-Register sollten als Diskussion beginnen, bevor Code entsteht. Siehe [`CONTRIBUTING.md`](../../CONTRIBUTING.md), [`CODE_OF_CONDUCT.md`](../../CODE_OF_CONDUCT.md) und [`SECURITY.md`](../../SECURITY.md). FĂŒr die Vergabe von Vendor-Namespaces siehe [`REGISTRY.md`](../../REGISTRY.md). Aktuelle Änderungen sind in [`CHANGELOG.md`](../../CHANGELOG.md) protokolliert. ## Lizenz - Open-Spec-Inhalte (`spec/`, `REGISTRY.md`, `SPEC.md`): [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/) - Schemata (`schemas/`), Tooling und Referenzimplementierungen: [Apache-2.0](../../LICENSE) ## Verwandte Links - Dokumentationsseite: https://mda.sno.dev - Spec-Diskussion: https://github.com/sno-ai/mda/discussions - LLM-lesbarer Repository-Leitfaden: [`llms.txt`](../../llms.txt)