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.

In five minutes you’ll write a .mda source, compile it to a SKILL.md that loads in every agentskills.io v1 consumer, and understand what each piece is doing.

​
What you need

  1. A text editor.
  2. The @markdown-ai/cli reference implementation, or — if you’d rather not install anything — the create-sign-verify guide, which uses only standard hashing and DSSE-capable signing tools.
  3. A basic grasp of Markdown.

​
A minimal .mda source

Create a file called pdf-tools.mda: 
---
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

Use this skill when the user asks for PDF text extraction, form filling, or file merging.

## Operations

- `extract-text` — pulls UTF-8 text from a PDF.
- `fill-form` — fills AcroForm fields from a JSON spec.
- `merge` — concatenates two or more PDFs into one.
What’s happening:
  • name and description are the open-standard floor every agent-skill consumer reads. No MDA awareness required to load this.
  • Everything under metadata.mda.* is the MDA-extended layer. doc-id (UUID) gives the document a stable identity for relationship references. version is SemVer 2.0.0. title and tags are routing hints.
  • The body is plain Markdown. Renders fine anywhere.

​
Compile

npx @markdown-ai/cli compile pdf-tools.mda --target SKILL.md
Output: pdf-tools/SKILL.md. Because the source already sits in the strict target shape — every MDA-extended field is nested under metadata.mda.* — the compile is essentially a rename. The output drops into Claude Code, OpenCode, Codex, Hermes, OpenClaw, skills.sh, Cursor, Windsurf, and any other agentskills.io v1 consumer. Same source compiles to AGENTS.md, MCP-SERVER.md (with its mcp-server.json sidecar), or CLAUDE.md by changing the --target flag.

​
Adding a typed relationship

If your skill builds on another, declare it. In the body, drop a footnote reference: 
This skill extends the PDF rendering primitives from pdf-core[^pdf-core].
At the bottom of the document: 
[^pdf-core]: `{"rel-type": "extends", "doc-id": "9c2ab16d-0f73-4f7a-9d1f-3c2d5e6a7b8c", "rel-desc": "Extends pdf-core's rendering primitives"}`
The compiler mirrors this footnote to metadata.mda.relationships in body order on compile. Standard Markdown renderers display it as a normal footnote with the JSON literal. MDA-aware tools traverse the typed edge. rel-type values: parent, child, related, cites, supports, contradicts, extends.

​
Adding a hard dependency

Relationships are the human-readable graph. For runtime dependencies — pinned versions, digest anchors — use depends-on directly in frontmatter: 
metadata:
  mda:
    depends-on:
      - doc-id: 9c2ab16d-0f73-4f7a-9d1f-3c2d5e6a7b8c
        version: "^1.0.0"
        digest: "sha256:7f3c8e2b4a9d7f0e9b91d2c3e4f56789abcd0123ef456789abc0123def456789"
version accepts exact (1.2.3) or caret (^1.2.0) ranges only — no other range grammar in v1.0. The optional digest is a content anchor: the resolver MUST refuse to load a candidate whose integrity.digest doesn’t match.

​
Signing (optional)

Compile with the --sign flag and Sigstore OIDC keyless signing kicks in: 
npx @markdown-ai/cli compile pdf-tools.mda --target SKILL.md --sign
The output SKILL.md gets top-level integrity.digest (a JCS-canonicalized hash of the canonical bytes) and top-level signatures[] (DSSE-enveloped signature with Rekor inclusion proof and Fulcio certificate metadata). A verifier rederives the digest, looks up Rekor, verifies the cert chain and signature, then applies the operator trust policy. For the air-gap path (no Sigstore reachability), did:web + mda-keys.json is the documented fallback. See spec/v1.0/09-signatures.md.

​
What you’ve learned

  • One .mda source produces drop-in .md outputs for the four target schemas (SKILL.md, AGENTS.md, MCP-SERVER.md, CLAUDE.md).
  • MDA-extended frontmatter sits under metadata.mda.*, never at the top level (top-level is reserved for the open-standard floor).
  • Typed footnotes mirror to a machine-readable relationship graph.
  • depends-on declares hard dependencies with SemVer ranges and digest anchors.
  • Signing is opt-in. Reproducible. The verifier surface is the same whether the artifact came from a human, an agent, or a compiler.

​
Next

Architecture

Deeper on the three additions: rich frontmatter, typed footnote relationships, cryptographic identity.

Specification

The normative entry point — every § of the v1.0 spec, linked.

Create, sign, and verify MDA

Hand-author, add integrity, sign, and verify without the reference CLI.

More examples

Worked .mda files covering common patterns.