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.
1. Reference-driven: from "read the spec and build" to "copy the working artifact and modify"
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:
