api-library-golang

Core principle: friendly, consistent, discoverable

APIs are contracts. Once published, every behavior — documented or not — becomes something users depend on (Hyrum's Law). This skill enforces the discipline of designing APIs that are stable, self-documenting, and difficult to misuse. A public API should be usable by someone reading only the function signatures and a few examples — without needing to read the implementation. Consistency across the whole library matters more than any single function being clever.

Process

Step 1: Design the Interface First

1. Write the usage examples before writing the implementation.
2. Ask: Is this easy to use correctly? Is it hard to use incorrectly?
3. Apply the principle of least surprise — the API should do what it looks like it does.
4. Design for the caller, not the implementer.

Verify: You can write 3 example usages without looking at the implementation.

Step 2: Apply Hyrum's Law