К основному содержанию
скилл CX Codex

ncu-trace — скилл для Claude Code: анализ NCU

Скилл ncu-trace для Claude Code собирает метрики NCU по раундам GPU-оценки. Он помогает агенту находить аппаратное узкое место по измерениям, а не по отчёту студента.

Apache-2.0 ★ 339 обновлён 2026-11-11

Установить в Claude Code · Вручную: положить файлы Все способы и платформы ↓
~/.claude/skills/ncu-trace/SKILL.md
Открыть на GitHub

Что делает ncu-trace

Скилл требует запускать профиль NCU в каждом раунде GPU-оценки, разбирать CSV через forgekernel.inner.ncu.profiler_from_ncu и записывать ключевые метрики в IterationRecord.profiler. Парсер выбирает самое медленное ядро по gpu__time_active.sum. Пустой профиль допустим, если проверка корректности завершилась сбоем или раунд сборки получил статус NEUTRAL до первого PASS.

Для сводки по раундам служит forge <op> ncu-report, а forge <op> ncu-trace показывает изменение метрик между итерациями. Так можно проверить, снизился ли spill после изменения, направленного на экономию регистров, или остались ли конфликты общей памяти после смены layout. Для сбора данных нужен GPU eval с задачей gpu_entry.sh ncu.

Какие задачи решает

  • сопоставить аппаратные метрики GPU между итерациями
  • определить, ограничивает ли ядро память, регистры или задержки
  • проверить, изменился ли целевой показатель после правки
  • отличить конфликты общей памяти от избыточного объёма wavefronts

Примеры запросов агенту

  • Покажи сводку NCU по раундам для <op>.
  • Сравни изменение метрик NCU после последней итерации для <op>.
  • Проверь, снизился ли spill после решения по сокращению регистров в <op>.

Как установить ncu-trace

Вручную: положить файлы

~/.claude/skills/ncu-trace/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/ncu-trace/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о ncu-trace

Как установить ncu-trace в Claude Code?

Скопируйте файл скилла в ~/.claude/skills/ncu-trace/SKILL.md.

Что делает ncu-trace?

Скилл записывает метрики NCU по раундам GPU-оценки и помогает определить аппаратное узкое место. ncu-report выдаёт сводку, а ncu-trace показывает динамику метрик.

Что нужно для работы ncu-trace?

Нужен GPU eval с задачей gpu_entry.sh ncu, которая собирает профиль NCU. Пустой профиль допустим после сбоя проверки корректности и в раунде сборки со статусом NEUTRAL до первого PASS.

Исходный текст

SKILL.md · Apache-2.0
# NCU-trace skill — let the meta agent see "how the performance metrics change" in hardware ground truth

> **Operator-agnostic.** Gives the meta agent a **cross-iteration evolution of NCU metrics**, so it judges the
> binding constraint from **measured hardware ground truth** instead of trusting the student's self-reported
> `binding_constraint` in its prose. Student prose turns "what wall it hit" into one sentence; behind the same
> sentence there may be a bank conflict, a register spill, or a memory-bound kernel — **only NCU can tell them apart**.

## Invariant: the student records NCU every round (no more `profiler={}`)

In every round's GPU eval the inner driver **must, besides correctness/perf, also run one NCU profile**
(the operator's `gpu_entry.sh ncu` task) and parse it with `forgekernel.inner.ncu.profiler_from_ncu(csv)` into a
compact key-metrics dict written to that round's `IterationRecord.profiler`. **Without this step the meta agent
can only aggregate student prose — the root cause of past diagnoses leaning too heavily on student signals.**

Two kinds of empty profiler are **expected** and are not missing data: correctness-broken rounds (the bench
crashed; NCU legitimately has nothing to collect); and build-phase `NEUTRAL` rounds (the whole machine has not
had its first PASS yet; under the build-phase semantics of POLICY §3 the driver skips the whole-machine eval
and defers verification to the gate row).

`profiler_from_ncu` automatically picks the **slowest kernel** (largest `gpu__time_active.sum`) as the bottleneck
kernel and keeps only the decision-relevant metrics (below).

## How to use it (the meta agent calls it directly)

```bash
forge <op> ncu-report       # a direct summary: one bottleneck verdict per round + key metrics tagged by severity
forge <op> ncu-trace        # the raw per-iteration metric evolution table (when you need to see how values change)
```

- **Look at `ncu-report` first**: it compresses dozens of NCU metrics into "one verdict per round (e.g. SMEM
  bank-conflict bound / register-spill / memory-bandwidth bound / latency bound) + a few key metrics tagged
  `severe`/`elevated`". This is the layer that lets you **see the key parts directly without studying thresholds**.
