Teaching agents product design at Vercel

John Phamous on the gap between an agent producing working UI and an agent producing UI that matches how your product already behaves. His framing of the problem:

Code shows agents what shipped, not why one component, phrase, or interaction became your standard.

Vercel’s answer is a product-design agent skill in the repo, split into references/ for the judgement calls, exemplars/ for decisions taken from shipped PRs along with mistakes to avoid, and a coverage-gaps.md listing what has no agreed standard yet. Anything a linter can catch reliably becomes a lint rule instead, so the skill carries only what needs context. The skill also recognises five request modes with different obligations: shape, implement, review, copy and harden. One number worth noting on skills generally: in separate Next.js evals, agents failed to invoke an available skill in 56% of cases, which is why the post pushes explicit triggers and firm boundaries.

The part I found most useful is the weekly evidence loop that keeps the guidance from going stale. A collector gathers Slack messages and links without proposing any rules, a judge validates and groups the evidence, and automation produces a review packet of candidates and coverage gaps for humans to turn into guidance, lint rules, examples or evals. The rule that keeps this honest is treat shipped code as evidence, not automatic precedent. It proves what exists, not why it is correct.

The closing point generalises past design: every team has decisions worth encoding, and the question is whether they live in someone’s head or somewhere agents can find them. See also Writing great skills.