Svg Quality Audit

Audits a folder of SVGs for XML integrity, executable-script risk, and visual quality via Chrome headless render plus a free vision-language model. Use when asked to analyze, check, or audit SVG quality, or before shipping a generated SVG batch. Not for creating or restyling SVGs (use svg-creator). Never claim visual quality from XML structure alone.

Kayforkind Updated Sep 9, 2026

Install

Press C to copy

$ npx skillmds@latest add kayforkind/svg-quality-audit

Installs into ~/.claude/skills (or .claude/skills inside a project). Restart Claude Code to pick it up.

＋ Add to collection

README badge

[![SkillMD](https://skillmd.com/badge/kayforkind/svg-quality-audit.svg)](https://skillmd.com/skills/kayforkind/svg-quality-audit)

Trust & safety

Audits pending

Not yet audited · commit 471eeed

Permissions this skill uses

Executes scripts
The instructions run shell commands or bundled script files.
Makes network calls
The instructions fetch remote URLs or call external services.
Reads secrets
The instructions read tokens, keys, or other credentials.

Works with: Claude Code Claude.ai OpenAI Codex +

File contents

SVG quality audit

When to Use

User wants a quality read on a collection of SVGs.
Before committing / shipping a generated SVG batch (pairs with the project's vision-verify-before-ship rule).
Diagnosing "why do these render wrong / look like sludge".

Prerequisites

Target folder: the SVG directory the user named. Do not assume a private vault path.
Project rules: if the repo has SVG shipping rules, read those first.
Vision gap: many agents cannot judge binary PNGs by reading pixels. Render each sample SVG → PNG (Chrome headless is reliable) and score the PNG with a vision-language model (OpenRouter free vision or local Ollama). Do not claim visual quality from XML structure alone.

Procedure

Phase 1 — Structural scan (100% of files, fast, no render needed).

Run scripts/structure_scan.py <dir>.
Review the output: valid-XML count, drawable-shape distribution, gradient/filter/text/image counts, and defect buckets. Pure stdlib, no deps.

Phase 2 — Render sample (only what you'll vision-judge).

Run scripts/render_vision_judge.py --render-only <dir> <out>.
This renders each SVG to a 400×400 PNG with a checkerboard (transparency) backdrop via Chrome headless. Resumable.

Phase 3 — Vision judge (the ONLY way to catch visual defects structure misses).

Run scripts/render_vision_judge.py --judge <out>.
Scores each PNG 1–10 with a strict rubric (SCORE: / FLAGS: / WHY:) via the free VLM. Resumable, per-call timeout, 429 backoff, incremental JSON. Run large passes in the background.

Working recipe:

OpenRouter free vision: list live free vision models via GET https://openrouter.ai/api/v1/models and pick one with image input. Pass the key via env OPENROUTER_API_KEY. Never print the key. Never read a redacted placeholder from a local config and treat it as live.
Local Ollama: a local vision-capable model is fine for small samples; flaky for large batches under VRAM pressure.
Load references/free-vision-endpoints.md when configuring VLM endpoints.

Defect taxonomy:

Load references/svg-defect-taxonomy.md for per-defect counts, example files, and recovery one-liners.
Escape-bug (dominant): literal \n / \t / \" where real newlines / quotes belong (JSON / repr() serialization bug). ~735 recover by un-escaping; Chrome already renders them. NOT corruption.
JSON-LD <script> is BENIGN. type="application/ld+json" = schema.org metadata. The "65% have <script>" alarm is false — 0 executable JS. ALWAYS separate application/ld+json from text/javascript / application/javascript.
LLM-junk-after-</svg>: model commentary leaked after the close tag. Renders but must be trimmed for a clean library.
Duplicate attributes (e.g. two opacity=), mismatched tags, undefined entities — invalid XML, fix required.
Structure ≠ visual quality: a file can be valid XML yet score 3 ("empty / basic shapes"). Vision is mandatory for a real quality verdict.

Pitfalls

ElementTree's strict parser over-flags: "invalid token at line 1 col 38" is almost always the escape-bug, NOT corruption. Test un-escape recovery before declaring a file dead.
Do NOT claim "done / shipped" from structure alone — render + vision a stratified sample first (vision-verify-before-ship rule).
agy/* generation needs heavy handholding or it emits low-quality / near-duplicate sludge — if you regenerate fixes via Jules / agy, over-specify the brief (subject, palette, shape budget, no Math.random(), no template recycling).
Free VLM tiers are rate-limited; loop with 429 backoff and run large passes in the background.
The escape-bug un-escape is a no-op on clean files (verified: 186 clean files stayed valid after the replace) — safe to apply across the whole set.

Verification

Confirm scripts/structure_scan.py outputs valid-XML count and defect buckets.
Confirm scripts/render_vision_judge.py --render-only generates 400×400 PNGs in the output directory.
Confirm scripts/render_vision_judge.py --judge outputs SCORE:, FLAGS:, and WHY: for the rendered PNGs.
Ensure no file is declared "dead" without testing un-escape recovery for the escape-bug.
Ensure no executable JS is falsely flagged from JSON-LD <script> tags.

---name: svg-quality-auditdescription: Audits a folder of SVGs for XML integrity, executable-script risk, and visual quality via Chrome headless render plus a free vision-language model. Use when asked to analyze, check, or audit SVG quality, or before shipping a generated SVG batch. Not for creating or restyling SVGs (use svg-creator). Never claim visual quality from XML structure alone.--- # SVG quality audit ## When to Use - User wants a quality read on a collection of SVGs. - Before committing / shipping a generated SVG batch (pairs with the project's vision-verify-before-ship rule). - Diagnosing "why do these render wrong / look like sludge". ## Prerequisites - **Target folder:** the SVG directory the user named. Do not assume a private vault path. - **Project rules:** if the repo has SVG shipping rules, read those first. - **Vision gap:** many agents cannot judge binary PNGs by reading pixels. Render each sample SVG → PNG (Chrome headless is reliable) and score the PNG with a vision-language model (OpenRouter free vision or local Ollama). Do not claim visual quality from XML structure alone. ## Procedure **Phase 1 — Structural scan (100% of files, fast, no render needed).** 1. Run `scripts/structure_scan.py <dir>`. 2. Review the output: valid-XML count, drawable-shape distribution, gradient/filter/text/image counts, and defect buckets. Pure stdlib, no deps. **Phase 2 — Render sample (only what you'll vision-judge).** 1. Run `scripts/render_vision_judge.py --render-only <dir> <out>`. 2. This renders each SVG to a 400×400 PNG with a checkerboard (transparency) backdrop via Chrome headless. Resumable. **Phase 3 — Vision judge (the ONLY way to catch visual defects structure misses).** 1. Run `scripts/render_vision_judge.py --judge <out>`. 2. Scores each PNG 1–10 with a strict rubric (`SCORE:` / `FLAGS:` / `WHY:`) via the free VLM. Resumable, per-call timeout, 429 backoff, incremental JSON. Run large passes in the background. **Working recipe:** - **OpenRouter free vision:** list live free vision models via `GET https://openrouter.ai/api/v1/models` and pick one with image input. Pass the key via env `OPENROUTER_API_KEY`. Never print the key. Never read a redacted placeholder from a local config and treat it as live. - **Local Ollama:** a local vision-capable model is fine for small samples; flaky for large batches under VRAM pressure. - Load `references/free-vision-endpoints.md` when configuring VLM endpoints. **Defect taxonomy:** - Load `references/svg-defect-taxonomy.md` for per-defect counts, example files, and recovery one-liners. - **Escape-bug (dominant):** literal `\n` / `\t` / `\"` where real newlines / quotes belong (JSON / `repr()` serialization bug). ~735 recover by un-escaping; Chrome already renders them. NOT corruption. - **JSON-LD `<script>` is BENIGN.** `type="application/ld+json"` = schema.org metadata. The "65% have `<script>`" alarm is false — 0 executable JS. ALWAYS separate `application/ld+json` from `text/javascript` / `application/javascript`. - **LLM-junk-after-`</svg>`:** model commentary leaked after the close tag. Renders but must be trimmed for a clean library. - **Duplicate attributes** (e.g. two `opacity=`), **mismatched tags**, **undefined entities** — invalid XML, fix required. - **Structure ≠ visual quality:** a file can be valid XML yet score 3 ("empty / basic shapes"). Vision is mandatory for a real quality verdict. ## Pitfalls - ElementTree's strict parser over-flags: "invalid token at line 1 col 38" is almost always the escape-bug, NOT corruption. Test un-escape recovery before declaring a file dead. - Do NOT claim "done / shipped" from structure alone — render + vision a stratified sample first (vision-verify-before-ship rule). - agy/* generation needs heavy handholding or it emits low-quality / near-duplicate sludge — if you regenerate fixes via Jules / agy, over-specify the brief (subject, palette, shape budget, no `Math.random()`, no template recycling). - Free VLM tiers are rate-limited; loop with 429 backoff and run large passes in the background. - The escape-bug un-escape is a **no-op on clean files** (verified: 186 clean files stayed valid after the replace) — safe to apply across the whole set. ## Verification - Confirm `scripts/structure_scan.py` outputs valid-XML count and defect buckets. - Confirm `scripts/render_vision_judge.py --render-only` generates 400×400 PNGs in the output directory. - Confirm `scripts/render_vision_judge.py --judge` outputs `SCORE:`, `FLAGS:`, and `WHY:` for the rendered PNGs. - Ensure no file is declared "dead" without testing un-escape recovery for the escape-bug. - Ensure no executable JS is falsely flagged from JSON-LD `<script>` tags.

Kayforkind/skill-slice commit 471eeed687

Frequently asked questions

npx skillmds@latest add kayforkind/svg-quality-audit