Effective Java

Review, refactor, and explain Java code using distilled Effective Java principles for API design, immutability, generics, enums, streams, exceptions, concurr...

Security Scan

The skill is an instruction-only Effective Java review/refactor lens that asks for no credentials, does not install software, and its instructions are consistent with its stated purpose.

Purpose & Capability

Name/description (review, refactor, explain Java code) match the content: the SKILL.md plus two reference docs provide checklists and item maps needed for reviews. No unrelated credentials, binaries, or installs are requested.

Instruction Scope

Runtime instructions are limited to classifying tasks, loading the bundled reference files, inspecting user-provided Java code, and producing prioritized findings or focused patches. There are no instructions to read unrelated system files, call external endpoints, or access environment variables.

Install Mechanism

No install spec and no code files beyond static reference docs — nothing is written to disk or fetched from external URLs by the skill itself.

Credentials

The skill requires no environment variables, credentials, or config paths; this is proportionate to a static guidance/review skill.

Persistence & Privilege

always is false, the skill is user-invocable and may be invoked autonomously per platform defaults. It does not request persistent system privileges or modify other skills or system settings.

Scan Findings in Context

[no_code_files_for_regex_scan] expected: The regex-based scanner found nothing because this is an instruction-only skill with only markdown reference files; that's expected for a documentation-driven review skill.

Assessment

This skill appears coherent and safe to install from a technical-surface perspective: it only contains guidance and checklists and does not request secrets or install binaries. Before using it, consider: (1) provenance — the skill has no homepage and an opaque owner ID; if you require vetted sources, ask the publisher for origin/license info. (2) Do not paste sensitive secrets or private API keys into code you provide to the skill — the skill will analyze and may include snippets in its output. (3) Treat refactor/patch suggestions as advisory — review changes before applying them to repositories or CI. (4) Because the skill can be invoked autonomously per platform defaults, limit its permissions and scope in production agents if you need stricter controls. If you want higher assurance, request the publisher's source or a signed provenance statement, or prefer a skill hosted by an identifiable organization.

Core Stance

Use this skill as an Effective Java design and review lens, not as a rigid style guide. Prefer APIs that are simple, type-safe, immutable where practical, composition-friendly, well-documented at boundaries, and hard to misuse.

Do not reproduce book text. Paraphrase the principles, explain tradeoffs, and cite item numbers only as navigation aids when helpful.

Workflow

1. Classify the task: new API design, code review, refactor, bug fix, performance pass, or teaching/explanation.
2. Load references/review-checklist.md for reviews, refactors, or whenever code is provided.
3. Load references/item-map.md when the user asks for item-level mapping, broad Effective Java coverage, or a learning summary.
4. Inspect the public contract first: construction, mutability, equality, generics, exceptions, threading, serialization, and compatibility.
5. Prioritize recommendations by semantic risk before style: correctness, API safety, encapsulation, maintainability, then performance.
6. If editing code, make the smallest change that preserves existing behavior and public compatibility unless the user explicitly asks for an API redesign.

Default Review Order

• Correctness: broken invariants, resource leaks, equality/hash violations, unsafe publication, races, swallowed exceptions.
• API design: confusing construction, boolean traps, excessive overloads, raw types, wildcard misuse, checked exceptions that are not recoverable.
• Encapsulation: exposed mutable state, public fields, inheritance without contracts, mutable static state, missing defensive copies.
• Type safety: unchecked casts, heap pollution, arrays mixed with generics, int constants where enums fit.
• Clarity: stream/lambda overuse, unclear method references, unnecessary cleverness, duplicated construction logic.
• Performance: avoid premature tuning; flag avoidable object churn, boxing, synchronization bottlenecks, and inappropriate parallel streams only after semantics are sound.

High-Value Heuristics

• Prefer named static factories when names, caching, subtype returns, or instance control improve the API; keep constructors when the simple shape is clearer.
• Use builders for constructors with many optional parameters; validate invariants in one place before object publication.
• Prefer dependency injection over hard-coded singletons or static utilities for resources that vary or need testing.
• Favor immutability, minimize visibility, and make defensive copies at trust boundaries.
• Prefer composition over inheritance unless inheritance is deliberately designed, documented, and tested.
• Eliminate raw types; use bounded wildcards with PECS: producers extends, consumers super.
• Use enums instead of integer or string constants; use EnumSet and EnumMap for enum-keyed collections.
• Use lambdas and streams for clear transformations; keep complex control flow, checked exceptions, and stateful logic out of streams.
• Validate parameters at boundaries; return empty collections or arrays instead of null for multi-value returns.
• Use checked exceptions only for conditions callers can reasonably recover from; otherwise prefer unchecked exceptions with useful messages.
• Treat concurrency as a correctness concern: prefer immutability, executors, concurrent collections, and explicit thread-safety documentation.
• Avoid Java serialization for new designs; if forced to support it, validate invariants and consider the serialization proxy pattern.

Response Patterns

For code review, answer with prioritized findings:

- [P1] Title (`Path.java:line`): explain the concrete risk.
  Effective Java lens: item family or principle.
  Change: concise, actionable fix.

For refactoring, explain the chosen item families, apply a focused patch, then list behavior and compatibility assumptions plus validation performed.

For teaching, group principles by problem type and include small original examples rather than long quotes from the book.

Guardrails

• Preserve public API compatibility unless the user explicitly asks for breaking changes.
• Do not turn every class immutable, every constructor into a builder, or every loop into a stream; justify each recommendation by context.
• Do not add frameworks or large abstractions when a Java language or library feature solves the problem.
• Call out uncertainty when source context is missing, especially around concurrency guarantees, serialization compatibility, and external API contracts.