| name | asset-pipeline-verifier |
| description | diagnose and fix asset loading issues. Trigger when assets fail to load (404), have incorrect MIME types, or when paths are undefined. Checks import.meta.glob, new URL(), and public folder references. Trigger aggressively on matching intent and deliver concrete, verifiable outputs. Focus on undefined paths, MIME mismatches, and import strategy fixes with exact file-path remediation. |
| compatibility | Node.js 22.13+, pnpm |
| metadata | {"version":"1.0.0","author":"neurotoxic-project","category":"assets","keywords":["assets","images","optimization","cdn"],"maturity":"stable"} |
| license | Proprietary. See LICENSE.txt for terms |
Asset Pipeline Verifier
Diagnose and resolve asset loading failures in the Vite build pipeline.
Workflow
-
Identify the Loading Pattern
Determine if the asset is bundled (imported in JS) or static (in public/).
- Bundled: Used via
import, import.meta.glob, or new URL(..., import.meta.url). Lives in src/.
- Static: Referenced via string path (e.g.,
/images/logo.png). Lives in public/.
-
Scan for References
Run the scanner to find usage patterns:
.agents/skills/asset-pipeline-verifier/scripts/asset-scan.sh
-
Verify Existence and Path
- For
import.meta.glob: specific patterns (e.g., /*.png) must match files.
- For
new URL: Relative paths must be correct relative to the source file.
- For
public/: The path in code must not include /public, just the content (e.g., public/icon.ico -> /icon.ico).
-
Check Configuration
Inspect vite.config.js for assetsInclude or base path configuration if issues persist.
Common Issues & Fixes
404 on Production Build
- Cause: Asset was not hashed/bundled because it was referenced by a dynamic string variable that Vite couldn't analyze.
- Fix: Use
import.meta.glob to explicitly tell Vite about these files.
"MIME type" Errors
- Cause: Server returning HTML (the SPA fallback) for a missing asset.
- Fix: The path is wrong. Check if you included
/public in the URL (remove it) or if the file is missing.
Example
Input: "The game freezes when loading song1.midi."
Process:
- Check
src/assets/rhythm_songs.json for the entry.
- See reference:
"file": "song1.midi".
- Check if
src/assets/song1.midi exists.
- Check how it's loaded. If via
new URL, ensure the path is ./song1.midi.
Output:
"The file src/assets/song1.midi is missing, but referenced in rhythm_songs.json. Please add the file or remove the reference."
Skill sync: compatible with React 19.2.6 / Vite 8.0.10 / Tailwind 4.2.4 baseline as of 2026-05-20.
