What is java-api-discovery?

This Claude skill enables developers to accurately discover Java API signatures directly from compiled JAR files using the javap utility. By inspecting bytecode, it eliminates reliance on outdated documentation or guesswork, providing precise information on method signatures, return types, and class structures to prevent compilation errors and streamline library integration.

When should I use java-api-discovery?

java-api-discovery is useful in the following scenarios: • Resolving compilation errors caused by incorrect assumptions about method signatures or parameter types in third-party libraries. • Exploring unfamiliar Java SDKs or internal libraries where documentation is missing, incomplete, or ambiguous. • Identifying specific pagination patterns (e.g., cursor-based vs. offset-based) by inspecting API client classes. • Verifying the existence of fields and return types (such as List vs. Set) to ensure type safety before writing implementation code. • Handling complex union types or polymorphic responses by discovering internal patterns like getActualInstance().

name	java-api-discovery
description	Discover Java API signatures from compiled JARs using javap instead of guessing or relying on incomplete documentation. Use when encountering unknown methods, pagination patterns, union types, or compilation errors from incorrect API assumptions.

Java API Discovery

Efficiently discover actual API signatures from compiled JARs using javap. This approach eliminates guessing and trial-and-error by examining the compiled bytecode directly.

When to Use This Skill

Encountering compilation errors from incorrect method assumptions
Working with unfamiliar Java SDKs or libraries
Need to understand pagination patterns (offset vs cursor)
Dealing with union types or polymorphic responses
Verifying field existence before writing code
Documentation is incomplete, outdated, or ambiguous

Core Workflow

1. Find the JAR

# Gradle projects
find ~/.gradle/caches -name "*library-name*.jar" -type f 2>/dev/null | head -5

# Maven projects
find ~/.m2/repository -name "*library-name*.jar" -type f 2>/dev/null | head -5

# Project libs
find . -name "*.jar" -type f 2>/dev/null

2. List Package Contents

# List all classes in a package
jar tf /path/to/library.jar | grep "com/example/package" | head -20

# Find specific class
jar tf /path/to/library.jar | grep -i "ClassName"

3. Examine Class API

# Show all public methods
javap -cp /path/to/library.jar com.example.ClassName

# Filter for getters
javap -cp /path/to/library.jar com.example.ClassName | grep -E "public.*get"

# Filter for setters/builders
javap -cp /path/to/library.jar com.example.ClassName | grep -E "public.*(set|with|build)"

# Show full signatures including generics
javap -s -cp /path/to/library.jar com.example.ClassName

4. Verify Before Coding

Before writing any API call:

Find the exact method name with javap
Check return type (especially for collections: List vs Set)
Verify parameter types
Look for builder patterns vs constructors

Common Patterns to Discover

Pagination

# Check for pagination methods
javap -cp /path/to/jar com.example.ApiClient | grep -iE "(page|offset|cursor|limit)"

Common patterns:

Offset-based: pageOffset(Long), pageLimit(Long)
Cursor-based: pageCursor(String), nextCursor()
Token-based: pageToken(String), nextPageToken()

Union Types

# Look for getActualInstance pattern
javap -cp /path/to/jar com.example.Response | grep -E "(getActualInstance|instanceof)"

Handling union types:

Object actual = response.getActualInstance();
if (actual instanceof TypeA) {
    TypeA typed = (TypeA) actual;
}

Builder vs Constructor

# Check construction options
javap -cp /path/to/jar com.example.Model | grep -E "(public.*\(|builder|Builder)"

Enum Constants

# List enum values
javap -cp /path/to/jar com.example.TokenType | grep -E "public static final"

Quick Reference

Need	Command
Find JAR	`find ~/.gradle/caches -name "name.jar"`
List classes	`jar tf file.jar \| grep package`
All methods	`javap -cp file.jar com.Class`
Getters only	`javap ... \| grep "get"`
With generics	`javap -s -cp file.jar com.Class`

Common Pitfalls

❌ Guessing method names → Always verify with javap
❌ Assuming collection types → Check if List, Set, or Collection
❌ Trusting old documentation → Bytecode is truth
❌ Ignoring return types → Union types need getActualInstance()

Progressive Context

For helper scripts: see scripts/discover-api.sh
For detailed patterns: see reference.md

java-api-discovery

When & Why to Use This Skill

Use Cases