|
| 1 | +--- |
| 2 | +name: async-profiler |
| 3 | +description: 'Install, run, and analyze async-profiler for Java — low-overhead sampling profiler producing flamegraphs, JFR recordings, and allocation profiles. Use for: "install async-profiler", "set up Java profiling", "Failed to open perf_events", "what JVM flags for profiling", "capture a flamegraph", "profile CPU/memory/allocations/lock contention", "profile my Spring Boot app", "generate a JFR recording", "heap keeps growing", "what does this flamegraph mean", "how do I read a flamegraph", "interpret profiling results", "open a .jfr file", "what''s causing my CPU hotspot", "wide frame in my profile", "I see a lot of GC / Hibernate / park in my profile". Use this skill any time a Java developer mentions profiling, flamegraphs, async-profiler, JFR, or wants to understand JVM performance.' |
| 4 | +compatibility: Requires Python 3.7+ for the analyze_collapsed.py script. |
| 5 | +--- |
| 6 | + |
| 7 | +# async-profiler |
| 8 | + |
| 9 | +async-profiler is a production-safe, low-overhead sampling profiler for Java |
| 10 | +that avoids the safepoint bias of standard JVM profilers. It can capture CPU |
| 11 | +time, heap allocations, wall-clock time, and lock contention, and produce |
| 12 | +interactive flamegraphs, JFR recordings, and collapsed stack traces. |
| 13 | + |
| 14 | +## Installing this skill |
| 15 | + |
| 16 | +### IntelliJ IDEA (Junie or GitHub Copilot) |
| 17 | + |
| 18 | +Skills live in a `.claude/skills/`, `.agents/skills/`, or `.github/skills/` |
| 19 | +directory, either in your project repo or in your home directory. |
| 20 | + |
| 21 | +**Project-level — recommended for teams** (commit so everyone gets it): |
| 22 | +```bash |
| 23 | +# From your project root: |
| 24 | +mkdir -p .github/skills |
| 25 | +cd .github/skills |
| 26 | +unzip /path/to/async-profiler.skill |
| 27 | +git add async-profiler |
| 28 | +git commit -m "Add async-profiler skill" |
| 29 | +``` |
| 30 | + |
| 31 | +**Global — personal use across all projects:** |
| 32 | +```bash |
| 33 | +mkdir -p ~/.claude/skills |
| 34 | +cd ~/.claude/skills |
| 35 | +unzip /path/to/async-profiler.skill |
| 36 | +``` |
| 37 | + |
| 38 | +> **Note for GitHub Copilot users:** There is a known issue where the Copilot |
| 39 | +> JetBrains plugin does not reliably pick up skills from the global `~/.copilot/skills` |
| 40 | +> directory. Use the project-level `.github/skills/` location to be safe. |
| 41 | +
|
| 42 | +Alternatively, install the **Agent Skills Manager** plugin from the JetBrains |
| 43 | +Marketplace (*Settings → Plugins → Marketplace* → "Agent Skills Manager") for |
| 44 | +a UI that installs skills without unzipping manually. |
| 45 | + |
| 46 | +--- |
| 47 | + |
| 48 | +## Using this skill in IntelliJ IDEA |
| 49 | + |
| 50 | +### With Junie (JetBrains AI) |
| 51 | + |
| 52 | +Junie is JetBrains' native coding agent, available in the AI Chat panel. |
| 53 | + |
| 54 | +1. Open the AI Chat panel (*View → Tool Windows → AI Chat*, or the chat icon |
| 55 | + in the right toolbar) |
| 56 | +2. In the agent dropdown at the top of the chat, select **Junie** |
| 57 | +3. Choose a mode: |
| 58 | + - **Code mode** — Junie can run terminal commands, write files, and execute |
| 59 | + the profiling scripts directly. Use this when you want it to actually run |
| 60 | + `scripts/install.sh` or `scripts/run_profile.sh` for you. |
| 61 | + - **Ask mode** — read-only; Junie analyzes and explains but won't touch |
| 62 | + files. Use this when you want help interpreting a flamegraph or JFR file. |
| 63 | +4. Just ask naturally — Junie loads the skill automatically when your question |
| 64 | + matches the description. You don't need to invoke it by name. |
| 65 | + |
| 66 | +Example prompts that will trigger this skill in Junie: |
| 67 | +- *"My Spring Boot app is using too much CPU. Help me capture a flamegraph."* |
| 68 | +- *"I have this JFR file — open it and tell me what's slow."* |
| 69 | +- *"Install async-profiler on this machine and set up the JVM flags."* |
| 70 | + |
| 71 | +In Code mode, Junie will run `scripts/install.sh`, execute `scripts/run_profile.sh` |
| 72 | +with the right flags, and then walk you through the results — all without |
| 73 | +leaving IntelliJ. |
| 74 | + |
| 75 | +### With GitHub Copilot in IntelliJ |
| 76 | + |
| 77 | +1. Enable agent mode: *Settings → GitHub Copilot → Chat → Agent* → turn on |
| 78 | + **Agent mode** and **Agent Skills** |
| 79 | +2. Open the Copilot Chat panel and make sure the mode selector shows **Agent** |
| 80 | +3. Ask naturally — Copilot loads the skill when your prompt matches |
| 81 | + |
| 82 | +Example prompts: |
| 83 | +- *"Profile my running Java app and show me where the CPU is going."* |
| 84 | +- *"Analyze this collapsed stack file and tell me what's allocating the most."* |
| 85 | + |
| 86 | +GitHub Copilot's agent mode can also run the bundled scripts on your behalf — |
| 87 | +it will propose the terminal command and ask for confirmation before executing. |
| 88 | + |
| 89 | +### GitHub Copilot CLI |
| 90 | + |
| 91 | +```bash |
| 92 | +# Copilot CLI |
| 93 | +mkdir -p ~/.copilot/skills |
| 94 | +cd ~/.copilot/skills |
| 95 | +unzip /path/to/async-profiler.skill |
| 96 | + |
| 97 | +# Or, if your version uses ~/.agents/skills/: |
| 98 | +mkdir -p ~/.agents/skills |
| 99 | +cd ~/.agents/skills |
| 100 | +unzip /path/to/async-profiler.skill |
| 101 | +``` |
| 102 | + |
| 103 | +Run `/skills list` to confirm it loaded. Then just ask naturally in the terminal. |
| 104 | + |
| 105 | +--- |
| 106 | + |
| 107 | +## Bundled scripts |
| 108 | + |
| 109 | +This skill includes four ready-to-run scripts in `scripts/`: |
| 110 | + |
| 111 | +| Script | What it does | |
| 112 | +|---|---| |
| 113 | +| `scripts/install.sh` | Auto-detects platform, downloads the right binary, verifies install | |
| 114 | +| `scripts/run_profile.sh` | Wraps `asprof` with defaults, timestamps output, prints opening instructions | |
| 115 | +| `scripts/collect.sh` | Agent-friendly background collection: start all-event profiling, do other work, then stop and get all flamegraphs | |
| 116 | +| `scripts/analyze_collapsed.py` | Ranked self-time / inclusive-time table for `.collapsed` files, with filters | |
| 117 | + |
| 118 | +Always offer to run these scripts on the user's behalf when relevant. |
| 119 | + |
| 120 | +## How to use this skill |
| 121 | + |
| 122 | +This skill has three sub-guides. Read the one that matches what the user needs: |
| 123 | + |
| 124 | +| Situation | Read | |
| 125 | +|---|---| |
| 126 | +| User needs to install or configure async-profiler, or is hitting setup errors | `setup/SKILL.md` | |
| 127 | +| User wants to run a profiling session (capture flamegraph, JFR, etc.) | `profile/SKILL.md` | |
| 128 | +| User has profiling output and wants to understand or interpret it | `analyze/SKILL.md` | |
| 129 | + |
| 130 | +**When the conversation spans multiple phases** (e.g., the user just ran a |
| 131 | +profile and now wants to understand the output), read whichever sub-guide is |
| 132 | +most relevant to the current question. If the user needs both setup *and* |
| 133 | +profiling guidance in one message, read `setup/SKILL.md` first and summarize |
| 134 | +the setup steps before moving to `profile/SKILL.md`. |
| 135 | + |
| 136 | +Read the relevant sub-guide now before responding. |
0 commit comments