OffchainLabs/arbitrum-docs / .agents/skills/image-debt-scan
image-debt-scan
VerifiedFind heavy image debt in public/img: both oversized raster photos (PNG/JPG) AND .svg files that are secretly base64 rasters (draw.io / editor exports, often 1 to 6 MB): map each to the MDX pages that reference it, and rank the best candidates to convert to lean brand SVGs. Use when asked to "find heavy images", "image debt scan", "what diagrams should we convert", or before a batch diagram-cleanup pass. Read-only reconnaissance that feeds the arbitrum-brand-svg-diagrams skill and the diagram-converter subagent.
Image debt scan
Locate the images worth converting to hand-authored SVG. This is the
reconnaissance step before arbitrum-brand-svg-diagrams.
When to use
- "Which images should we convert next?" / "find our heaviest diagrams"
- Planning a batch cleanup of
public/img/ - Before dispatching
diagram-convertersubagents: this produces their work list
When NOT to use
- Photos/screenshots: they legitimately stay raster (only diagrams convert well)
- A single known file: just use
arbitrum-brand-svg-diagramsdirectly
The blind spot this skill exists to close
The biggest image debt in this repo is not the PNGs: it's .svg files that
are actually a base64-encoded raster wrapped in draw.io/editor XML. They carry a
.svg extension (so a naïve size scan of *.png/*.jpg misses them entirely) yet
weigh 1 to 6 MB each and blur when zoomed. A whole-repo scan this session found
~15 of them at ~6 MB apiece (e.g. haw-token-gateway.svg, haw-batching.svg,
apps-pull-oracle.svg, arb-chain-aep-scenario-*.svg). The scanner detects them
by grepping each .svg for data:image/…;base64 (and mxfile for draw.io).
Run the scan (driver)
scan.sh reports raster-in-SVG first (top debt), then oversized rasters,
each with the MDX pages that reference it (or unreferenced = deletion
candidate). Sizes are largest-first.
# whole repo
.agents/skills/image-debt-scan/scan.sh
# scope the reference search to one section (only reports images that section uses)
.agents/skills/image-debt-scan/scan.sh content/docs/how-arbitrum-works
# raise the raster threshold (default 300 KB; raster-in-SVG is always reported)
THRESHOLD_KB=500 .agents/skills/image-debt-scan/scan.sh
Sample output (from the Docusaurus tree; paths and sizes differ here):
== Raster-in-SVG (draw.io / embedded-raster wearing a .svg extension: top debt) ==
6584 KB public/img/haw-token-gateway.svg [embedded-raster]
(unreferenced: candidate for deletion)
6087 KB public/img/apps-pull-oracle.svg [embedded-raster]
content/docs/build-decentralized-apps/oracles/01-overview.mdx
1863 KB public/img/arb-chain-aep-scenario-2.svg [draw.io PNG-in-SVG]
content/docs/launch-arbitrum-chain/.../02-set-up-aep-fee-router.mdx
== Raster images over 300 KB (convert diagrams; keep photos/screenshots) ==
7863 KB public/img/bold-before-vs-after-with-bold.png
content/docs/how-arbitrum-works/bold/gentle-introduction.mdx
Triage the output
Rank into tiers, biggest + most-referenced first:
- Raster-in-SVG, referenced → convert (highest value). Filename ends in
.svg, soarbitrum-brand-svg-diagramscan replace it in place with no MDX edit and nocheck-linksrisk. This is the sweet spot. - Raster-in-SVG, unreferenced → delete. Dead weight; confirm with the user,
then
trash(neverrm). - Heavy PNG/JPG that is a concept diagram → convert (boxes, flows, flat
fills). Converting changes the extension, so the MDX
src=must be updated. - Heavy PNG/JPG that is a photo/screenshot/pie-chart → keep, optionally recompress. Gradients and fine detail don't vectorize well.
Report a ranked table: size · path · referencing pages · verdict. Do not
convert here: that's the SVG skill's job. Hand the "convert" list to a
diagram-converter subagent per file (parallel) or arbitrum-brand-svg-diagrams
for one.
Gotchas
.svgextension guarantees nothing. Always grep forbase64/mxfile:head -c 2000can miss a base64 blob that starts later in the file (some Serif/Affinity exports reference embedded images via<use xlink:href>well past the header), soscan.shgreps the whole file.- Genuine large vector exists (e.g. an 80 KB Graphviz UML with no base64), and it is not flagged, correctly. Size alone isn't the signal; base64 is.
rgmay be rewritten togrepby a shell hook here;scan.shusesgrep -rdirectly to avoid that.
See also
arbitrum-brand-svg-diagrams(under.agents/skills/and.claude/skills/) does the actual conversion.- Subagent
diagram-converter(.codex/agents/diagram-converter.toml) parallelizes conversion across the list.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |