Skip to content
Skills Library
Programming · Analysis

performance-profiling

/performance-profiling

Find where the time actually goes before changing anything — define the metric and workload, build a repeatable baseline with its spread, profile on the right axis, confirm the suspected hotspot by removing its work, then re-measure under identical conditions. Use when something is slow, when an optimization is about to be written from a hunch, or when a speedup is being claimed without comparable numbers. Not for reading code to guess what is expensive, not for micro-tuning with no measured user impact, and not a licence to profile production without asking.

Licence
MIT
Last repository change
29.09.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 29.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Find where the time actually goes before changing anything — define the metric and workload, build a repeatable baseline with its spread, profile on the right axis, confirm the suspected hotspot by removing its work, then re-measure under identical conditions. Use when something is slow, when an optimization is about to be written from a hunch, or when a speedup is being claimed without comparable numbers. Not for reading code to guess what is expensive, not for micro-tuning with no measured user impact, and not a licence to profile production without asking.

Original author description

Find where the time actually goes before changing anything — define the metric and workload, build a repeatable baseline with its spread, profile on the right axis, confirm the suspected hotspot by removing its work, then re-measure under identical conditions. Use when something is slow, when an optimization is about to be written from a hunch, or when a speedup is being claimed without comparable numbers. Not for reading code to guess what is expensive, not for micro-tuning with no measured user impact, and not a licence to profile production without asking.

How it works

  1. When this fires
  2. Procedure
  3. The plausible-but-wrong hotspot
  4. Checklist
  5. Failure handling
  6. Evidence to report
Original SKILL.md headings · 100 lines, 1,082 words
SKILL.md preview
---
name: performance-profiling
description: Find where the time actually goes before changing anything — define the metric and workload, build a repeatable baseline with its spread, profile on the right axis, confirm the suspected hotspot by removing its work, then re-measure under identical conditions. Use when something is slow, when an optimization is about to be written from a hunch, or when a speedup is being claimed without comparable numbers. Not for reading code to guess what is expensive, not for micro-tuning with no measured user impact, and not a licence to profile production without asking.
---

# Performance profiling

The function that looks expensive and the function that is expensive are two different populations
with a modest overlap. Every optimization written before a profile is a guess with a diff attached.

## When this fires

- Something is measurably slow, or a latency, memory or throughput target is being missed.
- An optimization is about to be written on the strength of how the code reads.
- A speedup is being reported without a baseline, a spread, or comparable conditions.

It does not fire for correctness work, and it does not fire for a change whose only justification
is that a faster construct exists — a faster loop inside 2% of the runtime is not an improvement,
it is churn.

## Procedure

1. **Define the metric and the workload.** "Slow" is not a metric. Pick one: p95 latency of this
   request under this load, peak resident memory, time to first byte, wall-clock of this job,
   rows per second. Say which environment, which data, and what would count as good enough.
2. **Reproduce the slowness in a harness you can run repeatedly**, with representative data.
   Toy input profiles a different program: an N+1 query is invisible at ten rows, and a quadratic
   scan is free at n=12.
3. **Establish the baseline properly.** Run it several times and record every run, not the best
   one. Report the median and the spread. If the spread is wider than the improvement you are
   chasing, the harness is not ready and nothing measured on it will be believable.
4. **Profile rather than guess, on the axis that matches the metric.** Wall-clock sampling for
   "it takes too long", a CPU profile for compute, an allocation or heap profile for memory, the
   browser's performance trace for rendering and main-thread work, the database's own query plan
   for a slow query, distributed traces for a request crossing services. Use whatever the runtime
   ships; name the tool you used in the report.
5. **Read the profile carefully before believing it.** Separate self time from inclusive time — a
   frame near the top of the list may be cheap itself and merely called by everything. Check
   whether the time is spent computing or waiting: a CPU profile of an I/O-bound program shows an
   idle program, and chasing its top frame is the single most common wrong turn here.
6. **Confirm the hotspot before optimizing it.** Delete, stub or short-circuit the suspected work
   in a scratch copy and re-measure. If the total does not move, it was not the bottleneck however
   bad the code looked. This experiment costs minutes and prevents days.
7. **Ask whether the work can be avoided before making it faster.** Fewer round trips, less data
   fetched, computed once instead of per item, the right index, the result cached at a layer where
   invalidation is tractable. The cheapest optimization is the work that no longer happens.
8. **Change one thing.** Two changes measured together give you one number and no attribution.
9. **Re-measure under identical conditions** — same machine, data, build configuration, warm or
   cold state, same number of runs. A release build against a debug baseline is not a result.
10. **Check correctness alongside speed.** Caching, concurrency, laziness and batching all change
    semantics. Run the test suite and state the new invariants someone now has to maintain:
    invalidation, ordering, memory ceiling, error handling under partial failure.
