Automated summary
Analyzes PyTorch profiler and vLLM traces using Perfetto SQL queries to surface GPU, CPU, and multi-rank bottlenecks, then emits a structured report.
Strengths
- Explicit step-by-step workflow: find the merged trace, run overview queries, then gather evidence per area (sync waits, kernel hotspots, prefill/decode, rank imbalance)
- Enforced report template that separates confirmed evidence from hypotheses and calls out evidence gaps
- Ships SQL query presets and a Python runner, so the agent avoids pasting raw trace JSON
- Points to concrete next inspections in Perfetto/TensorBoard plus actionable optimization suggestions
Limitations
- Assumes a merged trace such as *-merged_trace.json already exists from a vLLM/VAP run; it does not explain how to capture one
- Tied to the PyTorch/vLLM and Perfetto ecosystem, not usable with other profilers
- Conclusion quality depends entirely on the bundled SQL presets and on how complete the trace is
Use it when you already have a PyTorch profiler or vLLM trace and need evidence-backed performance findings and an optimization report.
Avoid it when no trace has been collected yet, or when profiling a non-PyTorch runtime.
Security analysis
SafeSKILL.md is a documentation-oriented workflow for analyzing PyTorch/vLLM profiler traces using Perfetto SQL evidence. It contains no obfuscated payloads, destructive commands, secret exfiltration, or safety-disabling instructions. The only minor caveat is that it references an external runner.py and query presets whose contents are not shown.
- •No execution commands, network calls, credential access, or destructive actions are present in SKILL.md.
- •The skill references external files queries.yaml and runner.py, but those files are not included or invoked by the provided text; their behavior cannot be audited here.
Examples
Analyze the latest *-merged_trace.json from my vLLM run and tell me whether the bottleneck is in prefill or decode. Back every claim with Perfetto SQL evidence and give me an optimization report.Compare GPU kernel hotspots and idle gaps across ranks in this torch profiler trace — is there rank imbalance? Show the evidence table and separate confirmed findings from hypotheses.Run the trace overview queries on my merged trace, then look at synchronization waits and memory copies to explain why throughput dropped.name: torchprofiler-trace-analysis description: Analyze PyTorch profiler and vLLM trace files with Perfetto SQL evidence. Use when working with torch profiler traces, merged_trace files, vLLM profiling logs, Perfetto trace analysis, GPU kernel hotspots, synchronization waits, rank imbalance, prefill/decode bottlenecks, or optimization reports.
TorchProfiler Trace Analysis
Purpose
Use this skill to analyze PyTorch profiler traces from vLLM/VAP runs. Prefer evidence from Perfetto SQL and structured trace metadata over raw JSON snippets.
Attribution
This project is inspired by the evidence-driven workflow design of:
Gracker/Perfetto-Skills: standard Agent Skill structure, workflow routing, SQL-backed evidence, and report contracts.Gracker/SmartPerfetto: AI-assisted Perfetto analysis, evidence workflows, reports, and trace-processor-backed SQL analysis.
No code or SQL is copied from those projects. The SQL presets and workflows in this project are original and specialized for PyTorch profiler / vLLM traces.
Workflow
- Identify the latest or requested trace.
- Prefer merged traces named like
*-merged_trace.jsonor*-merged_trace.json.gz. - Run trace overview queries first.
- Collect evidence for:
- synchronization waits
- GPU kernel hotspots
- CPU operator hotspots
- rank imbalance
- memory copies
- prefill/decode spans
- idle gaps
- Summarize findings with evidence.
- Separate confirmed evidence from hypotheses.
- Recommend next inspections in Perfetto/TensorBoard.
Report Format
Use this structure:
# TorchProfiler Trace Report
## Executive Summary
Short summary of the most likely bottleneck.
## Trace Metadata
- Trace file:
- Merged trace:
- Event count:
- Time span:
- Ranks:
## Evidence
| Area | Evidence | Interpretation |
|---|---|---|
## Bottleneck Hypotheses
1. Hypothesis with supporting evidence.
## Perfetto Inspection Guide
- Tracks/events to inspect next.
## Optimization Suggestions
- Concrete model/config/benchmark changes to try.
## Evidence Gaps
- Missing data or uncertainty.
Safety
Do not infer causal conclusions from a query that only parsed successfully. Label uncertain conclusions as hypotheses. Do not request raw trace JSON unless a focused preview is necessary.
Utilities
- Query presets: queries.yaml
- Runner: runner.py
- Workflow details: WORKFLOWS.md
From the file to a first result
The download contains exactly the content displayed on this page. This copy may differ from the latest version in the source repository.
View the source and supporting filesThis download contains SKILL.md only. Any scripts, references, templates and dependencies are not included. Get the required files from the source, preserving their directory structure, before continuing.
1. Download the file
Download SKILL.mdFrom the root of a test project, save the file as .skill-downloads/torchprofiler-trace-analysis-mrwakfne/SKILL.md, or use the command below. This folder is for inspecting the skill before installation.
Command for macOS/Linux or WSL: requires a POSIX shell and curl. On Windows without WSL, use the download button and create the folder manually.
mkdir -p '.skill-downloads/torchprofiler-trace-analysis-mrwakfne' && curl --fail --show-error --location 'https://skills-guides.com/api/skills/torchprofiler-trace-analysis-mrwakfne/download' --output '.skill-downloads/torchprofiler-trace-analysis-mrwakfne/SKILL.md.part' && mv '.skill-downloads/torchprofiler-trace-analysis-mrwakfne/SKILL.md.part' '.skill-downloads/torchprofiler-trace-analysis-mrwakfne/SKILL.md'2. Check prerequisites
Read SKILL.md before using it. If it references scripts or external services, inspect them and prepare the required access in your test environment.
No recognized prerequisites section in this file. This does not mean it is self-contained: libraries, tools and access requirements may be mentioned elsewhere in the content or source repository.
The platforms on this page are catalog indications. The paths below follow tool documentation; they do not prove this skill has been run in those tools. No minimum tool version is confirmed for this listing.
3. Load the skill
After inspection, copy the complete folder into your project using one of the commands below, then open a new tool session. The command stops if a folder with the same name already exists: compare the files before replacing it.
Claude Code
test -f '.skill-downloads/torchprofiler-trace-analysis-mrwakfne/SKILL.md' && test -s '.skill-downloads/torchprofiler-trace-analysis-mrwakfne/SKILL.md' && mkdir -p '.claude/skills' && test ! -e '.claude/skills/torchprofiler-trace-analysis' && cp -R '.skill-downloads/torchprofiler-trace-analysis-mrwakfne' '.claude/skills/torchprofiler-trace-analysis'Cursor
test -f '.skill-downloads/torchprofiler-trace-analysis-mrwakfne/SKILL.md' && test -s '.skill-downloads/torchprofiler-trace-analysis-mrwakfne/SKILL.md' && mkdir -p '.cursor/skills' && test ! -e '.cursor/skills/torchprofiler-trace-analysis' && cp -R '.skill-downloads/torchprofiler-trace-analysis-mrwakfne' '.cursor/skills/torchprofiler-trace-analysis'Codex
test -f '.skill-downloads/torchprofiler-trace-analysis-mrwakfne/SKILL.md' && test -s '.skill-downloads/torchprofiler-trace-analysis-mrwakfne/SKILL.md' && mkdir -p '.agents/skills' && test ! -e '.agents/skills/torchprofiler-trace-analysis' && cp -R '.skill-downloads/torchprofiler-trace-analysis-mrwakfne' '.agents/skills/torchprofiler-trace-analysis'OpenSkills
OpenSkills must already be installed. The local install/read procedure is checked with OpenSkills 1.5.0, which requires Node.js ≥ 20.6.0. Catalog slugs are not resolved automatically.
Official OpenSkills installationopenskills install './.skill-downloads/torchprofiler-trace-analysis-mrwakfne'openskills read 'torchprofiler-trace-analysis-mrwakfne'Reading should display the installed file content and its base directory. It does not run the skill or install its dependencies.
For an agent that reads AGENTS.md, then sync the index. This command changes AGENTS.md: review the diff before using it.
openskills syncManual method or another tool: attach SKILL.md to a conversation, or open it in an agent that can read files. Include any required supporting resources. No universal folder is recognized by every tool.
4. Try a first task
Use a short, synthetic input: an API endpoint, a small document or an interface brief. In a new conversation, attach the file or give the agent its path, then adapt this request:
Read .skill-downloads/torchprofiler-trace-analysis-mrwakfne/SKILL.md and apply its instructions to this example: [describe a test input]. Identify any missing files, dependencies or access. Produce the result requested by the skill without inventing data or running unreviewed scripts.Expected result: output matching the skill instructions, or a precise list of missing prerequisites. A read confirmation alone does not validate a first use. If an external resource is unavailable, that path remains untested.
Create Interactive Maps with kepler.gl
Data & AI
Create interactive map visualizations and export standalone HTML using the keplergl Python package. Use to plot geospatial data from DataFrames, GeoJSON, or CSV.
Agent-Driven Parameter Optimization
Data & AI
Guide for optimizing configurable systems with a measurable objective, using bounded trials and evidence-based recommendations.
ICP Visitor Outreach
Data & AI
Identify signed-up users matching the ideal customer profile but stalled, and draft personalized outreach to re-engage them.