| name | skore-cpu-profiler |
| description | Add targeted CPU profiler markers, run perf scenes, analyze marker timings, and optionally remove temporary markers. |
skore-cpu-profiler
Use when the user asks why a subsystem is slow or asks to profile CPU cost. Marker placement requires reading the code; do not try to automate insertion blindly.
Workflow
- Identify the renderer:
gl, dx11, or dx12.
- Find the parent profiler marker with
rg "PROFILE_(BEGIN|SCOPED)" SkullbonezSource.
- Read the code under that parent marker and its immediate callees.
- Insert 4-8 meaningful temporary sub-markers using sentinel comments.
- Run a before perf sample.
- Analyze with
analyze_markers.py.
- Apply the fix if authorized.
- Run an after perf sample and compare.
- Ask whether to remove temporary markers.
Sentinel Format
PROFILE_SCOPED( "Frame/Render/Balls/DrawCalls" );
Use unique IDs (pm001, pm002, etc.). Record them in:
Agentic/Skills/skore-cpu-profiler/session_markers.json
Minimal session shape:
{
"concern": "balls render slowly",
"renderer": "dx12",
"area_path": "Frame/Render/Balls",
"added_markers": [
{
"id": "pm001",
"file": "SkullbonezSource/SkullbonezRun.cpp",
"marker": "Frame/Render/Balls/DrawCalls",
"macro": "PROFILE_SCOPED"
}
]
}
Run Perf Sample
$renderer = "dx12"
$args = if ($renderer -eq "gl") {
"--vsync off --fixed-step --scene SkullbonezData/scenes/perf_test.scene.json"
} else {
"--renderer $renderer --vsync off --fixed-step --scene SkullbonezData/scenes/perf_test.scene.json"
}
$proc = Start-Process "Profile\SKULLBONEZ_CORE.exe" -ArgumentList $args -WorkingDirectory . -PassThru
$proc.WaitForExit(120000) | Out-Null
Move Profile\perf_log.csv to a before/after name before running the next sample.
Analyze
py Agentic\Skills\skore-cpu-profiler\analyze_markers.py --csv Profile\perf_before_dx12.csv --area Frame/Render/Balls --session Agentic\Skills\skore-cpu-profiler\session_markers.json --slot before
py Agentic\Skills\skore-cpu-profiler\analyze_markers.py --csv Profile\perf_after_dx12.csv --area Frame/Render/Balls --session Agentic\Skills\skore-cpu-profiler\session_markers.json --slot after
Report the hottest sub-marker, its source location, average time, p99, and share of the parent marker.
Cleanup
Only remove markers that were recorded in the session file:
py Agentic\Skills\skore-cpu-profiler\cleanup_markers.py --session Agentic\Skills\skore-cpu-profiler\session_markers.json --delete-session
tools\validate_build.bat Profile
If markers are intentionally kept, delete session_markers.json and state that the markers are now permanent profiler coverage.
