Skip to content
mif-docs

Skill reference: mif-frontmatter

Skill reference: mif-frontmatter

Section titled “Skill reference: mif-frontmatter”

The mif-frontmatter skill is a substrate helper: it does not author a document genre of its own, it supplies the MIF metadata layer that every genre in the suite is written over. This reference describes what that frontmatter is, how the skill produces it, when it is invoked, and the provenance behind it.

PropertyValue
AuthorsThe MIF Level 1–3 frontmatter for any document
Purpose groupAuthoring helpers
MIF conceptTypesubstrate
Target MIF level1
Primary sourceMIF specification

What this document type is

Section titled “What this document type is”

MIF frontmatter is the YAML block at the head of a document that projects losslessly to canonical JSON-LD. It is not a free-form preamble: it is a layered schema with three conformance floors. Level 1 carries the identity floor — id, type, title, timestamps, namespace, and an entity block — so that any tool can address the document. Level 2 adds temporal validity, tags, and an ontology reference. Level 3 adds the full PROV-O provenance graph, citations, and relationships[] that wire the document into a knowledge graph.

The substrate is deliberately genre-agnostic: a tutorial, an ADR, and a runbook all share the same frontmatter spine, and only their extensions and conceptType differ. That uniformity is what lets the rest of the suite treat every artifact — regardless of genre — as one addressable, machine-readable unit. It is not a content format and carries no prose; the body genre owns the words.

How the skill produces one

Section titled “How the skill produces one”

mif-frontmatter carries the layered MIF schema as durable instructions plus eval cases and emits the block other skills build on.

  • Climb from the floor. The skill always satisfies L1 first, then climbs to L2 and L3 only as the drafting context supplies real detail — never inventing provenance or citations to reach a level the source does not support.
  • Eval cases. The skill ships evals/evals.json exercising the L1-to-L3 climb. As a substrate helper it carries no templates/ exemplars; the check-exemplars gate (which proves good-l1.md at L1 and good.md at its target level) applies only to the genre skills.
  • Lossless projection. The emitted YAML is required to round-trip to JSON-LD and back without loss; the mif-validate helper proves that round-trip before the document is considered done.

When it is beneficial

Section titled “When it is beneficial”

Reach for mif-frontmatter whenever a document needs MIF-conformant metadata — which, in this suite, is every document. It is invoked implicitly by every genre skill, and directly when you are adding MIF metadata to an existing file or raising a document from one level to the next. The L1-first discipline is the value: it produces a valid, addressable artifact immediately and defers richer metadata until it can be asserted truthfully.

There is no genre anti-trigger here because the helper has no genre — but do not over-reach for a level the content cannot honestly support. An early draft with no decided provenance belongs at L1 or L2; forcing an L3 PROV graph onto it fabricates an audit trail. The cost is minimal: the floor is a handful of fields.

Example

Section titled “Example”

A how-to guide begins life with an L1 block — id, type: procedural, a title, created/modified, and an entity name — enough for the round-trip to pass. As the guide matures, the author adds tags, an ontology reference, and temporal validity to reach L2, then a provenance graph and citations to reach L3, at which point mif-validate confirms the document is conformant at the claimed level.

Provenance & citations

Section titled “Provenance & citations”