java-api-designlisted

# Skill: java-api-design ## Activation Contract Use this skill when designing or reviewing Java APIs, public classes, interfaces, modules, package boundaries, visibility, method contracts, and compatibility risks. Do **not** use this skill for private implementation cleanup, general Clean Code review, REST API product design, or non-Java API design. ## Responsibility This skill teaches Java API boundary design. It does not call other skills, generate full libraries, or decide product behavior. ## Required Context - API consumers and expected usage. - Public vs internal surface. - Java version and module usage when known. - Compatibility expectations. - Error and validation contract expectations. ## Context Budget - Keep this `SKILL.md` focused on API decisions. - Use `references/java-api-boundaries.md` for detailed boundary guidance. ## Hard Rules - Minimize public surface; public means support burden. - Make invalid states hard to represent where practical. - Document preconditions, postconditions, exceptions, and thread-safety when relevant. - Prefer package-private/internal implementation until a stable consumer need exists. - Avoid leaking mutable internals. - Avoid breaking compatibility unless the user explicitly accepts it. ## Decision Gates | Condition | Action | |---|---| | Member need not be public | Reduce visibility. | | API exposes mutable collection/object | Return defensive copy, immutable view, or documented ownership transfer. | | Constructor has