Skip to content

Commit 3fa7ee5

Browse files
vetlerCopilot
vetler
and
Copilot
committed
Add async-profiler skill
Add skill for installing, running, and analyzing async-profiler for Java. Covers CPU/memory/allocation profiling, flamegraph capture and interpretation, JFR recordings, and common setup errors (e.g. perf_events). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 1565493 commit 3fa7ee5

File tree

10 files changed

+2143
-0
lines changed

10 files changed

+2143
-0
lines changed

‎docs/README.skills.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
4848
| [arize-trace](../skills/arize-trace/SKILL.md) | INVOKE THIS SKILL when downloading or exporting Arize traces and spans. Covers exporting traces by ID, sessions by ID, and debugging LLM application issues using the ax CLI. | `references/ax-profiles.md`<br />`references/ax-setup.md` |
4949
| [aspire](../skills/aspire/SKILL.md) | Aspire skill covering the Aspire CLI, AppHost orchestration, service discovery, integrations, MCP server, VS Code extension, Dev Containers, GitHub Codespaces, templates, dashboard, and deployment. Use when the user asks to create, run, debug, configure, deploy, or troubleshoot an Aspire distributed application. | `references/architecture.md`<br />`references/cli-reference.md`<br />`references/dashboard.md`<br />`references/deployment.md`<br />`references/integrations-catalog.md`<br />`references/mcp-server.md`<br />`references/polyglot-apis.md`<br />`references/testing.md`<br />`references/troubleshooting.md` |
5050
| [aspnet-minimal-api-openapi](../skills/aspnet-minimal-api-openapi/SKILL.md) | Create ASP.NET Minimal API endpoints with proper OpenAPI documentation | None |
51+
| [async-profiler](../skills/async-profiler/SKILL.md) | 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. | `README.md`<br />`analyze`<br />`profile`<br />`scripts/analyze_collapsed.py`<br />`scripts/collect.sh`<br />`scripts/install.sh`<br />`scripts/run_profile.sh`<br />`setup` |
5152
| [automate-this](../skills/automate-this/SKILL.md) | Analyze a screen recording of a manual process and produce targeted, working automation scripts. Extracts frames and audio narration from video files, reconstructs the step-by-step workflow, and proposes automation at multiple complexity levels using tools already installed on the user machine. | None |
5253
| [autoresearch](../skills/autoresearch/SKILL.md) | Autonomous iterative experimentation loop for any programming task. Guides the user through defining goals, measurable metrics, and scope constraints, then runs an autonomous loop of code changes, testing, measuring, and keeping/discarding results. Inspired by Karpathy's autoresearch. USE FOR: autonomous improvement, iterative optimization, experiment loop, auto research, performance tuning, automated experimentation, hill climbing, try things automatically, optimize code, run experiments, autonomous coding loop. DO NOT USE FOR: one-shot tasks, simple bug fixes, code review, or tasks without a measurable metric. | None |
5354
| [aws-cdk-python-setup](../skills/aws-cdk-python-setup/SKILL.md) | Setup and initialization guide for developing AWS CDK (Cloud Development Kit) applications in Python. This skill enables users to configure environment prerequisites, create new CDK projects, manage dependencies, and deploy to AWS. | None |

‎skills/async-profiler/README.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# async-profiler
2+
3+
Install, run, and analyze async-profiler for Java — a low-overhead sampling profiler producing flamegraphs, JFR recordings, and allocation profiles.
4+
5+
## What it does
6+
7+
- Installs async-profiler automatically for macOS or Linux
8+
- Captures CPU time, heap allocations, wall-clock time, and lock contention
9+
- Produces interactive flamegraphs, JFR recordings, and collapsed stack traces
10+
- Interprets profiling output: identifies hotspots, GC pressure, lock contention, N+1 Hibernate patterns
11+
12+
## Compatibility
13+
14+
Requires Python 3.7+ for the analysis script. async-profiler works on macOS and Linux with a running JVM process.
15+
16+
## Installation
17+
18+
**GitHub Copilot CLI:**
19+
20+
Point Copilot at the skill directory from within a session:
21+
```
22+
/skills add /path/to/async-profiler
23+
```
24+
25+
Or copy manually:
26+
```bash
27+
cp -r async-profiler ~/.copilot/skills/
28+
```
29+
30+
**Claude Code:**
31+
```bash
32+
cp -r async-profiler ~/.claude/skills/async-profiler
33+
```
34+
35+
**OpenCode:**
36+
```bash
37+
cp -r async-profiler ~/.config/opencode/skills/async-profiler
38+
```
39+
40+
## Trigger phrases
41+
42+
- "install async-profiler"
43+
- "capture a flamegraph"
44+
- "profile my Spring Boot app"
45+
- "heap keeps growing"
46+
- "what does this flamegraph mean"
47+
- "I see a lot of GC in my profile"
48+
49+
## Bundled scripts
50+
51+
| Script | Purpose |
52+
|---|---|
53+
| `scripts/install.sh` | Auto-detect platform, download and verify async-profiler |
54+
| `scripts/run_profile.sh` | Wrap `asprof` with defaults, timestamp output |
55+
| `scripts/collect.sh` | Background collection: start all-event profiling, stop and retrieve flamegraphs |
56+
| `scripts/analyze_collapsed.py` | Ranked self-time/inclusive-time table for `.collapsed` files |
57+
58+
## Directory structure
59+
60+
```
61+
async-profiler/
62+
├── SKILL.md # Entry point — routes to sub-guides
63+
├── scripts/ # Bundled scripts
64+
├── setup/
65+
│ └── SKILL.md # Installation and configuration
66+
├── profile/
67+
│ └── SKILL.md # Running profiling sessions
68+
└── analyze/
69+
└── SKILL.md # Interpreting profiling output
70+
```

‎skills/async-profiler/SKILL.md‎

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

0 commit comments

Comments
 (0)