Specs rot. Running code doesn't. How I restructured my AI agent skills around live references

A developer restructured AI agent skills around live production references instead of abstract specs, achieving near-perfect first-pass output quality. The engineer split 'build new' and 'repair existing' into separate skills and added write-time hooks to enforce critical rules. The approach, tested on a 600-tool fleet, eliminated the 20% quality gap that required correction rounds.

When I started having Claude Code build new web tools, I handed it abstract specs: design conventions, component rules, forbidden patterns. It would read the spec, produce something plausible, and stop at 80% quality. The remaining 20% took rounds of corrections. After doing that a few dozen times, I rebuilt the skill architecture from the ground up. The conclusion, up front: stop making the agent read specs — make it copy a live, production-deployed reference. And split "build new" and "repair existing" into completely separate skills. Two design decisions from running a 600-tool fleet. The problem with specs is that they start diverging from reality the moment you write them. Every small judgment made during implementation — this pattern gets this padding, this one case is an exception — never gets written back. It's not sustainable. So the AI fills those unwritten judgments its own way, every time, differently every time. Production code, on the other hand, has all of those judgments baked in. So I restructured the skills: The skill file itself is a thin wrapper; the substance lives in a catalog the canonical doc . The catalog opens with a decision tree — three questions that select the implementation pattern direct Canvas 2D / html2canvas / dom-to-image / dedicated library / pure SVG . For the selected pattern, pick two production references from the catalog's list and read them: one as the base, one for diffing. Each catalog row records line numbers — where the download handler lives, where the render core lives. Then copy the base reference wholesale and modify it for the new tool's data structure. First-pass output went from "80% plus correction rounds" to essentially production quality. Specs rot; code that keeps running in production doesn't rot for as long as it keeps running. A side benefit: the catalog records convergence. I tried five implementation patterns for image-output tools; the majority of production settled on direct Canvas 2D. The one-liner "when in doubt, Canvas 2D" is only writable because that convergence data exists. The second decision: new construction and repair of existing tools live in different skills. Same domain — why split? | build new | repair existing | | |---|---|---| | Input | requirements for a new tool | reported bug / validator flags | | Output | a full new template | pinpoint fix scoped to the symptom | | Verification depth | full checklist | symptom's surroundings only | Merge them into one skill and two bad things happen: the build procedure accumulates repair-only branches and bloats, and repair reference material gets diluted with build steps. Either way, you're making the agent pay a skip-the-irrelevant-parts tax on every read. Agent context is finite; that tax comes straight out of output quality. The repair side became a "mothership": it takes a symptom, routes it to a category layout breakage / image-output fidelity / translation quality / button conventions / description-vs-implementation drift / interaction , and opens only that category's reference. Unbuilt categories are stubs pointing at the canonical source — so the agent can't hallucinate a procedure that doesn't exist. One final boundary. A skill procedure doc is advisory — it has no enforcement power. The agent sometimes skims past it. So violations that must never ship get blocked mechanically by a write-time hook, not just written in the skill. Concrete example: a leftover CSS class on preview elements visually cancelled a JS-set height, making the UI punch through its card. It recurred across two tools. Writing "remove this class" in the skill didn't stop it. A hook that blocks writing the class did, immediately. "The skill said so but it still happened" isn't a skill-writing problem — it's the mistake of expecting enforcement from advice. Reference-driven means reference quality is the output ceiling. Building the first reference properly cannot be skipped, and that costs more up front than spec-driven. When a reference gets removed from production or heavily reworked, the catalog's line-number data goes stale. Catalog maintenance isn't free. And this architecture pays off because I mass-produce tools. Building a catalog for a one-off project makes no sense. Verified: April–June 2026. Environment: Claude Code + custom skills / 600+ web tools × 5 locales in production.