Intel Performance Skills

---
name: linux-perf
description: >-
  Profile and fix Linux performance problems using `perf`. Workflows: (A) hardware counters -- IPC, cache-miss, branch mispredictions; (B) hotspot profiling -- which functions and source lines consume CPU, with SIMD and accumulator detection; (C) cache-line contention -- false sharing, HITM, `perf c2c`; (D) core-count scaling -- dual-profile comparison, bottleneck categorization; (E) structured hotspot report with annotated source and pattern observations. Resolution strategies: TTAS spinlock, SIMD upconversion, parallel accumulator, structured false-sharing fix, per-CPU stats. Trigger on: perf, profiling, profile, hotspot, hotspots, cache miss, IPC, false sharing, HITM, scaling, core count, thread scaling, bottleneck, slow code, CPU bound, why is this slow, where does time go, does not scale. When in doubt, invoke this skill -- better to use it unnecessarily than to miss a performance opportunity.
---

<!-- (C) 2026 Intel Corporation, MIT license -->


# Linux perf profiling skill

Guide the user through profiling with Linux `perf` — from setup and data collection through reporting and interpretation.

The skill is organized into five parts:
- **Part 1: Setup** — permissions and build flags (always check these first)
- **Part 2: Flows** — end-to-end workflows (A: quick stats, B: hotspot profiling, C: cache contention)
- **Part 3: Cross-skill integrations** and **Reference** — when to delegate, and quick lookup tables
- **Part 4: Building blocks** — focused data collection primitives that flows and other skills can call directly
- **Part 5: Resolution strategies** — common fix patterns that flows can reference by name

---

# Part 1: setup

## Check permissions (always do this first)

```bash
cat /proc/sys/kernel/perf_event_paranoid
```

- **≤ 1**: no `sudo` needed for most data collection
- **2 or higher**: hardware events (cycles, cache-misses, etc.) require root

To lower the limit (ask the user first):
```bash
echo 0 | sudo tee /proc/sys/kernel/perf_event_paranoid
```

**Sudo protocol**: if `sudo` is needed, present these options and wait for the user's answer before proceeding:
1. Run with `sudo`
2. Lower paranoia level with the command above
3. Skip perf collection

## Ensure debug symbols

**Always compile with `-g`** alongside existing optimization flags (e.g. `-O2 -g`). This adds DWARF debug info so `perf report` and `perf annotate` show function names and source lines — it does not weaken optimization.

If given a pre-built binary without `-g`, offer to recompile. If you cannot, use **Building block: resolve address to source** (Part 4) for address correlation.

```bash