11. **Report absolutes with their spread**, name the fraction attributable to the change, and say
    what the bottleneck is now. Then remove the harness, or promote it deliberately to a
    repeatable benchmark that someone owns.

## The plausible-but-wrong hotspot

- **The nested loop over a list of twelve.** It reads badly and costs nothing.
- **The frame with the most samples that is merely popular.** Inclusive time is not self time.
- **A debug build, or profiler overhead.** Instrumentation distorts small hot functions most;
  cross-check a sampling profile against plain wall-clock timing of the whole workload.
- **The first run.** Cold caches, JIT warm-up, connection pools and lazy imports are paid once.
  Decide whether the metric is the cold path or the warm one, then measure that one consistently.
- **The micro-benchmark the compiler optimized away.** A result nobody consumes may never be
  computed; a number too good to be true usually is.
- **The environment that is not the user's.** A local SSD and a loopback network hide precisely
  the I/O and latency costs that make production slow.

## Checklist

- [ ] Metric, workload and environment written down before measuring
- [ ] Baseline taken from multiple runs, all recorded, with spread
- [ ] A profile was taken, on an axis that matches the metric
- [ ] Self time and inclusive time distinguished; compute separated from waiting
- [ ] The hotspot was confirmed by removing its work and re-measuring
- [ ] One change at a time
- [ ] After-measurement under identical conditions
- [ ] Correctness re-checked and new invariants named
- [ ] Remaining bottleneck stated

## Failure handling

- **No profiler for this runtime** — bracket timers around segments and bisect the region by
  halving, the same way you would isolate a bug. Say plainly that the attribution is coarse.
- **The difference is inside the noise** — report the change as unproven. A percentage quoted from
  two single runs is noise with a decimal point.
- **It only reproduces in production** — do not attach a profiler to production on your own
  judgement. Profiling costs overhead and can take load; stop and ask, and prefer a staging replay,
  a captured trace, or existing telemetry.
- **The bottleneck is in a dependency or in infrastructure** — report it with the evidence. Do not
  rewrite a library or resize infrastructure on a hunch.
- **The improvement requires a destructive or outward-facing step to validate** — a schema
  migration, a cache flush, a config change on a shared environment. Stop and ask; measure against
  a local or branch copy first.

## Evidence to report

The metric and workload; the harness command; machine, data and build configuration; every
baseline run, not the best one; the profile itself — top frames, query plan or trace — and how it
was taken; the confirmation experiment; the after-numbers under the same conditions with spread;
the correctness run; and the bottleneck that is now next. Measured, optimized and verified are
three different claims: "2x faster" with none of the above is a fourth one, which is a guess.
Files in this package (2)
  • SKILL.md 7 KB
  • manifest.json 1 KB

Versions

RepositoryScoreLicence
This page · nahid-sparktales/agent-dispatcher90MIT
akillness/jeo-skills100MIT
MengTo/Skills100MIT
Reprograme/redevkit100MIT
HeshamFS/materials-simulation-skills100Apache-2.0
charierefiedler/ronce-racine100MIT
Gattic/GatPi-Harness100MIT
reddygopalkrishna/developer-agent-skills100MIT
jeffersonvalente/cardume100MIT

Database snapshot: 13.11.2026 · package version a4f608131c7b (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95performance-investigation
    Measure, diagnose, and fix performance problems with evidence instead of code reading. Use when something is slow, a latency, throughput, memory, startup, render, or query time regressed, a user asks to "make it faster", "speed this up", "why is this slow", "profile this", or…
  • 100performance-pass
    Fixes measured slowness by setting a budget, profiling to find where time actually goes, changing one thing, and measuring again. Use for a latency regression, an N+1 query, memory growth, a slow build or test suite, or a Core Web Vitals miss. Refuses to optimize anything without a baseline number.
  • 100python-performance-optimization
    Measure first with cProfile, line_profiler, memory_profiler or py-spy, then fix what the numbers show. TRIGGER WHEN: debugging slow Python code, optimizing bottlenecks, cutting memory usage, or improving application performance.
  • 90profile-first
    Measures where a program's time really goes before anything is sped up. Profiles a production-sized input in fresh processes, splits out import time and I/O wait, confirms each hot spot by stubbing it out and timing the whole run, and allows no "done" until a re-profile shows…
  • 85performance-engineering
    Model a workload's cost, profile it, and prove claimed speedups. Use when something is too slow or allocation-heavy, when a workload's cost must be modeled, or when a claimed speedup needs proof.
  • 100windsurf-performance-profiling
    Profile and optimize code with AI-assisted analysis. Activate when users mention "performance profiling", "optimize performance", "bottleneck analysis", "profiling", or "performance tuning". Handles performance analysis and optimization. Use when working with windsurf…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.