Add async-profiler skill for Java profiling 🤖🤖🤖

[vetler]

What this adds

A skill for installing, running, and analyzing async-profiler for Java — a low-overhead sampling profiler that produces flamegraphs, JFR recordings, and allocation profiles.

Why it's useful

async-profiler is a niche, specialized tool with platform-specific quirks that frontier models don't reliably handle:

• Exact asprof CLI flags and syntax
• macOS-specific limitations (itimer vs perf_events, asprof stop -f output-path bug)
• JVM flags required for accurate profiles (-XX:+UnlockDiagnosticVMOptions -XX:+DebugNonSafepoints)
• Specific version/download URLs
• How to interpret flamegraph patterns (GC pressure, N+1 Hibernate, lock contention)

Structure

skills/async-profiler/
├── SKILL.md                      # Entry point — routes to sub-guides
├── README.md                     # Human-readable overview
├── setup/SKILL.md                # Installation and configuration
├── profile/SKILL.md              # Running profiling sessions
├── analyze/SKILL.md              # Interpreting profiling output
└── scripts/
    ├── install.sh                # Platform auto-detect installer
    ├── run_profile.sh            # asprof wrapper with timestamped output
    ├── collect.sh                # Background start/stop collection
    └── analyze_collapsed.py      # Ranked self-time table for .collapsed files

Validation

• npm run skill:validate ✅
• npm run build ✅ (docs/README.skills.md updated)

[github-actions]

🔍 Skill Validator Results

✅ All checks passed

Scope	Checked
Skills	1
Agents	1
Total	2
Severity	Count
---	---:
❌ Errors	0
⚠️ Warnings	0
ℹ️ Advisories	0

Summary

Level	Finding
ℹ️	Found 1 skill(s)
ℹ️	[async-profiler] 📊 async-profiler: 1,439 BPE tokens [chars/4: 1,511] (detailed ✓), 12 sections, 3 code blocks
ℹ️	✅ All checks passed (1 skill(s))

Full validator output

```text Found 1 skill(s) [async-profiler] 📊 async-profiler: 1,439 BPE tokens [chars/4: 1,511] (detailed ✓), 12 sections, 3 code blocks ✅ All checks passed (1 skill(s)) ```

[Copilot]

Pull request overview

Adds a new async-profiler skill under skills/async-profiler/ to guide Java developers through installing async-profiler, running profiling sessions (including agent-friendly background capture), and analyzing outputs (flamegraphs/JFR/collapsed stacks), and registers the skill in docs/README.skills.md.

Changes:

• Introduces async-profiler skill docs: setup, profiling workflows, and output analysis guidance.
• Adds helper scripts for install/run/background collection plus a Python collapsed-stack analyzer.
• Updates docs/README.skills.md to include the new skill entry.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
skills/async-profiler/SKILL.md	Skill entry-point and routing to setup/profile/analyze sub-guides.
skills/async-profiler/README.md	Human-readable overview and installation notes.
skills/async-profiler/setup/SKILL.md	Installation/configuration instructions and troubleshooting.
skills/async-profiler/profile/SKILL.md	How to run profiles, including collect.sh background workflows.
skills/async-profiler/analyze/SKILL.md	How to interpret flamegraphs/JFR/collapsed stacks.
skills/async-profiler/scripts/install.sh	Platform-detecting async-profiler installer.
skills/async-profiler/scripts/run_profile.sh	Convenience wrapper for one-shot profiles + (intended) JFR splitting.
skills/async-profiler/scripts/collect.sh	Start/stop/timed background collection workflow with JFR splitting.
skills/async-profiler/scripts/analyze_collapsed.py	CLI analyzer for .collapsed files.
docs/README.skills.md	Adds the skill to the repository skills index.

[vetler]

All 9 review comments have been addressed in an amended commit (3fa7ee5). Summary of changes:

1. python → python3 in run_profile.sh post-run guidance
2. from __future__ import annotations added to analyze_collapsed.py to restore Python 3.7+ compatibility (PEP 585 generics)
3. jfrconv --event alloc → jfrconv --alloc in analyze/SKILL.md
4. Install path comment in install.sh updated to ~/async-profiler-4.3
5. Bash syntax in collect.sh split_jfr: separated & local pid_X=$! onto two lines
6. asprof stop now passes -f "$jfr_path" so on Linux the JFR lands at the expected path; macOS sentinel workaround is unchanged
7. run_profile.sh comprehensive mode fixed to use --cpu/--alloc/--wall/--lock instead of --event cpu etc.
8. collect.sh timed docs corrected to -d 60 <PID> (flag before target)
9. Output filenames in profile/SKILL.md corrected to profile-cpu.html, profile-alloc.html, etc.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 7 comments.

[vetler]

Fixed all 7 review comments:

• profile/SKILL.md: Moved -maxdepth 8 before -name in all find examples (×2)
• profile/SKILL.md: timed table already fixed in previous round
• collect.sh: Moved -maxdepth 8 before predicates in JFR lookup (line ~230)
• collect.sh: Fixed -maxdepth order in troubleshooting echo (line ~238)
• collect.sh session_file(): Added UID and $XDG_RUNTIME_DIR support to prevent predictable tmp paths
• run_profile.sh: Changed sed -n '2,/^$/p' → sed -n '2,/^[^#]/p' to stop at first non-comment line
• run_profile.sh: Changed remaining python → python3 in single-event collapsed branch

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

