agentleFS
Sign inStart free
MohOneXMohOneX/claude-opus-skills/performance-profiling/SKILL.md

performance-profiling

Skill0 starsChanged 5 months agoMITView on GitHub

Diagnoses latency and throughput problems by measurement rather than intuition, locating true bottlenecks across CPU, memory, I/O, and contention. Use when a system is slow, p99 latency is bad, throughput plateaus under load, or before optimizing anything.

We split this skill into the rules it gives an agent

1 rule. 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 13 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Start with a flame graph / sampling profiler to find where wall-clock and CPU time actually go.

    line 18

“Common” is measured: kept by at least 6 in 10 of the 13 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Performance Profiling

Optimization without measurement is vandalism. The bottleneck is almost never where the experienced engineer guesses; commit to evidence before code.

Frame the question quantitatively

  1. Metric that matters: throughput, median, tail (p95/p99/p999), or cost-per-op? They optimize differently — tail latency is dominated by queuing and variance, not mean work.
  2. Workload: profile under representative load and data shape. Micro-benchmarks lie about cache behavior, branch prediction, and contention.
  3. Budget: define the target. "Faster" is not a goal; "p99 < 50ms at 5k rps" is.

Localize before optimizing

  • Start with a flame graph / sampling profiler to find where wall-clock and CPU time actually go. Distinguish on-CPU (compute) from off-CPU (blocked on lock/IO).
  • Apply Amdahl's law ruthlessly: optimizing a path that's 5% of runtime caps gains at 5%. Rank by time_share × tractability.
  • For tail latency, look for queuing and coordinated omission — the slow requests are waiting in line, not doing more work. Little's Law (L = λW) ties concurrency, arrival rate, and latency.

Layer-by-layer suspects

  • CPU-bound: algorithmic complexity, allocation churn/GC, cache misses, serialization, lock contention masquerading as CPU.
  • Memory-bound: working set vs cache size, false sharing, allocation rate, GC pause distribution.
  • I/O-bound: round-trip count (N+1), payload size, fsync/flush, connection pool saturation.
  • Contention-bound: lock hold time, thread pool starvation, head-of-line blocking.

Adversarial validation

  • Did the measurement change the result? (Observer effect from logging/instrumentation overhead.)
  • Is the speedup real under concurrency, or only single-threaded? Contention often inverts micro-wins.
  • Did you fix the symptom or the cause? A bigger cache may hide an O(n²) that explodes later.
  • Is the benchmark warm vs cold (JIT, page cache, connection warmup)? Production starts cold.

Non-obvious traps

  • Reducing mean latency can worsen the tail if it adds variance (e.g., batching).
  • Caching converts a latency problem into a consistency problem and a cold-start cliff.
  • Parallelism past the contention point reduces throughput (LMAX/USL retrograde region).

Output structure

Deliver: the measured baseline with the metric that matters, a ranked bottleneck list with time-share evidence (flame graph / counters), one change at a time with before/after under representative load, and the new limiting factor exposed by the fix.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free