agentleFS
MohamedAbdallah-14MohamedAbdallah-14/prompt-to-asset/.claude/skills/asset-validation-debug/SKILL.md

asset-validation-debug

Skill18 starsChanged 7 months agoMITView on GitHub

Diagnose and repair asset-generation failures. Maps tier-0/1/2 validation codes (checkerboard, missing alpha, safe-zone violation, palette drift, garbled wordmark, low contrast) to concrete repair primitives (matte, inpaint, route change, seed sweep, composite). Applies a retry budget so Claude does not loop on hopeless regenerations.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When a budget exhausts: stop retrying, report to user with diagnostic payload.

    line 28
  2. Distinctive:

    Prefer cheaper primitives first when they apply.

    line 60
  3. Very specific:

    Read validations.failures (when consuming an AssetBundle) or the top-level failures (when calling asset_validate directly).

    line 117

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Asset validation + repair

Triggered when asset_validate(), asset_generate_*, or asset_save_inline_svg returns warnings or errors. Do NOT loop on the same failure; follow the tree and respect the retry budget.

Failure code → repair table

CodeOriginRepair primitiveRetry budget
T0_CHECKERBOARDImagen/Gemini rendering fake transparencyRoute change → gpt-image-1 (background:"transparent"), Ideogram v3 (style:"transparent"), Recraft V32
T0_ALPHA_MISSINGRGB-only output on transparency-required assetMatte via asset_remove_background (BiRefNet preferred, RMBG fallback)1
T0_DIMENSIONSwrong width/height API paramsFix params, regenerate1
T0_SAFE_ZONEsubject bleeds outside platform centerRegenerate with explicit "centered with 20% padding on all sides"1
T0_FILE_SIZE (SVG)path count blows budgetasset_save_inline_svg → SVGO → K-means color reduction → vtracer1
T0_DCT_ENTROPYsolid-color / NSFW-filter hitRegenerate same params once; if repeats, change prompt1
T1_PALETTE_DRIFTmodel ignored hex constraintRecraft with controls.colors or recolor post-process (K-means remap in LAB)1
T1_TEXT_MISSPELLdiffusion garbled wordmarkDrop text, composite SVG type (retry Ideogram 3 if text-only asset)0 in-diffusion / 1 on Ideogram
T1_LOW_CONTRASTpale palette at 16×16 or over backgroundRegenerate with explicit contrast instruction; else post-boost luminance2
T1_VQASCOREprompt-image alignment weakDefect area <15% → inpaint; else full regenerate2
T2_BRAND_DRIFTstyle diverges from brand refsSeed sweep (N=4, rank by CLIPScore + HPSv2); augment brand bundle1
T2_COMPOSITIONoff-center, cluttered, poor whitespaceimg2img at low denoise (0.35) — preserves layout, fixes style1

When a budget exhausts: stop retrying, report to user with diagnostic payload. Do not loop.

Diagnosis tree

asset_validate() returns warnings[]
   └─ for each warning:
      ├─ read code + affected tier
      ├─ classify failure class:
      │    local   (<15% image area)         → inpaint / post-process
      │    global  (style/palette-wide)      → route change / regenerate
      │    compositional (safe-zone/framing) → regenerate with centering prompt
      └─ select repair primitive (table above)
         ├─ apply
         ├─ re-validate
         └─ if same code fires again:
              ├─ retry_count < budget → try next primitive in fallback chain
              └─ retry_count ≥ budget → escalate to user

Repair primitives — cost / ROI

PrimitiveCost relative to 1× generationWhen to choose
SVGO / palette remap / recolor0.01–0.05×Deterministic fix, no model call
Matte (BiRefNet / RMBG)0.05×alpha missing, no regeneration needed
Inpaint (masked edit)0.3×defect area <15%, composition is right
img2img low-denoise1×global style drift, preserve layout
ControlNet tile reinjection1.5×preserve structure, regen detail
Full regenerate4×architectural failure (checkerboard, wrong model)
Seed sweep (N=4)4× + selectionbrand drift, pick best

Prefer cheaper primitives first when they apply.

Route-change rules for architectural failures

