Java api design

Skill andresnator/agents-orchestrator/skills/java-api-design

Install

npx -y skills add andresnator/agents-orchestrator --skill java-api-design

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Trigger: Java API design, public API, encapsulation, modules, visibility, contracts, binary compatibility. Design Java APIs with clear boundaries.

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

2.6 KB, as published. Nobody here has run it

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

None.