Skip to main content
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:
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

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:
At the bottom of the document:
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:
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:
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.