sample-scout

Sample Scout

You analyze Skia GM (golden master) sample files from the externals/skia submodule to discover demos worth porting to the SkiaSharp Gallery. The goal is to find visually impressive, educationally valuable samples that showcase SkiaSharp's capabilities — and identify which ones we can build today vs. which need new APIs first.

Why This Matters

Skia has 400+ GM samples that exercise every API and visual technique. These are a goldmine for the SkiaSharp Gallery — each one is a proven, tested visual that demonstrates something users would want to learn. But nobody can manually review 400+ C++ files to find the gems. This skill automates the discovery.

Key References

• references/analysis-instructions.md — How to classify samples
• references/sample-scout-schema.json — JSON Schema for validation
• references/schema-cheatsheet.md — Human-readable schema docs

Workflow

Phase 1: Setup (list GM files, list existing Gallery samples)
Phase 2: Analyze GM files (parallel agents, each handles a chunk)
Phase 3: Cross-reference with existing Gallery samples
Phase 4: Validate and render
Phase 5: Present results

Phase 1: Setup

1a. Ensure the submodule is checked out

The GM files live in externals/skia/gm/. If the submodule isn't initialized:

git submodule update --init --depth=1 externals/skia

1b. List all GM files

ls externals/skia/gm/*.cpp | xargs -n1 basename | sort > gm-files.txt
wc -l < gm-files.txt

1c. List existing Gallery samples

find samples/Gallery -name "*.cs" -path "*/Samples/*" | sort

For each sample, extract the Title, Description, and Category to build a coverage map.

1d. Split into chunks for parallel processing

With 400+ files, split into 5 chunks of ~80-90 files each for parallel analysis.

Phase 2: Analyze GM Files

Launch 5 parallel background agents (general-purpose), each analyzing one chunk. Each agent:

1. For each .cpp file in its chunk, read it directly from the submodule:

   cat externals/skia/gm/{filename}
   

2. Read the file and extract:

   • What it demonstrates (1-2 sentences)
   • Key Skia APIs used (class::method names)
   • Interest level: high / medium / low
   • API availability: check if the required APIs exist in SkiaSharp by grepping binding/SkiaSharp/
   • Missing APIs: list any APIs not available in SkiaSharp
   • Notes: GPU-only, Graphite-specific, bug regression, etc.

3. Save findings as JSON array to a temp file.

See references/analysis-instructions.md for the classification criteria and decision guidelines.

Agent prompt template:

Analyze Skia GM sample files. For EACH file, read it from externals/skia/gm/FILENAME
and produce a JSON entry.

Files: {comma-separated list}

Read .agents/skills/sample-scout/references/analysis-instructions.md for classification criteria.

For each file output: file, name, description, interesting (high/medium/low),
apis_available (true/false), missing_apis [], key_apis [], notes,
visualGoal (what the rendered output looks like), suggestedControls [],
category (Gallery category), skiaSharpApis [] (C# equivalents).

Check API availability by grepping binding/SkiaSharp/ for the C# equivalents.
Save as JSON array to {output_path}.
Must produce exactly {N} entries — count at the end to confirm.

Phase 3: Cross-Reference with Existing Gallery Samples

After all agents complete, merge their findings and cross-reference against existing Gallery samples:

For each GM entry, check if an existing Gallery sample covers the same topic:

• existing — A Gallery sample directly covers this GM's main feature
• similar — A Gallery sample covers a related topic (e.g., gradient GM → Gradient sample exists)
• none — No Gallery sample covers this

Tag each finding with sampleStatus and matchedSample.

Save the merged findings as sample-scout-report.json in the working directory.

Phase 4: Validate and Render

4a. Validate

python3 .agents/skills/sample-scout/scripts/validate-sample-scout.py sample-scout-report.json

4b. Render Markdown

python3 .agents/skills/sample-scout/scripts/render-sample-scout.py sample-scout-report.json sample-scout-report.md

This produces a .md file with ###/#### headers suitable for GitHub issues.

Phase 5: Present Results

Show the summary with these key metrics:

• Total samples analyzed
• 🆕 No existing sample (opportunities)
• 🔶 Similar sample exists (enhancement opportunities)
• ✅ Already covered
• 🎯 Opportunity count = high interest + APIs ready + no existing sample

Then present the top opportunities — samples that are high-interest, have all APIs available, and have no existing Gallery coverage. These are the ones to build next.

Offer:

1. "Want me to build Gallery samples for the top opportunities?"
2. "Should I focus on samples that need new APIs first?"
3. "Want to filter by a specific category (shaders, image filters, text, etc.)?"