markdown-for-agent (@markdown-ai/cli)

MDA v1.0 (specifically v1.0.0-rc.3) focuses on the core specification, target schemas, integrity rules, signature envelopes, and the TypeScript reference CLI (@markdown-ai/cli).

Key architectural boundaries to note:

• No Central Registry: MDA does not host or mandate a registry for .mda artifacts; resolution is operator-defined.
• Conditional Sigstore Signatures: Signature claims depend on Fulcio and Rekor reachability. Operators must implement air-gap fallbacks to did:web and mda-keys.json if Sigstore is unreachable.
• Strict Schema Validation: The v1.0 SKILL.md schema uses unevaluatedProperties: false. This means runtime-specific top-level fields (like those used by Claude Code) are rejected by the MDA compiler. To include these, authors must hand-edit the compiled output, which subsequently exits MDA validation.
• Target Ecosystems: v1.0 targets the agentskills.io v1 ecosystem (SKILL.md) and the AAIF-aligned ecosystem (AGENTS.md, MCP-SERVER.md). It does not currently cover Cursor MDC, Windsurf rules, Continue, Aider, or *.instructions.md.

The MDA Open Spec is organized into several normative and informative sections. Use this map to locate specific technical requirements:

Note: The REGISTRY.md file at the repository root governs vendor namespace assignment, standard requires keys, and reserved Sigstore/DSSE values. It is referenced by sections §04, §08, §09, §10, and §13.

MDA (Markdown for Agent) is a superset of Markdown designed specifically for AI Agents. It follows a "one source, multiple outputs" philosophy: you write a single .mda source file, and a compiler generates multiple .md files compatible with various agent runtimes (such as SKILL.md, AGENTS.md, MCP-SERVER.md, and CLAUDE.md).

Key features include:

1. Rich YAML Frontmatter: Beyond standard name and description, it supports doc-id, version, requires, depends-on, relationships, and tags for routing and dependency resolution.
2. Typed Footnote Relationships: Uses standard Markdown footnotes with JSON payloads to define relationships like parent, child, related, cites, supports, contradicts, and extends.
3. Cryptographic Identity: Includes a JCS-normalized integrity.digest and signatures[] (using DSSE and anchored to Sigstore) to allow agents and humans to verify the content's authenticity and detect tampering.

MDA is a superset of Markdown designed for agent-oriented documents. It follows a "one source, multiple destinations" philosophy, allowing you to write a single .mda file that compiles into standard .md files compatible with various agent runtimes (e.g., SKILL.md, AGENTS.md, CLAUDE.md).

MDA adds three key capabilities to standard Markdown:

1. Rich YAML Frontmatter: Includes doc-id, version, requires, depends-on, relationships, and tags for routing and dependency resolution.
2. Typed Footnote Relationships: Uses standard Markdown footnotes with JSON payloads to define typed relationships like parent, child, related, cites, supports, contradicts, and extends.
3. Cryptographic Identity: Provides tamper detection via a JCS-canonicalized integrity.digest and signed identities using signatures[] wrapped in DSSE and anchored in Sigstore.

---
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

…

MDA (Markdown for Agents) is a superset of Markdown designed for agent-oriented documents. It follows a "one source, many targets" philosophy: you write a single .mda file, and a compiler generates multiple drop-in compatible .md files for different agent runtimes (such as SKILL.md, AGENTS.md, MCP-SERVER.md, and CLAUDE.md).

MDA adds three optional, machine-readable layers to standard Markdown:

1. Extended YAML frontmatter: Includes metadata like doc-id, version, requires, depends-on, relationships, and tags for dependency resolution and routing.
2. Typed relationships via footnotes: Uses standard Markdown footnotes with JSON payloads to define semantic links like parent, child, related, cites, supports, contradicts, or extends.
3. Cryptographic identity: Provides content integrity via integrity.digest (JCS-canonicalized) and signatures[] (DSSE-envelope anchored in Sigstore) within the frontmatter to prevent tampering and verify authors.

                ┌─────────────────────────┐
                │   <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