Building Agent Skills, One Step at a Time

The goal was to generate puzzles with code — the art and the answer both — reliably, at scale. The obvious approach, one detailed prompt that produces the whole thing, does not get there: the output is freestyle and low-quality. What works is the opposite — build the capability one small step at a time, and never move on until the current step is nearly perfect, because in a pipeline errors don't add up, they multiply.

One big prompt doesn't scale

The first attempt asked for everything at once — a full spec, the whole asset drawn in a single pass. This is what came back:

Flat ellipses, dot eyes, a hat pasted on. Not because the model can't draw — because "do the whole hard thing in one go" is the wrong shape of request. The fix wasn't a better prompt. It was a smaller problem.

Small, then general, then up

The work was broken into steps that climb in complexity, and each was nailed before the next began:

1. Set the frame first. Before generating anything, define a clean code interface every puzzle type shares — a fixed structure the model fills in, not a blank page. Rails, not freedom.
2. Solve the smallest piece. Just the SVG art — no puzzle logic yet. Ask for the faces, look at what comes back, raise the bar, ask again. A few passes, each stricter than the last, until the faces are genuinely good.
3. Generalize it. Freeze what worked into a reusable skill, then test it cold — a fresh context, new examples it was never tuned on — and keep tightening until it holds across cases, not just the one you polished.
4. Then climb one step. Only now add the harder layer: embed the puzzle inside the SVG, so the art and the answer become one object. Same loop — one example, iterate, raise the bar, generalize.

Each step is small enough to actually get right, and each is built on a floor that is already solid.

Why you can't skip a step

The discipline that makes this work: don't advance until the current step is near perfect — not "good enough," near perfect. Because the steps multiply.

Chain five steps at 99% and you are still at 95% (0.99⁵). Chain five steps at 90% and you are under 60% (0.9⁵ ≈ 0.59). "Pretty good" at each stage compounds into "broken" by the end. So the rule is not "move fast" — it is guard every step above ~0.99 before building the next one on top of it.

What to take from this

A complex capability is not written in one prompt; it is built one reliable step at a time — frame it, solve the smallest instance, generalize it, then climb. And the floor is guarded obsessively, because in a pipeline the errors don't add. They multiply.