generate-interface

Generate Interface

Design interfaces the way durable systems do:

• one contract per real responsibility
• one authority per state field or operation
• explicit transports, not accidental ones
• README-first subsystem manuals
• docstrings that explain what part of the interface a module implements
• code that follows the contract instead of inventing side channels

The target is an interface that feels old in the best way:

• obvious
• narrow
• composable
• boring
• hard to misunderstand

Think Unix and Linux, not app-framework churn.

This skill is for interface hardening, not generic architecture prose.

Core rule

Reduce a subsystem until a reader can answer these questions quickly:

1. What are the primary interfaces?
2. Who calls each one?
3. Who owns each write path?
4. What is authoritative?
5. What is compatibility-only or debug-only?
6. What is explicitly out of scope?

If the answer requires reading five modules and guessing, the interface is not done.

If the behavior of the subsystem is mostly encoded in ad hoc helper functions and not in a small set of named interfaces, the design is not done.

Output shape

Prefer this hierarchy:

1. subsystem README.md
2. local module docstrings
3. code

Do not create a new top-level taxonomy document unless the user explicitly wants one.

The default move is to consolidate interface definitions into the correct subsystem README.md files.

The user should be able to understand the subsystem by reading:

1. README.md
2. module docstrings
3. code

and nothing else.

When to use

Use this skill when the user asks for things like:

• “make the interfaces solid”
• “reduce this architecture to a few APIs”
• “clean up the controlplane/runtime boundary”
• “document the subsystem so it reads cleanly”
• “collapse ad hoc functions into real interfaces”
• “make the README and docstrings the source of truth”
• “make this feel like a real subsystem manual”
• “make the API surface obvious”

Typical triggers: