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

Short summary

The author rebuilt their Claude Code agent skill architecture after abstract specs produced 80%-quality output requiring correction rounds. The fix: make agents copy live production references instead of reading specs, and split build-new and repair-existing into separate skills. First-pass output jumped to near-production quality, and write-time hooks enforce rules that advisory skill docs cannot.

• •Replace abstract specs with live production code references for AI agents
• •Split build-new and repair-existing into separate skills to reduce context tax
• •Use mechanical write-time hooks for enforcement — skills are advisory, not enforceable

Generated with AI, which can make mistakes.