principle-design-the-surfacelisted

# Design the Surface Agents are good at solving the technical problem and bad at crafting the experience of using the result. Everything you build has a consumer at its boundary. Design that surface deliberately: simple and seamless for the consumer, regardless of the complexity under the hood. The user is whoever consumes the work. For a UI that is the end user. For a library or an internal API it is the colleague who imports it. For a tool schema or a skill it is the LLM that reads it. The engineer who maintains the code next is a user too. Weigh their experience the same way, and explain impact from their seat. **Why:** A surface that leaks its internals exports complexity to every consumer, forever. The consumer then learns both the surface and the implementation, and every internal change becomes their problem. Solving the problem is half the work; the other half is making the solution good to consume, and it is the half that gets skipped. **The pattern:** - Complexity is paid inside, never exported. Absorb it in the implementation instead of passing it to the consumer as extra options, steps, or caveats. - The simple case takes the simple path. The common call needs no configuration. - One obvious entry point. A consumer should determine how the surface is meant to be used without reading the implementation. - Expose domain concepts, not your private representation. The **boundary-discipline** principle skill states this for validation wiring; it holds for every su