Update Skia

Update Skia

Use this skill as the source of truth for both a developer-run update and the automated sync. The workflow only supplies resolved inputs, a prepared host, and automated PR delivery.

Skia C++ -> SkiaSharp C API -> generated P/Invoke -> managed wrappers

Run from the mono/SkiaSharp repository root. Each phase lives in a separate reference so only the current work enters context.

Start state

Automation exports the SKIA_SYNC_* variables below. A local run resolves them in Phase 01. Never replace supplied automation values with assumptions about main, skiasharp, or branch names.

SKIA_SYNC_AUTOMATION=1 selects the automation handoff in Phase 11. Without it, use the repository PR templates and normal developer pushes.

Initialize the artifact directory once:

ARTIFACT_DIR="${SKIA_SYNC_ARTIFACT_DIR:-${TMPDIR:-/tmp}/skia-sync-agent}"
mkdir -p "$ARTIFACT_DIR"

Definition of success

An update is complete only when:

• The authoritative old-upstream-to-target range was analyzed before merging.
• The mono/skia result is a genuine two-parent merge with every fork patch and dependency decision accounted for.
• The updated native source builds; downloaded old native artifacts were never substituted.
• Bindings were regenerated and every required managed wrapper was reviewed.
• The final unfiltered tests/SkiaSharp.Tests.Console.slnx run passes every host, including every GPU backend required by GpuPolicy on the validation host.
• The parent points to the exact tested mono/skia commit.
• Both PR descriptions identify untested platforms and are ready for human review.

Working rules

• Create feature branches in both repositories before changes; never commit to protected branches.
• Use a genuine two-parent merge in mono/skia; never use a tree-override merge.
• Preserve every fork patch unless upstream contains an equivalent or improved form.
• Mark a removed patch upstreamed only after enumerating every independent behavior in its old delta and locating each one in the target; one upstreamed hunk does not cover another lost hunk.
• Classify dependency revisions against the fork base, not only the prior upstream milestone.
• Treat final DEPS as ground truth: every enabled revision that differs from the fork base must have a matching final decision, exact-SHA evidence, and reconciled Component Governance metadata. A dependency recorded as preserved must still equal the fork-base revision.
• Let update_versions.py identify dependency changes from exact base/final DEPS. For every tracked changed dependency, and every legacy tracked registration missing verification evidence, derive the semantic version from checked-out source and complete the skia_dependency fields before the helper can pass. Never update a manifest version when its DEPS identity did not change.
• Components not sourced from Skia DEPS, including ANGLE and its dependencies, are updated in separate dependency PRs rather than bundled into a Skia upstream sync.
• Never use externals-download after a submodule/native/C API change.
• Never hand-edit *.generated.cs; regenerate it.
• Keep public managed ABI additive.
• A focused project test is diagnostic only; it never satisfies the final gate.
• GPU bring-up failures are test failures. The validation environment must provide every backend required by GpuPolicy for its platform.
• Diagnose failures from repository evidence. Do not add one-off compiler/GN flags, skip tests, weaken assertions, or encode milestone-specific answers to make one run green.
• Execute the update phases in this agent. Do not delegate the full update, or any mutating, build, test, or delivery phase, to a general-purpose/background agent. Only Phase 03's explicitly read-only discrepancy review may be delegated.
• Run long builds and full test suites in the foreground as one shell invocation. Do not use nohup, &, or agent-turn progress polling. If the shell tool keeps a command running, block on that existing session and inspect its output once after it exits.
• Keep complete logs and broad diffs in $ARTIFACT_DIR; inspect bounded excerpts instead of streaming large generated files, manifests, or successful build/test logs into model context.
• Do not create PRs, write automation handoff files, or report completion while any gate fails.
• In automation, no-work is handled before the agent starts. A started agent that cannot complete must fail rather than return success-shaped output.

Modes

CURRENT == TARGET means bug-fix behavior only when {UPSTREAM_REF} != main.

Phase router

Open the router's exact linked phase file once, complete its gate, then move to the next row. Do not glob for alternate phase names or reread an unchanged phase file.

Do not preload other phase files. The current phase file names any narrower reference section needed for that phase.

Deterministic helpers

• Automation stages this entire skill outside the mutable product checkout and exports its path as SKIA_SYNC_SKILL_DIR. After changing the product branch, continue reading phase references and running helpers from that staged directory rather than the branch-local .agents tree.
• scripts/update_versions.py updates and validates version surfaces, Skia hashes, and deterministic DEPS-to-Component-Governance identity/review signals.
• scripts/regenerate_bindings.py runs every binding configuration from the checked-out source and reports new native functions.
• scripts/audit_fork_patches.py compares the old and new fork deltas and fails while any added, removed, or changed patch lacks a final evidence-backed disposition.

These scripts are idempotent and are the source of truth for their phases. Do not manually recreate their behavior.

Additional references

• references/known-gotchas.md — read only the phase-specific sections directed by a phase file.
• references/breaking-changes-checklist.md — detailed Phase 2 audit checklist.
• references/validation-prompt.md — independent Phase 3 prompt.
• documentation/dev/dependencies.md — dependency and cgmanifest.json model.

Completion

Report the upstream ref/SHA, fork-patch and dependency decisions, C API/binding changes, exact build and per-host test results, both PR links, and unresolved cross-platform review. Do not merge either PR without explicit approval.