[vetler]

Fixed 3 of 4 review comments; the 4th is already handled:

analyze_collapsed.py — list[tuple[...]] compatibility (no code change needed)
from __future__ import annotations (PEP 563, added in a prior commit) defers evaluation of all annotations in this module to strings at runtime. list[tuple[list[str], int]] in the return type of parse_collapsed() is therefore never evaluated on Python 3.7/3.8 and will not raise a SyntaxError.

analyze_collapsed.py — ZeroDivisionError when total_samples == 0
Added guard: matching_pct = 0.0 if total_samples == 0 else 100 * surviving / total_samples

run_profile.sh — missing $# check before $2 in option loop
Added [[ $# -ge 2 ]] || { echo "❌ Missing value for $1" >&2; exit 1; } before each $2 access for --event, --duration, --format, --output, --asprof.

collect.sh — missing $# check for -d/--duration and --asprof
Same guard added for both options.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[vetler]

@all-contributors add @vetler for skills

[allcontributors]

@vetler

I couldn't determine any contributions to add, did you specify any contributions?
Please make sure to use valid contribution names.

[vetler]

@all-contributors add @vetler for 🧰

[allcontributors]

@vetler

I couldn't determine any contributions to add, did you specify any contributions?
Please make sure to use valid contribution names.

[vetler]

@all-contributors add @vetler for skill

[allcontributors]

@vetler

I couldn't determine any contributions to add, did you specify any contributions?
Please make sure to use valid contribution names.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

[vetler]

Fixed all 3 review comments:

install.sh — INSTALL_DIR exists but invalid
Added an explicit check after the 'already installed' guard: if ${INSTALL_DIR} exists but bin/asprof is not executable, the script now aborts with a clear message and instructs the user to remove it or set a custom INSTALL_PARENT.

collect.sh — --help truncation at line 35
Changed sed -n '2,35p' to sed -n '2,/^[^#]/p' — the same technique used in run_profile.sh — so help output stops at the first non-comment line rather than at a hardcoded line number.

collect.sh — session file deleted unconditionally before verifying JFR
Added a [[ ! -s "$jfr_path" ]] check before rm -f "$sess". If the JFR is missing or empty (both on Linux and after the macOS copy), the script now exits with an error and preserves the session state file for recovery.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 7 comments.

[vetler]

All 7 review comments from round 6 addressed:

1. SKILL.md description — converted from block scalar to single-line quoted string
2. analyze/SKILL.md description — same fix
3. profile/SKILL.md description — same fix
4. setup/SKILL.md description — same fix
5. install.sh INSTALL_PARENT hint — changed to bash scripts/install.sh /path/to/dir (script uses $1, not env var)
6. collect.sh xargs empty input — replaced pipeline with array-based approach that safely handles empty find output
7. install.sh unzip check — added command -v unzip check before .zip extraction on macOS

All validated with npm run skill:validate ✅

[vetler]

@copilot review

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

[vetler]

All 4 review comments from round 7 addressed:

1. run_profile.sh wait — replaced single wait with per-PID loop to catch individual jfrconv failures
2. collect.sh wait — same per-PID wait pattern with labeled error messages
3. SKILL.md install paths — documented both ~/.copilot/skills/ and ~/.agents/skills/ paths
4. README.md install paths — same dual-path documentation

All validated with npm run skill:validate ✅

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

[vetler]

All 5 review comments from round 8 addressed:

1. README.md Python version — The script uses from __future__ import annotations (line 21), which defers annotation evaluation and makes list[...]/tuple[...] syntax work on Python 3.7+. No change needed; 3.7+ is correct.
2. collect.sh sentinel removal — Moved rm -f "$sentinel" to after successful JFR copy. On failure, sentinel is preserved and the error message now includes a retry hint using -newer "$sentinel".
3. collect.sh header comment — Updated to reflect $XDG_RUNTIME_DIR preference over /tmp.
4. SKILL.md Python version — Same as Durable Ownership - Repository github/awesome-copilot will be archived #1: from __future__ import annotations ensures 3.7+ compat.
5. analyze/SKILL.md Python version — Same as Durable Ownership - Repository github/awesome-copilot will be archived #1.

All validated with npm run skill:validate ✅

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

[vetler]

All 4 review comments from round 9 addressed:

1. collect.sh cmd_timed outdir — Sanitized TARGET for filesystem use (tr -c '[:alnum:]._-' '_') while still passing raw value to asprof.
2. install.sh version hardcoding — Good observation. The script already supports --path-only (line 18) for programmatic path resolution. Centralizing the version constant further is a worthwhile follow-up but would be a larger refactor beyond this PR's scope.
3. run_profile.sh shared asprof discovery — Agreed this would reduce drift. install.sh --path-only already exists as a building block. Extracting a shared locate_asprof sourced by both scripts is a good follow-up improvement.
4. collect.sh cmd_start outdir — Same sanitization fix as Durable Ownership - Repository github/awesome-copilot will be archived #1.

All validated with npm run skill:validate ✅