- When you need to see **how values move across iterations** (whether a decision really moved the metric it was
  supposed to move), then look at the raw `ncu-trace` table.
- You can also read `profiler[]` in `operators/<op>/student/digest.json` (same source, includes KEEP and REVERT,
  tagged with the verdict).

## Decision-relevant metrics → diagnostic meaning

| Column | Meaning | A high value means |
|----|------|-----------|
| `bankconf_st` / `bankconf_ld` | shared-mem store/load bank conflicts | **A degenerate / conflicting smem layout.** If the milestone names a "conflict-free" decision but this value is still large ⇒ the student delivered a **degenerate fallback** (knows what to do, cannot use that hardware interface) → **G3: add an hw_kb recipe, do not change the milestone** |
| `smem_wavefronts_st` / `smem_wavefronts_ld` | shared-mem store/load wavefront **volume** (≠ conflicts) | No absolute threshold; **only comparable against the reference signature**: a total far above the reference ⇒ a **scalar / per-element access path** (wrong copy atom, not a swizzle problem — conflicts can be zero while the volume tax is still paid, and the read side in particular is invisible to every conflict metric). The fix = change the atom (STSM/LDSM/direct descriptor reads): G1/R1 pointing at the milestone's path contract, **not** a G3 swizzle tweak |
| `spill_st_sectors` / `spill_ld_sectors` | local-mem store/load (= register spill traffic) | **Register pressure.** Read together with `regs_per_thread`; if a foundation choice pins the footprint above the spill cliff and the in-phase levers are exhausted ⇒ **R1 foundation ceiling** |
| `regs_per_thread` | registers per thread | near the limit + high spill = register-limited |
| `tensor_pct` | tensor-pipe active share | low = the tensor cores are not fed (a latency/scheduling problem, not a compute problem) |
| `warp_active_pct` | warp activity | low = latency-limited (held back by stalls) |
| `stall_long_sb` | long-scoreboard stall | ⚠ **In an mbarrier-pipelined kernel this bucket is dominated by mbarrier/TMA spin-waits (NANOSLEEP)** (measured: almost all NANOSLEEP samples land here), not "waiting for DRAM" — optimizing for memory latency goes the wrong way; the real memory-access criterion is `dram_pct` and spill |
| `stall_barrier` | barrier stall | **In a WGMMA kernel the bulk is `wgmma wait_group` waiting** (the vast majority of DEPBAR waits land here) + named barriers — read it as a "wait depth / overlap quality" signal, not only as CTA synchronization imbalance |
| `stall_mio` | MIO throttle (smem / special function units) | high = congestion on the smem path or the SFU |
| `dram_pct` | DRAM throughput as a share of peak | high = memory-bound; low = not a bandwidth problem |

## How to read "the course of change" (this is where the skill earns its keep)

Do not look at single points; look at **whether, after a decision lands, the metric it was supposed to move actually moved**:

- After an M5 decision that claims "drop a fragment to reduce spill" lands, if `spill_*` / `regs_per_thread`
  **did not go down** ⇒ that lever does not bind: spill is not the current real bottleneck, or this cut is below the cliff.
- After a decision that claims a "conflict-free layout" lands, if `bankconf_*` **is still large** ⇒ the student did
  not produce the conflict-free version (degenerate fallback) ⇒ **G3 / KB**, not a milestone defect.
