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 many parameters |
Consider named factory, parameter object, or builder based on complexity. |
| Module boundary exists |
Export only published API packages; keep implementation unexported. |
| Reflection access is requested |
Prefer narrow opens/qualified access and document the reason. |
Execution Steps
- Identify consumers and stability expectations.
- Separate API surface from implementation.
- Review visibility, mutability, construction, errors, and documentation.
- Check Java module/package implications.
- Recommend API shape and compatibility notes.
Output Contract
Return:
- API boundary verdict.
- Public surface changes recommended.
- Contract documentation needed.
- Compatibility risks.
- Minimal API design proposal.
References
references/java-api-boundaries.md — Visibility, modules, mutability, and compatibility guidance.
Assets
1---2name: java-api-design3description: Trigger: Java API design, public API, encapsulation, modules, visibility, contracts, binary compatibility. Design Java APIs with clear boundaries.4license: MIT5---67# Skill: java-api-design89## Activation Contract1011Use this skill when designing or reviewing Java APIs, public classes, interfaces, modules, package boundaries, visibility, method contracts, and compatibility risks.1213Do **not** use this skill for private implementation cleanup, general Clean Code review, REST API product design, or non-Java API design.1415## Responsibility1617This skill teaches Java API boundary design. It does not call other skills, generate full libraries, or decide product behavior.1819## Required Context2021- API consumers and expected usage.22- Public vs internal surface.23- Java version and module usage when known.24- Compatibility expectations.25- Error and validation contract expectations.2627## Context Budget2829- Keep this `SKILL.md` focused on API decisions.30- Use `references/java-api-boundaries.md` for detailed boundary guidance.3132## Hard Rules3334- Minimize public surface; public means support burden.35- Make invalid states hard to represent where practical.36- Document preconditions, postconditions, exceptions, and thread-safety when relevant.37- Prefer package-private/internal implementation until a stable consumer need exists.38- Avoid leaking mutable internals.39- Avoid breaking compatibility unless the user explicitly accepts it.4041## Decision Gates4243| Condition | Action |44|---|---|45| Member need not be public | Reduce visibility. |46| API exposes mutable collection/object | Return defensive copy, immutable view, or documented ownership transfer. |47| Constructor has many parameters | Consider named factory, parameter object, or builder based on complexity. |48| Module boundary exists | Export only published API packages; keep implementation unexported. |49| Reflection access is requested | Prefer narrow `opens`/qualified access and document the reason. |5051## Execution Steps52531. Identify consumers and stability expectations.542. Separate API surface from implementation.553. Review visibility, mutability, construction, errors, and documentation.564. Check Java module/package implications.575. Recommend API shape and compatibility notes.5859## Output Contract6061Return:6263- API boundary verdict.64- Public surface changes recommended.65- Contract documentation needed.66- Compatibility risks.67- Minimal API design proposal.6869## References7071- `references/java-api-boundaries.md` — Visibility, modules, mutability, and compatibility guidance.7273## Assets7475- None.
andresnator