Debugging JVM performance issues usually means sifting through heap dumps, GC logs, thread dumps, and flight recordings by hand. It's tedious, error-prone, and requires deep expertise. I built a skill that lets an AI coding assistant do it for you.

What It Does

The jvm-diagnostics skill turns your AI assistant into a JVM diagnostics specialist. Drop in your diagnostic files, and it produces a structured markdown report covering memory leaks, thread issues, GC pressure, CPU hotspots, deadlocks, and more — complete with severity ratings and prioritized recommendations.

Supported Formats

• Java Flight Recorder** (`.jfr`)
• Heap Dumps** (`.hprof`)
• Thread Dumps** (`.txt`, `.tdump`)
• GC Logs** (`.gc.log`)
• VisualVM Snapshots** (`.apps`, `.nps`)
• Core Dumps & Crash Logs** (`.core`, `hs_err_pid*.log`)

How it works

The skill follows a simple pipeline:

1. Detect - Identifies file types by extension and magic bytes
2. Probe - Checks for JDK tools (`jfr`, `jmap`, `jstack`, `jhsdb`) on the system
3. Parse - Uses JDK tools when available, falls back to custom Python parsers that require zero external dependencies
4. Analyze & Report - Cross-references data across files and generates a jvm-diagnostics.md report

Every parser is written in Python using only standard library modules (`struct`, `re`, `json`, `zipfile`, `xml`). No pip installs, no JDK requirement. The parsers handle binary formats directly — LEB128 decoding for JFR, HPROF record walking for heap dumps, ELF header parsing for core dumps — all from scratch.

Built-in Detection Rules

The skill codifies expert-level diagnostic for the following:

• GC Overhead
• Deadlocks
• GC Pause times
• Post-GC heap baseline increasing
• Blocked threads
• Single method CPU hogger
• and others.

Each finding comes with an explanation and an actionable fix.

Setup

The skill follows the Agent Skills open standard, so it works with any AI coding assistant that supports it.

The setup is the same: clone the skill folder and place it where your tool expects to find skills.

OpenCode

OpenCode discovers skills from:

• .opencode/skills/ inside your project directory
• .claude/skills/ inside your project directory
• .agents/skills/ inside your project directory
• ~/.config/opencode/skills/ global path

Pick whichever location works for you and:

# Project-local (recommended — commit it with your repo)
cp -r jvm-diagnostics .opencode/skills/jvm-diagnostics

# Or global (available in every project)
cp -r jvm-diagnostics ~/.config/opencode/skills/jvm-diagnostics

Once in place, OpenCode sees the skill automatically. You can invoke it explicitly:

/jvm-diagnostics

Or just ask a question like "analyze this heap dump" and OpenCode will load the skill when it's relevant.

Claude Code

Claude Code uses the same .claude/skills/ convention:

# Project-local
cp -r jvm-diagnostics .claude/skills/jvm-diagnostics

# Or global
cp -r jvm-diagnostics ~/.claude/skills/jvm-diagnostics

Then invoke it directly:

/jvm-diagnostics

Or let Claude pick it up automatically when you ask it to analyze JVM diagnostic files. Claude reads the skill description and decides when to load it.

Conclusion

Once the skill is installed, point your assistant at any supported diagnostic file and go drink a coffee while waiting for the report.

The full source is available on GitHub.