SymptomCurrent routeChange to
CheckerboardImagen / Geminigpt-image-1 (first), Ideogram v3, Recraft V3
Wordmark garbledany diffusionIdeogram 3 Turbo (first), gpt-image-1 (second), composite SVG (always works)
Palette drift after 2 triesanyRecraft (hard palette lock via controls.colors)
Subject misrenderedSDXLFlux.1 [dev], gpt-image-1
Path count >200 on SVGRecraft SVGinline_svg mode + strict path budget

Proactive (pre-generation) checks

Prevent 70% of failures by validating the brief before calling asset_generate_*:

BRIEF:
☐ asset_type in closed enum (logo|app_icon|favicon|og_image|splash_screen|
                             illustration|icon_pack|sticker|hero|transparent_mark)
☐ subject noun concrete (not just adjectives)
☐ prompt ≥ 10 words OR brand_bundle provides style refs

TEXT-IN-IMAGE:
☐ quoted string ≤ 12 chars? else composite SVG type
☐ string > 5 words? force composite, skip diffusion-text path

PALETTE:
☐ brand.palette provided?
☐ hex codes ≤ 4 (over-constraint degrades Flux/SDXL)

TRANSPARENCY:
☐ transparency required + model in [Imagen, Gemini]?   → reroute
☐ transparency required + gpt-image-1?                  → set API `background:"transparent"`
☐ transparency required + Flux/SDXL?                    → plan post-matte

ROUTING:
☐ text required + model ≠ Ideogram/gpt-image-1?         → suggest reroute
☐ native SVG needed + model ≠ Recraft?                  → suggest Recraft or inline_svg

Where the codes come from

asset_validate (and every generator that runs a tier-0 pass before returning) emits the codes as a structured array:

{
  "pass": false,
  "warnings": [...],
  "failures": [
    { "code": "T0_CHECKERBOARD", "tier": 0, "detail": "checkerboard pattern detected in 42.7% of analyzed pixels; reject and route to native-RGBA provider", "data": { "ratio": 0.427 } },
    { "code": "T1_PALETTE_DRIFT", "tier": 1, "detail": "...", "data": { "avg_delta_e2000": 14.2, "threshold": 10 } }
  ],
  "tier0": { "width": 1024, "height": 1024, "has_alpha": false, ... }
}

Read validations.failures (when consuming an AssetBundle) or the top-level failures (when calling asset_validate directly). The data field on each failure carries enough context (bbox coords, ΔE value, Levenshtein distance) to pick a repair primitive without re-running the check. Source: packages/mcp-server/src/pipeline/validate.ts, ValidationFailure type in types.ts.

Integration with systematic debugging

Four-phase loop per failure:

  1. Gather evidence — read validate output; log model, seed, guidance, prompt_hash.
  2. Pattern analysis — match to failure code; classify local/global/compositional.
  3. Hypothesis — pick cheapest repair primitive from the matrix.
  4. Verify — re-validate; if same code recurs, step down the route-change ladder, not the same primitive.

Red flags (stop, escalate):

  • Same failure code 3+ times in a row
  • Two different route changes failed for the same asset
  • Cascading repairs (matte → vectorize → safe-zone) — brief is structurally wrong

Evidence to log per pipeline boundary

GENERATION:   model, seed, guidance_scale, num_steps, prompt_hash, latency_ms, status
MATTE:        tool (birefnet|rmbg|difference), alpha_px_before, alpha_px_after, checker_probe
VECTORIZE:    path_count_before, path_count_after, color_count, tool (recraft|vtracer|potrace)
EXPORT:       variants[].{path, format, w, h, size_bytes}
VALIDATE:     tier0{...}, tier1{palette_de: x, vqa: y, ocr_lev: z}, tier2{sim: w}

Research

  • docs/research/14-negative-prompting-artifacts/14b-artifact-taxonomy.md — taxonomy + origin points
  • docs/research/14-negative-prompting-artifacts/14c-regenerate-vs-repair-strategies.md — primitives, cost/time tradeoffs
  • docs/research/03-evaluation-metrics/3e-asset-specific-eval.md — VQAScore, OCR, WCAG, CSD thresholds
  • docs/research/24-skills-for-p2a/06-validation-debug-skill.md — full design spec

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.