---
title: "Quickstart"
description: "Author a minimal .mda source and compile it to a drop-in SKILL.md in under five minutes."
---

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](https://github.com/sno-ai/mda/blob/main/docs/create-sign-verify-mda.md), 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`:

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

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

```bash
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:

```markdown
This skill extends the PDF rendering primitives from pdf-core[^pdf-core].
```

At the bottom of the document:

```markdown
[^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:

```yaml
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:

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

<CardGroup cols="2">
  <Card title="Architecture" icon="diagram-project" href="/mdx/architecture">
    Deeper on the three additions: rich frontmatter, typed footnote relationships, cryptographic identity.
  </Card>
  <Card title="Specification" icon="book" href="/mdx/specification">
    The normative entry point — every § of the v1.0 spec, linked.
  </Card>
  <Card title="Create, sign, and verify MDA" icon="terminal" href="https://github.com/sno-ai/mda/blob/main/docs/create-sign-verify-mda.md">
    Hand-author, add integrity, sign, and verify without the reference CLI.
  </Card>
  <Card title="More examples" icon="code" href="/mda-examples/quickstart-hello-world">
    Worked `.mda` files covering common patterns.
  </Card>
</CardGroup>