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.
SKILL.md
View on GitHub---
name: image-debt-scan
description: >-
Find 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.
disable-model-invocation: true
---
# 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-converter` subagents: 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-diagrams` directly
## 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.
```bash
# 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:
1. **Raster-in-SVG, referenced → convert (highest value).** Filename ends in
`.svg`, so `arbitrum-brand-svg-diagrams` can replace it **in place** with no
MDX edit and no `check-links` risk. This is the sweet spot.
2. **Raster-in-SVG, unreferenced → delete.** Dead weight; confirm with the user,
then `trash` (never `rm`).
3. **Heavy PNG/JPG that is a concept diagram → convert** (boxes, flows, flat
fills). Converting changes the extension, so the MDX `src=` must be updated.
4. **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
- **`.svg` extension guarantees nothing.** Always grep for `base64`/`mxfile`:
`head -c 2000` can 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), so `scan.sh` greps 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.
- `rg` may be rewritten to `grep` by a shell hook here; `scan.sh` uses `grep -r`
directly 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: 471k | 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: 471k | 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: 471k | 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: 194k | Updated | Claude CodeCodex | Verified | Install |