API Docs

Documents

api-docs

API Docs is an Agent Skill for documents published in the mono/SkiaSharp repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Write AND review XML API documentation for SkiaSharp (ECMA/mdoc XML in the docs submodule). Two modes: (1) ADD docs for new APIs with "To be added." placeholders; (2) REVIEW existing docs by scope for accuracy, freshness, examples, and hygiene. Triggers: "document class", "add XML docs", "write XML documentation", "fill in missing docs", "remove To be added placeholders", "review documentation", "check docs for errors", "fix doc issues", "audit the docs", "review the font docs", "are the examples correct", "update out-of-date docs", any request to add, validate, correct, or expand SkiaSharp API documentation.

View on GitHub ↗

QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

Open your project in Codex.
Copy and paste the prompt below.
Review files and risks before approving any action.

Prompt to paste

Inspect the Agent Skill at https://github.com/mono/SkiaSharp/blob/HEAD/.agents/skills/api-docs/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/api-docs, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

API Documentation

Add and review SkiaSharp API documentation. This file is a router: it picks a procedure and points to the reference and tooling files that do the work. The detailed instructions live in references/ so they load only when needed.

Key facts

docs/ is the mono/SkiaSharp-API-docs submodule — one ECMA/mdoc .xml per type, generated from NuGet assemblies via mdoc. CDATA <remarks> may hold csharp code fences. Run git submodule update --init docs if it is empty.
Each <Type>.xml maps 1:1 to binding/SkiaSharp/<Type>.cs (or binding/HarfBuzzSharp/) → always read source before documenting.
Edit the XML directly. Safety comes from docs-format-docs, which formats every file and fails the build on broken XML/CDATA (references/validation.md).
Never edit generated files: index.xml, ns-*.xml, _filter.xml, FrameworksIndex/.

How to work

One agent does the whole pass. Read the relevant reference, resolve scope into an explicit file list, then work in batches of ~25–40 files so each pass stays auditable and resumable.

If the task is…	Read
Documenting new APIs / filling `To be added.` placeholders	`references/adding.md`
Reviewing/correcting/expanding existing docs (one type, a theme, what changed, or all)	`references/reviewing.md`

The user asks in plain language ("review the font docs", "fill in what's missing"). The docs live at docs/SkiaSharpAPI/<Namespace>/<Type>.xml; list them directly, and use git -C docs diff --name-only origin/main...HEAD for "what changed". Each <Type>.xml maps to its source at binding/<Namespace>/<Type>.cs, and you pick the files a request covers — for a theme, scan the list and select the matching types yourself; the chosen procedure file covers the rest.

All findings use one machine-parseable contract: SEVERITY | class | file | docId | message.

References (canonical facts)

references/patterns.md — .NET XML doc syntax, verb conventions, formatting.
references/skia-patterns.md — domain facts (color layouts, struct defaults, standard-based enums, caller-owned vs parent-owned).
references/checklist.md — CRITICAL/IMPORTANT/MINOR severity taxonomy.
references/obsolete-api-map.md — obsolete members and their modern replacements; the writer and example reviewer read it (not the linter — obsolete use is a model judgement, see the reference for why).

DRY rule: the procedures describe what to do; the reference tables hold the facts. Procedures point to references — they must not restate the tables. Keep reference chains one level deep.

Tooling & validation

Format + checks (one Cake target in scripts/infra/docs/docs.cake): docs-format-docs formats every type file and runs the deterministic content checks — warnings for missing/quality issues, build-failing errors for broken XML/CDATA. See references/validation.md.
Snippet build (C#-only, download is fine): dotnet cake --target=externals-download then dotnet build binding/SkiaSharp/SkiaSharp.csproj.

Landing changes

The docs submodule protects main — commit on a dev/... branch and open a PR (per-wave). Skill asset changes land in the parent mono/SkiaSharp repo; the auto-api-docs-writer agentic workflow that runs this skill on CI lives in mono/SkiaSharp-API-docs.