Add performance-fixer skill + make the benchmark harness AI-ready

[mattleibow]

What

Adds a performance-fixer skill — a periodic AI scanner that finds a hot-path performance opportunity in the managed C# binding, proves it, fixes it (managed-only, ABI-safe), and opens a linked issue + draft PR — plus source changes that make the benchmark harness easy for that skill (and humans) to write and run benchmarks against.

Modelled on the existing memory-leak-fixer skill and on a colleague's optimize-aspnetcore-performance skill, and grounded in our real perf PRs:

PR	Win	Lesson encoded
#4241	SKMatrix native→managed, up to 24×	bit-exact port + the x86/x87 native fallback
#4345	SKColor alloc-free parse, 1.4–2.3×	span parser + additive ReadOnlySpan overload
#4247	SKSurface.Canvas caching	cache a stable native wrapper (4 preconditions)

The defining discipline: two proofs

Unlike a generic perf pass, every fix must be shown faster (a BenchmarkDotNet New vs Old measurement) and behaviour-identical (an equivalence test — bit-exact vs SkiaApi.sk_* for numeric ports). A faster answer that differs from Skia is a rendering regression, not a win. The skill also hard-codes the traps we learned the hard way: the x87 float-determinism fallback, the ARM64 Vector256 5.7–6.5× regression, benchmark statistical rigor, and full behaviour parity (exceptions / ownership / GC.KeepAlive / rendered pixels).

Structure

References are split by area (the aspnetcore pattern): hot-paths/ (SkiaSharp code areas) + bcl-patterns/ (.NET techniques), plus decision-framework.md (impact×complexity rubric), measuring.md, signals.md (detection routing), and repo-helpers.md. A lean router SKILL.md ties them together.

.agents/skills/performance-fixer/
├── SKILL.md
└── references/
    ├── decision-framework.md · measuring.md · signals.md · repo-helpers.md
    ├── hot-paths/     geometry-math · color · handles-and-collections · text-and-fonts · pixels-and-images
    └── bcl-patterns/  strings-and-spans · numerics-and-simd · memory-and-buffers · collections · interop-and-marshalling

A gh-aw workflow (.github/workflows/performance-fixer.md) runs the skill on a schedule (every 12h, dry-run on PR, focus-area knob), compiled to .lock.yml.

Benchmark harness: ready in the source

So a skill run never wastes time repairing infra:

• Replaced TheBenchmark.cs → TemplateBenchmark.cs. The old template was a trap: [SimpleJob(Net48/Net70/Net80)] silently skips on macOS/Linux (verified) and its empty bodies taught none of the conventions. The new one is a working New vs Old + [MemoryDiagnoser] + [Params] + return-sink skeleton that runs out of the box (verified: Old 88/1048 B → New 0 B).
• Added benchmarks/README.md — the on-ramp: how to add/run a benchmark, --list flat for discovery and --job short for fast iteration, the single-TFM warning, the New-vs-Old + sink conventions, and the InternalsVisibleTo native-oracle note.

Labels

Every finding is labelled tenet/performance (the quality-tenet umbrella) plus one agent-chosen perf/* sub-type, decided by the win's dominant measured driver (a removed P/Invoke → perf/interop, removed managed allocations → perf/allocations, etc.). This aligns to the canonical taxonomy in .agents/skills/issue-triage/references/labels.md (#4362) and matches the memory-leak-fixer convention, so agentic perf findings triage the same way as human-filed ones.

Verification

• Skill passes quick_validate; all cross-reference links resolve; the gh-aw workflow compiles with 0 errors / 0 warnings.
• Smoke-tested the harness end-to-end: externals-download → built the benchmark project → ran SKColorParseBenchmark's full New-vs-Old comparison and the new TemplateBenchmark (clean, Ratio/Allocated populated).
• Two GPT-5.5 review passes drove fixes (x87 fallback, benchmark rigor, StringUtilities vs Utils naming, TFM guards).

Validated end to end on real CI

The workflow self-tests on any PR touching the skill via a forced dry-run. Those runs demonstrated the full range of correct behaviour:

• Correctly rejected a non-finding — SKFourByteTag.Parse's char[4] is already stack-allocated by .NET 9/10 escape analysis, so it emitted a noop rather than a bogus "removes per-frame allocation" PR.
• Found real, fully-proven wins — SKShaper.Shape throwaway glyph-array extraction (~30% faster, 55–71% fewer allocations → perf/allocations) and the SKColor→SKColorF operator P/Invoke (→ perf/interop), each with a New-vs-Old benchmark run twice and a mutation-checked bit-exact equivalence test.
• A real dispatch run created correctly-labelled artifacts — issue [performance] Port SKColor -> SKColorF conversion from native P/Invoke to managed C# #4369 and draft PR [performance] Port SKColor -> SKColorF conversion to managed C# #4370 (the SKColor→SKColorF port), both carrying tenet/performance + perf/interop, confirming the labels land on the issue and the PR.

Notes

• Pure additive: a new skill, a new workflow, benchmark docs/template, and two rows in AGENTS.md. No binding/runtime code changes.
• The skill is intentionally an autonomous scanner, not an interactive review assistant (a findings-DB / snippets subsystem would be over-engineering here) — happy to add a lightweight interactive review mode if wanted.
• [performance] Port SKColor -> SKColorF conversion from native P/Invoke to managed C# #4369 / [performance] Port SKColor -> SKColorF conversion to managed C# #4370 are demonstration artifacts from the validation run above; they can be closed or kept (the SKColor→SKColorF port is a legitimate optimization).

Co-authored-by: Copilot App 223556219+Copilot@users.noreply.github.com

[github-actions]

📦 Try the packages from this PR

Warning

Do not run these scripts without first reviewing the code in this PR.

Step 1 — Download the packages

bash / macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/mono/SkiaSharp/main/scripts/get-skiasharp-pr.sh | bash -s -- 4361

PowerShell / Windows:

iex "& { $(irm https://raw.githubusercontent.com/mono/SkiaSharp/main/scripts/get-skiasharp-pr.ps1) } 4361"

Step 2 — Add the local NuGet source

dotnet nuget add source ~/.skiasharp/hives/pr-4361/packages --name skiasharp-pr-4361

More options

Option	Description
--successful-only / -SuccessfulOnly	Only use successful builds
--force / -Force	Overwrite previously downloaded packages
--list / -List	List available artifacts without downloading
--build-id ID / -BuildId ID	Download from a specific build

Or download manually from Azure Pipelines — look for the nuget artifact on the build for this PR.

Remove the source when you're done:

dotnet nuget remove source skiasharp-pr-4361

[github-actions]

📖 Documentation Preview

The documentation for this PR has been deployed and is available at:

🔗 View Staging Site
🔗 View Staging Docs
🔗 View Staging Gallery (Blazor)
🔗 View Staging Gallery (Uno Platform)
🔗 View Staging SkiaFiddle

This preview will be updated automatically when you push new commits to this PR.

---

This comment is automatically updated by the documentation staging workflow.