Markdown as a first-class format — linting agent skills, and why paths do not fit prose

[kinlane]

Discussed at length in office hours on 2026-08-21 as the leading candidate for the feature
that makes people switch. It also has prior art, from inside Stoplight, that was tried and
abandoned — which makes this a design problem with known failure modes rather than a blank page.

Why markdown

• Agent skills are markdown with YAML front matter. They are proliferating, they are
  becoming a governed artifact inside organizations, and nothing lints them.
• Markdown is already inside OpenAPI. Every description is CommonMark. A markdown format
  is not a single-purpose addition — it makes the existing formats lintable at a depth they are
  not today.
• It is the clearest expression of "multi-format is a goal, not an accident" (Multi-format is a goal, not an accident — say so in the specification #24) that anyone
  can point at.

What the prior art found

Stoplight built a proof of concept for this and stopped. Three specific findings:

1. Paths do not work; node types do. Rather than JSON Path expressions, they targeted
   node types — heading, list — treating the parsed document as a tree of kinds rather
   than a tree of addresses. That is a different targeting model from the one the format has.
2. The built-in functions do not survive the transition. truthy, falsy and friends are
   meaningless against prose. The functions markdown wants are different in kind — a spell
   checker was the example given — and they do not exist.
3. The reason both of those happen: "it's less of a focus on structure and more on the
   contents. It is structured in a way, but generally speaking it's unstructured."

They abandoned it on (2). That is the risk to plan around.

What this issue needs to produce

• The targeting model. Node types, a markdown-appropriate query language, or the existing
  path language over a parsed AST. This is the load-bearing decision and it interacts with Elevate aliases out of the core ruleset into their own namespace, and get rules off JSONPath #20
  and the JSON Path dialect question.
• The function set. Which built-ins carry over, which are meaningless, and what the minimum
  new set is. If the answer is "a whole parallel function library," that is a real cost and
  should be stated before anyone starts.
• Scope split: front matter vs. body. The front matter is YAML and is essentially free —
  existing rules work on it today with a parser change. The body is the hard part. These
  should probably ship separately, because the cheap half delivers most of the agent-skill
  value on its own.
• Which flavor. CommonMark, and what happens to extensions (tables, front matter delimiters,
  directives).

Related: #20, #24.