migaki: Design Sense for Coding Agents

A coding agent will build almost anything you describe, but left to its defaults it keeps arriving at the same page, with the same gradient and the same card grid. A written correction starts aging the day you save it, because whatever reads as fresh now ends up in the next model’s training data. I started migaki (磨き, to polish) to deal with both problems. It is a skill, a set of instructions an agent like Claude Code loads when a task calls for it, and it gives the agent visual judgement that doesn’t go stale.

How it’s structured

SKILL.md tells the agent which file to open. core.md holds sixteen principles of visual judgement that don’t change with fashion. slop.md lists what reads as AI-generated or dated, and edge.md what reads as excellent right now. Those two are refreshed monthly from shipped products, so the advice keeps up with the present. The whole thing is about five hundred lines, and I keep it that size on purpose.

Making the rules measurable

In an early test, an instruction asking for a slightly warm neutral produced a heavy beige, and one asking for a Tiempos-style serif produced Palatino. Both described the right thing but set no limits. I fixed them with numbers: a warm neutral stays within about four RGB points of gray, and a display serif needs a licensed webfont or the pattern is skipped. Since then, every new rule has to name a value someone could check.

Letting the user decide

The biggest design question was how much authority the skill’s opinions should have. It builds what was asked, then lists the taste decisions it made so the user can accept or reject each one in a word. Every pattern it warns against also says when that pattern is still the right choice, and the user’s own instructions override all of it.

What I’d do differently

I would start with the text. My first two versions were an MCP server and a JavaScript rewrite, and I scrapped both before settling on three markdown files. I would also limit length from the start: one round of edits grew the files by fourteen percent before I capped each entry at eight lines.