- The whole perf curve is flat while `bankconf_st` and `spill_*` are **both** high ⇒ do not conclude from one number:
  when two real bottlenecks coexist, fix the **more foundational / cheaper** one first (foundation first), and use the
  next round's NCU to verify it really lowered the corresponding metric.

## Hard rules

- **NCU first, student prose second**: the self-reported `binding_constraint` is only a "navigation hypothesis";
  load-bearing conclusions must be confirmed by NCU metrics (matching the evidence binding in `meta_milestone.md` /
  `diagnose_prompt.md`).
- **Metrics are cited only from the trace/digest**: do not assume from memory what bottleneck an operator "should"
  have (operator-agnostic L1).
- **Missing NCU data**: if a round's `profiler` is empty, the trace skips it; in the diagnosis say "this round has no
  hardware ground truth; the conclusion is downgraded to a prose inference" — do not pretend to have evidence.

© OpenBMB · Apache-2.0 · OpenBMB/ForgeKernel

Похожие скиллы

Каталог скиллов SKILL.md →
dotnet-trace-collect dotnet Скилл dotnet-trace-collect помогает выбрать диагностические утилиты и собрать трейсы для разбора сбоев производительности .NET на Windows, Linux и в контейнерах. CX Codex +1 4 900установок browser-trace browserbase Скилл browser-trace цепляет второй CDP-клиент к уже идущей браузерной сессии и пишет весь поток событий DevTools в файлы, чтобы потом разобрать упавший прогон. CX Codex +1 3 100установок trace-to-training-data Seth Hobson Скилл trace-to-training-data для Claude Code преобразует размеченные трейсы и логи в примеры SFT и пары DPO. Превращает собранные оценки запусков в датасет. CX Codex +1 2 600установок break-trace официальный anthropics Скилл break-trace прослеживает расхождение в сверке до исходной проводки и объясняет причину. Пригодится после классификации расхождения в gl-recon. CX Codex +1 1 300установок arize-trace официальный arize Скилл arize-trace для GitHub Copilot экспортирует трейсы и спаны Arize по ID и разбирает ошибки и поведение LLM-приложения. CX Codex +1 1 100установок analyzing-mlflow-trace mlflow Скилл analyzing-mlflow-trace разбирает один трейс MLflow по его ID: находит ошибки, объясняет поведение и указывает, где именно всё сломалось. CX Codex +1 1 000установок

Из того же набора8

job-env-check Скилл job-env-check для Claude Code проверяет доступность PyTorch в базовом интерпретаторе python3 перед запуском вспомогательных скриптов задачи. Тест выполняется на старте каждого цикла вычислений на GPU-хосте. CX Codex +1 ★ 339звёзд репо stall Скилл stall для Claude Code разбирает счётчики простоев из профиля .ncu-rep и связывает их с инструкциями SASS. Он помогает найти участки кода, на которых теряются такты GPU. CX Codex +1 ★ 339звёзд репо orchestration Скилл orchestration для Claude Code разбирает топологию синхронизации и подачу данных по странице SASS. Он связывает простои tensor pipe с ролями участков ядра. CX Codex +1 ★ 339звёзд репо timeline Скилл timeline для Claude Code показывает, на каких этапах GPU-ядро тратит время. Он строит временные ряды из .ncu-rep и считает циклы по сегментам ядра. CX Codex +1 ★ 339звёзд репо lever-pricing Скилл lever-pricing для Claude Code измеряет вклад оптимизаций в GPU-ядро. Он сравнивает рычаги по отдельности, в полном наборе и после удаления из него. CX Codex +1 ★ 339звёзд репо sass Анализирует SASS-код GPU-ядер по данным профилирования. Он разбирает дампы и проверяет инструкции, планирование и параметры запуска. CX Codex +1 ★ 339звёзд репо forge-start Скилл forge-start для Claude Code настраивает и запускает оптимизацию оператора в ForgeKernel. Запускается по просьбе начать или продолжить такую оптимизацию. CX Codex +1 ★ 339звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой