Define or refactor subsystem interfaces into small, explicit contracts with clear ownership, narrow scope, stable semantics, and README-first documentation. Use when designing a new API, collapsing ad hoc module boundaries into a few coherent interfaces, hardening internal contracts, or rewriting subsystem docs so engineers can understand the system by reading README.md files, docstrings, and code only.
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
Define or refactor subsystem interfaces into small, explicit contracts with clear ownership, narrow scope, stable semantics, and README-first documentation. Use when designing a new API, collapsing ad hoc module boundaries into a few coherent interfaces, hardening internal contracts, or rewriting subsystem docs so engineers can understand the system by reading README.md files, docstrings, and code only.
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:
What are the primary interfaces?
Who calls each one?
Who owns each write path?
What is authoritative?
What is compatibility-only or debug-only?
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:
subsystem README.md
local module docstrings
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:
README.md
module docstrings
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:
new system design
existing subsystem cleanup
RPC / REST / CRD ownership confusion
duplicated transports for the same operation
stale compatibility layers that no one can explain
Design principles
1. Interfaces describe authority
Every interface must say:
what it owns
what it does not own
what state it may write
what state it may only observe
If two interfaces claim authority over the same operation or field, pick one. The other is either:
compatibility
debug-only
wrong
Ambiguous authority is not a documentation problem. It is an interface bug.
2. Contract first, transport second
Do not confuse:
REST
ConnectRPC
WebSocket
SSH
VSOCK
with the interface itself.
Multiple transports can implement one interface. One transport can also expose multiple interfaces. Name the interface by responsibility, not by wire format.
Do not let implementation detail harden into architecture accidentally.
3. README-first documentation
A good subsystem README.md should let a new engineer answer:
what this subsystem is
which primary interface it implements
which neighboring subsystem it talks to
what is authoritative
what remains compatibility-only
Do not dump global architecture into every README. Give each README one job.
The README is the manual for the subsystem. It should define the contract,
boundaries, ownership, and compatibility story, not just list folders.
4. Linux-docs style
Aim for:
short scope section
constraints before abstractions
glossary for local terms
clear ownership statements
small tables when useful
diagrams only when they explain one mechanism cleanly
Avoid:
product-marketing voice
“vision” paragraphs
giant rainbow architecture diagrams
documents that re-explain the whole system when they should define one boundary
Prefer text that reads like a subsystem maintainer wrote it for the next
maintainer, not like a platform team wrote it for a launch review.
5. Narrow, durable interfaces
Good interface names survive implementation changes:
Public Access API
Host Runtime API
Guest Runtime API
Bad interface names mirror folder layout or current wiring accidents:
“the Huma layer”
“the CRD stuff”
“the Axum endpoints”
“the protobuf side”
Good interface names should survive a rewrite of transports, frameworks,
directories, and helper packages.
6. Compose interfaces, do not compose helper soup
The right way to combine complexity is:
interface A calls interface B
interface B calls interface C
The wrong way is:
function A imports helper B
helper B reaches into state C
callback D mutates field E
the behavior only exists in call graph archaeology
If the system currently composes through ad hoc functions, collapse those
behaviors behind a smaller number of named interfaces.
side effects that are not obvious from the contract
status fields owned by a different writer than the docs say
Every interface description should be executable as a mental model.
Workflow
Step 1: Inventory actual surfaces
Find the real surfaces:
public HTTP / WebSocket / SSH routes
RPC services
guest protocols
CRDs and status/spec ownership
debug endpoints
compatibility endpoints
Write them down as concrete resources and operations, not abstractions yet.
Also inventory:
direct function-call boundaries that should probably be promoted into explicit contracts
duplicated endpoints that claim to do the same thing
“temporary” surfaces that have outlived their dignity
Step 2: Group by coherent responsibility
Partition surfaces into a small number of interfaces.
A good interface groups operations that:
share authority
share lifecycle semantics
share the same caller class
belong in the same subsystem manual
Do not force “three” if four is cleaner. Do not keep seven if three is cleaner.
The number of interfaces is not the goal. Coherent cuts are the goal.
Step 3: Classify each surface
For every endpoint / service / CRD path, classify it as one of:
authoritative
compatibility
debug-only
operational
Definitions:
authoritative: the canonical contract for doing real work
compatibility: temporary old surface during migration
debug-only: operator introspection, not product core
operational: health, metrics, openapi, readiness, etc.
If a surface does not fit one of those categories cleanly, the design is not
settled yet.
Step 4: Define ownership
For each resource or state subtree, define:
spec writer
status writer
local-runtime owner
projection owner
Prefer small tables.
Example:
| Area | Writer | Meaning |
| --- | --- | --- |
| `spec` | controlplane API | desired lifecycle and resource intent |
| `status.runtime` | host-agent | observed runtime facts from the compute host |
| `status.summary` | controlplane controller | public lifecycle projection |
Step 5: Put the contract into the right README
Default locations:
repo/service root README: index of subsystem interfaces
subsystem README: the actual contract manual
protocol README: wire contract only, if a protocol crate/package exists
package/module docstrings: local declaration of which contract is implemented
Also update local package docs and type comments so they agree with the README.
Step 6: Remove or demote strays
After the contract is written:
delete standalone taxonomy docs if they duplicate subsystem READMEs
remove dead references
relabel compatibility routes as compatibility
relabel debug routes as debug-only
If code and docs disagree, code wins for current truth, then docs are corrected.
If the code reveals the interface is wrong, fix the interface, not just the prose.
Required sections for a subsystem interface README
Use this template.
# <Subsystem>
One sentence describing what this subsystem does.
## Scope
What this subsystem owns.
What it does not own.
## Interface boundary- primary interface(s)
- neighboring systems
- authoritative contract
- compatibility/debug/operational split
## Ownership
Small tables for spec/status/runtime/projection ownership if applicable.
## Surface
Routes, services, resources, or protocol entry points.
## Semantics
What each major operation guarantees.
What it refuses.
What is synchronous, asynchronous, or eventually consistent.
## Compatibility and debug
What is transitional, what is debug-only, and what should eventually be deleted.
## References
Links to the neighboring subsystem README, proto, or type definitions.
Optional sections when useful:
Glossary
Constraints
State model
Versioning
Non-goals
Docstring pattern
Top-level module docs should say which interface the module implements.
Examples:
//! ConnectRPC service implementations for the host-agent.//!//! This module is the authoritative Host Runtime API: the controlplane-to-host//! contract for lifecycle, health, migration, release, and artifact operations.
// Workspace is the durable declarative envelope around the Host Runtime API.// Spec carries controlplane intent; status combines controller-authored// projection with host-agent-authored runtime fact.
Cutover rules
When refactoring an existing system:
Do not introduce a new abstraction layer unless it removes a real one.
New features land only on the authoritative interface.
Compatibility surfaces must be labeled as such.
Debug surfaces must not be described as architecture.
Prefer deletion over shims.
Prefer moving behavior behind a real interface over adding one more helper.
Anti-patterns
Bad: one interface document plus stale subsystem READMEs
The subsystem README must stand on its own. Do not make readers hop through a taxonomy doc to understand the boundary.
Bad: folder-shaped interfaces
Do not define interfaces by current file organization.
Bad: transport-shaped interfaces
Do not define “the WebSocket API” or “the protobuf API” unless transport is actually the product boundary.
Bad: mixed authority
If one README says controlplane owns preview status and another says host-agent owns it, the interface is broken.
Bad: architecture spill
Do not turn every README into a full system architecture essay. Put enough context to understand the boundary, then stop.
Bad: interface inflation
Do not create five tiny interfaces where one coherent subsystem contract would do.
Bad: helper accretion
Do not preserve ad hoc helper layers just because they already exist. If they
encode part of the real contract, pull that behavior upward into the interface.
Completion checklist
Primary interfaces are explicitly named
Every interface has a clear authority statement
Every significant surface is classified authoritative / compatibility / debug-only / operational
Ownership tables exist where state is split
Subsystem READMEs contain the contract, not a separate taxonomy doc
Module docstrings and type comments agree with the README
Obsolete references are removed
Behavior is composed through interfaces instead of helper-call archaeology
Interface names and semantics would still make sense after a transport or framework rewrite
