File formats
Choose a file’s format by asking these questions in order. The first yes decides.
| Question | Format | Examples |
|---|---|---|
| Does a program read or write it? | JSON, with a schema | Records, kit manifests, the data model, policies |
| Is it an append-only log? | JSONL | provenance.jsonl |
| Does another tool expect the name? | .md | SKILL.md, AGENTS.md, CLAUDE.md, README.md, vault notes |
| Is it prose for people that is published, or that needs a component or live data? | MDX | These docs, guides, reference pages |
| Is it prose that stays private? | .md | A venture profile, working notes |
MDX is stricter than Markdown: a bare < or { in text breaks a page. npm run check:mdx in site/ compiles every page, and the build fails on a page that does not compile.
This convention is in force (EE-033).
Last updated on